Skip to content
FirmEasy
← Inicio

Ingestion Status

GET
https://api.firmeasy.legal/api/v1/documents/envelopes/{{ingest_token}}/status

Ingestion Status

Section titled “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

Section titled “Authentication”
Authorization
string
Bearer authentication token.
Limits:Required (Bearer <token>)

Path Parameters

Section titled “Path Parameters”
ingest_token
string (UUID)
The identifier token of the batch received in the 202 response from the async endpoint.
Limits:Required

In-Progress Response (200 OK)

Section titled “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
}
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)

Section titled “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"
}
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)

Section titled “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
}
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

Section titled “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.