Skip to main content

Trigger Delivery

Request delivery for a structuring run with POST /v1/structuring/delivery/:runId and learn how approved records reach destinations via delivery bindings.

POST /v1/structuring/delivery/{runId} requests delivery for an entire structuring run after review. The runId is the job run id (the same id GET /v1/jobs lists). The call verifies the run belongs to your organization and acknowledges the trigger; what actually ships is governed by the delivery pipeline's approved-records rule — only results with an approved decision are exported, so unreviewed and rejected records never leave the platform through this channel.

Structuring delivery is signal-driven under the hood. When a run completes, the platform emits a run.structuring.completed signal carrying the run and schema ids; delivery bindings subscribed to that signal resolve the run.structuring.outcome deliverable — the run's approved result rows — and send them to your configured destinations (webhook, S3, SFTP, email). A run with zero approved rows still fires the binding with an empty payload, so your consumer learns "the run produced nothing approved" instead of silence.

For this endpoint to result in data arriving anywhere, a delivery binding must exist that pairs the run.structuring.completed signal (or your chosen trigger) with the run.structuring.outcome deliverable and a destination. Configure destinations and bindings under the Delivery API — the trigger call does not create routing by itself.
POST/v1/structuring/delivery/{runId}

Path parameters

runId*uuidThe structuring (job) run to deliver. Must belong to your organization.

curl

curl -s -X POST https://api.talonic.com/v1/structuring/delivery/1a0c681d-ea20-4bb4-8892-01a6d7f834da \
  -H "Authorization: Bearer tlnc_your_api_key"

Response

Response fields

statusstringAlways triggered on success.
run_idstringUUID of the job run delivery was requested for.
messagestringConfirmation message.

Response

{
  "status": "triggered",
  "run_id": "1a0c681d-ea20-4bb4-8892-01a6d7f834da",
  "message": "Structuring delivery triggered."
}

Errors

Error responses

400VALIDATION_ERRORThe runId path parameter is not a valid UUID.
401unauthorizedMissing or invalid API key.
404RESOURCE_NOT_FOUNDJob run not found or does not belong to your organization ("Job run '...' not found.").
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

The call is safe to repeat: it performs no destructive work of its own — repeating it re-acknowledges the same run rather than duplicating records, and duplicate suppression on the wire is the delivery pipeline's responsibility, not the caller's. The typical end-to-end sequence is: run completes → gates auto-approve the clean rows → reviewers action the [pending queue](pending-approvals) via [approve/reject](approve-reject-result) → trigger delivery for the run → the approved set lands at your destinations.

If triggered delivery never arrives, debug in this order: confirm the run id is the job run (not a pipeline or result id); confirm at least one result carries an approved decision — a fully-unreviewed run delivers an empty set; then check your delivery bindings and destination health under the [Delivery API](list-delivery-destinations), where per-delivery attempts and failures are visible in the delivery history.

Frequently asked questions

What happens to unapproved results when I trigger delivery?+
They are excluded. The run.structuring.outcome deliverable resolves only results whose approval status is approved, so pending and rejected records stay on the platform. A run with nothing approved delivers an empty payload rather than erroring.
Can I trigger delivery multiple times for the same run?+
Yes — the call is an acknowledgment-style trigger with no destructive side effects, so repeating it is safe. Whether your destination receives duplicate payloads depends on your binding configuration; webhook consumers should key on run_id for idempotent ingestion.
Where do delivered results actually go?+
To the destinations wired through delivery bindings: a binding pairs a signal (like run.structuring.completed) with the run.structuring.outcome deliverable and a destination such as a webhook, S3 bucket, SFTP server, or email. Manage all three under the Delivery API; a gate's destination_id records the intended destination for its approved output.
Which id do I pass — run, pipeline, or result?+
The structuring (job) run id: the id returned by GET /v1/jobs and carried by each result row as its run. Passing a result id or a Spec pipeline id returns 404 "Job run not found."

Related

Approve / Reject a Result
Pending Review Queue
Delivery Destinations
Delivery Bindings
List Structuring Jobs