Submit KYC / KYB Applicant

How It Works

Before submitting a KYC/KYB application, check the Product Details to determine which
KYC/KYB requirements apply. The product response lists the required requirement types you
must satisfy when submitting the applicant.

📌 KYC/KYB requirements are driven by each Product.

🔒 Proof of Address is a cross-cutting rule, not a product requirement.
Unlike the requirement types below (which only apply when your product's kyc_requirements
list includes them), proof of address is enforced automatically on every external
submission whenever the customer's country of residence differs from their country of
origin — regardless of what your product requires.
These two country values are set once, at customer creation
(countryOfResidencyIsoTwo / countryOfOriginIsoTwo on POST /api/v1/customers) —
not from the address/companyAddress you send in this endpoint.
Individual (KYC): provide a documents[] entry with "type": "PROOF_OF_ADDRESS".
Business (KYB): provide company.proofOfAddressUrl — a dedicated field, not
an entry in company.requiredDocuments[].
If it's required and missing, the call returns 422 VALIDATION_ERROR (see the example
at the bottom of this page).

Step 1: Get product KYC requirements  →  GET  /api/v1/Products/{productId}
Step 2: Upload required documents      →  POST /api/v1/uploadfile
Step 3: Submit KYC/KYB with file URLs  →  POST /api/v1/customers/{customerId}/products/{productId}/applicant

Step 1 — Check KYC Requirements

GET /api/v1/Products/{productId}

The response contains a kyc_requirements array listing which requirement types are needed
for that product. Use it to decide which fields and documents to collect.

Step 2 — Upload Documents

Upload all required documents (ID images, selfies, signatures, company docs, …) first.

POST /api/v1/uploadfile

Supports images (JPEG, PNG) and PDFs

Files are stored in Azure Blob Storage

Returns a file URL for each uploaded file

Response (200):

{
  "data": [
    {
      "file_name": "passport_front.jpg",
      "file_url": "https://storage.blob.core.windows.net/docs/abc123.jpg"
    }
  ]
}

⚠️ Important: Save the returned file_url values — you pass these URLs as the
frontUrl / backUrl / selfieUrl / documentUrl fields in Step 3.

Step 3 — Submit KYC/KYB Application

POST /api/v1/customers/{customerId}/products/{productId}/applicant

Parameter	In	Type	Required	Description
`customerId`	path	uuid	✅	The customer identifier
`productId`	path	uuid	✅	The product identifier
body	body	JSON	✅	`kyc` for an individual applicant, or `kyb` for a business applicant

The request body has exactly two top-level objects — send one of them:

{
  "kyc": { ... },   // individual applicant
  "kyb": { ... }    // business applicant
}

⚠️ Only send the fields that match the requirements returned by the Product Details API.
Requirements vary by product.

Individual (KYC)

The kyc object is grouped into person, address, and a single unified documents[] list,
plus two top-level fields (ipAddress, kycRequirements).

{
  "kyc": {
    "person":  { ... },
    "address": { ... },
    "documents": [ ... ],
    "ipAddress": "192.168.1.1",
    "kycRequirements": "FullName,Comms,FullAddress,Passport,Face,Sign,FinancialProfile"
  }
}

`person`

Field	Type	Notes
`firstName`	string
`lastName`	string
`dateOfBirth`	string	`YYYY-MM-DD`
`gender`	string	`male` / `female` / …
`email`	string
`countryIsoTwo`	string	Applicant country ISO 2-letter code
`phoneCountryCode`	string	e.g. `+44`
`phoneNumber`	string
`occupation`	string	send the Description value (see Occupation List)
`emergencyContactName`	string
`accountPurpose`	string
`annualSalary`	number
`expectedMonthlyVolume`	number

`address`

Field	Type	Notes
`addressLine1`	string
`addressLine2`	string
`city`	string
`state`	string
`postalCode`	string
`addressCountryIsoTwo`	string	ISO alpha-2 (e.g. `GB`)
`countryIsoThree`	string	Optional — ISO alpha-3, only when a provider needs it

