Submit KYC API

The Submit KYC API lets you programmatically submit identity verification details for a customer or entity. Use this API as an alternative to the Pre-built KYC Form.

For corporate customers, the applicant and all individual stakeholders are treated as separate entities. You must call the Submit KYC API separately for each entity to complete their respective KYC process.

note

Initiate KYC only after you receive a webhook with subStatus: awaiting_kyc. See Step 6 of the onboarding flow.

API reference

POST /api/v5/client/{clientHashId}/customer/{customerHashId}/submitKyc

See Submit KYC for the full API reference.

Path parameters

Parameter	Type	Required	Description
`clientHashId`	string	Yes	Unique client identifier generated and shared before API handshake.
`customerHashId`	string	Yes	Unique hash ID of the customer received in the response of the Create Customer v5 API.

Request body parameters

Field	Required	Type	Description
`region`	Mandatory	string	Regulatory region where the customer is being onboarded (for example, `US`).
`entityType`	Mandatory	enum	Type of entity for which KYC is being submitted. Values: `individual_stakeholder`, `applicant`, `individual_customer`.
`isResident`	Mandatory	boolean	Whether the entity is a resident of the specified `region`. Set to `false` if the entity resides outside the region (for example, if `region = US` and the entity resides in `GB`).
`entityReferenceId`	Mandatory	string	The `referenceId` of the entity returned in the Create Customer v5 API response. You may also pass the `externalId` provided during customer creation.
`kycMode`	Mandatory	enum	KYC verification method. Values: `e_kyc` (electronic, auto-verified), `biometric_kyc` (liveness check against their government-issued document) or`manual_kyc` (requires manual review by Nium compliance).
`proofOfIdentityDocument`	Mandatory	array of object	Identity document details for the entity. See fields below.
`proofOfIdentityDocument.type`	Mandatory	enum	Document type. Use `national_id` if `isResident = true`. If `isResident = false`, use `national_id`, `passport`, or `driver_licence`.
`proofOfIdentityDocument.identificationNumber`	Mandatory	string	Identification number of the document (for example, nationalID number or passport number).
`proofOfIdentityDocument.issuanceCountry`	Mandatory	string	Two-letter ISO country code of the country where the document was issued. Use the Fetch Corporate Constants API with `category = countryName` for valid values.
`proofOfIdentityDocument.expiryDate`	Conditional	date	Expiry date of the document. Required if `type` is `passport` or `driver_licence`.
`proofOfIdentityDocument.fileIds`	Conditional	array of UUID	Required if `kycMode = manual_kyc`. Provide the `fileId` values from the Upload File API response.
`proofOfAddressDocument`	Optional	object	Address proof details. Acceptable documents are: Utility bill, bank statement, govt issued letter etc.
`proofOfAddressDocument.type`	Optional	enum	Type of address document. Value: `proof_of_address`.
`proofOfAddressDocument.fileIds`	Optional	array of string	`fileId` values from the Upload File API response.
`stakeholderDetails`	Optional	Object	New stakeholder data identified by Nium during verification. Applciable in case of AU region.

Sample requests

For US Resident — electronic KYC (`isResident=true`, `kycMode=e_kyc`)

{
    "region": "US",
    "entityType": "applicant",
    "isResident": true,
    "kycMode": "e_kyc",
    "entityReferenceId": "REF123456",
    "proofOfIdentityDocument": [
        {
            "type": "national_id",
            "identificationNumber": "1234",
            "issuanceCountry": "US"
        }
    ]
}

For US Resident — manual KYC (`isResident=true`, `kycMode=manual_kyc`)

{
    "region": "US",
    "entityType": "individual_stakeholder",
    "isResident": true,
    "kycMode": "manual_kyc",
    "entityReferenceId": "8aaddf0f-a4c9-4c3c-bdd8-2534cb5a4008",
    "proofOfIdentityDocument": [
          {
            "type": "passport",
            "identificationNumber": "123456789",
            "issuanceCountry": "US",
            "expiryDate":"2028-09-01",
            "fileIds": [
                "6502ff10-86bf-43f9-ade8-3da16374acc2"                
            ]
        },{
            "type": "national_id",
            "identificationNumber": "123456789",
            "issuanceCountry": "US"            
        }
    ],
    "proofOfAddressDocument": {
        "type": "proof_of_address",
        "fileIds": [
            "1218ab50-500e-4c8c-98e8-2dd44068d044"
        ]
    }
}

For US Non-resident — manual KYC (`isResident=false`, `kycMode=manual_kyc`)

{
    "region": "US",
    "entityType": "individual_stakeholder",
    "isResident": false,
    "kycMode": "manual_kyc",
    "entityReferenceId": "REF123456",
    "proofOfIdentityDocument": [
        {
            "type": "passport",
            "identificationNumber": "JP10FAKAIV",
            "issuanceCountry": "GB",
            "fileIds": [
                "1218ab50-500e-4c8c-98e8-2dd44068d044"
            ]
        }
    ],
    "proofOfAddressDocument": {
        "type": "proof_of_address",
        "fileIds": [
            "1218ab50-500e-4c8c-98e8-2dd44068d044"
        ]
    }
}

