Document statuses

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

• List account documents
• Get person
• Onboarding document webhooks

---

1. Document status

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

Status	Description
NOT_SUBMITTED	No file has been uploaded against this document requirement yet.
PENDING_VERIFICATION	File has been uploaded and is queued for automated validation. Transient — usually resolves within seconds.
VALIDATION_WARNINGS	Automated validation flagged concerns. The customer must either acknowledge the warning and continue, or re-upload a corrected file. See Acknowledging validation warnings below.
PENDING_REVIEW	Document is awaiting review by Hubpay.
APPROVED	Document accepted. No further action required.
DECLINED	Document 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.

Value	Meaning
WARNING_NOT_CERTIFIED	Document appears to be uncertified but certification is required.
WARNING_SUSPECTED_INVALID_DOCUMENT_TYPE	The uploaded file may not be the requested document type.
WARNING_QUALITY_INSUFFICIENT	Image quality is low — text is unclear, obscured, or partially unreadable.
WARNING_EXPIRED_DOCUMENT	Document appears to have expired.
WARNING_EXPIRING_DOCUMENT	Document is close to its expiry date.
WARNING_REQUIRED_FIELDS_MISSING	One or more expected fields (e.g. name, ID number) could not be read.
WARNING_OTHER	A generic warning not covered by the values above. See validationMessage.

Critical issues

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

Value	Meaning
CRITICAL_CERTAIN_INVALID_DOCUMENT_TYPE	The file is not the requested document type.
CRITICAL_DOCUMENT_UNREADABLE	The file could not be read at all (corrupt or fully obscured).
CRITICAL_OTHER	A 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.

Value	Meaning
NOT_CERTIFIED	Document is missing required certification (e.g. notarisation).
INVALID_DOCUMENT_TYPE	The uploaded file is not the requested document type.
QUALITY	Document quality is too low to be usable.
OTHER_SEE_SUPPORT	A 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.

---