Skip to main content
POST
/
customers
Create customer
curl --request POST \
  --url https://api.fernhq.com/customers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customerType": "INDIVIDUAL",
  "email": "john.doe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "businessName": "John Doe Inc."
}
'
{
  "customerId": "03b7030f-6da1-4d76-9352-cdebd82112c8",
  "customerStatus": "ACTIVE",
  "customerType": "INDIVIDUAL",
  "name": "John Doe",
  "email": "johndoe@example.com",
  "verificationLink": "https://forms.fernhq.com/verify-customer/03b7030f-6da1-4d76-9352-cdebd82112c8",
  "updatedAt": "2023-10-01T12:00:00Z",
  "organizationId": "8469411c-48c1-4e26-a032-44688be9cb4b"
}

Authorizations

​
Authorization
string
header
required

To authenticate server-side requests

Body

application/json

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

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

​
customerType
enum<string>
required

The type of customer - either individual or business

Available options:
INDIVIDUAL,
BUSINESS
​
email
string<email>
required

Email of the customer

Example:

"john.doe@example.com"

​
firstName
string

First name of the customer

Example:

"John"

​
lastName
string

Last name of the customer

Example:

"Doe"

​
businessName
string

Name of the business

Example:

"John Doe Inc."

​
kycData
KYC Data (Create) · object

Optional KYC data for immediate verification submission.

​
kybData
KYB Data (Create) · object

Optional KYB data for immediate verification submission.

Response

Response schema for a customer retrieval request

Response schema for a customer retrieval request

​
customerId
string<uuid>
required

Unique identifier of the customer

Example:

"abc123"

​
customerStatus
enum<string>
required

Current status of the customer

Available options:
CREATED,
UNDER_REVIEW,
NEEDS_ADDITIONAL_INFORMATION,
ACTIVE,
REJECTED,
DEACTIVATED
Example:

"ACTIVE"

​
email
string<email>
required

Email of the customer

Example:

"john.doe@example.com"

​
customerType
enum<string>
required

The type of customer - either individual or business

Available options:
INDIVIDUAL,
BUSINESS
​
name
string
required

Full name of the customer or business

Example:

"John Doe"

​
verificationLink
string<uri>
required

URL for KYC/KYB verification process

Example:

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

​
updatedAt
string<date-time>
required

Timestamp of the last status update

​
organizationId
string
required

Organization identifier

Example:

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

​
availablePaymentMethods
string[]

Available payment methods for the customer

Example:
[
  "ACH",
  "WIRE",
  "SEPA",
  "CA_INTERAC",
  "IN_NEFT_RTGS_IMPS",
  "ARBITRUM",
  "BASE",
  "ETHEREUM",
  "OPTIMISM",
  "POLYGON",
  "SOLANA"
]
​
verificationIssues
Verification Issue · object[]

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

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"
  }
]