KYC Log Service

Manages the KYC review workflow, including reviewer comments, additional document requests, and status tracking.

Get KYC Logs

GET /v1/kyc/{id}/logs

Retrieves all logs for a specific KYC verification.

Path Parameters:

Parameter	Type	Description
id	string	KYC ID (pattern: kyc_*)

Response:

{
  "object": "kyc_log",
  "kyclog": {
    "id": "klg_abc123",
    "kyc_id": "kyc_abc123",
    "customer_id": "cus_abc12345",
    "messages": [
      {
        "date": "2025-01-15T10:00:00Z",
        "message": "KYC verification initiated",
        "reviewer_id": null,
        "kyc_status": "initiated",
        "version": 1
      },
      {
        "date": "2025-01-16T14:30:00Z",
        "message": "Document verified successfully",
        "reviewer_id": "emp_7890",
        "kyc_status": "verified",
        "version": 1
      }
    ],
    "additional_documents": []
  }
}

---

Add Message

POST /v1/kyc/{id}/logs

Adds a new message/comment to the KYC log.

Path Parameters:

Parameter	Type	Description
id	string	KYC ID (pattern: kyc_*)

Request Body:

{
  "comment": "Document reviewed. Additional proof of address required.",
  "reviewer_id": "emp_7890"
}

Field	Type	Required	Description
comment	string	Yes	Message content
reviewer_id	string	No	Reviewer ID (omit for system-generated messages)

Response:

{
  "object": "bool",
  "status": true
}

---

Upload Additional Document

POST /v1/kyc/{id}/logs/save

Uploads an additional document requested during KYC review. Uses multipart/form-data.

Path Parameters:

Parameter	Type	Description
id	string	KYC ID (pattern: kyc_*)

Request Body (multipart/form-data):

Field	Type	Required	Description
reference	string	Yes	Document reference from the KYC log
document_name	string	Yes	Description of the additional document
type	string	Yes	Document type
attachment	file	Yes	The document file

Response:

{
  "object": "bool",
  "status": true
}

---

Add Document Validity

POST /v1/kyc/{id}/logs/save-date

Sets the validity period for an uploaded additional document.

Path Parameters:

Parameter	Type	Description
id	string	KYC ID (pattern: kyc_*)

Request Body:

{
  "expiry_date": "2027-01-15",
  "reference": "ref_doc_001"
}

Field	Type	Required	Description
expiry_date	string	Yes	Document expiration date
reference	string	Yes	Document reference from the KYC log

Response:

{
  "object": "bool",
  "saved_date": true
}

---

Review KYC Verification

PUT /v1/customers/{id}/kyc/{kyc_id}/reviews

Allows a back-office reviewer to approve, reject, or request additional documents for a KYC verification.

Path Parameters:

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

Request Body:

{
  "status": "verified",
  "reviewer_id": "emp_7890",
  "rejection_reason": null,
  "additional_request": {
    "comment": null,
    "checklist_items": []
  }
}

Field	Type	Required	Description
status	string	Yes	New status: verified, pending, or rejected
reviewer_id	string	Yes	Reviewer's employee ID
rejection_reason	string	Conditional	Required if status is rejected
additional_request	object	Yes	Additional document requests (for pending status)

Additional Request Object:

Field	Type	Description
comment	string	Reason for pending status
checklist_items	array	List of required documents

Response:

{
  "object": "kyc",
  "kyc": {
    "kyc_id": "kyc_abc123",
    "status": "verified",
    ...
  }
}

---

Submit Documents for Review

POST /v1/customers/{id}/kyc/{kyc_id}/reviews/ready

Customer signals that all requested additional documents have been uploaded and are ready for review.

Path Parameters:

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

Response:

{
  "object": "ready",
  "submit": true
}

---

Get KYC Verification

GET /v1/customers/{id}/kyc/{kyc_id}

Retrieves details of a specific KYC verification.

Path Parameters:

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

Response:

{
  "object": "kyc",
  "kyc": {
    "kyc_id": "kyc_abc123",
    "customer_id": "cus_abc12345",
    "document_type": "passport",
    "status": "verified",
    ...
  }
}

---

Get Customer KYC Logs

GET /v1/customers/{id}/kyc/logs

Retrieves KYC logs for a customer.

Path Parameters:

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

Response:

{
  "object": "kyc_log",
  "kyclog": {
    "id": "klg_abc123",
    "kyc_id": "kyc_abc123",
    "customer_id": "cus_abc12345",
    "messages": [...],
    "additional_documents": [...]
  }
}