Skip to main content

Preferences

Document extraction endpoints (/documents/single and /documents/append) support the standard HTTP Prefer header (RFC 7240) to express expectations about the document being submitted.

This is useful when your application knows what type of document it expects — for example, a bank statement upload flow can declare that preference so the API can flag or reject documents that don't match.

Specifying preferences​

Add a Prefer header to your extraction request. Preferences are comma-separated, and values containing commas must be quoted.

By document class​

Use document-class with a class identifier from the classIdentifier field in the extraction response schema. Multiple identifiers can be comma-separated within a quoted string:

curl -X POST https://api.onteric.com/documents/single \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Prefer: document-class="banking-statement"' \
  -F "document=@statement.pdf"

By document context​

Use document-context to match any document within a broader category — for example, accepting any property-related document rather than a specific class:

curl -X POST https://api.onteric.com/documents/single \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Prefer: document-context="Property"' \
  -F "document=@document.pdf"

Context categories correspond to the prefix before the colon in the className response field (e.g. Banking, Property, Earnings).

When both document-class and document-context are specified, the document is accepted if it matches either preference.

Handling mode​

By default, a mismatch is reported as a warning in the expectations.warnings array of the response. The document is still fully processed and all extracted data is returned as normal.

To reject mismatched documents before extraction takes place, add handling=strict:

curl -X POST https://api.onteric.com/documents/single \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Prefer: document-class="banking-statement", handling=strict' \
  -F "document=@document.pdf"

In strict mode, a mismatch returns 412 Precondition Failed. Classification still takes place and the uploaded file is retained, but extraction is skipped.

Response headers​

When preferences are evaluated, the API includes two additional response headers:

  • Preference-Applied — lists which preferences were applied (e.g. document-class, handling)
  • Vary: Prefer — signals that the response varies depending on the Prefer header

These are included on successful responses. A 412 rejection does not include Preference-Applied.