Classify (Async)

POST/api/v1/classify/{classifierId}/asyncASYNC

Classify a document and automatically trigger extraction with a single API call. Classification happens immediately and returns the result, while extraction runs in the background. This eliminates the need to manually queue extraction after classification.

The call is identical for project-scoped and global classifiers. With a global classifier the extraction runs in whichever project owns the routed deployment.

Parameters

Name	Type	In	Required	Description
`classifierId`	string	path	Yes	The classifier ID from your classifier settings.
`fileId`	string	body	Yes	The file ID returned from the classifier get-url endpoint after uploading.

Request

const response = await fetch(
`https://app.limai.io/api/v1/classify/${CLASSIFIER_ID}/async`,
{
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_TOKEN}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ fileId })
}
)
const { fileId: classifiedFileId, deploymentName, extractionSchemaId } = await response.json()

Response

Returns the classification result immediately. Extraction is triggered automatically in the background.

Response200

{
  "fileId": "file_abc123def456",
  "deploymentName": "Invoice Processing",
  "extractionSchemaId": "schema_789xyz012"
}

Field	Type	Description
`fileId`	string	The classified file ID. Use this to poll for extraction results.
`deploymentName`	string	The deployment the document was routed to.
`extractionSchemaId`	string	The extraction schema ID of the routed model or deployment — not the deployment's own ID. Pass it to the process-file endpoints, which expect this ID.

Polling for Results

After async classification, poll the get-file-data endpoint using just the fileId. The status may transition through CLASSIFYING and PROCESSING before reaching COMPLETED.

async function pollForResults(fileId) {
while (true) {
  const response = await fetch(
    `https://app.limai.io/api/v1/document/get-file-data?fileId=${fileId}`,
    { headers: { "Authorization": `Bearer ${API_TOKEN}` } }
  )
  const data = await response.json()

  if (data.status === "COMPLETED") return data
  if (data.status === "FAILED") throw new Error(data.errorMessage)

  await new Promise(r => setTimeout(r, 5000))
}
}

Sync vs Async Classification

	Sync (`/classify/{id}`)	Async (`/classify/{id}/async`)
Classification	Returns result immediately	Returns result immediately
Extraction	Must be queued manually	Triggered automatically
Polling	Requires `fileId` + `extractionSchemaId`	Requires only `fileId`
Best for	Custom routing logic after classification	Simple end-to-end pipelines

Skip the Polling

Rather than polling get-file-data, subscribe to the DOCUMENT_CLASSIFIED webhook. It fires once the classifier reaches a decision and carries the outcome, the confidence, the classifier's own reasoning, and the routed deployment -- for documents that routed and for documents that did not, on the same event. DOCUMENT_CLASSIFICATION_FAILED covers the runs that broke.