`documents[]` — one unified list for all individual documents

Each item's type decides how it is handled (case-insensitive).

Field	Type	Notes
`type`	string	Required. See the type taxonomy below
`documentNumber`	string	ID number (identity docs only)
`issueDate`	string	`YYYY-MM-DD`
`expiryDate`	string	`YYYY-MM-DD`
`frontUrl`	url	Front image — or the single image for selfie/sign/etc., or the URL for a supporting document
`backUrl`	url	Back image (identity docs only)

`type` taxonomy

Category	Accepted `type` values	Fields used
Primary identity document (first one wins)	`PASSPORT`, `NATIONAL_ID`, `ID_CARD`, `DRIVERS_LICENSE`, `DRIVER_LICENSE`, `RESIDENCE_PERMIT`, `VOTER_ID`	`documentNumber`, `issueDate`, `expiryDate`, `frontUrl`, `backUrl`
Selfie / face	`SELFIE`, `FACE`, `PHOTO`	`frontUrl`
Signature	`SIGNATURE`, `SIGN`	`frontUrl`
Biometric	`BIOMETRIC`	`frontUrl`
Hand-held ID	`HANDHELD_ID`, `HANDHOLDING_ID`, `HANDHELDPASSPORT`, `HANDEDPASSPORT`	`frontUrl`
Card hand-held ID	`CARD_HANDHELD_ID`, `CARDHANDHOLDING_ID`	`frontUrl`
Supporting document (anything else — proof of address, tax doc, secondary ID, extra copies…)	any other value, e.g. `TAX_DOC`, `PROOF_OF_ADDRESS`	`frontUrl` (the doc URL)

💡 Multiple documents for a personal account = just add more entries to documents[].
The first identity-type entry is the primary ID; extra identity entries and any other
types become supporting documents automatically.

Individual Requirement Types → where each field goes

Requirement	Provide
PassportOnly	`documents[]` → `{ "type":"PASSPORT", "documentNumber", "frontUrl", "backUrl" }`
Passport	`documents[]` → `{ "type":"PASSPORT", "documentNumber", "frontUrl", "backUrl", "expiryDate" }`
IdTypes	`documents[]` → `{ "type":"NATIONAL_ID" \| "DRIVERS_LICENSE" \|"PASSPORT" …, "documentNumber", "frontUrl", "backUrl", "expiryDate" }`
IssueDate	`documents[]` identity item → `issueDate`
FullNameOnly	`person.firstName`, `person.lastName`
FullName	`person.firstName`, `person.lastName`, `person.gender`, `person.dateOfBirth`
Comms	`person.email`, `person.phoneCountryCode`, `person.phoneNumber`
EmergencyContact	`person.emergencyContactName`
Address	`address.addressLine1`, `address.addressLine2`
FullAddress	`address.addressLine1`, `address.addressLine2`, `address.city`, `address.state`, `address.postalCode`, `address.addressCountryIsoTwo`
HandedPassport	`documents[]` → `{ "type":"HANDHELD_ID", "frontUrl" }`
Face	`documents[]` → `{ "type":"SELFIE", "frontUrl" }`
Sign	`documents[]` → `{ "type":"SIGNATURE", "frontUrl" }`
Biometric	`documents[]` → `{ "type":"BIOMETRIC", "frontUrl" }`
IpAddress	`kyc.ipAddress`
FinancialProfile	`person.occupation`, `person.accountPurpose`, `person.annualSalary`, `person.expectedMonthlyVolume`
TaxDoc	`documents[]` → `{ "type":"TAX_DOC", "frontUrl" }`
SSN	`SSN Number`

ℹ️ docNeverExpire is not exposed in this contract (leave expiryDate empty for
never-expiring documents).

Occupation List

The person.occupation field must use one of the following. Send the Description value.

