KYC Requirements

This endpoint retrieves the KYC requirements for a specific entity and routing provider.

Field Type	Description	Example Use Case
`section`	Container for related fields	Personal Information grouping
`list_section`	Container for a list of objects	Employment history, Address history
`string`	Text input	Name, Email, Address
`number`	Numeric input	Age, Income
`boolean`	True/False value	Terms acceptance, Consent
`select`	Dropdown selection	Country, Nationality
`timestamp`	Date/time input	Date of Birth
`document`	Single document upload	Passport, Driver's License
`document_list`	Multiple document uploads	Supporting documents
`ip_address`	IP address input	User's location verification

Core Properties

Every requirement object contains these core properties:

fieldId: Unique identifier for the field (will be used as key in your submission)

fieldName: Display name for the field

fieldType: Type of field from the table above

fieldRequired: Boolean indicating if the field is mandatory

fieldDescription: Description of the field

Type-Specific Properties

Additional properties will be present depending on the field type:

fieldChoices: Array of options (only for select fields)

fieldDefaultValue: Pre-filled value (for non-section fields)

isEditable: Whether the field can be edited (for non-section fields)

children: Nested fields (only for section and list_section fields)

Property Behavior by Field Type

The presence and behavior of properties varies by field type:

Field Type	fieldChoices	fieldDefaultValue	isEditable	children
`section`	Not present	Not present	Not present	Always present
`list_section`	Not present	Not present	Not present	Always present
`string`	Not present	May be present	May be present	Not present
`number`	Not present	May be present	May be present	Not present
`boolean`	Not present	May be present (true/false)	May be present	Not present
`select`	Always present	May be present (one of the values)	May be present	Not present
`timestamp`	Not present	May be present (ISO format)	May be present	Not present
`document`	Not present	Rarely present	May be present	Not present
`document_list`	Not present	Rarely present	May be present	Not present
`ip_address`	Not present	May be present	May be present	Not present

Field-to-Payload Mapping

Understanding how the requirement objects translate to the submission payload is crucial:

The fieldId of each requirement becomes the key in your payload

For section fields, the value is an object containing the fields within that section

For list_section fields, the value is an array of objects, where each object follows the structure defined by the children

For non-section fields, the value is the actual data for that field

For each field type, the following sections provide detailed examples of how they appear in the requirements response and how they should be included in your submission payload.

String Fields

Description: Text input for names, emails, addresses, etc.

Requirements Example:

{
  "fieldId": "full_name",
  "fieldName": "Full Name",
  "fieldType": "string",
  "fieldRequired": true,
  "fieldDescription": "Your full legal name",
  "fieldDefaultValue": null,
  "isEditable": true
}

Submission Example:

{
  "full_name": "John Smith"
}

Number Fields

Description: Numeric input for age, income, etc.

Requirements Example:

{
  "fieldId": "annual_income",
  "fieldName": "Annual Income",
  "fieldType": "number",
  "fieldRequired": true,
  "fieldDescription": "Your annual income in USD",
  "fieldDefaultValue": null,
  "isEditable": true
}

Submission Example:

{
  "annual_income": 75000
}

Boolean Fields

Description: True/False values for consent, agreements, etc.

Requirements Example:

{
  "fieldId": "terms_acceptance",
  "fieldName": "Terms Acceptance",
  "fieldType": "boolean",
  "fieldRequired": true,
  "fieldDescription": "I agree to the [Terms & Conditions](https://example.com/terms.pdf)",
  "fieldDefaultValue": false,
  "isEditable": true
}

Submission Example:

{
  "terms_acceptance": true
}

Select Fields

Description: Dropdown selections for countries, nationalities, etc.

Requirements Example:

{
  "fieldId": "country",
  "fieldName": "Country",
  "fieldType": "select",
  "fieldRequired": true,
  "fieldDescription": "Your country of residence",
  "fieldChoices": [
    { "value": "US", "label": "United States" },
    { "value": "CA", "label": "Canada" },
    { "value": "UK", "label": "United Kingdom" }
  ],
  "fieldDefaultValue": null,
  "isEditable": true
}

Submission Example:

{
  "country": "US"
}

Note: Always submit the value property from the choices, not the label.

Timestamp Fields

Description: Date/time input for birth dates, document issuance dates, etc.

Requirements Example:

{
  "fieldId": "date_of_birth",
  "fieldName": "Date of Birth",
  "fieldType": "timestamp",
  "fieldRequired": true,
  "fieldDescription": "Your date of birth",
  "fieldDefaultValue": null,
  "isEditable": true
}

Submission Example:

{
  "date_of_birth": "1985-07-15T00:00:00Z"
}

Note: Use the ISO 8601 format for timestamp values.

Document Fields

Description: Single document uploads for ID proofs, passports, etc.