For US Non-resident — biometric KYC (`isResident=false`, `kycMode=biometric_kyc`)

{
    "region": "US",
    "entityType": "individual_stakeholder",
    "isResident": false,
    "kycMode": "manual_kyc",
    "entityReferenceId": "REF123456"
}

Responses

200 — Success (manual_kyc)

{
    "customerHashId": "83e9cb73-c8f3-4ada-8371-ac215826461q",
    "kycStatus": "initiated",
    "externalId": "357244f3-b4f9-4c54-92df-b472123a6067",
    "referenceId": "9215203c-8ba5-43e1-b780-70c2d77115ef",
    "entityType": "applicant",
    "kycMode": "manual_kyc"
}

200 — Success (biometric_kyc)

{
    "customerHashId": "83e9cb73-c8f3-4ada-8371-ac215826461q",
    "kycStatus": "initiated",
    "externalId": "357244f3-b4f9-4c54-92df-b472123a6067",
    "referenceId": "9215203c-8ba5-43e1-b780-70c2d77115ef",
    "entityType": "applicant",
    "kycMode": "biometric_kyc",
    "redirectUrl":"https://idv.sandbox.nium.com/sandbox/compliance/callback/load?referenceNumber=4a72c7b1-ca24-4921-a414-470823f8e982"
}

400 — Bad Request

The errors array in the response describes what failed. Correct the data and resubmit.

// Missing mandatory field
{
    "errors": [
        {
            "code": "missing_required_fields",
            "description": "entityReferenceId is required",
            "field": "entityReferenceId"
        }
    ]
}

// Invalid document type for the region/residency combination
{
    "errors": [
        {
            "code": "invalid_input",
            "description": "Invalid value 'passport'. Allowed values: [national_id]",
            "field": "proofOfIdentityDocument[0].type"
        }
    ]
}

// Invalid identification number format
{
    "errors": [
        {
            "code": "invalid_input",
            "description": "must match \"^\\d{4}$|^\\d{9}$\"",
            "field": "proofOfIdentityDocument[0].identificationNumber"
        }
    ]
}

KYC status reference

When a customer is created using the Create Customer v5 API, the response includes a kycStatus for each entity.

`kycStatus`	Description	Next action
`kyc_required`	KYC is required for this entity.	Call the Submit KYC API for this entity.
`kyc_not_required`	KYC is not required for this entity.	No action required.
`initiated`	KYC details submitted; verification initiated by Nium.	Wait for a `CUSTOMER_ENTITY_KYC_STATUS` webhook with the final status.
`submitted`	Applicable for `manual_kyc`. KYC details submitted for review.	Terminal status — no further action required.
`verified`	Applicable for `e_kyc`. KYC successfully verified.	Terminal status — no further action required.
`failed`	Applicable for `e_kyc`. KYC verification failed.	Reinitiate KYC with `kycMode = manual_kyc`.

Webhooks

Nium sends a CUSTOMER_ENTITY_KYC_STATUS webhook whenever the kycStatus of an entity changes.

{
    "clientHashId": "9f9e58c3-7b48-4cf7-8195-76a8a94f36ed",
    "customerHashId": "83e9cb73-c8f3-4ada-8371-ac215826461e",
    "template": "CUSTOMER_ENTITY_KYC_STATUS",
    "customerType": "corporate",
    "kycStatus": "verified",
    "kycMode": "e_kyc",
    "externalId": "357244f3-b4f9-4c54-92df-b472123a6067",
    "referenceId": "9215203c-8ba5-43e1-b780-70c2d77115ef"
}

Field	Type	Description
`clientHashId`	UUID	Unique client identifier.
`customerHashId`	UUID	Unique customer identifier.
`template`	string	Always `CUSTOMER_ENTITY_KYC_STATUS`.
`customerType`	enum	`individual` or `corporate`.
`kycStatus`	enum	KYC status of the entity: `submitted`, `verified`, or `failed`.
`kycMode`	enum	Verification mode used: `e_kyc` or `manual_kyc`.
`externalId`	string	Client-provided unique ID of the entity.
`referenceId`	UUID	Nium-generated unique ID of the entity.
`redirectUrl`	string	Client needs to send this link to the applicant/stakehodler to complete the KYC verification on Nium page.

For more information, see Notifications and Webhooks.

API reference​

Path parameters​

Request body parameters​

Sample requests​

For US Resident — electronic KYC (isResident=true, kycMode=e_kyc)​

For US Resident — manual KYC (isResident=true, kycMode=manual_kyc)​

For US Non-resident — manual KYC (isResident=false, kycMode=manual_kyc)​

For US Non-resident — biometric KYC (isResident=false, kycMode=biometric_kyc)​

Responses​

200 — Success (manual_kyc)​

200 — Success (biometric_kyc)​

400 — Bad Request​

KYC status reference​

Webhooks​