Customers

Use this API to create a customer, update their details, and get their details.

Create a customer

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.

POSThttps://app.fernhq.com/api/v0/customers

Body

application/json

type*Customer Type

The type of customer - either individual or business

individualbusiness

firstNamestring

First name of the individual customer

Example: "John"

lastNamestring

Last name of the individual customer

Example: "Doe"

businessNamestring

Name of the business for business customers

Example: "Acme Corp"

email*string

Valid email address for the customer

Example: "[e-mail]"

Pattern: ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$

Response

200400403404

Customer created successfully with KYC link

Body

application/json

kycLink*string

URL for KYC verification process

Example: "https://kyb.example.com/verify/abc123"

customerId*string

Unique identifier for the created customer

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

customerStatus*Customer Status

Current status of the customer account

Example: "pending"

createdpendingactiverejecteddeactivated

Request

JavaScriptCurlPython

const response = await fetch('https://app.fernhq.com/api/v0/customers', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "type": "individual",
      "email": "[e-mail]"
    }),
});
const data = await response.json();

Response

200400403404

{
  "kycLink": "https://kyb.example.com/verify/abc123",
  "customerId": "03b7030f-6da1-4d76-9352-cdebd82112c8",
  "customerStatus": "pending"
}

Get customer details

GEThttps://app.fernhq.com/api/v0/customers/{customerId}

Path parameters

customerId*string

Unique identifier of the customer

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

Response

200403404

Customer details retrieved successfully

Body

application/json

type*Customer Type

The type of customer - either individual or business

individualbusiness

firstNamestring

First name of the individual customer

Example: "John"

lastNamestring

Last name of the individual customer

Example: "Doe"

businessNamestring

Name of the business for business customers

Example: "Acme Corp"

Request

JavaScriptCurlPython

const response = await fetch('https://app.fernhq.com/api/v0/customers/{customerId}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200403404

{
  "type": "individual",
  "firstName": "John",
  "lastName": "Doe",
  "businessName": "Acme Corp"
}

List Customers

GEThttps://app.fernhq.com/api/v0/customers

Query parameters

Response

200

Customers retrieved successfully

Body

application/json

customersarray of Create Customer Response

Retrieved customers

nextPageTokenstring

Page token to use to fetch next page

Example: "xyz"

Request

JavaScriptCurlPython

const response = await fetch('https://app.fernhq.com/api/v0/customers', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "customers": [
    {
      "kycLink": "https://kyb.example.com/verify/abc123",
      "customerId": "03b7030f-6da1-4d76-9352-cdebd82112c8",
      "customerStatus": "pending"
    }
  ],
  "nextPageToken": "xyz"
}