> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fernhq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Verification Issues

## Overview

When customers require additional information during verification, Fern provides detailed verification issues to help you understand what needs to be corrected. These issues are returned when a customer's status changes to `NEEDS_ADDITIONAL_INFORMATION`, giving you specific guidance on how to resolve verification problems.

Verification issues help you:

* Understand exactly what information needs to be corrected
* Provide clear guidance to your customers
* Reduce verification turnaround time
* Improve the customer verification experience

**Related guides:**

* For verification statuses see [Customer statuses](/docs/create-and-verify-customers/customer-statuses)
* For verification process see [Verification workflow](/docs/create-and-verify-customers/verification-workflow)
* For webhook notifications see [Webhook integration](/docs/webhooks/overview)
* For API operations see [Customer API](/api-reference/customers)

## When verification issues appear

Verification issues are included in API responses when a customer's status is `NEEDS_ADDITIONAL_INFORMATION`, `UNDER_REVIEW`, or `REJECTED`. You can access these issues through:

* **[GET `/customers/{id}` endpoint](/api-reference/customers/get-customer)** - Issues are included in the response
* **`customer.updated` webhook** - Issues are included in the webhook payload

The `verificationIssues` array provides actionable information to help customers resolve verification problems and complete their verification successfully.

## Verification issues schema

Each verification issue contains the following information:

```json theme={null}
{
  ...
  "customerStatus": "NEEDS_ADDITIONAL_INFORMATION",
  "verificationIssues": [
    {
      "code": "DOCUMENT_EXPIRED",
      "message": "The provided document has expired. Please upload a valid ID.",
      "timestamp": "2023-10-01T12:00:00Z"
    },
    {
      "code": "DOC_QUALITY_POOR",
      "message": "We couldn't verify your ID. Please upload clear, complete photos of your ID.",
      "timestamp": "2023-10-01T12:00:00Z"
    }
  ]
}
```

**Schema properties:**

* `code`: Standardized error code identifying the specific issue
* `message`: User-friendly description explaining what needs to be corrected
* `timestamp`: When the issue was detected

## Common verification issues

The table below shows some of the most common verification issues and their meanings:

