Skip to main content

Classify

Classify ambiguous fields into identity, transaction, or reference link keys with AI. Returns the classified count and triggers a backfill for new keys.

When new fields are extracted, some may not be automatically classified as link keys. The classify endpoint runs AI-powered classification on ambiguous fields to determine whether they are identity, transaction, or reference link keys. This is useful after onboarding new document types or when the field registry grows.

Call this endpoint after uploading a new batch of documents or after adding a new document type to your workspace. The endpoint returns immediately with the count of fields that were classified — any graph rebuilding happens asynchronously via a triggered backfill.

The response includes a classified count (number of fields newly assigned a category) and a backfillTriggered boolean. When backfillTriggered is true, entity links across all documents are being rebuilt in the background. Poll the Backfill progress endpoint to monitor completion.

Only fields with a null category are evaluated — already-classified link keys are not re-assessed. To verify which fields were classified, call the Link Keys endpoint before and after. If no ambiguous fields remain, classified returns 0 and no backfill is triggered.

Classification uses a two-pass approach: rule-based heuristics handle obvious cases (e.g. fields named invoice_number), then an LLM call classifies the remaining ambiguous fields. A backfill is automatically triggered when new link keys are identified.
POST/v1/linking/classify

Request

curl -X POST https://api.talonic.com/v1/linking/classify \
  -H "Authorization: Bearer $TALONIC_API_KEY"

Response

Response fields

classifiedintegerNumber of fields newly classified as link keys.
backfillTriggeredbooleanWhether a backfill was started because new link keys were identified.

Response

{
  "classified": 3,
  "backfillTriggered": true
}

Errors

Error responses

401unauthorizedMissing or invalid API key.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Frequently asked questions

Does classification run synchronously?+
The endpoint returns immediately with the count of classified fields. If new link keys are found, a backfill is triggered asynchronously to update entity links across all documents.
Can I reclassify an already-classified link key?+
The classify endpoint targets unclassified or ambiguous fields. Already-classified link keys are not re-evaluated unless their category is null.
How do I know when the triggered backfill has finished?+
Poll GET /v1/linking/backfill/progress. The backfill is complete when the running field is false; the processed and total counters track document-level progress while it runs.

Related

Link Keys
Backfill