Skip to main content
Tavrn works the request with the facility for days or weeks. Your integration needs three things during that time: to know when something changed, to answer the occasional question, and to pick up records and invoices when they land.

​
Register a webhook

Create one endpoint for the three retrieval events. Needs webhooks:write.
Payloads are HMAC-signed; verify them with the secret returned at creation (Signature verification). Treat the payload as a pointer: on every event, fetch the request and act on its current state.
status is one of received, processing, action_required, completed, cancelled; stage is the finer step shown in Tavrn. Full tables in Track Status.

​
Reconcile with incremental polling

Webhooks can be missed; polling catches up. Keep a checkpoint and ask for everything that changed since it:
Upsert each result by id, follow next until it is null, then save next_public_updated_since as the new checkpoint. The lower bound is inclusive, so compare public_updated_at before overwriting a cached request. Details in Incremental polling.

​
Answer action requests

When status is action_required, pending_action_request says what Tavrn needs. The most common one is payment_needed: a provider invoice above your approval limit.
A clear approve or decline in message is enough for payments. Other reasons (a new authorization, a corrected date of birth) take an attachment: upload it with the retrieval sign-upload endpoint and pass the upload_id. See Responding to Action Requests.

​
Download records and invoices

On documents_available (or any time), list the request’s documents:
Each entry has a category of records, invoice, or cost_summary, with file metadata when available. Invoice entries also carry metadata.provider_fee_amount in USD, so you can post the provider fee to the matter before or after you download the PDF. Then fetch a time-limited URL per document:
Completed requests with finalized billing also include cost_summary, a PDF of Tavrn credits and fees, provider fees, and the total. Use /documents/cost_summary/download to get its download URL. See Request cost PDF. GET /v2/retrieval-requests/{id} also returns costs (provider_fees, tavrn_fee, total_cost, in USD; get endpoint only) and documents_summary counts, so one call is enough to reconcile what a request has cost. The documents_available event lists the new document_ids and invoice_ids. More in Download Records and Invoices.

​
Done

completed and cancelled are final. Keep polling after completion: a late provider invoice can still arrive and shows up as a new document.

Retrieval guide

Every field, status and edge case.

Webhooks

Payload shapes, signatures, retries.