> ## 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.

# Customer Statuses

## Overview

The customer verification engine manages customer verification through a well-defined state machine with six statuses. Understanding these statuses helps you build better integrations and provide clear user experiences. Each status represents a distinct phase in the verification lifecycle, from initial creation through final approval or rejection.

Every customer has a `customerStatus` field that indicates their current verification status. This status determines what actions you can perform and what your customer can access on your platform.

**Related guides:**

* 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)

## Status overview

The six possible statuses represent different phases of the verification lifecycle:

| Status                         | Description                              | Can Update Data? |
| ------------------------------ | ---------------------------------------- | ---------------- |
| `CREATED`                      | Initial status, verification not started | Yes              |
| `UNDER_REVIEW`                 | Verification in progress                 | No               |
| `NEEDS_ADDITIONAL_INFORMATION` | Additional information required (RFI)    | Yes              |
| `ACTIVE`                       | Verification approved, customer verified | No               |
| `REJECTED`                     | Verification permanently failed          | No               |
| `DEACTIVATED`                  | Account administratively deactivated     | No               |

## Status definitions

### CREATED

**What it means:** Customer profile has been created but verification has not started yet.

**Characteristics:**

* No verification process initiated
* Customer data collection phase
* All fields can be freely updated
* Default status for new customers

**Developer actions:**

* Use PATCH customers/:id to update customer data
* Add or update KYC/KYB information
* Upload identity documents
* Prepare customer for verification submission

**When it transitions:**

* Customer data is submitted and verification is automatically initiated
* Status changes to `UNDER_REVIEW` when verification begins

### UNDER\_REVIEW

**What it means:** Customer verification is actively being processed.

**Characteristics:**

* Verification submission has been sent to providers
* Identity and compliance checks are in progress
* Customer data is locked to maintain submission integrity
* No action required from developer (monitoring only)

**Developer actions:**

* Monitor status via GET customers/:id
* Set up webhooks to receive status change notifications
* Display "Verification in progress" status to user
* Check `verificationIssues` array if present for any issues detected during review
* Cannot update customer data (PATCH will return error)

**When it transitions:**

* **To `ACTIVE`:** All verification checks pass
* **To `NEEDS_ADDITIONAL_INFORMATION`:** Provider requests more information

**Typical duration:** Less than 10 minutes for individuals (1 to 3 business days if manual intervention is required), 4-7 business days for businesses

<Hint>
  You cannot update customer data while verification is in progress. Wait for the status to transition or monitor via webhooks.
</Hint>

### NEEDS\_ADDITIONAL\_INFORMATION

**What it means:** The verification provider requires additional information, documents, or clarifications (Request for Information - RFI).

**Characteristics:**

* Verification process is reset as critical details require correcting
* Specific issues or missing data have been flagged
* Customer must take action to proceed

**Developer actions:**

* Use PATCH customers/:id to update customer data
* Upload additional documents
* Review webhook payload for specific requirements
* Check `verificationIssues` array for detailed guidance
* After updates, verification automatically re-submits

**Common reasons for RFI:**

* Missing or expired identity documents
* Unclear business ownership structure
* Insufficient address verification
* Ambiguous beneficial owner information
* Document quality issues (blurry images, partial visibility)

**Recovery process:**

1. **Receive RFI notification** via webhook or API polling
2. **Review requirements** indicated in the response
3. **Update customer data** using PATCH endpoint
4. **Verification automatically re-initiates** after update
5. **Status transitions to UNDER\_REVIEW** when resubmitted

<Hint>
  This is a recoverable status. Most RFI cases can be resolved by providing the requested information.
</Hint>

### ACTIVE

**What it means:** Customer has successfully completed verification and is approved for platform use.

**Characteristics:**

* All verification checks passed
* Customer is fully verified
* Can perform transactions and operations
* Full platform access granted

**Developer actions:**

* Enable all platform features for the customer
* Allow transaction creation
* Grant access to payment operations
* Display verification success status
* Cannot update core customer data (contact support for changes)

**When it transitions:**

* **To `DEACTIVATED`:** Account is administratively closed
* **To `REJECTED`:** Post-approval compliance issues detected (rare)

<Hint>
  Customers in ACTIVE status have passed all compliance and identity checks. You can proceed with full platform functionality.
