Customers

Use this API to create, update, retrieve, and verify customers.

Fern supports two ways to verify your customers:

  • Hosted KYC/KYB link (default): Share a link for your customer to complete verification in Fern's UI.

  • API-based KYC submission: Submit all required KYC data directly via API using the kycData field. This enables a fully branded onboarding experience in your own UI.

Create customer

post

Upon successful customer creation, a hosted KYC link requesting the required information to fill in will be generated. This may be distributed to your end-user for completion, or it can be completed on the customer's behalf by your team.

Authorizations
Body

Request payload for creating a new customer account with optional KYC data

customerTypestring · enumRequired

The type of customer - either individual or business

Possible values:
firstNamestringOptional

First name of the customer

Example: John
lastNamestringOptional

Last name of the customer

Example: Doe
businessNamestringOptional

Name of the business

Example: John Doe Inc.
emailstring · emailRequired

Email of the customer

Example: [email protected]
Responses
201

Response schema for a customer retrieval request

application/json
post
POST /customers HTTP/1.1
Host: api.fernhq.com
Authorization: Bearer API Key
Content-Type: application/json
Accept: */*
Content-Length: 3713

{
  "customerType": "INDIVIDUAL",
  "firstName": "John",
  "lastName": "Doe",
  "businessName": "John Doe Inc.",
  "email": "[email protected]",
  "kycData": {
    "legalFirstName": "John",
    "legalMiddleName": "Michael",
    "legalLastName": "Doe",
    "phoneNumber": "+12223334444",
    "dateOfBirth": "1990-01-15",
    "address": {
      "streetLine1": "123 Main St",
      "streetLine2": "Apt 4B",
      "city": "New York",
      "stateRegionProvince": "NY",
      "postalCode": "10001",
      "countryCode": "US",
      "locale": "en-US"
    },
    "nationalIdIssuingCountry": "US",
    "nationalIdType": "ssn",
    "nationalIdNumber": "123-45-6789",
    "nationality": "US",
    "employmentStatus": "EMPLOYED",
    "mostRecentOccupation": "132011",
    "sourceOfFunds": "SALARY",
    "accountPurpose": "PERSONAL_EXPENSES",
    "accountPurposeOther": "Real estate transactions",
    "expectedMonthlyPaymentsUsd": "BETWEEN_10000_49999",
    "isIntermediary": false,
    "documents": [
      {
        "type": "GOVERNMENT_ID",
        "subtype": "NATIONAL_ID",
        "countryCode": "US",
        "documentIdNumber": "123456789",
        "issuanceDate": "2020-01-15",
        "expirationDate": "2030-01-15",
        "frontIdImage": "text",
        "backIdImage": "text",
        "proofOfAddressImage": "text",
        "description": "Electric bill from January 2024"
      }
    ]
  },
  "kybData": {
    "businessInfo": {
      "legalBusinessName": "Acme Corporation Inc.",
      "dbaName": "Acme Corp",
      "businessType": "CORPORATION",
      "businessIndustries": "611519",
      "businessDescription": "Software development and technology consulting services",
      "website": "https://www.acmecorp.com",
      "otherLinks": [
        "https://linkedin.com/company/acme",
        "@acmetech"
      ],
      "formationDate": "2020-01-15",
      "registrationCountry": "DE",
      "isDao": false
    },
    "businessRegisteredAddress": {
      "streetLine1": "123 Main St",
      "streetLine2": "Apt 4B",
      "city": "New York",
      "stateRegionProvince": "NY",
      "postalCode": "10001",
      "countryCode": "US",
      "locale": "en-US"
    },
    "businessOperatingAddress": {
      "streetLine1": "123 Main St",
      "streetLine2": "Apt 4B",
      "city": "New York",
      "stateRegionProvince": "NY",
      "postalCode": "10001",
      "countryCode": "US",
      "locale": "en-US"
    },
    "businessRegistrationNumber": "text",
    "businessDocuments": [
      {
        "type": "ARTICLES_OF_INCORPORATION",
        "description": "Articles of Incorporation filed in Delaware",
        "documentImage": "text"
      }
    ],
    "associatedPersons": [
      {
        "legalFirstName": "Jane",
        "legalMiddleName": "Marie",
        "legalLastName": "Smith",
        "email": "[email protected]",
        "phoneNumber": "+14155551234",
        "dateOfBirth": "1985-06-20",
        "address": {
          "streetLine1": "123 Main St",
          "streetLine2": "Apt 4B",
          "city": "New York",
          "stateRegionProvince": "NY",
          "postalCode": "10001",
          "countryCode": "US",
          "locale": "en-US"
        },
        "ownershipPercentage": 0.25,
        "title": "Chief Technology Officer",
        "isControlPerson": true,
        "isSigner": true,
        "isDirector": false,
        "nationalIdIssuingCountry": "US",
        "nationalIdType": "ssn",
        "nationalIdNumber": "123-45-6789",
        "nationality": "US",
        "documents": [
          {
            "type": "GOVERNMENT_ID",
            "subtype": "NATIONAL_ID",
            "countryCode": "US",
            "documentIdNumber": "123456789",
            "issuanceDate": "2020-01-15",
            "expirationDate": "2030-01-15",
            "frontIdImage": "text",
            "backIdImage": "text",
            "proofOfAddressImage": "text",
            "description": "Electric bill from January 2024"
          }
        ]
      }
    ],
    "sourceOfFunds": "SALE_OF_GOODS_AND_SERVICES",
    "sourceOfFundsDescription": "Revenue from software licensing and consulting services",
    "accountPurpose": "CHARITABLE_DONATIONS",
    "accountPurposeOther": "International trade financing",
    "expectedMonthlyVolumeUsd": "LESS_THAN_10000",
    "estimatedAnnualRevenueUsd": "LESS_THAN_100000",
    "conductsMoneyServices": false,
    "conductsMoneyServicesDescription": "International wire transfers for clients",
    "conductsMoneyServicesThroughFern": false,
    "operatesInProhibitedCountries": false,
    "complianceScreeningDescription": "We screen all clients against OFAC and international sanctions lists",
    "highRiskActivities": [
      "ADULT_ENTERTAINMENT",
      "FOREIGN_EXCHANGE_OR_BROKERAGE"
    ],
    "highRiskActivitiesExplanation": "We operate an adult entertainment platform with proper licensing and compliance measures in place."
  }
}
{
  "customerId": "03b7030f-6da1-4d76-9352-cdebd82112c8",
  "customerStatus": "ACTIVE",
  "customerType": "INDIVIDUAL",
  "name": "John Doe",
  "email": "[email protected]",
  "kycLink": "https://app.fernhq.com/verify-customer/03b7030f-6da1-4d76-9352-cdebd82112c8",
  "verificationLink": "https://app.fernhq.com/verify-customer/03b7030f-6da1-4d76-9352-cdebd82112c8",
  "updatedAt": "2023-10-01T12:00:00Z",
  "organizationId": "8469411c-48c1-4e26-a032-44688be9cb4b"
}

Get customer

get

Get details about a customer

Authorizations
Path parameters
customerIdstring · uuidRequired

Unique identifier of the customer

Example: 03b7030f-6da1-4d76-9352-cdebd82112c8
Responses
200

Response schema for a customer retrieval request

application/json
get
GET /customers/{customerId} HTTP/1.1
Host: api.fernhq.com
Authorization: Bearer API Key
Accept: */*