Requirements Example:

{
  "fieldId": "id_proof",
  "fieldName": "Identity Proof",
  "fieldType": "document",
  "fieldRequired": true,
  "fieldDescription": "Government-issued ID (passport, driver's license)",
  "fieldDefaultValue": null,
  "isEditable": true
}

Submission Example:

{
  "id_proof": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEA..."
}

Note: Document fields must be submitted as base64 URI data strings.

Document List Fields

Description: Multiple document uploads for supporting documents, proof of address, etc.

Requirements Example:

{
  "fieldId": "supporting_docs",
  "fieldName": "Supporting Documents",
  "fieldType": "document_list",
  "fieldRequired": true,
  "fieldDescription": "Upload all relevant supporting documents",
  "fieldDefaultValue": null,
  "isEditable": true
}

Submission Example:

{
  "supporting_docs": [
    "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEA...",
    "data:application/pdf;base64,JVBERi0xLjUNCiW1tbW..."
  ]
}

Note: Document list fields must be submitted as an array of base64 URI data strings.

IP Address Fields

Description: IP address input for location verification.

Requirements Example:

{
  "fieldId": "client_ip",
  "fieldName": "Client IP Address",
  "fieldType": "ip_address",
  "fieldRequired": true,
  "fieldDescription": "Your current IP address",
  "fieldDefaultValue": null,
  "isEditable": false
}

Submission Example:

{
  "client_ip": "192.168.1.1"
}

Section Fields

Description: Containers for grouping related fields.

Requirements Example:

{
  "fieldId": "personal_info",
  "fieldName": "Personal Information",
  "fieldType": "section",
  "fieldRequired": true,
  "fieldDescription": "Basic personal details",
  "children": [
    {
      "fieldId": "full_name",
      "fieldName": "Full Name",
      "fieldType": "string",
      "fieldRequired": true,
      "fieldDescription": "Your full legal name",
      "fieldDefaultValue": null,
      "isEditable": true
    },
    {
      "fieldId": "date_of_birth",
      "fieldName": "Date of Birth",
      "fieldType": "timestamp",
      "fieldRequired": true,
      "fieldDescription": "Your date of birth",
      "fieldDefaultValue": null,
      "isEditable": true
    }
  ]
}

Submission Example:

{
  "personal_info": {
    "full_name": "John Smith",
    "date_of_birth": "1985-07-15T00:00:00Z"
  }
}

Note: For section fields, create a nested object with the children's fieldIds as keys.

List Section Fields

Description: Containers for a list of objects, where each object follows the structure defined by the children.

Requirements Example:

{
  "fieldId": "employment_history",
  "fieldName": "Employment History",
  "fieldType": "list_section",
  "fieldRequired": true,
  "fieldDescription": "List of your previous employment",
  "children": [
    {
      "fieldId": "company_name",
      "fieldName": "Company Name",
      "fieldType": "string",
      "fieldRequired": true,
      "fieldDescription": "Name of the company",
      "fieldDefaultValue": null,
      "isEditable": true
    },
    {
      "fieldId": "position",
      "fieldName": "Position",
      "fieldType": "string",
      "fieldRequired": true,
      "fieldDescription": "Your job title",
      "fieldDefaultValue": null,
      "isEditable": true
    },
    {
      "fieldId": "start_date",
      "fieldName": "Start Date",
      "fieldType": "timestamp",
      "fieldRequired": true,
      "fieldDescription": "When you started working",
      "fieldDefaultValue": null,
      "isEditable": true
    },
    {
      "fieldId": "end_date",
      "fieldName": "End Date",
      "fieldType": "timestamp",
      "fieldRequired": false,
      "fieldDescription": "When you left (leave empty if current)",
      "fieldDefaultValue": null,
      "isEditable": true
    }
  ]
}

Submission Example:

{
  "employment_history": [
    {
      "company_name": "Tech Corp",
      "position": "Software Engineer",
      "start_date": "2020-01-15T00:00:00Z",
      "end_date": "2022-06-30T00:00:00Z"
    },
    {
      "company_name": "Innovation Inc",
      "position": "Senior Developer",
      "start_date": "2022-07-01T00:00:00Z",
      "end_date": null
    }
  ]
}

Note: For list_section fields, create an array of objects, where each object follows the structure defined by the children's fieldIds as keys.

Nested Section Mapping

For nested sections, maintain the hierarchical structure in your payload:

Nested requirement object (Simplified):

{
  "fieldId": "personal_details",
  "fieldType": "section",
  "children": [
    {
      "fieldId": "name",
      "fieldType": "string"
    },
    {
      "fieldId": "address_info",
      "fieldType": "section",
      "children": [
        {
          "fieldId": "street",
          "fieldType": "string"
        },
        {
          "fieldId": "city",
          "fieldType": "string"
        }
      ]
    }
  ]
}

