KYC/KYB Requirements

How It Works

Before submitting a KYC/KYB application, you must check the Product Details to determine which KYC requirements apply. The product response includes a list of required KYC fields that must be provided when submitting the applicant.

📌

Need to do KYC/KYB Based on Each Product.

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

Step 1 — Check KYC Requirements

GET /api/v1/Products/{productId}

The response will contain a kyc_requirements array listing which requirement types are needed for that product. Use this to determine which fields and documents you need to collect.

Step 2 — Upload Documents

Before submitting KYC, upload all required documents (ID images, selfies, signatures, etc.) using the file upload API.

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 will pass these URLs as field values (e.g., frontDoc, backDoc, selfie, photo) in Step 3.

Step 3 — Submit KYC Application

Pass the uploaded file URLs along with the required KYC fields:

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 fields based on product requirements

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

Individual(KYC) Requirement Types

Requirement	Required Fields
PassportOnly	`docType`, `docId`, `frontDoc` 📎, `backDoc` 📎
Passport	`docType`, `docId`, `frontDoc` 📎, `backDoc` 📎, `docExpireDate`, `docNeverExpire`
FullNameOnly	`firstName`, `lastName`
FullName	`firstName`, `lastName`, `gender`, `dob`
Comms	`email`, `mobileCode`, `mobile`
EmergencyContact	`emerencyContactName`
Address	`addressLine1`,`addressLine2`
FullAddress	`addressLine1`, `addressLine2`,`town`, `city`, `state`, `postalCode`, `countryIsoTwo`
HandedPassport	`handHoldingIdPhoto` 📎
Face	`photo` 📎
Sign	`signImage` 📎
Biomatric	`biomatric` 📎
IssueDate	`docIssueDate`
IpAddress	`ipAddress`
FinancialProfile	`occupation`, `accountPurpose`, `annualSalary`, `expectedMonthlyVolume`
IdTypes	`docType`, `docId`, `frontDoc` 📎, `backDoc` 📎, `docExpireDate`, `docNeverExpire`
TaxId	`taxId`
TaxDoc	`taxDoc` 📎

📎 = File field. Upload the file first via POST /api/v1/uploadfile, then pass the returned file_url as the value.

Occupation List

The occupation field in FinancialProfile must use one of the following values.

⚠️ The Description value must be passed in the API request.

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

📌 Important

When submitting KYB, pass the Description value.

Example: occupation = "Software Engineer"

Business(KYB) Requirement Types

Requirement	Required Fields
CompanyInformation	`companyName`, `type`, `description`, `industry`, `registrationNumber`, `taxId`, `website`
CompanyDocuments	`certificateOfIncorporation` 📎, `shareholderRegistry` 📎
CompanyAddress	`line1`, `city`,`state`, `postalCode`, `countryIsoTwo`
TaxId	`taxId`
TaxDoc	`taxDoc` 📎
CompanyRequiredDocuments	`documentType`, `url` 📎, `subTypes`

Personal Information (Primary Applicant)

Requirement	Required Fields
PersonalInformation	`firstName`, `lastName`, `dateOfBirth`, `email`, `phoneNumber`, `phoneCode`
PersonalInformationAddress	`line1`, `city`,`state`, `postalCode`, `countryIsoTwo`
PersonalIdentification	`idType`, `idNumber`, `countryIsoTwo`, `docExpireDate`, `frontDocument` 📎, `backDocument` 📎

UBOs (Ultimate Beneficial Owners)

Requirement	Required Fields
UBO	`firstName`, `lastName`, `dateOfBirth`, `countryIsoTwo`, `email`, `phoneCode`, `phoneNumber`, `shareHolderPercentage`
UBOAddress	`line1`, `city`,`state`, `postalCode`, `countryIsoTwo`
UBOIdentification	`idType`, `idNumber`, `frontDocument` 📎, `backDocument` 📎
UBOSelfie	`selfie` 📎

Representatives

Requirement	Required Fields
Representatives	`firstName`, `lastName`, `dateOfBirth`, `countryIsoTwo`, `email`, `phoneCode`, `phoneNumber`, `shareHolderPercentage`
RepresentativeAddress	`line1`, `city`,`state`, `postalCode`, `countryIsoTwo`
RepresentativeIdentification	`idType`, `idNumber`, `frontDocument` 📎, `backDocument` 📎
RepresentativeSelfie	`selfie` 📎

Directors