| Issue Code | Description | Resolution |
| - | - | - |
| `DOCUMENT_MISSING_BACK` | We couldn't verify your ID. Please upload clear, complete photos of your ID. | Upload clear, valid documents as specified |
| `DOCUMENT_MISSING_FRONT` | We couldn't verify your ID. Please upload clear, complete photos of your ID. | Upload clear, valid documents as specified |
| `DOCUMENT_NUMBER_UNREADABLE` | We couldn't verify your ID. Please upload clear, complete photos of your ID. | Upload clear, valid documents as specified |
| `DOC_QUALITY_POOR` | We couldn't verify your ID. Please upload clear, complete photos of your ID. | Upload clear, valid documents as specified |
| `NAME_UNREADABLE` | We couldn't verify your ID. Please upload clear, complete photos of your ID. | Upload clear, valid documents as specified |
| `NO_FACE_PORTRAIT` | We couldn't verify your ID. Please upload clear, complete photos of your ID. | Upload clear, valid documents as specified |
| `MISSING_ID_DETAILS` | We couldn't verify your ID. Please upload clear, complete photos of your ID. | Upload clear, valid documents as specified |
| `DOCUMENT_EXPIRED` | The provided document has expired. Please upload a valid ID. | Upload clear, valid documents as specified |
| `NO_GOVERNMENT_ID` | No government ID found in submission. Please upload your ID. | Upload clear, valid documents as specified |
| `INCORRECT_ID_TYPE` | Incorrect ID type selected. Please select the correct type and resubmit. | Review your submission or contact support for assistance |
| `ID_REQUIRES_ADDITIONAL_VERIFICATION` | Additional verification is required for your ID. Please provide supplementary proof of identity and address. | Provide complete, valid address information |
| `ID_COUNTRY_MISMATCH` | The country of your ID doesn't match the country you selected. | Review your submission or contact support for assistance |
| `GOVERNMENT_ID_VERIFICATION_FAILED` | We couldn't verify your government ID. Please try again or use a different ID. | Review your submission or contact support for assistance |
| `DATABASE_CHECK_FAILED_ON_NAME_FIRST` | We couldn't verify the information provided with our records. | Review your submission or contact support for assistance |
| `DATABASE_CHECK_FAILED_ON_NAME_LAST` | We couldn't verify the information provided with our records. | Review your submission or contact support for assistance |
| `DATABASE_CHECK_FAILED_ON_SOCIAL_SECURITY_NUMBER` | We couldn't verify the information provided with our records. | Review your submission or contact support for assistance |
| `DATABASE_CHECK_FAILED_ON_STREET_NAME` | We couldn't verify your address with our records. | Provide complete, valid address information |
| `DATABASE_CHECK_FAILED_ON_CITY` | We couldn't verify your address with our records. | Provide complete, valid address information |
| `DATABASE_CHECK_FAILED_ON_SUBDIVISION` | We couldn't verify your address with our records. | Provide complete, valid address information |
| `DATABASE_CHECK_FAILED_ON_POSTAL_CODE` | We couldn't verify your address with our records. | Provide complete, valid address information |
| `ADDRESS_TOO_SHORT` | The address you provided is too short. Please enter your complete address. | Provide complete, valid address information |
| `INCONSISTENT_INFORMATION` | Inconsistent or incomplete information. Please review your details. | Review your submission or contact support for assistance |
| `INCONSISTENT_DETAILS` | Your information could not be verified due to inconsistent details. | Review your submission or contact support for assistance |
| `INVALID_PARAMETERS` | Please review and correct the information you provided. | Review and correct the information as indicated |
| `VERIFICATION_ISSUE` | A verification issue was detected. Please review your submission. | Review your submission or contact support for assistance |
| `API_ERROR` | An error occurred during verification. Please try again. | Review your submission or contact support for assistance |
| `NAME_VERIFICATION_FAILED` | The name on your document could not be verified. Please ensure your name matches exactly. | Review your submission or contact support for assistance |
| `ID_TYPE_MISMATCH` | The ID type doesn't match the expected type. Please select the correct ID type. | Review your submission or contact support for assistance |
| `BIRTH_DATE_MISMATCH` | The date of birth on your document doesn't match your provided information. | Review your submission or contact support for assistance |
| `ID_DATA_MISMATCH` | The information on your ID doesn't match the provided details. Please review and correct. | Review and correct the information as indicated |
| `ID_NUMBER_NOT_VERIFIED` | Your ID number could not be verified. Please check and resubmit. | Review your submission or contact support for assistance |
| `MISSING_NAME` | The name is missing from your document. Please provide a document with your full name. | Review your submission or contact support for assistance |
| `DOCUMENT_NOT_FOUND` | No document was found in your submission. Please upload your ID document. | Upload clear, valid documents as specified |
| `UNREADABLE_DOCUMENT` | Your document is unreadable. Please upload a clearer image. | Upload clear, valid documents as specified |
| `UNRECOGNIZED_DOCUMENT` | Your document type is not recognized. Please upload a valid government-issued ID. | Upload clear, valid documents as specified |
| `MISSING_DOCUMENT_NUMBER` | The document number is missing or unreadable. Please upload a clearer image. | Upload clear, valid documents as specified |
| `MISSING_ISSUE_DATE` | The issue date is missing from your document. Please upload a complete document. | Upload clear, valid documents as specified |
| `MISSING_EXPIRY_DATE` | The expiry date is missing from your document. Please upload a complete document. | Upload clear, valid documents as specified |
| `DOCUMENT_FRONT_OR_BACK_MISSING` | Please upload both the front and back of your ID document. | Upload clear, valid documents as specified |
| `DOCUMENT_BACK_MISSING` | The back of your document is missing. Please upload both sides. | Upload clear, valid documents as specified |
| `ID_NOT_ALLOWED` | This ID type is not accepted for verification. Please use a different form of ID. | Review your submission or contact support for assistance |
| `FACE_PREVIOUSLY_ONBOARDED` | This identity has already been registered. Please contact support if you believe this is an error. | Contact support for assistance |
| `ID_PREVIOUSLY_SEEN` | This ID has already been used for verification. Please contact support if you believe this is an error. | Contact support for assistance |
| `ID_PREVIOUSLY_ATTEMPTED` | This ID was previously submitted. Please contact support if you need assistance. | Contact support for assistance |
| `SUSPICIOUS_USER_BEHAVIOUR` | Unusual activity was detected during verification. Please try again or contact support. | Contact support for assistance |
| `SCREEN_DETECTED` | Please use a physical document rather than a photo of a screen. | Review your submission or contact support for assistance |
| `AML_MATCH` | Additional compliance review is required. Our team will be in touch. | Review your submission or contact support for assistance |
| `ADDRESS_DOCUMENT_DOCUMENT_NOT_ISSUED_RECENTLY` | Your address document is too old. Please provide a document issued within the last 3 months. | Provide complete, valid address information |
| `ADDRESS_DOCUMENT_MISSING_NAME` | Your address document is missing your name. Please provide a document showing your full name. | Provide complete, valid address information |
| `ADDRESS_DOCUMENT_MISSING_ADDRESS` | Your address document is missing the address. Please provide a complete document. | Provide complete, valid address information |
| `ADDRESS_DOCUMENT_UNRECOGNIZED_DOCUMENT` | Your address document is not recognized. Please provide a utility bill, bank statement, or government letter. | Provide complete, valid address information |
| `ADDRESS_DOCUMENT_NAME_VERIFICATION_FAILED` | The name on your address document doesn't match. Please ensure names match across all documents. | Provide complete, valid address information |
| `DATABASE_LOOKUP_ISSUE` | We encountered an issue verifying your information. Please try again. | Review your submission or contact support for assistance |
| `THIRD_PARTY_API_FAILED` | Verification service is temporarily unavailable. Please try again later. | Review your submission or contact support for assistance |
| `API_DATA_REQUIREMENTS_NOT_MET` | Some required information is missing. Please complete all required fields. | Review your submission or contact support for assistance |
| `WORKFLOW_CONFIG_ERROR` | An error occurred during verification. Please try again or contact support. | Contact support for assistance |
| `ID_WARNING` | An issue was detected with your ID document. Please review and resubmit. | Review your submission or contact support for assistance |
| `AML_WARNING` | Additional review is required to complete verification. | Review your submission or contact support for assistance |
| `FRAUD_WARNING` | Additional verification is required. Please contact support if this persists. | Contact support for assistance |
| `ADDITIONAL_WARNING` | Additional information is required to complete verification. | Review your submission or contact support for assistance |

