List customers

List customers

curl --request GET \
  --url https://api.fernhq.com/customers \
  --header 'Authorization: Bearer <token>'

{
  "customers": [
    {
      "customerId": "abc123",
      "customerStatus": "ACTIVE",
      "email": "[email protected]",
      "customerType": "INDIVIDUAL",
      "name": "John Doe",
      "verificationLink": "https://forms.fernhq.com/verify-customer/0423300f-ae6d-4e82-8afb-a3b430e22e29",
      "updatedAt": "2023-11-07T05:31:56Z",
      "organizationId": "8469411c-48c1-4e26-a032-44688be9cb4b",
      "availablePaymentMethods": [
        "ACH",
        "WIRE",
        "SEPA",
        "CA_INTERAC",
        "IN_NEFT_RTGS_IMPS",
        "ARBITRUM",
        "BASE",
        "ETHEREUM",
        "OPTIMISM",
        "POLYGON",
        "SOLANA"
      ],
      "verificationIssues": [
        {
          "code": "DOCUMENT_MISSING_BACK",
          "message": "Please upload clear photos of both the front and back of your ID.",
          "timestamp": "2023-10-01T12:00:00Z"
        }
      ]
    }
  ],
  "nextPageToken": "xyz"
}

GET

customers

List customers

curl --request GET \
  --url https://api.fernhq.com/customers \
  --header 'Authorization: Bearer <token>'

{
  "customers": [
    {
      "customerId": "abc123",
      "customerStatus": "ACTIVE",
      "email": "[email protected]",
      "customerType": "INDIVIDUAL",
      "name": "John Doe",
      "verificationLink": "https://forms.fernhq.com/verify-customer/0423300f-ae6d-4e82-8afb-a3b430e22e29",
      "updatedAt": "2023-11-07T05:31:56Z",
      "organizationId": "8469411c-48c1-4e26-a032-44688be9cb4b",
      "availablePaymentMethods": [
        "ACH",
        "WIRE",
        "SEPA",
        "CA_INTERAC",
        "IN_NEFT_RTGS_IMPS",
        "ARBITRUM",
        "BASE",
        "ETHEREUM",
        "OPTIMISM",
        "POLYGON",
        "SOLANA"
      ],
      "verificationIssues": [
        {
          "code": "DOCUMENT_MISSING_BACK",
          "message": "Please upload clear photos of both the front and back of your ID.",
          "timestamp": "2023-10-01T12:00:00Z"
        }
      ]
    }
  ],
  "nextPageToken": "xyz"
}

Authorizations

Authorization

string

header

required

To authenticate server-side requests

Query Parameters

pageToken

string

Token for forward pagination

pageSize

integer

default:10

Number of items per page (default: 10, max: 100)

Required range: x >= 1

organizationId

string<uuid>

Organization ID to filter customers

Response

Response schema for listing customers

customers

Customers · object[]

Retrieved customers

Show child attributes

customers.customerId

string<uuid>

required

Unique identifier of the customer

Example:

"abc123"

customers.customerStatus

enum<string>

required

Current status of the customer

Available options:

CREATED,

UNDER_REVIEW,

NEEDS_ADDITIONAL_INFORMATION,

ACTIVE,

REJECTED,

DEACTIVATED

Example:

"ACTIVE"

customers.email

string<email>

required

Email of the customer

Example:

"[email protected]"

customers.customerType

enum<string>

required

The type of customer - either individual or business

Available options:

INDIVIDUAL,

BUSINESS

customers.name

string

required

Full name of the customer or business

Example:

"John Doe"

customers.verificationLink

string<uri>

required

URL for KYC/KYB verification process

Example:

"https://forms.fernhq.com/verify-customer/0423300f-ae6d-4e82-8afb-a3b430e22e29"

customers.updatedAt

string<date-time>

required

Timestamp of the last status update

customers.organizationId

string

required

Organization identifier

Example:

"8469411c-48c1-4e26-a032-44688be9cb4b"

customers.availablePaymentMethods

string[]

Available payment methods for the customer

Example:

[
  "ACH",
  "WIRE",
  "SEPA",
  "CA_INTERAC",
  "IN_NEFT_RTGS_IMPS",
  "ARBITRUM",
  "BASE",
  "ETHEREUM",
  "OPTIMISM",
  "POLYGON",
  "SOLANA"
]