{
  "customerId": "03b7030f-6da1-4d76-9352-cdebd82112c8",
  "customerStatus": "ACTIVE",
  "customerType": "INDIVIDUAL",
  "name": "John Doe",
  "email": "[email protected]",
  "kycLink": "https://app.fernhq.com/verify-customer/03b7030f-6da1-4d76-9352-cdebd82112c8",
  "verificationLink": "https://app.fernhq.com/verify-customer/03b7030f-6da1-4d76-9352-cdebd82112c8",
  "updatedAt": "2023-10-01T12:00:00Z",
  "organizationId": "8469411c-48c1-4e26-a032-44688be9cb4b"
}

List customers

get

List all customers with cursor-based pagination

Authorizations
Query parameters
pageTokenstringOptional

Token for forward pagination

Example: ZDE4YmViMjYtYjRkMS00N2VlLThlNWQtMGQzOTA1ZjIwMGM3
pageSizeinteger · min: 1Optional

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

Default: 10Example: 10
organizationIdstring · uuidOptional

Organization ID to filter customers

Example: 77863f21-a92a-4919-bd83-bded799d938b
Responses
200

Default Response

application/json
get
GET /customers HTTP/1.1
Host: api.fernhq.com
Authorization: Bearer API Key
Accept: */*

{
  "customers": [
    {
      "customerId": "03b7030f-6da1-4d76-9352-cdebd82112c8",
      "customerStatus": "ACTIVE",
      "customerType": "INDIVIDUAL",
      "name": "John Doe",
      "email": "[email protected]",
      "kycLink": "https://app.fernhq.com/verify-customer/03b7030f-6da1-4d76-9352-cdebd82112c8",
      "verificationLink": "https://app.fernhq.com/verify-customer/03b7030f-6da1-4d76-9352-cdebd82112c8",
      "updatedAt": "2023-10-01T12:00:00Z",
      "organizationId": "8469411c-48c1-4e26-a032-44688be9cb4b"
    }
  ],
  "nextPageToken": "xyz"
}

Update customer KYC data

patch

Update specific fields in a customer's KYC data. This endpoint allows partial updates to customer information. Only the fields provided in the request will be updated, leaving other KYC data unchanged.

Authorizations
Path parameters
customerIdstring · uuidRequired

Unique identifier of the customer

Example: 03b7030f-6da1-4d76-9352-cdebd82112c8
Body

Payload for customer KYC data partial update

Responses
200

Response schema for a customer retrieval request

application/json
patch
PATCH /customers/{customerId} HTTP/1.1
Host: api.fernhq.com
Authorization: Bearer API Key
Content-Type: application/json
Accept: */*
Content-Length: 3587

