Skip to main content

KYC (Know Your Customer) Guide

KYC is a process to verify user identity, ensuring compliance with regulations and preventing fraud or illegal activities. It involves validating personal information and documents.

info

Remember that to perform KYC for a Subaccount, simply pass the subAccountId field as a request parameter.

KYC Level 1 - Web SDK​

To complete KYC Level 1, you will receive a link that redirects to a verification form. Follow the instructions on the site to submit your information. The completion deadline is 24 hours.

HTTP Post Request:​

https://api.sandbox.avenia.io:10952/v2/kyc/level-1/web-sdk

cURL Example:​

curl -X POST "https://api.sandbox.avenia.io:10952/v2/kyc/level-1/web-sdk" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

JSON Response:​

{
  "url": "https://in.sumsub.com/websdk/p/sbx_dC000HhJ0Sel0000"
}

KYC Level 1 - API​

Another way to perform KYC Level 1 for your user is through the API.

HTTP Post Request:​

https://api.sandbox.avenia.io:10952/v2/kyc/level-1/api
info

Remember that to perform this endpoint for a Subaccount, simply pass the subAccountId field as a request parameter.

Fields​

FieldTypeRequiredDescription
fullNamestringYesThe complete name of the individual.
dateOfBirthstringYesThe date of birth of the individual (Format: YYYY-MM-DD).
countryOfDocumentstringYesThe country issuing the document.
documentTypestringYesThe type of document (must be one of ID, Passport, Driver's License).
documentNumberstringYesThe number of the document.
countryOfTaxIdstringYesThe country where the tax identification number was issued.
taxIdNumberstringYesThe tax identification number of the individual.
emailstringNoThe email address of the individual.
phonestringNoThe phone number of the individual.
countrystringYesThe country of residence.
statestringYesThe state/province of residence.
citystringYesThe city of residence.
zipCodestringYesThe postal code of the residence.
streetAddressstringYesThe street address of the residence.
info

All countries and states follow the ISO Alpha-3 standard (Example: USA-CA)

Sample JSON Body:​

{
  "fullName": "Jane Doe",
  "dateOfBirth": "1999-08-16",
  "countryOfDocument": "BRA",
  "documentType": "Passport",
  "documentNumber": "UJ252482",
  "countryOfTaxId": "BRA",
  "taxIdNumber": "75764220173",
  "country": "BRA",
  "state": "SP",
  "city": "SP",
  "zipCode": "12243010",
  "streetAddress": "Rua Madre Paula"
}

cURL Example:​

curl -X POST "https://api.sandbox.avenia.io:10952/v2/kyc/level-1/api" \
     -H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
     -H "Content-Type: application/json" \
     -d '{ ... }'

JSON Response:​

{
  "id": "1ee11163-9tjb-4389-9f84-074ccff7085d"
}

List All KYC Attempts​

Check all KYC attempt histories associated with your account or subaccount.

info

To filter by specific subaccount, add the subAccountId parameter to the request.

HTTP Get Request:​

https://api.sandbox.avenia.io:10952/v2/kyc/attempts

cURL Example:​

curl -X GET "https://api.sandbox.avenia.io:10952/v2/kyc/attempts" \
     -H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

JSON Response Example:​

{
  "attempts": [
    {
      "id": "e51359cd-04b0-4bbc-bf7d-0ee515112d74",
      "levelName": "level-1",
      "submissionData": null,
      "status": "COMPLETED",
      "result": "APPROVED",
      "resultMessage": "",
      "retryable": false,
      "createdAt": "2025-03-25T07:39:40.54713Z",
      "updatedAt": "2025-03-25T07:39:40.54713Z"
    }
  ],
  "cursor": "MTYtMTc0MjQ4MjA5NzAxMQ=="
}

Get KYC Attempt​

Ensure the KYC has been successfully validated.

HTTP Get Request:​

https://api.sandbox.avenia.io:10952/v2/kyc/attempts/{kyc-attempt-id}
info

For subaccount validation, include subAccountId in the request.

cURL Example:

curl -X GET "https://api.sandbox.avenia.io:10952/v2/kyc/attempts/{kyc-attempt-id}" \
     -H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

JSON Response:

{
  "attempt": {
    "id": "e51359cd-04b0-4bbc-bf7d-0ee515112d74",
    "levelName": "level-1",
    "submissionData": null,
    "status": "COMPLETED",
    "result": "APPROVED",
    "resultMessage": "",
    "retryable": false,
    "createdAt": "2025-03-25T07:39:40.54713Z",
    "updatedAt": "2025-03-25T07:39:40.54713Z"
  }
}

KYC - Track KYC Validation​

This endpoint allows you to track the progress and outcome of a specific KYC attempt by ID. The response includes the current status (PENDING, COMPLETED), the final result (APPROVED, REJECTED), and additional context such as retry eligibility and rejection reasons.

HTTP GET Request​

https://api.sandbox.avenia.io:10952/v2/kyc/attempts/**YOUR-KYC-ID-HERE**

cUrl Example​

curl -X GET "https://api.sandbox.avenia.io:10952/v2/kyc/attempts/{kyc-attempt-id}" \
 -H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

JSON Response - COMPLETED example​

{
  "attempt": {
    "id": "e51359cd-04b0-4bbc-bf7d-0ee515112d74",
    "levelName": "level-1",
    "submissionData": null,
    "status": "COMPLETED",
    "result": "APPROVED",
    "resultMessage": "",
    "retryable": false,
    "createdAt": "2025-03-25T07:39:40.54713Z",
    "updatedAt": "2025-03-25T07:39:40.54713Z"
  }
}

JSON Response - PENDING example​

{
  "attempt": {
    "id": "b83802a1-afe9-46ac-96d6-ade6c5961bd3",
    "levelName": "level-1",
    "submissionData": null,
    "status": "PENDING",
    "result": "",
    "resultMessage": "",
    "retryable": false,
    "createdAt": "2025-03-26T22:50:14.201695Z",
    "updatedAt": "2025-03-26T22:50:14.201695Z"
  }
}

JSON Response - REJECT example​

{
  "attempt": {
    "id": "5bafd6cd-ec40-4dd3-83e0-a5af117c304a",
    "levelName": "level-1",
    "submissionData": null,
    "status": "COMPLETED",
    "result": "REJECTED",
    "resultMessage": "name does not match",
    "retryable": false,
    "createdAt": "2025-03-26T22:50:14.201695Z",
    "updatedAt": "2025-03-26T22:50:14.201695Z"
  }
}