Code	Description (Value to Send)
marketing_manager	Marketing Managers
political_scientist	Political Scientists
dancer	Dancers
nurse	Nurse Midwives
teacher	Teacher Assistants
accountant	Accountants and Auditors
lawyer	Lawyers
pilot	Commercial Pilots
surveyor	Surveyors
librarian	Librarians
data_entry	Data Entry Keyers
residential_advisor	Residential Advisors
inspector	Construction and Building Inspectors
optometrist	Optometrists
self_employed	Self-Enrichment Education Teachers
curator	Curators
sales	Sales Managers
marketing	Marketing Managers
engineer	Industrial Engineers
architect	Computer Network Architects
mechanic	Motorcycle Mechanics
driver	Light Truck or Delivery Services Drivers
designer	Interior Designers
artist	Multimedia Artists and Animators
trainer	Athletic Trainers
social_worker	Healthcare Social Workers
scientist	Physicists
computer_operator	Computer Operators
barber	Barbers

Business (KYB)

The kyb object contains company, primaryContact, and the control-person lists
(representatives[], directors[], ubos[]), plus a top-level ipAddress.

{
  "kyb": {
    "company":          { ... },
    "primaryContact":   { ... },
    "representatives":  [ ... ],
    "directors":        [ ... ],
    "ubos":             [ ... ],
    "ipAddress": "123.123.123.123"
  }
}

`company`

Field	Type	Notes
`companyName`	string
`companyType`	string	e.g. `limited_company`
`description`	string
`industry`	string	send the exact Description value (see Industry List)
`registrationNumber`	string
`website`	url
`certificateOfIncorporationUrl`	url
`dateOfIncorporation`	date
`shareholderRegistryUrl`	url
`companyAddress`	object	see below
`requiredDocuments`	array	see below

`company.companyAddress`

Field	Type
`addressType`	string (e.g. `registered`)
`addressLine1`	string
`addressLine2`	string
`city`	string
`state`	string
`postalCode`	string
`countryIsoTwo`	string (ISO alpha-2)

`company.requiredDocuments[]`

Field	Type	Notes
`documentType`	string	e.g. `CERTIFICATE_OF_INCORPORATION`, `SHAREHOLDER_REGISTRY`
`documentUrl`	url	the document URL

⚠️ Do not send proof of address here. A {"documentType": "PROOF_OF_ADDRESS", ...}
entry in this list is stored only as a supplementary document — it does not satisfy
the proof-of-address requirement. Use company.proofOfAddressUrl instead.

Person blocks — `primaryContact`, `representatives[]`, `directors[]`, `ubos[]`

They all share the same shape (control-person lists additionally accept id and
recordStatus for updates):

{
  "personDetails": {
    "firstName": "Jane",
    "lastName": "Smith",
    "dateOfBirth": "1985-03-20",
    "gender": "female",
    "countryIsoTwo": "GB",
    "email": "jane.smith@acmecorp.com",
    "phoneCountryCode": "+44",
    "phoneNumber": "7700900000",
    "shareholderPercentage": "60"
  },
  "documents": [
    {
      "documentType": "passport",
      "documentNumber": "CD7654321",
      "countryIsoTwo": "GB",
      "documentIssueDate": "2019-06-15",
      "documentExpiryDate": "2029-06-15",
      "frontDocumentUrl": "https://storage.blob.../front.jpg",
      "backDocumentUrl": "https://storage.blob.../back.jpg"
    }
  ],
  "selfieUrl": "https://storage.blob.../selfie.jpg",
  "address": {
    "addressType": "residential",
    "addressLine1": "789 Home Lane",
    "addressLine2": "",
    "city": "London",
    "state": "England",
    "postalCode": "SW1A 1AA",
    "countryIsoTwo": "GB"
  }
}

ℹ️ documents is a list — add more than one identity document per person if needed.
The first entry is used as that person's identity document.