<Note>
  If you receive a `VERIFICATION_ISSUE` code, this indicates our system detected an issue but couldn't provide a specific error code. Please contact support for further investigation and assistance resolving the verification problem.
</Note>

## Resolving verification issues

When you receive verification issues, you can resolve them by updating the customer's information using the [PATCH `/customers/{id}` endpoint](/api-reference/customers/update-customer-kyc-data). This allows you to correct any problematic data and automatically restart the verification process.

**Resolution workflow:**

1. **Parse the issues array** - Extract the specific codes and messages from `verificationIssues`
2. **Display clear guidance** - Show user-friendly messages to your customers
3. **Collect corrected information** - Allow customers to provide updated data or documents
4. **Update customer data** - Use [PATCH `/customers/{id}`](/api-reference/customers/update-customer-kyc-data) to submit corrections
5. **Automatic restart** - Verification process restarts automatically after the update

## How to resolve verification issues

Use the [PATCH `/customers/{id}` endpoint](/api-reference/customers/update-customer-kyc-data) to update customer information and resolve verification issues. The endpoint accepts the same fields as customer creation, allowing you to correct any problematic data.

**Common resolution actions:**

* **Document issues**: Upload new, higher-quality document images
* **Information mismatches**: Correct name, address, or other personal details
* **Missing data**: Provide additional required information
* **Expired documents**: Upload current, valid identification

Once you update the customer data, the verification process automatically restarts. The customer status will change from `NEEDS_ADDITIONAL_INFORMATION` to `UNDER_REVIEW`, and you'll receive a new `customer.updated` webhook notification.

<Hint>
  When customers update their information to resolve verification issues, the verification process automatically restarts. You'll receive another `customer.updated` webhook when the status changes.
</Hint>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.