Documentation

Pre-registering via API

Digiteal KYC API - Pre-Registration Guide

This guide outlines the process for pre-registering companies as well as submitting Know Your Customer (KYC) documentation using the Digiteal API. Integrating these endpoints allows you to seamlessly embed Digiteal's verification compliance directly into your platform.


1. Company Pre-Registration

To pre-register a company or update its missing information, submit a payload containing the company's KYC details and the associated contact person.

POST /api/v1/kyc/company

Payload Structure

The payload must conform to the CompanyCustomerKYCInfo schema:

  • customerCompany: Contains the legal company details (e.g., VAT number, IBANs, company name, pack type) and the nested contactPerson object.
  • customerInfo: Contains the basic customer association, including customerId, product type, and an optional welcomeMessage.
  • contractApproval: (Optional) Contains the IP address, User-Agent, and approval date for terms and conditions acceptance.
🚧

Important Uniqueness Requirements

To successfully pre-register a company without throwing a validation error, the following fields must be strictly unique across your integration:

  • Company Identity: The vatNumber (or alternatively, the identificationNumber) within customerCompany.
  • Contact Identity: The email address within the nested contactPerson object.
  • System Identity: The customerId within customerInfo.

Example Request

{
    "customerCompany": {
        "companyName": "Example Company LLC",
        "creationDate": "2020-01-01",
        "vatNumber": "BE0123456789",
        "integratorVATNumber": "BE9876543210",
        "pack": "START",
        "paymentMethods": ["BANCONTACT"],
        "ibans": ["BE00000000000000"],
        "contactPerson": {
            "firstName": "John",
            "lastName": "Doe",
            "email": "[email protected]",
            "language": "EN",
            "nationalities": ["BE"],
            "integratorVat": "BE9876543210",
            "ibans": ["BE00000000000000"]
        }
    },
    "customerInfo": {
        "customerId": "123e4567-e89b-12d3-a456-426614174000",
        "vatNumber": "BE9876543210",
        "welcomMessage": "Welcome to Digiteal!"
    },
    "contractApproval": {
        "approvalDate": "2026-05-13",
        "ipAddress": "192.0.2.1",
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
    }
}

2. Uploading KYC Documents

After pre-registering an entity, you will need to upload supporting KYC documentation to attach to the contact person of the company.

POST /api/v1/kyc/document

🚧

Important

This endpoint requires a multipart/form-data request. The file binary MUST be passed in the document form field.

Query Parameters

When uploading a document, pass the following query parameters in the URL:

ParameterTypeRequiredDescription
emailStringYesThe email of the contact person to which the document should be attached.
typeEnumYesThe document type. Common values include: ID, ID_FRONT, ID_BACK, SELFIE_WITH_ID, BANK_MANDATE, BANK_ACCOUNT_VALIDATION, BY_LAWS.
nameStringYesThe file name (e.g., id_front.jpeg or mandate.pdf).
requesterVATStringNo*The VAT number of the company requesting the upload.
requesterIdentificationNumberStringNo*The identification number of the company requesting the upload.

** Note: Either requesterVAT or requesterIdentificationNumber must be provided.*

Examples

Uploading an ID Card (Front)

POST /api/v1/kyc/[email protected]&name=id_front.jpeg&type=ID_FRONT&requesterVAT=BE9876543210
Content-Type: multipart/form-data

[Attached binary image file in "document" field]

Uploading a Selfie with ID

POST /api/v1/kyc/[email protected]&name=selfie.jpeg&type=SELFIE_WITH_ID&requesterVAT=BE9876543210
Content-Type: multipart/form-data

[Attached binary image file in "document" field]

Uploading a Bank Mandate (PDF)

POST /api/v1/kyc/[email protected]&name=mandate.pdf&type=BANK_MANDATE&requesterVAT=BE9876543210
Content-Type: multipart/form-data

[Attached binary PDF file in "document" field]

3. Retrieving Contracts for Approval

To retrieve the latest contracts or terms and conditions that a company or person must approve before becoming an active Digiteal customer, use the following endpoints:

These endpoints accept an optional language query parameter (defaulting to EN) and will return an array of ContractDetails. This array includes the localized name and URL to the respective contract documents.

Updated 3 days ago