Skip to main content
A successful delivery confirms only that your endpoint received a record. An acknowledgement reports what your system did with it afterward.
Acknowledgements are for delivery tracking and observability, not control flow.An acknowledgement that reports failure does not trigger a retry or a redelivery. To understand retry and redelivery, see Delivery failure handling.

​
When to use acknowledgements

  1. Batch delivery: A status code covers the whole batch file, so acknowledgements are the only way Prequel learns the outcome of any single record inside it.
  2. Asynchronous ingestion: When your endpoint queues a record and responds before processing it, the acknowledgement carries the real verdict back.
    • Return a 2xx on receipt so the delivery is not retried, then acknowledge with a record-level status code once processed asynchronously.
  3. Provider feedback: Downstream failures become available per record, which you can optionally surface to Providers so they correct the offending records at the source. See Replication monitoring.
Acknowledgements are valuable for record delivery to handle asynchronous ingestion. With batch delivery, acknowledgements are required in order to provide record-level statuses to your users on their source data.

​
Where to send them

Every delivery carries an acknowledgement URL. Make an HTTP PUT to that URL with your acknowledgement as the body. Where the URL arrives, and the Content-Type to send, depend on the delivery type. Send the Content-Type shown above or the request is rejected. Each URL expires 24 hours after the delivery.

​
What to send

A record delivery takes a single acknowledgement object. A batch delivery takes newline-delimited JSON, one acknowledgement per line. The example below is expanded for readability:
Example
​
string
required
Schema version of the acknowledgement. Currently v0.
​
string
required
Identifies the record being acknowledged.
​
integer
required
The HTTP status code your system reached for this record. Use 200, 201, or 204 to mark it succeeded, or a 4xx or 5xx to mark it failed.
​
string
required
RFC 3339 timestamp of when your system reached this outcome. When a record has more than one acknowledgement, the latest timestamp takes precedence, so sending again re-acknowledges the record.
​
string
The batch the record was delivered in, taken from batch_id on the delivery envelope.
​
string
A description of the failure. Kept only when status_code is 400 or above.
An acknowledgement that fails schema validation is not dropped; it marks the record as errored. Use the dataset’s primary_key_column value as the record_id. Batch deliveries carry it as prequel__record_id on every record in the batch file, except when a body template shapes a json batch. In that case the template controls the payload, so render the primary key into it with {{.Record.<field>}} or you will have no id to acknowledge against. Get record returns a record by that id, including its acknowledgement state.

​
When acknowledgements appear

Prequel ingests acknowledgements automatically, typically within 15 minutes of the load completing, and only those sent within 75 minutes of it. Once ingested, a record’s downstream outcome sits alongside its delivery history in Get record and load debugging, so you can trace one record from extraction through to your system’s final verdict. Optionally, you can use the initialize acknowledgement endpoint to ingest on demand. Use this when your processing finishes outside the 75-minute window. The endpoint does not accept acknowledgements; it tells Prequel to process acknowledgements you have already sent, optionally bounded by start_time and end_time on when you sent them.