ℹ️ primaryContact does not take id / recordStatus. Control persons in
representatives[] / directors[] / ubos[] may include "id" and "recordStatus"
to update an existing record.

Business Requirement Types → where each field goes

Requirement	Provide
CompanyInformation	`company.companyName`, `company.companyType`, `company.description`, `company.industry`, `company.registrationNumber`, `company.website` ,`dateOfIncorporation`
CompanyDocuments	`company.certificateOfIncorporationUrl`, `company.shareholderRegistryUrl`

| proofOfAddressUrl | url | Business proof of address. Conditionally required — see the Proof of Address rule at the top of this page. A dedicated field, not an entry in requiredDocuments[]. |

| CompanyAddress | company.companyAddress.* |
| TaxDoc | company.taxDocumentUrl |
| CompanyRequiredDocuments | company.requiredDocuments[] → { documentType, documentUrl } |
| PersonalInformation | primaryContact.personDetails.{firstName,lastName,dateOfBirth,email,phoneCountryCode,phoneNumber} |
| PersonalInformationAddress | primaryContact.address.* |
| PersonalIdentification |

primaryContact.documents[].{documentType,documentNumber,countryIsoTwo,documentExpiryDate,frontDocumentUrl,backDocumentUrl}

|
| UBO |

ubos[].personDetails.{firstName,lastName,dateOfBirth,countryIsoTwo,email,phoneCountryCode,phoneNumber,shareholderPercentage}

|
| UBOSSN | SSN Number |
| UBOAddress | ubos[].address.* |
| UBOIdentification | ubos[].documents[].{documentType,documentNumber,frontDocumentUrl,backDocumentUrl} |
| UBOSelfie | ubos[].selfieUrl |
| Representatives | representatives[].personDetails.* |
| RepresentativeSSN | SSN Number* |
| RepresentativeAddress | representatives[].address.* |
| RepresentativeIdentification | representatives[].documents[].* |
| RepresentativeSelfie | representatives[].selfieUrl |
| Directors | directors[].personDetails.* | DirectorSSN|SSN Number*
| DirectorAddress | directors[].address.* |
| DirectorIdentification | directors[].documents[].* |
| DirectorSelfie | directors[].selfieUrl |
| IpAddress | kyb.ipAddress |

Industry List

The company.industry field must use one of the following. Send the exact Description value.

