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
• For verification process see Verification workflow
• For webhook notifications see Webhook integration
• For API operations see Customer API

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 - 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:

{
  ...
  "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

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.

Resolving verification issues

When you receive verification issues, you can resolve them by updating the customer’s information using the PATCH /customers/{id} endpoint. 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} to submit corrections
5. Automatic restart - Verification process restarts automatically after the update

How to resolve verification issues

Use the PATCH /customers/{id} endpoint 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.