KYC (Know Your Customer)
Know Your Customer (KYC) verification is a crucial compliance requirement for telecommunications services. On this page, we will dive into the different KYC endpoints you can use to manage customer verification processes programmatically. We will look at how to submit address details, upload supporting documents, and manage the verification workflow.
The KYC verification model
The KYC verification process involves collecting and verifying customer information and supporting documents to ensure compliance with telecommunications regulations. This includes address verification, identity document uploads, and proof of business registration where applicable.
Properties
- Name
id- Type
- string
- Description
Unique identifier for the KYC verification request.
- Name
number_id- Type
- string
- Description
The virtual number ID this KYC verification is associated with.
- Name
status- Type
- string
- Description
Current verification status: "pending", "under_review", "approved", "rejected".
- Name
type- Type
- string
- Description
Type of KYC verification: "individual", "business".
- Name
address- Type
- object
- Description
Address information submitted for verification.
- Name
documents- Type
- array
- Description
Array of uploaded document references.
- Name
submitted_at- Type
- timestamp
- Description
Timestamp when the KYC request was submitted.
- Name
reviewed_at- Type
- timestamp
- Description
Timestamp when the KYC request was reviewed (if applicable).
- Name
rejection_reason- Type
- string
- Description
Reason for rejection if the verification was declined.
- Name
expires_at- Type
- timestamp
- Description
Expiration timestamp for the verification (if applicable).
Submit address details
This endpoint allows you to submit address details and related information for KYC verification of a specific virtual number. This is typically the first step in the KYC process before uploading supporting documents.
Required attributes
- Name
address_line_1- Type
- string
- Description
Primary address line (street address).
- Name
city- Type
- string
- Description
City or locality.
- Name
state_province- Type
- string
- Description
State, province, or region.
- Name
postal_code- Type
- string
- Description
Postal or ZIP code.
- Name
country- Type
- string
- Description
ISO 3166-1 alpha-2 country code.
- Name
verification_type- Type
- string
- Description
Type of verification: "individual" or "business".
Optional attributes
- Name
address_line_2- Type
- string
- Description
Secondary address line (apartment, suite, etc.).
- Name
company_name- Type
- string
- Description
Company name (required for business verification).
- Name
tax_id- Type
- string
- Description
Tax identification number (for business verification).
- Name
contact_person- Type
- string
- Description
Primary contact person name (for business verification).
- Name
phone_number- Type
- string
- Description
Contact phone number for verification purposes.
- Name
email- Type
- string
- Description
Contact email address for verification updates.
Request
curl -X POST https://api.xnumbers.io/v1/numbers/num_WAz8eIbvDR60rouK/KYC/address \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"address_line_1": "123 Main Street",
"address_line_2": "Suite 456",
"city": "New York",
"state_province": "NY",
"postal_code": "10001",
"country": "US",
"verification_type": "business",
"company_name": "Acme Telecommunications Inc.",
"tax_id": "12-3456789",
"contact_person": "John Smith",
"phone_number": "+1-555-123-4567",
"email": "compliance@acmetel.com"
}'
Response
{
"id": "kyc_4Kp8mN9qL2xY6wR3",
"number_id": "num_WAz8eIbvDR60rouK",
"status": "pending",
"type": "business",
"address": {
"address_line_1": "123 Main Street",
"address_line_2": "Suite 456",
"city": "New York",
"state_province": "NY",
"postal_code": "10001",
"country": "US"
},
"company_name": "Acme Telecommunications Inc.",
"tax_id": "12-3456789",
"contact_person": "John Smith",
"phone_number": "+1-555-123-4567",
"email": "compliance@acmetel.com",
"documents": [],
"submitted_at": "2022-01-01T10:00:00Z",
"reviewed_at": null,
"rejection_reason": null,
"expires_at": null
}
This endpoint allows you to update the address details that were previously submitted for KYC verification. This is useful for correcting address information or updating it if your business has moved.
Optional attributes
- Name
address_line_1- Type
- string
- Description
Updated primary address line (street address).
- Name
address_line_2- Type
- string
- Description
Updated secondary address line (apartment, suite, etc.).
- Name
city- Type
- string
- Description
Updated city or locality.
- Name
state_province- Type
- string
- Description
Updated state, province, or region.
- Name
postal_code- Type
- string
- Description
Updated postal or ZIP code.
- Name
country- Type
- string
- Description
Updated ISO 3166-1 alpha-2 country code.
- Name
company_name- Type
- string
- Description
Updated company name (for business verification).
- Name
contact_person- Type
- string
- Description
Updated primary contact person name.
- Name
phone_number- Type
- string
- Description
Updated contact phone number.
- Name
email- Type
- string
- Description
Updated contact email address.
Request
curl -X PATCH https://api.xnumbers.io/v1/numbers/num_WAz8eIbvDR60rouK/KYC/address \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"address_line_1": "456 Business Ave",
"address_line_2": "Floor 10, Suite 1001",
"city": "New York",
"state_province": "NY",
"postal_code": "10002",
"phone_number": "+1-555-987-6543",
"email": "updated-compliance@acmetel.com"
}'
Response
{
"id": "kyc_4Kp8mN9qL2xY6wR3",
"number_id": "num_WAz8eIbvDR60rouK",
"status": "pending",
"type": "business",
"address": {
"address_line_1": "456 Business Ave",
"address_line_2": "Floor 10, Suite 1001",
"city": "New York",
"state_province": "NY",
"postal_code": "10002",
"country": "US"
},
"company_name": "Acme Telecommunications Inc.",
"tax_id": "12-3456789",
"contact_person": "John Smith",
"phone_number": "+1-555-987-6543",
"email": "updated-compliance@acmetel.com",
"documents": [
{
"id": "doc_8mN4pL9qX2vY7wK5",
"document_type": "business_registration",
"filename": "business_license.pdf",
"status": "verified",
"uploaded_at": "2022-01-01T10:10:00Z"
}
],
"submitted_at": "2022-01-01T10:00:00Z",
"updated_at": "2022-01-01T10:26:40Z",
"reviewed_at": null,
"rejection_reason": null,
"expires_at": "2023-01-01T00:00:00Z"
}
Upload supporting documents
This endpoint allows you to upload supporting documents for KYC verification. Documents should be uploaded after submitting address details. Multiple documents can be uploaded by making multiple requests to this endpoint.
Required attributes
- Name
file- Type
- file
- Description
The document file to upload (PDF, JPG, PNG formats supported).
- Name
document_type- Type
- string
- Description
Type of document: "identity", "address_proof", "business_registration", "tax_certificate", "utility_bill", "bank_statement", "other".
Optional attributes
- Name
description- Type
- string
- Description
Description or notes about the uploaded document.
- Name
expiration_date- Type
- string
- Description
Document expiration date (ISO 8601 format) if applicable.
File requirements
- Name
max_size- Type
- string
- Description
Maximum file size: 10MB per document.
- Name
formats- Type
- array
- Description
Supported formats: PDF, JPG, JPEG, PNG.
- Name
resolution- Type
- string
- Description
Minimum resolution: 300 DPI for scanned documents.
Request
curl -X POST https://api.xnumbers.io/v1/numbers/num_WAz8eIbvDR60rouK/KYC/files \
-H "Authorization: Bearer {token}" \
-F "file=@/path/to/business_license.pdf" \
-F "document_type=business_registration" \
-F "description=Business registration certificate" \
-F "expiration_date=2025-12-31"
Response
{
"id": "doc_8mN4pL9qX2vY7wK5",
"kyc_id": "kyc_4Kp8mN9qL2xY6wR3",
"document_type": "business_registration",
"filename": "business_license.pdf",
"file_size": 2048576,
"mime_type": "application/pdf",
"description": "Business registration certificate",
"expiration_date": "2025-12-31",
"status": "uploaded",
"uploaded_at": "2022-01-01T10:10:00Z",
"download_url": "https://api.xnumbers.io/v1/kyc/documents/doc_8mN4pL9qX2vY7wK5/download"
}
Get KYC status
This endpoint allows you to retrieve the current KYC verification status and details for a specific virtual number. Use this to track the progress of verification requests and check for any required actions.
Request
curl https://api.xnumbers.io/v1/numbers/num_WAz8eIbvDR60rouK/KYC \
-H "Authorization: Bearer {token}"
Response
{
"id": "kyc_4Kp8mN9qL2xY6wR3",
"number_id": "num_WAz8eIbvDR60rouK",
"status": "under_review",
"type": "business",
"address": {
"address_line_1": "123 Main Street",
"address_line_2": "Suite 456",
"city": "New York",
"state_province": "NY",
"postal_code": "10001",
"country": "US"
},
"company_name": "Acme Telecommunications Inc.",
"tax_id": "12-3456789",
"contact_person": "John Smith",
"phone_number": "+1-555-123-4567",
"email": "compliance@acmetel.com",
"documents": [
{
"id": "doc_8mN4pL9qX2vY7wK5",
"document_type": "business_registration",
"filename": "business_license.pdf",
"status": "verified",
"uploaded_at": "2022-01-01T10:10:00Z"
},
{
"id": "doc_3nL7qK4pV1zX8wM2",
"document_type": "address_proof",
"filename": "utility_bill.pdf",
"status": "pending_review",
"uploaded_at": "2022-01-01T10:20:00Z"
}
],
"submitted_at": "2022-01-01T10:00:00Z",
"reviewed_at": null,
"rejection_reason": null,
"expires_at": "2023-01-01T00:00:00Z"
}
This endpoint allows you to update the address details that were previously submitted for KYC verification. This is useful for correcting address information or updating it if your business has moved.
Optional attributes
- Name
address_line_1- Type
- string
- Description
Updated primary address line (street address).
- Name
address_line_2- Type
- string
- Description
Updated secondary address line (apartment, suite, etc.).
- Name
city- Type
- string
- Description
Updated city or locality.
- Name
state_province- Type
- string
- Description
Updated state, province, or region.
- Name
postal_code- Type
- string
- Description
Updated postal or ZIP code.
- Name
country- Type
- string
- Description
Updated ISO 3166-1 alpha-2 country code.
- Name
company_name- Type
- string
- Description
Updated company name (for business verification).
- Name
contact_person- Type
- string
- Description
Updated primary contact person name.
- Name
phone_number- Type
- string
- Description
Updated contact phone number.
- Name
email- Type
- string
- Description
Updated contact email address.
Request
curl -X PATCH https://api.xnumbers.io/v1/numbers/num_WAz8eIbvDR60rouK/KYC/address \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"address_line_1": "456 Business Ave",
"address_line_2": "Floor 10, Suite 1001",
"city": "New York",
"state_province": "NY",
"postal_code": "10002",
"phone_number": "+1-555-987-6543",
"email": "updated-compliance@acmetel.com"
}'
Response
{
"id": "kyc_4Kp8mN9qL2xY6wR3",
"number_id": "num_WAz8eIbvDR60rouK",
"status": "pending",
"type": "business",
"address": {
"address_line_1": "456 Business Ave",
"address_line_2": "Floor 10, Suite 1001",
"city": "New York",
"state_province": "NY",
"postal_code": "10002",
"country": "US"
},
"company_name": "Acme Telecommunications Inc.",
"tax_id": "12-3456789",
"contact_person": "John Smith",
"phone_number": "+1-555-987-6543",
"email": "updated-compliance@acmetel.com",
"documents": [
{
"id": "doc_8mN4pL9qX2vY7wK5",
"document_type": "business_registration",
"filename": "business_license.pdf",
"status": "verified",
"uploaded_at": "2022-01-01T10:10:00Z"
}
],
"submitted_at": "2022-01-01T10:00:00Z",
"updated_at": "2022-01-01T10:26:40Z",
"reviewed_at": null,
"rejection_reason": null,
"expires_at": "2023-01-01T00:00:00Z"
}
Delete KYC document
This endpoint allows you to delete a previously uploaded KYC document. This is only possible before the verification process is completed.
Request
curl -X DELETE https://api.xnumbers.io/v1/kyc/documents/doc_8mN4pL9qX2vY7wK5 \
-H "Authorization: Bearer {token}"
Response
{
"message": "Document deleted successfully",
"deleted_at": "2022-01-01T10:33:20Z"
}