KYC

KYC (Know Your Customer) is a crucial process in financial services to verify the identity of customers, prevent fraud, and comply with regulatory requirements. On this page, we’ll dive into the different KYC endpoints you can use to manage KYC processes programmatically. We'll look at how to query, create, update, and delete KYC records.

The KYC model

The KYC model contains all the information related to a customer's KYC process, including their identity details, verification status, and associated documents.

Properties

Name
id
Type
string
Description
Unique identifier for the KYC record.
Name
customer_id
Type
string
Description
Unique identifier for the customer.
Name
verification_status
Type
string
Description
Current status of the KYC verification (e.g., pending, verified, failed).
Name
document_type
Type
string
Description
Type of document used for verification (e.g., passport, driver’s license).
Name
document_number
Type
string
Description
Document number of the verification document.
Name
created_at
Type
timestamp
Description
Timestamp of when the KYC record was created.
Name
updated_at
Type
timestamp
Description
Timestamp of when the KYC record was last updated.

GET/v1/kyc

List all KYC records

This endpoint allows you to retrieve a paginated list of all your KYC records. By default, a maximum of ten records are shown per page.

Optional attributes

Name
limit
Type
integer
Description
Limit the number of KYC records returned.
Name
customer_id
Type
string
Description
Only show records for the specified customer.
Name
verification_status
Type
string
Description
Only show records with the specified verification status.

Request

GET

/v1/kyc

curl -G https://api.finx.ai/v1/kyc \
  -H "Authorization: Bearer {token}" \
  -d limit=10

Response

{
  "has_more": false,
  "data": [
    {
      "id": "xgQQXg3hrtjh7AvZ",
      "customer_id": "WAz8eIbvDR60rouK",
      "verification_status": "verified",
      "document_type": "passport",
      "document_number": "123456789",
      "created_at": 705103200,
      "updated_at": 705103200
    },
    {
      "id": "hSIhXBhNe8X1d8Et"
      // ...
    }
  ]
}

POST/v1/kyc

Create a KYC record

This endpoint allows you to add a new KYC record. You need to provide the customer ID, verification status, document type, and document number to create a KYC record.

Required attributes

Name
customer_id
Type
string
Description
Unique identifier for the customer.
Name
verification_status
Type
string
Description
Current status of the KYC verification (e.g., pending, verified, failed).
Name
document_type
Type
string
Description
Type of document used for verification (e.g., passport, driver’s license).
Name
document_number
Type
string
Description
Document number of the verification document.

Request

POST

/v1/kyc'

curl https://api.finx.ai/v1/kyc \
  -H "Authorization: Bearer {token}" \
  -d 'customer_id'="WAz8eIbvDR60rouK" \
  -d 'verification_status'="pending" \
  -d 'document_type'="passport" \
  -d 'document_number'="123456789"

Response

{
  "id": "xgQQXg3hrtjh7AvZ",
  "customer_id": "WAz8eIbvDR60rouK",
  "verification_status": "pending",
  "document_type": "passport",
  "document_number": "123456789",
  "created_at": 705103200,
  "updated_at": 705103200
}

GET/v1/kyc/:id

Retrieve a KYC record

This endpoint allows you to retrieve a KYC record by providing the record id. Refer to the list at the top of this page to see which properties are included with KYC objects.

Request

GET

/v1/kyc/xgQQXg3hrtjh7AvZ

curl https://api.finx.ai/v1/kyc/xgQQXg3hrtjh7AvZ \
  -H "Authorization: Bearer {token}"

Response

{
  "id": "xgQQXg3hrtjh7AvZ",
  "customer_id": "WAz8eIbvDR60rouK",
  "verification_status": "verified",
  "document_type": "passport",
  "document_number": "123456789",
  "created_at": 705103200,
  "updated_at": 705103200
}

PUT/v1/kyc/:id

Update a KYC record

This endpoint allows you to perform an update on a KYC record. Examples of updates are changing the verification status, updating the document type, or modifying the document number.

Optional attributes

Name
verification_status
Type
string
Description
Updated status of the KYC verification (e.g., pending, verified, failed).
Name
document_type
Type
string
Description
Updated type of document used for verification.
Name
document_number
Type
string
Description
Updated document number of the verification document.

Request

PUT

/v1/kyc/xgQQXg3hrtjh7AvZ

curl -X PUT https://api.finx.ai/v1/kyc/xgQQXg3hrtjh7AvZ \
  -H "Authorization: Bearer {token}" \
  -d 'verification_status'="verified"

Response

{
  "id": "xgQQXg3hrtjh7AvZ",
  "customer_id": "WAz8eIbvDR60rouK",
  "verification_status": "verified",
  "document_type": "passport",
  "document_number": "123456789",
  "created_at": 705103200,
  "updated_at": 705103200
}

DELETE/v1/kyc/:id

Delete a KYC record

This endpoint allows you to delete your KYC records in Fin X. Note: This will permanently delete the record and all its data — ensure this is the desired action before proceeding.

Request

DELETE

/v1/kyc/xgQQXg3hrtjh7AvZ

curl -X DELETE https://api.finx.ai/v1/kyc/xgQQXg3hrtjh7AvZ \
  -H "Authorization: Bearer {token}"