</Hint>

### REJECTED

**What it means:** Customer verification has permanently failed and cannot be approved.

**Characteristics:**

* Verification process ended negatively
* Customer cannot use platform services
* Typically due to compliance or identity verification issues
* Account closure or manual review may be required

**Developer actions:**

* Display rejection status to customer
* Check `verificationIssues` array for specific rejection reasons
* Provide support contact information
* Log rejection for compliance records
* Cannot update customer data
* Cannot re-initiate verification (contact support)

**Common reasons:**

* Identity documents could not be verified
* Compliance concerns or sanctions list matches
* Fraudulent information detected
* Regulatory restrictions
* Customer-requested cancellation during verification

<Hint>
  REJECTED is typically a permanent status. Contact support if you believe this was an error or if circumstances have changed.
</Hint>

### DEACTIVATED

**What it means:** Customer account has been administratively deactivated.

**Characteristics:**

* Account is inactive by administrative action
* Not related to verification failure
* May be temporary or permanent
* Can potentially be reactivated (contact support)

**Developer actions:**

* Display deactivation status
* Prevent new transactions
* Allow view-only access to historical data
* Provide reactivation contact information
* Cannot update customer data
* Cannot create new transactions

**Common reasons:**

* Customer requested account closure
* Compliance hold or investigation
* Regulatory requirement
* Inactivity-based closure
* Terms of service violation

## Status transition diagram

```mermaid theme={null}
flowchart TD
     A[CREATED] --> |Submit Data,
     Verification Starts| B[UNDER REVIEW]
     B -->|All Checks Pass| C[ACTIVE]

     C -->|Admin Action| D[DEACTIVATED]
     C -->|Compliance Issue| E[REJECTED]
     B -->|Needs more Information| F[NEEDS MORE INFORMATION]

     F -->|Update Data| B
     F -->|Irrecoverable| E
```

### Transition summary

| From                           | To                             | Trigger                     | Automatic? |
| ------------------------------ | ------------------------------ | --------------------------- | ---------- |
| CREATED                        | UNDER\_REVIEW                  | Verification submission     | Yes        |
| UNDER\_REVIEW                  | ACTIVE                         | All checks passed           | Yes        |
| UNDER\_REVIEW                  | NEEDS\_ADDITIONAL\_INFORMATION | Provider requests more info | Yes        |
| NEEDS\_ADDITIONAL\_INFORMATION | UNDER\_REVIEW                  | Customer updates data       | Yes        |
| NEEDS\_ADDITIONAL\_INFORMATION | REJECTED                       | Irrecoverable failure       | Manual     |
| ACTIVE                         | DEACTIVATED                    | Administrative action       | Manual     |
| ACTIVE                         | REJECTED                       | Post-approval issues        | Manual     |

## Testing customer statuses

### Test checklist

Test your integration handles all statuses:

* CREATED - Show profile completion UI
* UNDER\_REVIEW - Show waiting/progress indicator
* NEEDS\_ADDITIONAL\_INFORMATION - Show RFI resolution flow
* ACTIVE - Enable full platform features
* REJECTED - Show support contact and disable features
* DEACTIVATED - Show reactivation contact and disable transactions

## Frequently asked questions

### How long does verification take?

* **Individuals (KYC):** Typically under 10 minutes
* **Businesses (KYB):** Typically 4-7 business days
* Complex cases may take longer

### Can I expedite verification?

Contact your account manager to discuss expedited processing options for your use case.

### What happens if verification fails?

If verification transitions to `NEEDS_ADDITIONAL_INFORMATION`, you can provide the requested information and resubmit. If it transitions to `REJECTED`, contact support.

### Can I update customer data after approval?

Once a customer is `ACTIVE`, profile data cannot be updated via the API. Contact support for approved customer data changes.

### How do I handle RFI situations?

1. Monitor for `NEEDS_ADDITIONAL_INFORMATION` status
2. Review webhook payload or API response for specific requirements
3. Update customer data with requested information
4. System automatically re-submits for verification

### What is the difference between REJECTED and DEACTIVATED?

* `REJECTED`: Verification failed due to identity or compliance issues
* `DEACTIVATED`: Administrative account closure unrelated to verification failure