Skip to main content
GET
/
customers
/
{customerId}
Get customer
curl --request GET \
  --url https://api.fernhq.com/customers/{customerId} \
  --header 'Authorization: Bearer <token>'
{
  "customerId": "abc123",
  "customerStatus": "ACTIVE",
  "email": "john.doe@example.com",
  "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"
    }
  ],
  "kycData": {
    "legalFirstName": "John",
    "legalMiddleName": "Michael",
    "legalLastName": "Doe",
    "phoneNumber": "+12223334444",
    "dateOfBirth": "1990-01-15",
    "address": {
      "countryCode": "US",
      "streetLine1": "350 5th Avenue",
      "streetLine2": "Floor 21",
      "city": "New York",
      "stateRegionProvince": "NY",
      "postalCode": "10016",
      "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": "DRIVERS_LICENSE_FRONT",
        "frontIdImage": "data:image/png;base64,iVBORw0KGgoAAA...",
        "backIdImage": "data:image/png;base64,iVBORw0KGgoAAA...",
        "proofOfAddressImage": "data:application/pdf;base64,JVBERi0xLjQKJ...",
        "documentImage": "data:application/pdf;base64,JVBERi0xLjQKJ..."
      }
    ]
  },
  "kybData": {
    "businessInfo": {
      "legalBusinessName": "Acme Corporation Inc.",
      "dbaName": "Acme Corp",
      "businessType": "B_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": {
      "countryCode": "US",
      "streetLine1": "350 5th Avenue",
      "streetLine2": "Floor 21",
      "city": "New York",
      "stateRegionProvince": "NY",
      "postalCode": "10016",
      "locale": "en-US"
    },
    "businessOperatingAddress": {
      "countryCode": "US",
      "streetLine1": "350 5th Avenue",
      "streetLine2": "Floor 21",
      "city": "New York",
      "stateRegionProvince": "NY",
      "postalCode": "10016",
      "locale": "en-US"
    },
    "businessRegistrationNumber": "<string>",
    "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.",
    "associatedPersons": [
      {
        "legalFirstName": "Jane",
        "legalMiddleName": "Marie",
        "legalLastName": "Smith",
        "email": "jane.smith@example.com",
        "phoneNumber": "+14155551234",
        "dateOfBirth": "1985-06-20",
        "address": {
          "countryCode": "US",
          "streetLine1": "350 5th Avenue",
          "streetLine2": "Floor 21",
          "city": "New York",
          "stateRegionProvince": "NY",
          "postalCode": "10016",
          "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": "DRIVERS_LICENSE_FRONT",
            "frontIdImage": "data:image/png;base64,iVBORw0KGgoAAA...",
            "backIdImage": "data:image/png;base64,iVBORw0KGgoAAA...",
            "proofOfAddressImage": "data:application/pdf;base64,JVBERi0xLjQKJ...",
            "documentImage": "data:application/pdf;base64,JVBERi0xLjQKJ..."
          }
        ]
      }
    ],
    "businessDocuments": [
      {
        "type": "DRIVERS_LICENSE_FRONT",
        "frontIdImage": "data:image/png;base64,iVBORw0KGgoAAA...",
        "backIdImage": "data:image/png;base64,iVBORw0KGgoAAA...",
        "proofOfAddressImage": "data:application/pdf;base64,JVBERi0xLjQKJ...",
        "documentImage": "data:application/pdf;base64,JVBERi0xLjQKJ..."
      }
    ]
  }
}

Authorizations

​
Authorization
string
header
required

To authenticate server-side requests

Path Parameters

​
customerId
string<uuid>
required

Unique identifier of the customer

Query Parameters

​
includeVerification
boolean
default:false

Whether to include verification details

​
includePaymentMethods
boolean
default:false

Whether to include available payment methods in the response

Response

Developer API customer response including optional KYC/KYB verification data.

​
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"
  }
]
​
kycData
object

Know Your Customer data for an individual.

​
kybData
object

Know Your Business data for a business entity.