KYC Failure Reasons | Crossmint Docs

A rejected eligibility entry from the Get Identity Verification Status endpoint may include a failureReasons array with more detail about why the verification failed:

{
    "type": "offramp",
    "status": "rejected",
    "failureReasons": [
        {
            "code": "id-document-expired",
            "message": "The ID document provided is expired. Please submit a currently valid ID."
        }
    ]
}

Each entry in the array is a {code, message} object. code is a machine-readable identifier your integration can branch on; message is returned as-is by the API and can be shown directly to your users.

Not every rejected entry includes failureReasons. Its absence usually means the rejection was risk-based and not retriable.

Reason codes

The message column below is quoted verbatim from the API response, not paraphrased, since partners may display it as-is.

Code	Message
`id-document-expired`	The ID document provided is expired. Please submit a currently valid ID.
`id-document-unsupported-type`	This type of ID document is not supported. Please submit a different government-issued ID (e.g. passport or national ID).
`id-document-country-mismatch`	The ID document’s issuing country does not match the declared country. Please review the submitted information or provide an ID issued by the declared country.
`id-document-unreadable`	The document image could not be read. Please upload a clear, complete photo of the document (all corners visible, no glare).
`proof-of-address-outdated`	The proof of address provided is too old. Please submit one issued within the accepted period.
`proof-of-address-invalid`	The proof of address document could not be read or does not contain the required information. Please submit a valid, readable proof of address.
`source-of-wealth-outdated`	The source of wealth document provided is too old. Please submit one issued within the accepted period.
`source-of-wealth-invalid`	The source of wealth document could not be read or does not contain the required information. Please submit a valid, readable document.
`supporting-document-outdated`	The supporting document provided is too old. Please submit one issued within the accepted period.
`supporting-document-invalid`	The supporting document could not be read or does not contain the required information. Please submit a valid, readable document.
`selfie-failed`	The selfie could not be verified. Please retake it in good lighting, facing the camera directly, without face coverings.
`selfie-document-mismatch`	The selfie does not match the photo on the ID document. Please retake the selfie or provide the correct person’s ID.
`address-verification-failed`	The address provided could not be verified. Please review it or provide a previous address.
`age-requirement-not-met`	The user does not meet the minimum age requirement.
`unsupported-geo`	This service is not available in the user’s region.

code is an open enum: new values may be added over time. Treat an unrecognized code as a generic failure, and display the returned message rather than your own copy.

Introduction

User Identity

User Authentication

API Reference

Failure Reasons

Reason codes

​Reason codes

Reason codes