Requirement	Required Fields
Directors	`firstName`, `lastName`, `dateOfBirth`, `countryIsoTwo`, `email`, `phoneCode`, `phoneNumber`, `shareHolderPercentage`
DirectorAddress	`line1`, `city`,`state`, `postalCode`, `countryIsoTwo`
DirectorIdentification	`idType`, `idNumber`, `frontDocument` 📎, `backDocument` 📎
DirectorSelfie	`selfie` 📎

IpAddress

Requirement	Required Fields
IpAddress	`ipAddress`

Industry List

The industry field in CompanyInformation must use one of the following values.

⚠️ The exact Description value must be passed in the API request.

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

Assume the product requires: FullName, Comms, FullAddress, Passport, Face, Sign, FinancialProfile

Step 1 — Upload documents:

POST /api/v1/uploadfile

→ passport_front.jpg   → "https://storage.blob.../passport_front.jpg"
→ passport_back.jpg    → "https://storage.blob.../passport_back.jpg"
→ selfie.jpg           → "https://storage.blob.../selfie.jpg"
→ signature.png        → "https://storage.blob.../signature.png"

Step 2 — Submit KYC:

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

{
  "kycDetails": {
    "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "firstName": "Jane",
    "lastName": "Doe",
    "gender": "female",
    "dob": "1990-06-15",
    "email": "jane@example.com",
    "mobileCode": "+44",
    "mobile": "7700900000",
    "addressLine1": "10 Downing Street",
    "addressLine2": "10 Downing Street",
    "city": "London",
    "state": "England",
    "postalCode": "SW1A 2AA",
    "country": "GB",
    "town": "Westminster",
    "idType": "passport",
    "idNumber": "AB1234567",
    "profilePicFront": "https://storage.blob.../passport_front.jpg",
    "profilePicBack": "https://storage.blob.../passport_back.jpg",
    "docExpiryDate": "2030-01-01",
    "docIssueDate": "2020-01-01",
    "faceImage": "https://storage.blob.../selfie.jpg",
    "signature": "https://storage.blob.../signature.png",
    "occupation": "software_engineer",
    "accountPurpose": "personal_spending",
    "annualSalary": 75000,
    "expectedMonthlyVolume": 5000,
    "ipAddress": "192.168.1.1",
    "taxId": "502086316",
    "taxDoc": "https://storage.googleapis.com/sample-bucket/taxDoc_12345.jpg"
  }
}

Example 2: Business KYB Submission

Assume the product requires: CompanyInformation, CompanyDocuments, CompanyAddress, PersonalInformation, PersonalIdentification, PersonalInformationAddress, UBO, UBOAddress, UBOIdentification, UBOSelfie, Representatives, RepresentativeAddress, RepresentativeIdentification, RepresentativeSelfie, Directors, DirectorAddress, DirectorIdentification, DirectorSelfie

Step 1 — Upload documents:

POST /api/v1/uploadfile

→ certificate_of_inc.pdf     → "https://storage.blob.../certificate.pdf"
→ shareholder_registry.pdf   → "https://storage.blob.../shareholders.pdf"
→ personal_id_front.jpg      → "https://storage.blob.../personal_front.jpg"
→ personal_id_back.jpg       → "https://storage.blob.../personal_back.jpg"
→ ubo_id_front.jpg           → "https://storage.blob.../ubo_front.jpg"
→ ubo_id_back.jpg            → "https://storage.blob.../ubo_back.jpg"
→ ubo_selfie.jpg             → "https://storage.blob.../ubo_selfie.jpg"
→ rep_id_front.jpg            → "https://storage.blob.../rep_front.jpg"
→ rep_id_back.jpg             → "https://storage.blob.../rep_back.jpg"
→ rep_selfie.jpg              → "https://storage.blob.../rep_selfie.jpg"
→ dir_id_front.jpg            → "https://storage.blob.../dir_front.jpg"
→ dir_id_back.jpg             → "https://storage.blob.../dir_back.jpg"
→ dir_selfie.jpg              → "https://storage.blob.../dir_selfie.jpg"

Step 2 — Submit KYB:

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

