Document splitting API

Classify an upload to detect several documents in one file. The page-plan endpoints can split or combine PDFs, attach whole documents, select pages to scan, and change a document's type or name.

Authentication and access

The external upload endpoint accepts an organization API key and the classify parameter. The other endpoints on this page use the application's authenticated user API. They require a user bearer token and organization context (X-Organization-Id), with permission to view the project and each affected document. An organization API key does not grant access to those routes.

Use https://apiv2.recognito.io as the base URL. Send Accept: application/json, and use Content-Type: application/json for page-plan and attachment requests.

Classify an upload

Add classify=true to the multipart request to detect document types and possible cuts. Send classify=false to bypass classification. If omitted, it follows the project's Classify and split files uploaded from the app by default setting, which defaults to off. This also applies to the Make and n8n upload endpoints.

The project's Document splitting setting decides whether a multi-document file splits automatically or waits for review. Off still holds a multi-document file for review when classification was requested for the upload. Only PDF, PNG, JPG and JPEG files can be classified; only PDFs can be cut.

The external upload response remains {"status":"success"}. It supplies neither a document UUID nor a request ID for polling.

Apply a page plan

POST /api/prebuilt-documents/review-pages

A plan covers all pages of the supplied documents, in the order of the documents array. Page numbers start at 1 and continue across document boundaries. For example, two three-page documents occupy pages 1–3 and 4–6.

Field	Type	Required	Meaning
documents	string array	Yes	One or more distinct document UUIDs, all in the same project.
segments	object array	Yes	Parts that cover every page, without gaps or overlaps.
segments[].start_page	integer	Yes	First page in the combined sequence, inclusive.
segments[].end_page	integer	Yes	Last page, inclusive.
segments[].role	string	No	main (default), supporting, or discard.
segments[].doc_type	string or null	No	Document type, up to 255 characters.
segments[].name	string or null	No	Name for a main part, up to 255 characters.
segments[].skip_pages	integer array	No	Pages in a main part to leave unscanned, using the combined page numbering.
segments[].segment_id	string or null	No	Proposal segment identifier, up to 64 characters.

Keep at least one main part and at least one scanned page in every main part. A supporting part attaches to the nearest main part before it, or the first main part if it comes first. A discard part removes those pages. Skipped pages remain in the file.

This example turns a three-page PDF into two documents, with page 3 attached to the second:

{
  "documents": ["DOCUMENT_UUID"],
  "segments": [
    {"start_page": 1, "end_page": 1, "doc_type": "Invoices", "role": "main", "name": "March invoice 1"},
    {"start_page": 2, "end_page": 2, "doc_type": "Invoices", "role": "main", "name": "March invoice 2"},
    {"start_page": 3, "end_page": 3, "doc_type": "DeliveryNotes", "role": "supporting"}
  ]
}

Changing only type or name saves in place. Attaching a whole document does not scan it again. Cutting, joining pages or changing the scanned pages of a processed PDF starts new extraction; extracted values and manual edits are lost. Image documents can be kept, attached or deleted whole, but cannot be cut.

Approved, validated, exported or processing documents cannot be changed through review-pages. A plan with no changes returns 422.

Responses

A change that needs PDF cutting returns 202 Accepted:

{"status":"queued","request_id":"split-REQUEST_ID"}

Poll upload status with that request ID. Changes completed within the request return 200 OK:

{
  "status": "done",
  "documents": [
    {
      "uuid": "DOCUMENT_UUID",
      "original_filename": "March invoice 1",
      "status": "done",
      "page_count": 1,
      "needs_action_type": null
    }
  ]
}

The outer done means the page change completed. Check each document's status for extraction or a hold; it may still be processing or needs_action.

Status	Meaning
422	Invalid plan, no changes, different projects, or a PDF that could not be processed.
409	A document is approved, validated, exported, processing, or already being changed.
403	The authenticated user cannot access an affected document or project.
404	A document was not found.

Plan errors return a message, for example Segments overlap at page 2 or Part 1-3 has no pages left to scan. Request-field validation can also include an errors object.

Check upload or correction status

GET /api/prebuilt-documents/upload-status/{requestId}

Use the request_id returned by an application upload or queued page change. The external API-key upload endpoint does not return this ID.

{
  "request_id": "split-REQUEST_ID",
  "status": "pending",
  "files": [],
  "documents": [
    {
      "uuid": "DOCUMENT_UUID",
      "original_filename": "March invoices",
      "status": "processing",
      "page_count": 3,
      "needs_action_type": null
    }
  ]
}

status	Meaning
pending	Upload or page change is still running.
classifying	The classifier is running.
review	Intake or the page change completed, with at least one document held for action.
done	Intake or the page change completed. Individual documents can still be processing.
failed	Intake or the page change failed. A correction response can include message.

When present, files contains id, original_name, status, hold, children and segments. The last two fields are counts. documents contains the summaries shown above. Results are restricted to the caller's visibility; an unknown request ID returns 404.

Attach whole documents

POST /api/prebuilt-documents/attach

This is the action labelled Merge in the documents list. Every document in attachments becomes an attachment of every document in documents:

{
  "documents": ["RECEIVING_DOCUMENT_UUID"],
  "attachments": ["SUPPORTING_DOCUMENT_UUID"]
}

Both arrays must contain at least one distinct UUID. All documents must belong to the same project, and a document cannot be its own attachment. The source documents are removed from the list after attachment. Their extracted values are not merged into the receivers, and nothing is scanned again.

Approved, validated or exported documents can receive attachments but cannot become attachments. Processing documents cannot participate. The response is 200 with status: "done" and the receiving document summaries. Invalid selections return 422; documents that cannot be changed return 409.

List classifier categories

GET /api/projects/{uuid}/classifier-categories

Returns the category values used for accepted document types and doc_type:

{
  "analyzer": "ANALYZER_NAME",
  "categories": [
    {"value": "Invoices", "description": "Invoice documents"},
    {"value": "DeliveryNotes", "description": null}
  ]
}

The category list depends on the project's classifier. description can be null. If the classifier definition is unavailable, the endpoint returns an empty categories array.

Document metadata and webhooks

The application document resource (GET /api/prebuilt-documents/{uuid}) exposes these optional keys under metadata:

Key	Meaning
split	The split child's provenance, including its source pages.
split_proposal	The classifier's proposed segments and confidence.
split_confirmed	The accepted split plan and confirmation mode.
doc_type	{type, confidence, source}. Source is classifier, review or manual; confidence can be null.
needs_action	Hold type and human-readable reason; split holds also include a code.
replaced	Source document identities and the replacement action.
replacing	A page change is queued or running, with its request ID.
correction_failed	The last failed change, with its request ID and message.
correction_done	Completion record for a change that did not create a new document.

These fields are document metadata, separate from extracted data.metadataFields. Supporting parts appear in the ordinary attachments collection.

Webhook payloads and event names are unchanged. Each new document follows the usual document events. There is no separate document-replaced webhook event, and these metadata keys are not automatically added to webhook payloads.

See also

• Upload documents: API-key upload parameters and examples.
• Splitting, combining and trimming documents: review page plans in the app.
• Webhooks: receive document events.