KYC Service

Manages Know Your Customer verification records.

List KYC Verifications

GET /v1/customers/{id}/kyc

Retrieves all KYC verification records for a customer.

Path Parameters:

Parameter	Type	Description
id	string	Customer ID (pattern: usr_*)

Query Parameters:

Parameter	Type	Default	Description
page_size	integer	50	Max results per page (max: 100)
page_token	string	-	Token for next page

Response:

{
  "object": "list",
  "data": [
    {
      "kyc_id": "kyc_abc123",
      "customer_id": "cus_abc12345",
      "document_type": "passport",
      "document_front": {
        "file_id": "file_001",
        "file_bucket": "kyc-docs",
        "file_link": "/files/kyc-docs/file_001"
      },
      "document_back": null,
      "liveness": {
        "file_id": "file_002",
        "file_bucket": "kyc-docs",
        "file_link": "/files/kyc-docs/file_002"
      },
      "verification_result": {
        "name": "John Doe",
        "date_of_birth": "1990-01-15",
        "id_number": "ABC123456",
        "liveness_score": 0.98,
        "match_score": 0.95
      },
      "reviewer_id": "emp_7890",
      "status": "verified",
      "rejection_reason": null,
      "version": 1,
      "submitted_at": "2025-01-15T10:00:00Z",
      "reviewed_at": "2025-01-16T14:30:00Z"
    }
  ],
  "has_more": false,
  "next_page_token": null
}

KYC Status Values

Status	Description
initiated	Document upload started
under_review	Submitted for back-office review
pending	Additional documents requested from customer
verified	Approved by reviewer
rejected	Rejected by reviewer

Document Types

Type	Description
passport	International passport
dire	DIRE (Documento de Identidade de Residente Estrangeiro)
bi	BI (Bilhete de Identidade)