Check status (polling)

Query the status of a validation transaction until it reaches a terminal state. While the transaction has not finished, the response contains only the identifier and the status. When it reaches a terminal state with diagnosis, it also includes the result response complete.

Endpoint

GET /document/validate/{transactionId}

Headers

Name	Type	Required	Description
Authorization	string	Yes	Consumer Token in Bearer format Bearer <token> (see Authentication).
consumer-id	string	Yes	Consumer identifier.
operation-id	string	Yes	Validation operation identifier, the same one that was sent when it was started.

Path parameters

Parameter	Type	Required	Description
transactionId	string	Yes	Transaction identifier returned by POST /document/validate.

Responses

200 Success (transaction in progress)

{
  "transactionId": "1c7d...e9",
  "status": "IN_PROGRESS"
}

200 Success (terminal transaction)

When the transaction reaches a terminal state with diagnosis (COMPLETED), the response also includes the full diagnosis. See Result response.

Transaction states

State	Meaning	Terminal?
PROCESSED	The transaction was created and accepted for processing.	No
ERROR	The transaction could not be created/started (failure in the initial request).	Yes
IN_PROGRESS	Validation is in progress.	No
COMPLETED	A diagnosis is available (APPROVED, DECLINED or DOUBTFUL).	Yes
FAILED	Unrecoverable failure during processing. Includes failureReason.	Yes

The terminal state COMPLETED is unique for any result with diagnosis. In the event of ERROR or FAILED, there will be no diagnostic or OCR in the response. The state FAILED does include failureReason and timestamp.

failureReason

When status = FAILED, the field failureReason describes the cause of the failure with a generic and stable. These are the possible values:

failureReason	Meaning / recommended action
Validation could not be completed	Transient processing failure. It is safe to retry by starting a new transaction with the same assets; if it persists, contact support.
Internal processing error	Unexpected error during processing. Retry later; if it persists, contact support.
Asset not found in storage: <fileKey>	One of the referenced assets could not be resolved. Verify that the fileKeys exist and were uploaded correctly before retrying.
Invalid <front|back|face> asset token	The specified asset is not a valid capture token. Capture/upload that asset again and restart the process.

failureReason is deliberately generic: different internal causes (including analysis timeouts) are grouped into Validation could not be completed. The specific detail remains in the service's internal logs; if you need to diagnose a case, share it with support together with the transactionId.

Other responses

Code	Description
400	The header operation-id is missing or empty.
401	Missing, invalid, or expired Token.
403	The consumer is not provisioned with the service DOCUMENT_ANTIFRAUD.
404	The transaction does not exist or belongs to another consumer.
429	The consumer has exceeded its request rate limit. The response includes Retry-After with the wait seconds, and X-RateLimit-Limit and X-RateLimit-Burst with the current thresholds.
503	The service persistence is temporarily unavailable.

The body of an error response has the form described in MIDAPI v2.

The 429 of this Endpoint is the rate limit, and it should be taken into account when choosing the polling cadence: polling every few milliseconds causes it. The recommended strategy, phased and with backoff, is in Best practices.