Client Reference

Add X-Client-Reference to connect an extraction request to a record in your system. The reference appears in the response and usage reporting, so you can trace work back to a customer, case, invoice, or batch.

Choose a reference that matches how you want to track usage:

Your use case	Example reference
Group extraction usage for one customer	customer-42
Find requests belonging to one case	case-8042
Track an invoice through your integration	account-42:invoice-1001
Reconcile a batch of uploaded files	import-2026-09-14-01

You can reuse a reference across related requests. Use a stable identifier from your system and keep the API’s requestId or job.id alongside it to identify each individual extraction.

Send The Header

Include the header when uploading a file through sync or async extraction. You choose the value; no registration is needed.

curl -X POST "https://api.terrafai.com/api/v1/extraction-jobs" \
  -H "Authorization: api-key $API_KEY" \
  -H "Idempotency-Key: invoice-1001-upload-1" \
  -H "X-Client-Reference: account-42:invoice-1001" \
  -F "file=@invoice.pdf;type=application/pdf" \
  -F "templateName=invoice"

Choose A Value

Use a single-line identifier of up to 512 characters, without carriage returns, line feeds, or NUL characters. Surrounding whitespace is removed; a blank value is treated as omitted. References preserve case, and usage searches match the exact value.

Keep the reference to an identifier, such as a customer ID rather than a customer’s name or email address. It is stored with usage records.

Find It In Responses

The reference is returned as top-level clientReference:

{
  "success": true,
  "requestId": "req_9d6a4f3c-0d7b-4ab1-9b1a-5b27499e9c2f",
  "clientReference": "account-42:invoice-1001",
  "job": {
    "id": "2c0d2f0e-1f4e-4c11-a0d6-64cc7b71697d",
    "status": "queued",
    "statusUrl": "/api/v1/extraction-jobs/2c0d2f0e-1f4e-4c11-a0d6-64cc7b71697d",
    "retryAfterMs": 5000
  }
}

Sync responses, async create/status/result responses, and completed or failed webhook events include the reference when you supplied one. For async jobs, send it on creation; subsequent responses use the saved value.

Use It With An Idempotency Key

The two headers serve different purposes:

Header	Example	Purpose
X-Client-Reference	account-42:invoice-1001	Connects related work to the same business record.
Idempotency-Key	invoice-1001-upload-1	Identifies one intended async upload so it can be retried safely.

If a connection drops during upload, retry with the same key, file, and settings. The existing job keeps its original client reference. If you later process a corrected invoice, use a new idempotency key; you can keep the same client reference to associate both extractions with that invoice.

Changing only X-Client-Reference does not cause an idempotency conflict or replace the original job’s reference. For changed files or extraction settings, see Key Conflicts.

See Safe Retries for the time limit on duplicate protection. Your API key continues to determine access to the environment; a client reference is for attribution.

Usage Dashboard

In the Usage dashboard, view usage grouped by client reference or search for an exact reference to filter request, page, and cost totals. Select No reference to find requests that omitted the header.