Ingestion Status

GET {{base_url}}/v1/documents/envelopes/{{ingest_token}}/status

Ingestion Status

Returns the batch processing progress. When the status changes to ready, the response includes the actual document_token, which must be used for subsequent queries in the document reading endpoints.

Authentication

Parameter	Type	Description	Limits
`Authorization*`	string	Bearer authentication token.	Required (Bearer <token>)

Path Parameters

Parameter	Type	Description	Limits
`ingest_token*`	string (UUID)	The identifier token of the batch received in the 202 response from the async endpoint.	Required

In-Progress Response (200 OK)

Shows the batch status while files are being downloaded and assembled in the background.

{
  "ingest_token": "01234567-...",
  "status": "ingesting",
  "documents_total": 80,
  "documents_ingested": 67,
  "documents_failed": 0,
  "bytes_ingested": 743891200,
  "bytes_limit": 1073741824,
  "errors": [],
  "document_token": null,
  "external_id": "BATCH-12345",
  "started_at": "2026-04-15T14:30:00Z",
  "completed_at": null
}

Nombre	Type	Description
`ingest_token`	string (UUID)	Unique identifier of the ingestion process.
`status`	string	Current batch status: ingesting · assembling · ready · failed · cancelled.
`documents_total`	integer	Total number of documents sent in the batch.
`documents_ingested`	integer	Number of documents already downloaded and successfully processed.
`documents_failed`	integer	Number of documents that failed during ingestion.
`bytes_ingested`	integer	Number of bytes processed so far.
`bytes_limit`	integer	Maximum allowed weight limit for the batch (1 GB total).
`errors`	array	Collection with details of individual errors per document.
`document_token`	string (UUID)	Final envelope token (null while in progress).
`external_id`	string	External identifier sent during batch creation (pass-through).
`started_at`	string (ISO8601)	Start date and time of background processing.
`completed_at`	string (ISO8601)	Batch completion date and time (null while in progress).

Successfully Completed Response (200 OK)

Response structure when processing has finished successfully and the envelope is ready for production.

{
  "ingest_token": "01234567-...",
  "status": "ready",
  "documents_total": 80,
  "documents_ingested": 80,
  "documents_failed": 0,
  "document_token": "abcdef01-...",
  "external_id": "BATCH-12345",
  "started_at": "2026-04-15T14:30:00Z",
  "completed_at": "2026-04-15T14:42:00Z"
}

Nombre	Type	Description
`ingest_token`	string (UUID)	Unique identifier of the ingestion process.
`status`	string	Final successful status: ready.
`documents_total`	integer	Total number of processed documents.
`documents_ingested`	integer	Number of successfully processed documents.
`documents_failed`	integer	Number of failed documents (0 on total success).
`document_token`	string (UUID)	Definitive envelope token generated for use in the rest of the API.
`external_id`	string	External identifier associated with the batch.
`started_at`	string (ISO8601)	Ingestion start date and time.
`completed_at`	string (ISO8601)	Exact process completion date and time.

Response with Processing Errors (200 OK)

Structure returned if one or more files could not be integrated into the envelope (for example, download failures from source URLs).

{
  "ingest_token": "01234567-...",
  "status": "failed",
  "failure_reason": "source_error",
  "documents_total": 80,
  "documents_ingested": 79,
  "documents_failed": 1,
  "errors": [
    {
      "ref_id": "doc-43",
      "error": "The URL for 'doc-43' responded with HTTP 404."
    }
  ],
  "document_token": null
}

Nombre	Type	Description
`ingest_token`	string (UUID)	Unique identifier of the ingestion process.
`status`	string	Terminal failure status: failed.
`failure_reason`	string	General failure reason code. Possible values: `timeout` (download timed out), `size_limit` (exceeds weight limit), `source_error` (error downloading from source URL) or `internal_error` (internal server error).
`documents_total`	integer	Total number of requested documents.
`documents_ingested`	integer	Number of documents that were processed before the failure.
`documents_failed`	integer	Number of documents that triggered the error.
`errors`	array	List of error objects with the ref_id of the affected document and the error message detail.
`document_token`	null	No envelope token is generated if ingestion fails.

Common Error Responses

Code	Status	Description
`401`	Unauthorized	The authentication token is invalid, expired, or was not sent.
`404`	Not Found	The provided `ingest_token` does not exist or does not belong to the active organization.