customers.verificationIssues

Verification Issue · object[]

Current verification issues blocking customer approval. Only present for customers in NEEDS_ADDITIONAL_INFORMATION, UNDER_REVIEW, or REJECTED status.

Show child attributes

customers.verificationIssues.code

enum<string>

required

Error code for programmatic handling. See documentation for complete list of error codes and their meanings.

Available options:

DOCUMENT_MISSING_BACK,

DOCUMENT_MISSING_FRONT,

DOCUMENT_NUMBER_UNREADABLE,

DOC_QUALITY_POOR,

NAME_UNREADABLE,

NO_FACE_PORTRAIT,

MISSING_ID_DETAILS,

DOCUMENT_EXPIRED,

NO_GOVERNMENT_ID,

INCORRECT_ID_TYPE,

ID_REQUIRES_ADDITIONAL_VERIFICATION,

ID_COUNTRY_MISMATCH,

GOVERNMENT_ID_VERIFICATION_FAILED,

DATABASE_CHECK_FAILED_ON_NAME_FIRST,

DATABASE_CHECK_FAILED_ON_NAME_LAST,

DATABASE_CHECK_FAILED_ON_SOCIAL_SECURITY_NUMBER,

DATABASE_CHECK_FAILED_ON_STREET_NAME,

DATABASE_CHECK_FAILED_ON_CITY,

DATABASE_CHECK_FAILED_ON_SUBDIVISION,

DATABASE_CHECK_FAILED_ON_POSTAL_CODE,

ADDRESS_TOO_SHORT,

INCONSISTENT_INFORMATION,

INCONSISTENT_DETAILS,

INVALID_PARAMETERS,

VERIFICATION_ISSUE,

API_ERROR,

NAME_VERIFICATION_FAILED,

ID_TYPE_MISMATCH,

BIRTH_DATE_MISMATCH,

ID_DATA_MISMATCH,

ID_NUMBER_NOT_VERIFIED,

MISSING_NAME,

DOCUMENT_NOT_FOUND,

UNREADABLE_DOCUMENT,

UNRECOGNIZED_DOCUMENT,

MISSING_DOCUMENT_NUMBER,

MISSING_ISSUE_DATE,

MISSING_EXPIRY_DATE,

DOCUMENT_FRONT_OR_BACK_MISSING,

DOCUMENT_BACK_MISSING,

ID_NOT_ALLOWED,

FACE_PREVIOUSLY_ONBOARDED,

ID_PREVIOUSLY_SEEN,

ID_PREVIOUSLY_ATTEMPTED,

SUSPICIOUS_USER_BEHAVIOUR,

SCREEN_DETECTED,

AML_MATCH,

ADDRESS_DOCUMENT_DOCUMENT_NOT_ISSUED_RECENTLY,

ADDRESS_DOCUMENT_MISSING_NAME,

ADDRESS_DOCUMENT_MISSING_ADDRESS,

ADDRESS_DOCUMENT_UNRECOGNIZED_DOCUMENT,

ADDRESS_DOCUMENT_NAME_VERIFICATION_FAILED,

DATABASE_LOOKUP_ISSUE,

THIRD_PARTY_API_FAILED,

API_DATA_REQUIREMENTS_NOT_MET,

WORKFLOW_CONFIG_ERROR,

ID_WARNING,

AML_WARNING,

FRAUD_WARNING,

ADDITIONAL_WARNING

Example:

"DOCUMENT_MISSING_BACK"

customers.verificationIssues.message

string

required

Human-readable, actionable explanation

Example:

"Please upload clear photos of both the front and back of your ID."

customers.verificationIssues.timestamp

string<date-time>

required

When the issue was detected

Example:

"2023-10-01T12:00:00Z"

Example:

[
  {
    "code": "DOCUMENT_MISSING_BACK",
    "message": "Please upload clear photos of both the front and back of your ID.",
    "timestamp": "2023-10-01T12:00:00Z"
  }
]

nextPageToken

string

Page token to use to fetch next page

Example:

"xyz"

Create customer

⌘I

Customers

Transactions

Quotes

Payment Accounts

Automation Rules

Webhooks

Authorizations

Query Parameters

Response