Description (Value to Send)
International Affairs
National Security
Space Research and Technology
Regulation, Licensing, and Inspection of Miscellaneous Commercial Sectors
Regulation of Agricultural Marketing and Commodities
Regulation and Administration of Communications, Electric, Gas, and Other Utilities
Regulation and Administration of Transportation Programs
Administration of General Economic Programs
Administration of Urban Planning and Community and Rural Development
Administration of Housing Programs
Administration of Conservation Programs
Administration of Air and Water Resource and Solid Waste Management Programs
Administration of Veterans' Affairs
Administration of Human Resource Programs (except Education, Public, Health, and Veterans' Affairs Programs)
Administration of Public Health Programs
Administration of Education Programs
Other Justice, Public Order, and Safety Activities
Fire Protection
Parole Offices and Probation Offices
Correctional Institutions

Example 1 — Individual KYC Submission

Product requires: FullName, Comms, FullAddress, Passport, Face, Sign, FinancialProfile

POST /api/v1/customers/{customerId}/products/{productId}/applicant

{
  "kyc": {
    "person": {
      "firstName": "Jane",
      "lastName": "Doe",
      "gender": "female",
      "countryIsoTwo": "AU",
      "dateOfBirth": "1990-06-15",
      "email": "jane@example.com",
      "phoneCountryCode": "+44",
      "phoneNumber": "7700900000",
      "occupation": "Industrial Engineers",
      "accountPurpose": "personal spending",
      "annualSalary": 75000,
      "expectedMonthlyVolume": 5000
    },
    "address": {
      "addressLine1": "10 Downing Street",
      "addressLine2": "",
      "city": "London",
      "state": "England",
      "postalCode": "SW1A 2AA",
      "addressCountryIsoTwo": "GB"
    },
    "documents": [
      {
        "type": "PASSPORT",
        "documentNumber": "AB1234567",
        "issueDate": "2020-01-01",
        "expiryDate": "2030-01-01",
        "frontUrl": "https://storage.blob.../passport_front.jpg",
        "backUrl": "https://storage.blob.../passport_back.jpg"
      },
      { "type": "SELFIE",    "frontUrl": "https://storage.blob.../selfie.jpg" },
      { "type": "SIGNATURE", "frontUrl": "https://storage.blob.../signature.png" }
    ],
    "ipAddress": "192.168.1.1",
    "kycRequirements": "FullName,Comms,FullAddress,Passport,Face,Sign,FinancialProfile"
  }
}

Example 2 — Business KYB Submission

Product requires: CompanyInformation, CompanyDocuments, CompanyAddress,
PersonalInformation, PersonalIdentification, PersonalInformationAddress,
UBO,UBOSSN, UBOAddress, UBOIdentification, UBOSelfie,
Representatives,RepresentativeSSN, RepresentativeAddress, RepresentativeIdentification, RepresentativeSelfie,
Directors, DirectorSSN,DirectorAddress, DirectorIdentification, DirectorSelfie

POST /api/v1/customers/{customerId}/products/{productId}/applicant

{
  "kyb": {
    "company": {
      "companyName": "Acme Corp Ltd",
      "companyType": "limited_company",
      "description": "Fintech payment solutions provider",
      "industry": "International Affairs",
      "registrationNumber": "12345678",
      "website": "https://acmecorp.com",
      "dateOfIncorporation":"2013-01-01"
      "certificateOfIncorporationUrl": "https://storage.blob.../certificate.pdf",
      "shareholderRegistryUrl": "https://storage.blob.../shareholders.pdf",
      "companyAddress": {
        "addressType": "registered",
        "addressLine1": "456 Business Avenue",
        "addressLine2": "Floor 3",
        "city": "London",
        "state": "England",
        "postalCode": "EC1A 1BB",
        "countryIsoTwo": "GB"
      },
      "requiredDocuments": [
        {
          "documentType": "CERTIFICATE_OF_INCORPORATION",
          "documentUrl": "https://example.com/docs/certificate_of_incorporation.pdf"
        },
        {
          "documentType": "SHAREHOLDER_REGISTRY",
          "documentUrl": "https://example.com/docs/shareholder_registry.pdf"
        }
      ]
    },
    "primaryContact": {
      "personDetails": {
        "firstName": "Jane",
        "lastName": "Smith",
        "dateOfBirth": "1985-03-20",
        "countryIsoTwo": "GB",
        "email": "jane.smith@acmecorp.com",
        "phoneCountryCode": "+44",
        "phoneNumber": "7700900000"
      },
      "documents": [
        {
          "documentType": "passport",
          "documentNumber": "CD7654321",
          "countryIsoTwo": "GB",
          "documentIssueDate": "2019-06-15",
          "documentExpiryDate": "2029-06-15",
          "frontDocumentUrl": "https://storage.blob.../personal_front.jpg",
          "backDocumentUrl": "https://storage.blob.../personal_back.jpg"
        }
      ],
      "address": {
        "addressLine1": "789 Home Lane",
        "city": "London",
        "state": "England",
        "postalCode": "SW1A 1AA",
        "countryIsoTwo": "GB"
      }
    },
    "ubos": [
      {
        "personDetails": {
          "firstName": "John",
          "lastName": "Doe",
          "dateOfBirth": "1980-01-10",
          "gender": "male",
          "countryIsoTwo": "GB",
          "uboSsn": "958748348559559",
          "email": "john.doe@acmecorp.com",
          "phoneCountryCode": "+44",
          "phoneNumber": "7700800000",
          "shareholderPercentage": "60"
        },
        "documents": [
          {
            "documentType": "national_id",
            "documentNumber": "NI12345678",
            "countryIsoTwo": "GB",
            "documentExpiryDate": "2028-12-01",
            "frontDocumentUrl": "https://storage.blob.../ubo_front.jpg",
            "backDocumentUrl": "https://storage.blob.../ubo_back.jpg"
          }
        ],
        "selfieUrl": "https://storage.blob.../ubo_selfie.jpg",
        "address": {
          "addressLine1": "100 Owner Street",
          "city": "Manchester",
          "postalCode": "M1 1AA",
          "countryIsoTwo": "GB"
        }
      }
    ],
    "representatives": [
      {
        "personDetails": {
          "firstName": "Sarah",
          "lastName": "Connor",
          "dateOfBirth": "1988-07-25",
          "countryIsoTwo": "GB",
          "representativeSSn":       "958748348559553",
          "email": "sarah@acmecorp.com",
          "phoneCountryCode": "+44",
          "phoneNumber": "7700700000",
          "shareholderPercentage": "0"
        },
        "documents": [
          {
            "documentType": "passport",
            "documentNumber": "EF9876543",
            "countryIsoTwo": "GB",
            "documentExpiryDate": "2031-03-10",
            "frontDocumentUrl": "https://storage.blob.../rep_front.jpg",
            "backDocumentUrl": "https://storage.blob.../rep_back.jpg"
          }
        ],
        "selfieUrl": "https://storage.blob.../rep_selfie.jpg",
        "address": {
          "addressLine1": "50 Rep Road",
          "city": "Birmingham",
          "postalCode": "B1 1AA",
          "countryIsoTwo": "GB"
        }
      }
    ],
    "directors": [
      {
        "personDetails": {
          "firstName": "Mike",
          "lastName": "Johnson",
          "dateOfBirth": "1975-11-30",
          "countryIsoTwo": "GB",
          "directorSsn":"958748348359559"
          "email": "mike@acmecorp.com",
          "phoneCountryCode": "+44",
          "phoneNumber": "7700600000",
          "shareholderPercentage": "40"
        },
        "documents": [
          {
            "documentType": "driving_license",
            "documentNumber": "DL98765432",
            "countryIsoTwo": "GB",
            "documentExpiryDate": "2027-08-20",
            "frontDocumentUrl": "https://storage.blob.../dir_front.jpg",
            "backDocumentUrl": "https://storage.blob.../dir_back.jpg"
          }
        ],
        "selfieUrl": "https://storage.blob.../dir_selfie.jpg",
        "address": {
          "addressLine1": "25 Director Lane",
          "city": "Leeds",
          "postalCode": "LS1 1AA",
          "countryIsoTwo": "GB"
        }
      }
    ],
    "ipAddress": "123.123.123.123"
  }
}

Responses

Status	Meaning
`200`	KYC/KYB submitted successfully
`404`	Customer not found
`422`	Validation error — missing or invalid fields

Example — Proof of Address Missing (422)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Proof of address is required because the customer's country of residence and country of origin differ. Provide a Kyc.RequiredDocuments entry with documentType 'PROOF_OF_ADDRESS'.",
    "details": []
  }
}

KYC/KYB Requirements

Submit KYC / KYB Applicant#

How It Works#

Step 1 — Check KYC Requirements#

Step 2 — Upload Documents#

Step 3 — Submit KYC/KYB Application#

Individual (KYC)#

person#

address#

documents[] — one unified list for all individual documents#

type taxonomy#

Individual Requirement Types → where each field goes#

Occupation List#

Business (KYB)#

company#

company.companyAddress#

company.requiredDocuments[]#

Person blocks — primaryContact, representatives[], directors[], ubos[]#

Business Requirement Types → where each field goes#

Industry List#

Example 1 — Individual KYC Submission#

Example 2 — Business KYB Submission#

Responses#

Example — Proof of Address Missing (422)#