Guides
Start typing to search…

Individual Clients

Individual clients are related to individual customers who are using your platform. They are an object in our API that relates specific information about the individual (PII/Proof of Id) and their KYC status.

1. Create a individual client

  • expectedMonthlyPaymentsUsd values: from0To4999 from5000To9999 from10000To49999 from50000Plus
  • employmentStatus values: employed homemaker retired selfEmployed student unemployed
  • sourceOfFunds values: companyFunds ecommerceReseller gifts governmentBenefits inheritance investmentsLoans pensionRetirement salary saleOfAssetsRealEstate savings
See API Reference 
curl --request POST \
  --url https://api.sandbox.keyrails.com/api/v1/clients/individual \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{AccessToken}}'  \
  --data '{
  "firstName": "John",
  "lastName": "Doe",
  "email": "[email protected]",
  "phone": "+12223334444",
  "address": {
    "street1": "80 Queens Road",
    "street2": "Suite 3B",
    "postalCode": "M11AE", // Required for US and UK.
    "city": "Manchester",
    "state": "MAN", // ISO 3166-2 Subdivision code without the country prefix
    "country": "GB" // ISO 3166-1 alpha-2 country code
  },
  "taxIdentificationNumber": "111111111",
  "birthDate": "2019-08-24",
  "expectedMonthlyPaymentsUsd": "from0To4999",
  "employmentStatus": "employed",
  "sourceOfFunds": "salary"
}'

Example response:

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", // individualClientId
  "accountType": "Individual",
  "firstName": "string",
  "complianceStatus": "UnderReview",
  ...
}

📘

Supported Countries and States List

To retrieve the list of supported countries and states, use the Get List of Countries API. This endpoint provides up-to-date information on all available regions.

2. Upload individual client documents

  • Allowed GovIdType values: passport driversLicense permanentResidencyId visa
See API Reference 
curl --request POST \
  --url https://api.sandbox.keyrails.com/api/v1/clients/{individualClientId}/individual-documents \
  --header 'Accept: application/json' \
  --header 'Content-Type: multipart/form-data' \
  --header 'Authorization: Bearer {{AccessToken}}' \
  --form ProofOfAddress= \
  --form GovIdImageFront= \
  --form GovIdImageBack=  \
  --form GovIdCountry="GB" \ // ISO 3166-1 alpha-2 country code
  --form GovIdNumber="12749595851" \
  --form GovIdType="passport"

3. Accept the Terms of Service

When you register a new client, they must agree to the terms of service.

See API Reference 
curl --request POST \
  --url https://api.sandbox.keyrails.com/api/v1/clients/{individualClientId}/terms-of-service \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {{AccessToken}}'

Example response:

{
  "url": "https://example.co/accept-terms-of-service?session_token=xxxx&redirect_uri=https://api.sandbox.keyrails.com/api/v1/terms-of-service-agreements/xxxxx"
}

Use this url to guide the client towards accepting the Terms of Service. You can embed this URL in an iFrame or open it in a new browser window. Upon acceptance of the Terms of Service, the page will redirect to our application, and you may then close the browser.

Webhooks Examples

Before proceeding, ensure that your webhook configuration is set up. Refer to the setup guide for detailed instructions.

Webhook types: - Identity

Client approved

{
  "tenantId": "64790ea8-f9b1-4b52-aff6-f6177bb3fcee",
  "action": "Update",
  "id": "cfc05dcb-5983-413b-8d8b-f8ef69a14787",
  "resourceId": "d8d01119-4b78-41a6-b868-0849b9ecf2ff",
  "resourceType": "Identity",
  "createdAtUtc": "0001-01-01T00:00:00",
  "changes": {
    "complianceStatus": "Approved"
  }
}

Client rejected

{
  "tenantId": "47dce736-7fe1-42f9-a317-2676733823fe",
  "action": "Update",
  "id": "fa85e3f4-99cb-46be-bbd3-4faad0bf565d",
  "resourceId": "51777f07-8b43-468f-8808-c7cb1405f254",
  "resourceType": "Identity",
  "createdAtUtc": "0001-01-01T00:00:00",
  "changes": {
    "complianceStatus": "Rejected",
    "rejectionReasons": [
      "Failed to verify proof of address",
      "Poor quality of the document"
    ]
  }
}

Updated 13 days ago