{
  "kycData": {
    "legalFirstName": "John",
    "legalMiddleName": "Michael",
    "legalLastName": "Doe",
    "phoneNumber": "+12223334444",
    "dateOfBirth": "1990-01-15",
    "address": {
      "streetLine1": "123 Main St",
      "streetLine2": "Apt 4B",
      "city": "New York",
      "stateRegionProvince": "NY",
      "postalCode": "10001",
      "countryCode": "US",
      "locale": "en-US"
    },
    "nationalIdIssuingCountry": "US",
    "nationalIdType": "ssn",
    "nationalIdNumber": "123-45-6789",
    "nationality": "US",
    "employmentStatus": "EMPLOYED",
    "mostRecentOccupation": "132011",
    "sourceOfFunds": "SALARY",
    "accountPurpose": "PERSONAL_EXPENSES",
    "accountPurposeOther": "Real estate transactions",
    "expectedMonthlyPaymentsUsd": "BETWEEN_10000_49999",
    "isIntermediary": false,
    "documents": [
      {
        "type": "GOVERNMENT_ID",
        "subtype": "NATIONAL_ID",
        "countryCode": "US",
        "documentIdNumber": "123456789",
        "issuanceDate": "2020-01-15",
        "expirationDate": "2030-01-15",
        "frontIdImage": "text",
        "backIdImage": "text",
        "proofOfAddressImage": "text",
        "description": "Electric bill from January 2024"
      }
    ]
  },
  "kybData": {
    "businessInfo": {
      "legalBusinessName": "Acme Corporation Inc.",
      "dbaName": "Acme Corp",
      "businessType": "CORPORATION",
      "businessIndustries": "611519",
      "businessDescription": "Software development and technology consulting services",
      "website": "https://www.acmecorp.com",
      "otherLinks": [
        "https://linkedin.com/company/acme",
        "@acmetech"
      ],
      "formationDate": "2020-01-15",
      "registrationCountry": "DE",
      "isDao": false
    },
    "businessRegisteredAddress": {
      "streetLine1": "123 Main St",
      "streetLine2": "Apt 4B",
      "city": "New York",
      "stateRegionProvince": "NY",
      "postalCode": "10001",
      "countryCode": "US",
      "locale": "en-US"
    },
    "businessOperatingAddress": {
      "streetLine1": "123 Main St",
      "streetLine2": "Apt 4B",
      "city": "New York",
      "stateRegionProvince": "NY",
      "postalCode": "10001",
      "countryCode": "US",
      "locale": "en-US"
    },
    "businessRegistrationNumber": "text",
    "businessDocuments": [
      {
        "type": "ARTICLES_OF_INCORPORATION",
        "description": "Articles of Incorporation filed in Delaware",
        "documentImage": "text"
      }
    ],
    "associatedPersons": [
      {
        "legalFirstName": "Jane",
        "legalMiddleName": "Marie",
        "legalLastName": "Smith",
        "email": "[email protected]",
        "phoneNumber": "+14155551234",
        "dateOfBirth": "1985-06-20",
        "address": {
          "streetLine1": "123 Main St",
          "streetLine2": "Apt 4B",
          "city": "New York",
          "stateRegionProvince": "NY",
          "postalCode": "10001",
          "countryCode": "US",
          "locale": "en-US"
        },
        "ownershipPercentage": 0.25,
        "title": "Chief Technology Officer",
        "isControlPerson": true,
        "isSigner": true,
        "isDirector": false,
        "nationalIdIssuingCountry": "US",
        "nationalIdType": "ssn",
        "nationalIdNumber": "123-45-6789",
        "nationality": "US",
        "documents": [
          {
            "type": "GOVERNMENT_ID",
            "subtype": "NATIONAL_ID",
            "countryCode": "US",
            "documentIdNumber": "123456789",
            "issuanceDate": "2020-01-15",
            "expirationDate": "2030-01-15",
            "frontIdImage": "text",
            "backIdImage": "text",
            "proofOfAddressImage": "text",
            "description": "Electric bill from January 2024"
          }
        ]
      }
    ],
    "sourceOfFunds": "SALE_OF_GOODS_AND_SERVICES",
    "sourceOfFundsDescription": "Revenue from software licensing and consulting services",
    "accountPurpose": "CHARITABLE_DONATIONS",
    "accountPurposeOther": "International trade financing",
    "expectedMonthlyVolumeUsd": "LESS_THAN_10000",
    "estimatedAnnualRevenueUsd": "LESS_THAN_100000",
    "conductsMoneyServices": false,
    "conductsMoneyServicesDescription": "International wire transfers for clients",
    "conductsMoneyServicesThroughFern": false,
    "operatesInProhibitedCountries": false,
    "complianceScreeningDescription": "We screen all clients against OFAC and international sanctions lists",
    "highRiskActivities": [
      "ADULT_ENTERTAINMENT",
      "FOREIGN_EXCHANGE_OR_BROKERAGE"
    ],
    "highRiskActivitiesExplanation": "We operate an adult entertainment platform with proper licensing and compliance measures in place."
  }
}
{
  "customerId": "03b7030f-6da1-4d76-9352-cdebd82112c8",
  "customerStatus": "ACTIVE",
  "customerType": "INDIVIDUAL",
  "name": "John Doe",
  "email": "[email protected]",
  "kycLink": "https://app.fernhq.com/verify-customer/03b7030f-6da1-4d76-9352-cdebd82112c8",
  "verificationLink": "https://app.fernhq.com/verify-customer/03b7030f-6da1-4d76-9352-cdebd82112c8",
  "updatedAt": "2023-10-01T12:00:00Z",
  "organizationId": "8469411c-48c1-4e26-a032-44688be9cb4b"
}

Last updated