{
  "kybDetails": {
    "company": {
      "companyName": "Acme Corp Ltd",
      "type": "limited_company",
      "description": "Fintech payment solutions provider",
      "industry": "financial_services",
      "registrationNumber": "12345678",
      "website": "https://acmecorp.com",
      "certificateofincorporation": "https://storage.blob.../certificate.pdf",
      "shareholderregistry": "https://storage.blob.../shareholders.pdf",
      "taxId": "GB502086316",
      "taxDoc": "https://storage.googleapis.com/sample-bucket/taxDoc_12345.jpg",
      "companyAddress": {
        "addressType": "registered",
        "line1": "456 Business Avenue",
        "line2": "Floor 3",
        "city": "London",
        "postalCode": "EC1A 1BB",
        "countryIsoTwo": "GB",
        "town": "City of London"
      },
      "companyRequiredDocuments": [
               {
      "documentType":
             "CERTIFICATE_OF_INCORPORATION",
"url":"https://example.com/docs/certificate_of_incorporation.pdf",
      "subTypes": []
    },
    {
      "documentType": "SHAREHOLDER_REGISTRY",
      "url": "https://example.com/docs/shareholder_registry.pdf",
      "subTypes": []
    }]
    },
    "personaldetails": {
      "firstName": "Jane",
      "lastName": "Smith",
      "dateOfBirth": "1985-03-20",
      "countryIsoTwo": "GB",
      "email": "jane.smith@acmecorp.com",
      "phoneCode": "+44",
      "phoneNumber": "7700900000",
      "identification": {
        "idType": "passport",
        "idNumber": "CD7654321",
        "countryOfIssue": "GB",
        "docExpireDate": "2029-06-15",
        "docIssueDate": "2019-06-15",
        "frontDocument": "https://storage.blob.../personal_front.jpg",
        "backDocument": "https://storage.blob.../personal_back.jpg"
      },
      "address": {
        "line1": "789 Home Lane",
        "city": "London",
        "state": "England",
        "postalCode": "SW1A 1AA",
        "countryIsoTwo": "GB"
      }
    },
    "ubos": [
      {
        "personDetails": {
          "firstName": "John",
          "lastName": "Doe",
          "dateOfBirth": "1980-01-10",
          "countryIsoTwo": "GB",
          "email": "john.doe@acmecorp.com",
          "phoneCode": "+44",
          "phoneNumber": "7700800000",
          "shareHolderPercentage": "60",
          "gender": "male"
        },
        "identification": {
          "idType": "national_id",
          "idNumber": "NI12345678",
          "countryOfIssue": "GB",
          "docExpireDate": "2028-12-01",
          "frontDocument": "https://storage.blob.../ubo_front.jpg",
          "backDocument": "https://storage.blob.../ubo_back.jpg"
        },
        "selfie": "https://storage.blob.../ubo_selfie.jpg",
        "address": {
          "line1": "100 Owner Street",
          "city": "Manchester",
          "postalCode": "M1 1AA",
          "countryIsoTwo": "GB"
        }
      }
    ],
    "representatives": [
      {
        "personDetails": {
          "firstName": "Sarah",
          "lastName": "Connor",
          "dateOfBirth": "1988-07-25",
          "countryIsoTwo": "GB",
          "email": "sarah@acmecorp.com",
          "phoneCode": "+44",
          "phoneNumber": "7700700000",
          "shareHolderPercentage": "0"
        },
        "identification": {
          "idType": "passport",
          "idNumber": "EF9876543",
          "countryOfIssue": "GB",
          "docExpireDate": "2031-03-10",
          "frontDocument": "https://storage.blob.../rep_front.jpg",
          "backDocument": "https://storage.blob.../rep_back.jpg"
        },
        "selfie": "https://storage.blob.../rep_selfie.jpg",
        "address": {
          "line1": "50 Rep Road",
          "city": "Birmingham",
          "postalCode": "B1 1AA",
          "countryIsoTwo": "GB"
        }
      }
    ],
    "directors": [
      {
        "personDetails": {
          "firstName": "Mike",
          "lastName": "Johnson",
          "dateOfBirth": "1975-11-30",
          "countryIsoTwo": "GB",
          "email": "mike@acmecorp.com",
          "phoneCode": "+44",
          "phoneNumber": "7700600000",
          "shareHolderPercentage": "40"
        },
        "identification": {
          "idType": "driving_license",
          "idNumber": "DL98765432",
          "countryOfIssue": "GB",
          "docExpireDate": "2027-08-20",
          "frontDocument": "https://storage.blob.../dir_front.jpg",
          "backDocument": "https://storage.blob.../dir_back.jpg"
        },
        "selfie": "https://storage.blob.../dir_selfie.jpg",
        "address": {
          "line1": "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

How It Works#

Step 1 — Check KYC Requirements#

Step 2 — Upload Documents#

Step 3 — Submit KYC Application#

Individual(KYC) Requirement Types#

Occupation List#

Business(KYB) Requirement Types#

Company Information#

Personal Information (Primary Applicant)#

UBOs (Ultimate Beneficial Owners)#

Representatives#

Directors#

IpAddress#

Industry List#

Example 1: Individual KYC Submission#

Example 2: Business KYB Submission#

Responses#