Corresponding payload:

{
  "personal_details": {
    "name": "John Smith",
    "address_info": {
      "street": "123 Main St",
      "city": "New York"
    }
  }
}

Complete Example

Example Requirements Response

{
  "success": true,
  "data": {
    "message": "KYC requirements retrieved successfully",
    "kycRequirements": [
      {
        "fieldId": "personal_details",
        "fieldName": "Personal Details",
        "fieldType": "section",
        "fieldRequired": true,
        "fieldDescription": "Basic information about you",
        "children": [
          {
            "fieldId": "full_name",
            "fieldName": "Full Name",
            "fieldType": "string",
            "fieldRequired": true,
            "fieldDescription": "Your full legal name",
            "fieldDefaultValue": null,
            "isEditable": true
          },
          {
            "fieldId": "date_of_birth",
            "fieldName": "Date of Birth",
            "fieldType": "timestamp",
            "fieldRequired": true,
            "fieldDescription": "Your date of birth",
            "fieldDefaultValue": null,
            "isEditable": true
          }
        ]
      },
      {
        "fieldId": "address",
        "fieldName": "Residential Address",
        "fieldType": "section",
        "fieldRequired": true,
        "fieldDescription": "Where you currently live",
        "children": [
          {
            "fieldId": "country",
            "fieldName": "Country",
            "fieldType": "select",
            "fieldRequired": true,
            "fieldDescription": "Country of residence",
            "fieldChoices": [
              { "value": "US", "label": "United States" },
              { "value": "CA", "label": "Canada" }
            ],
            "fieldDefaultValue": null,
            "isEditable": true
          },
          {
            "fieldId": "street_address",
            "fieldName": "Street Address",
            "fieldType": "string",
            "fieldRequired": true,
            "fieldDescription": "Street name and number",
            "fieldDefaultValue": null,
            "isEditable": true
          }
        ]
      },
      {
        "fieldId": "employment_history",
        "fieldName": "Employment History",
        "fieldType": "list_section",
        "fieldRequired": true,
        "fieldDescription": "List of your previous employment",
        "children": [
          {
            "fieldId": "company_name",
            "fieldName": "Company Name",
            "fieldType": "string",
            "fieldRequired": true,
            "fieldDescription": "Name of the company",
            "fieldDefaultValue": null,
            "isEditable": true
          },
          {
            "fieldId": "position",
            "fieldName": "Position",
            "fieldType": "string",
            "fieldRequired": true,
            "fieldDescription": "Your job title",
            "fieldDefaultValue": null,
            "isEditable": true
          },
          {
            "fieldId": "start_date",
            "fieldName": "Start Date",
            "fieldType": "timestamp",
            "fieldRequired": true,
            "fieldDescription": "When you started working",
            "fieldDefaultValue": null,
            "isEditable": true
          },
          {
            "fieldId": "end_date",
            "fieldName": "End Date",
            "fieldType": "timestamp",
            "fieldRequired": false,
            "fieldDescription": "When you left (leave empty if current)",
            "fieldDefaultValue": null,
            "isEditable": true
          }
        ]
      },
      {
        "fieldId": "verification_documents",
        "fieldName": "Verification Documents",
        "fieldType": "section",
        "fieldRequired": true,
        "fieldDescription": "Documents required for verification",
        "children": [
          {
            "fieldId": "primary_id",
            "fieldName": "Primary ID",
            "fieldType": "document",
            "fieldRequired": true,
            "fieldDescription": "Passport or government-issued ID",
            "fieldDefaultValue": null,
            "isEditable": true
          },
          {
            "fieldId": "additional_documents",
            "fieldName": "Additional Documents",
            "fieldType": "document_list",
            "fieldRequired": false,
            "fieldDescription": "Any additional supporting documents",
            "fieldDefaultValue": null,
            "isEditable": true
          }
        ]
      },
      {
        "fieldId": "agreements",
        "fieldName": "Legal Agreements",
        "fieldType": "section",
        "fieldRequired": true,
        "fieldDescription": "Required legal agreements",
        "children": [
          {
            "fieldId": "terms_acceptance",
            "fieldName": "Terms Acceptance",
            "fieldType": "boolean",
            "fieldRequired": true,
            "fieldDescription": "I agree to the [Terms & Conditions](https://example.com/terms.pdf)",
            "fieldDefaultValue": false,
            "isEditable": true
          }
        ]
      }
    ]
  }
}

Corresponding Complete Submission Payload

Based on the requirements example above, a valid submission payload would look like:

