Skip to main content

Document statuses

This page describes every value you may see for a document's status, validationStatus, declinedReason, and documentCategory. These appear in:

The same per-document review pipeline (validation → review → approve/decline) applies whether a file was uploaded during initial KYB onboarding or attached to an RFI document request. The status taxonomy below is identical across both flows.

1. Document status​

Every document has a status that reflects where it is in the review lifecycle.

StatusDescription
NOT_SUBMITTEDNo file has been uploaded against this document requirement yet.
PENDING_VERIFICATIONFile has been uploaded and is queued for automated validation. Transient: usually resolves within seconds.
VALIDATION_WARNINGSAutomated validation flagged concerns. The customer must either acknowledge the warning and continue, or re-upload a corrected file. See Acknowledging validation warnings below.
PENDING_REVIEWDocument is awaiting review by Hubpay.
APPROVEDDocument accepted. No further action required.
DECLINEDDocument not accepted. declinedReason and declinedCustomerDisplayReason explain why. Customer should re-upload.

Status transitions​

  1. A document starts as NOT_SUBMITTED until the customer uploads a file.
  2. After upload, the document enters PENDING_VERIFICATION while automated validation runs.
  3. If validation finds concerns, the status moves to VALIDATION_WARNINGS. The customer can either acknowledge (moves to PENDING_REVIEW) or re-upload (goes back to PENDING_VERIFICATION).
  4. If validation passes cleanly, the document goes straight to PENDING_REVIEW.
  5. After review, the document is either APPROVED or DECLINED.
  6. If declined, the customer can re-upload and the cycle starts again from PENDING_VERIFICATION.

2. Validation status​

When a document is in VALIDATION_WARNINGS, the validationStatus field carries the specific issue our automated review found. Values are split by severity.

Warnings​

Warnings are recoverable. The customer can either acknowledge the warning to proceed (the document moves to PENDING_REVIEW) or re-upload a corrected file.

ValueMeaning
WARNING_NOT_CERTIFIEDDocument appears to be uncertified but certification is required.
WARNING_SUSPECTED_INVALID_DOCUMENT_TYPEThe uploaded file may not be the requested document type.
WARNING_QUALITY_INSUFFICIENTImage quality is low: text is unclear, obscured, or partially unreadable.
WARNING_EXPIRED_DOCUMENTDocument appears to have expired.
WARNING_EXPIRING_DOCUMENTDocument is close to its expiry date.
WARNING_REQUIRED_FIELDS_MISSINGOne or more expected fields (e.g. name, ID number) could not be read.
WARNING_OTHERA generic warning not covered by the values above. See validationMessage.

Critical issues​

Critical issues usually cannot be accepted: the customer should re-upload.

ValueMeaning
CRITICAL_CERTAIN_INVALID_DOCUMENT_TYPEThe file is not the requested document type.
CRITICAL_DOCUMENT_UNREADABLEThe file could not be read at all (corrupt or fully obscured).
CRITICAL_OTHERA generic critical issue. See validationMessage for details.

The accompanying validationMessage field is a human-readable string appropriate to show the customer directly.

3. Decline reasons​

When a document is DECLINED, declinedReason indicates the category of issue.

ValueMeaning
NOT_CERTIFIEDDocument is missing required certification (e.g. notarisation).
INVALID_DOCUMENT_TYPEThe uploaded file is not the requested document type.
QUALITYDocument quality is too low to be usable.
OTHER_SEE_SUPPORTA reason not covered by the values above. declinedCustomerDisplayReason carries the reviewer's note to the customer.

The declinedCustomerDisplayReason field (when present) is a free-text explanation written by the reviewer and is safe to show the customer directly.

4. Acknowledging validation warnings​

When a document lands in VALIDATION_WARNINGS, the customer has two paths:

Option 1: Acknowledge. The customer reviews the warning and decides the document is fine as-is. The document moves to PENDING_REVIEW and continues through manual review.

Option 2: Re-upload. The customer uploads a corrected file. The document goes back to PENDING_VERIFICATION and automated validation runs again.

UX guidance​

We recommend presenting the warning message (validationMessage) to the end customer and offering both actions (e.g. "Acknowledge and proceed" next to "Re-upload").

Use severity as a hint for which action to emphasise:

  • For WARNING_* values, acknowledging is often fine: warnings can include false positives on valid documents (e.g. WARNING_QUALITY_INSUFFICIENT on a scan that reads fine to a human).
  • For CRITICAL_* values, re-uploading is almost always the right answer: the automated check is highly confident something is wrong. Acknowledging is still allowed, but discourage it in the UI.

5. Document category​

The documentCategory field tells you which review flow the document belongs to.

ValueMeaning
BUSINESS_DOCUMENTFile uploaded against the business itself during onboarding (e.g. trade license, memorandum of association).
PERSON_DOCUMENTFile uploaded against a related person during onboarding (e.g. passport, Emirates ID).
RFI_DOCUMENTFile attached to an RFI document request. Per-doc events for this category go through v1.rfi.document.*, not the onboarding family.