Skip to main content

Integration guide

Intake API

Submit, batch, and poll embedded human evaluation intake via the integrator API.

Field-level detail for every endpoint is in the API reference.

Programmatic registration of review work for embedded pipelines.

Endpoints

MethodPathPurpose
POST/v1/intake/submitSingle-item submission
POST/v1/intake/batchMulti-item submission (max batch size enforced server-side)
GET/v1/intake/submissions/{submission_id}Poll submission + item statuses

Schemas: OpenAPI integrator subset.

Request shape (single)

Required fields include filename, file_size (bytes, up to 50 MB), and mime_type (PDF, DOCX, XLSX, plain text, HTML, or XML). Optional: external_reference, item_metadata (up to 50 keys, 10 KB, 3 levels deep), module, and tier. Leave module and tier out unless QueryTek has confirmed values for your workspace; unrecognized values return 422.

POST /v1/intake/submit records intake metadata and creates submission/item rows. Use the portal upload / document APIs when binary content must land in encrypted storage — do not assume base64 body on this route.

Idempotency

Send an optional Idempotency-Key header (1–128 characters) on the write routes below.

MethodPathStored success
POST/v1/intake/submit201
POST/v1/intake/batch201
POST/v1/documents201
POST/v1/batches201
POST/v1/documents/{id}/pay200
POST/v1/batches/{id}/pay200
POST/v1/documents/{id}/withdraw200
POST/v1/batches/{id}/withdraw200
POST/v1/documents/{id}/payment/confirm200
POST/v1/batches/{id}/payment/confirm200
POST/v1/documents/{id}/payment/sync200
POST/v1/batches/{id}/payment/sync200
POST/v1/pay/invite/redeem200
RetryResult
Same key + same bodyStored 201 or 200 is replayed. No second submission, document, batch, checkout, withdraw, confirm, sync, invite redeem, audit event, or webhook.
Same key + different body409 IDEMPOTENCY_KEY_MISMATCH
Same key while the first call is still running409 IDEMPOTENCY_IN_PROGRESS — retry after a short wait
Empty or longer-than-128 key422 IDEMPOTENCY_KEY_INVALID
No headerSame as before this feature — a new write every time

Keys are scoped to your tenant + your user + the route. Pay-invite redeem is unauthenticated and scoped to the invite tenant plus a pay_invite principal. They expire after 24 hours (API_IDEMPOTENCY_TTL_HOURS). Only successful 201 (creates) and 200 (pay / withdraw / confirm / sync / invite) responses are remembered; a validation 422 is not stored, so you may reuse the same key after you fix the body.

Multipart uploads (/v1/documents, /v1/batches) hash form fields plus a SHA-256 digest of the uploaded bytes. The file itself is not stored on the idempotency row. Pay, withdraw, and sync hash the resource id. Confirm hashes the resource id plus transaction_id. Pay-invite redeem hashes the token.

Authorize.Net webhooks stay on their existing event-id path. They do not send Idempotency-Key.

Status polling

GET /v1/intake/submissions/{submission_id}
Authorization: Bearer …

Response includes submission aggregate status and per-item rows (document_id when linked).

Example

curl -sS -X POST "$API_BASE/v1/intake/submit" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "external_reference": "integrator-demo-001",
    "filename": "sample.txt",
    "mime_type": "text/plain",
    "file_size": 12,
    "item_metadata": {"source": "integrator-example"}
  }'

Auditing

Successful submits emit audit actions such as intake.submitted / intake.batch_submitted (tenant-scoped).