Skip to main content

Classify

Classify link keys into categories (identity, transaction, reference) using AI. Runs asynchronously on ambiguous fields.

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

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.

Related

Link Keys
Backfill