{
  "personal_details": {
    "full_name": "John Smith",
    "date_of_birth": "1985-07-15T00:00:00Z"
  },
  "address": {
    "country": "US",
    "street_address": "123 Main Street, Apt 4B"
  },
  "employment_history": [
    {
      "company_name": "Tech Corp",
      "position": "Software Engineer",
      "start_date": "2020-01-15T00:00:00Z",
      "end_date": "2022-06-30T00:00:00Z"
    },
    {
      "company_name": "Innovation Inc",
      "position": "Senior Developer",
      "start_date": "2022-07-01T00:00:00Z",
      "end_date": null
    }
  ],
  "verification_documents": {
    "primary_id": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEA...",
    "additional_documents": [
      "data:application/pdf;base64,JVBERi0xLjUNCiW1tbW...",
      "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAAAOh..."
    ]
  },
  "agreements": {
    "terms_acceptance": true
  }
}

Markdown Support

Both fieldName and fieldDescription may contain markdown-formatted text, including hyperlinks. The markdown formatting serves several important purposes:

Use Cases for Markdown

Documentation Links: Link to detailed documentation or guidelines

Terms & Conditions: Provide links to legal documents that need to be agreed to

External Resources: Link to reference materials or help resources

Styling: Apply emphasis, lists, or other formatting to improve readability

Instruction Formatting: Structure complex instructions with headers, lists, and emphasis

Supported Markdown Features

The following markdown features should be supported by your client application:

Links: [Link Text](https://example.com)

Emphasis: *italic* and **bold** text

Lists: Both ordered and unordered lists

Paragraphs: Line breaks for better content organization

Headers: For structuring longer descriptions

Examples

Boolean field with Terms & Conditions link:

{
  "fieldId": "terms_agreement",
  "fieldName": "Terms Agreement",
  "fieldType": "boolean",
  "fieldRequired": true,
  "fieldDescription": "I agree to the [Terms & Conditions](https://example.com/terms.pdf) and [Privacy Policy](https://example.com/privacy.pdf)",
  "fieldDefaultValue": false,
  "isEditable": true
}

Document field with formatting and links:

{
  "fieldId": "proof_of_residence",
  "fieldName": "Proof of Residence",
  "fieldType": "document",
  "fieldRequired": true,
  "fieldDescription": "Please upload **one** of the following documents:\n\n- Utility bill (not older than 3 months)\n- Bank statement (not older than 3 months)\n- Government-issued document showing address\n\nLearn more about [acceptable documents](https://example.com/docs/residence-proof).",
  "fieldDefaultValue": null,
  "isEditable": true
}

Document Submission Guidelines

For document and document_list fields:

Use the base64 URI data string format: data:[<media type>][;base64],<data>

Include the proper content type prefix (e.g., data:image/jpeg;base64, or data:application/pdf;base64,)

Commonly supported formats include JPEG, PNG, and PDF

Be aware of file size limits (typically 10MB or less per document)

Partner Implementation Best Practices

Progressive Form Rendering: Break complex requirements into steps for better user experience

Respect Field Properties: Honor the fieldRequired and isEditable properties

Conditional Display: Some sections may only be relevant based on other field values

Markdown Rendering: Properly render markdown in field names and descriptions

Pre-Validation: Validate field formats on the client before submission

Document Preparation: Inform users about acceptable document formats and sizes

Default Values: Use the provided fieldDefaultValue when available

Accessibility: Ensure your form is accessible to all users

KYC Requirements

Core Properties

Type-Specific Properties

Property Behavior by Field Type

Field-to-Payload Mapping

String Fields

Number Fields

Boolean Fields

Select Fields

Timestamp Fields

Document Fields

Document List Fields

IP Address Fields

Section Fields

List Section Fields

Nested Section Mapping

Complete Example

Example Requirements Response

Corresponding Complete Submission Payload

Markdown Support

Use Cases for Markdown

Supported Markdown Features

Examples

Document Submission Guidelines

Request

Responses

KYC Requirements

Core Properties#

Type-Specific Properties#

Property Behavior by Field Type#

Field-to-Payload Mapping#

String Fields#

Number Fields#

Boolean Fields#

Select Fields#

Timestamp Fields#

Document Fields#

Document List Fields#

IP Address Fields#

Section Fields#

List Section Fields#

Nested Section Mapping#

Complete Example#

Example Requirements Response#

Corresponding Complete Submission Payload#

Markdown Support#

Use Cases for Markdown#

Supported Markdown Features#

Examples#

Document Submission Guidelines#

Request

Responses

Core Properties

Type-Specific Properties

Property Behavior by Field Type

Field-to-Payload Mapping

String Fields

Number Fields

Boolean Fields

Select Fields

Timestamp Fields

Document Fields

Document List Fields

IP Address Fields

Section Fields

List Section Fields

Nested Section Mapping

Complete Example

Example Requirements Response

Corresponding Complete Submission Payload

Markdown Support

Use Cases for Markdown

Supported Markdown Features

Examples

Document Submission Guidelines