Internal / Private BetaThis documentation describes the new Compliance API which is currently in private beta. This API is not yet available for general use. Access is limited to internal teams and select beta partners.For questions or beta access, contact the Plivo product team.
Supported Countries: The Compliance API currently supports India only. Support for additional countries will be added in future releases.
https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/Compliance/
The Requirements Object
The Requirements object describes what documents and fields are needed for compliance in a specific country.
Attributes
ISO 3166-1 alpha-2 country code.
Type of number. Values: local, mobile, tollfree.
Type of end user. Currently only business is supported.
List of required document types. Each object includes title, type, accepted_formats, and description.
Array of field objects specifying end user fields. Each object includes field_name, field_label, required, field_type, max_length, and min_length.
Estimated number of business days for compliance review.
Example Object
{
"country_iso": "IN",
"number_type": "local",
"user_type": "business",
"required_documents": [
{
"title": "Identity Proof",
"type": "identity_proof",
"accepted_formats": ["passport", "national_id", "aadhaar"],
"description": "Government-issued photo ID of authorized representative"
},
{
"title": "Address Proof",
"type": "address_proof",
"accepted_formats": ["utility_bill", "bank_statement"],
"description": "Document dated within 3 months showing business address"
},
{
"title": "Business Registration",
"type": "business_registration",
"accepted_formats": ["certificate_of_incorporation", "gst_certificate"],
"description": "Official company registration document"
}
],
"required_fields": [
{
"field_name": "business_name",
"field_label": "Business Name",
"required": true,
"field_type": "string",
"max_length": 255,
"min_length": 1
},
{
"field_name": "registration_number",
"field_label": "Registration Number",
"required": true,
"field_type": "string",
"max_length": 50,
"min_length": 1
},
{
"field_name": "address.line1",
"field_label": "Address Line 1",
"required": true,
"field_type": "string",
"max_length": 255,
"min_length": 1
},
{
"field_name": "address.city",
"field_label": "City",
"required": true,
"field_type": "string",
"max_length": 100,
"min_length": 1
},
{
"field_name": "address.postal_code",
"field_label": "Postal Code",
"required": true,
"field_type": "string",
"max_length": 10,
"min_length": 1
},
{
"field_name": "address.country",
"field_label": "Country",
"required": true,
"field_type": "string",
"max_length": 2,
"min_length": 2
}
],
"estimated_review_days": 3
}
Get Requirements
Query compliance requirements before creating a compliance record. Returns available number types and their requirements for a country.
GET https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/Compliance/Requirements
Query Parameters
ISO 3166-1 alpha-2 country code. Currently only IN (India) is supported.
Filter by number type. Values: local, mobile, tollfree.
Filter by end user type. Currently only business is supported.
Example
import plivo
client = plivo.RestClient('<auth_id>', '<auth_token>')
# Get all requirements for India
response = client.compliance.get_requirements(country_iso="IN")
print(response)
Response
Returns available number types and requirements for the country.
{
"api_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"country_iso": "IN",
"number_types": [
{
"number_type": "local",
"user_types": [
{
"user_type": "business",
"required_documents": [
{
"title": "Identity Proof",
"type": "identity_proof",
"accepted_formats": ["passport", "national_id", "aadhaar"],
"description": "Government-issued photo ID of authorized representative"
},
{
"title": "Address Proof",
"type": "address_proof",
"accepted_formats": ["utility_bill", "bank_statement"],
"description": "Document dated within 3 months showing business address"
},
{
"title": "Business Registration",
"type": "business_registration",
"accepted_formats": ["certificate_of_incorporation", "gst_certificate"],
"description": "Official company registration document"
}
],
"required_fields": [
{
"field_name": "business_name",
"field_label": "Business Name",
"required": true,
"field_type": "string",
"max_length": 255,
"min_length": 1
},
{
"field_name": "registration_number",
"field_label": "Registration Number",
"required": true,
"field_type": "string",
"max_length": 50,
"min_length": 1
},
{
"field_name": "address.line1",
"field_label": "Address Line 1",
"required": true,
"field_type": "string",
"max_length": 255,
"min_length": 1
},
{
"field_name": "address.city",
"field_label": "City",
"required": true,
"field_type": "string",
"max_length": 100,
"min_length": 1
},
{
"field_name": "address.postal_code",
"field_label": "Postal Code",
"required": true,
"field_type": "string",
"max_length": 10,
"min_length": 1
},
{
"field_name": "address.country",
"field_label": "Country",
"required": true,
"field_type": "string",
"max_length": 2,
"min_length": 2
}
],
"estimated_review_days": 3
}
]
},
{
"number_type": "mobile",
"user_types": [
{
"user_type": "business",
"required_documents": [
{
"title": "Identity Proof",
"type": "identity_proof",
"accepted_formats": ["passport", "national_id", "aadhaar"],
"description": "Government-issued photo ID of authorized representative"
},
{
"title": "Address Proof",
"type": "address_proof",
"accepted_formats": ["utility_bill", "bank_statement"],
"description": "Document dated within 3 months showing business address"
},
{
"title": "Business Registration",
"type": "business_registration",
"accepted_formats": ["certificate_of_incorporation", "gst_certificate"],
"description": "Official company registration document"
}
],
"required_fields": [
{
"field_name": "business_name",
"field_label": "Business Name",
"required": true,
"field_type": "string",
"max_length": 255,
"min_length": 1
},
{
"field_name": "registration_number",
"field_label": "Registration Number",
"required": true,
"field_type": "string",
"max_length": 50,
"min_length": 1
},
{
"field_name": "address.line1",
"field_label": "Address Line 1",
"required": true,
"field_type": "string",
"max_length": 255,
"min_length": 1
},
{
"field_name": "address.city",
"field_label": "City",
"required": true,
"field_type": "string",
"max_length": 100,
"min_length": 1
},
{
"field_name": "address.postal_code",
"field_label": "Postal Code",
"required": true,
"field_type": "string",
"max_length": 10,
"min_length": 1
},
{
"field_name": "address.country",
"field_label": "Country",
"required": true,
"field_type": "string",
"max_length": 2,
"min_length": 2
}
],
"estimated_review_days": 3
}
]
}
]
}
The Compliance Object
A Compliance record combines end user information and documents for regulatory compliance review.
Attributes
Unique identifier (UUID format).
A friendly name to identify this compliance record.
Current status. Values: pending_review, approved, rejected, more_info_required.
ISO 3166-1 alpha-2 country code.
Type of number. Values: local, mobile, tollfree.
End user information including type, name, email, address, and registration details.
Unique identifier for the end user (UUID format).
End user type. Values: individual, business.
Full name (individual) or business name.
Address with line1, line2, city, state, postal_code, country.
end_user.registration_number
Business registration number (for business users).
List of attached documents with id, type, file_url, and status.
ISO 8601 timestamp of creation.
ISO 8601 timestamp of last update.
Reason for rejection when status is rejected. Null for other statuses.
ISO 8601 timestamp of the most recent submission for review.
Example Object
{
"compliance_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"alias": "Plivo India Local",
"status": "approved",
"country_iso": "IN",
"number_type": "local",
"end_user": {
"id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"type": "business",
"name": "Plivo India Pvt Ltd",
"email": "compliance@plivo.in",
"address": {
"line1": "123 MG Road",
"city": "Bangalore",
"state": "Karnataka",
"postal_code": "560001",
"country": "IN"
},
"registration_number": "U72200KA2020PTC123456"
},
"documents": [
{
"id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
"type": "identity_proof",
"file_name": "passport.pdf",
"file_url": "https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/Compliance/a1b2c3d4-e5f6-7890-abcd-ef1234567890/Document/c3d4e5f6-a7b8-9012-cdef-345678901234/download",
"status": "verified"
},
{
"id": "d4e5f6a7-b8c9-0123-def4-567890123456",
"type": "address_proof",
"file_name": "utility_bill.png",
"file_url": "https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/Compliance/a1b2c3d4-e5f6-7890-abcd-ef1234567890/Document/d4e5f6a7-b8c9-0123-def4-567890123456/download",
"status": "verified"
},
{
"id": "e5f6a7b8-c9d0-1234-ef56-789012345678",
"type": "business_registration",
"file_name": "registration.pdf",
"file_url": "https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/Compliance/a1b2c3d4-e5f6-7890-abcd-ef1234567890/Document/e5f6a7b8-c9d0-1234-ef56-789012345678/download",
"status": "verified"
}
],
"rejection_reason": null,
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-18T14:00:00Z",
"submitted_at": "2024-01-15T10:30:00Z"
}
Compliance Records
Compliance records combine end user information and documents into a single unit for regulatory review.
Create Compliance
Create and submit a compliance record with end user details and documents in a single request. The record is automatically submitted for review upon creation.
POST https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/Compliance/
Arguments
ISO 3166-1 alpha-2 country code.
Type of number. Values: local, mobile, tollfree.
A friendly name to identify this compliance record.
End user information object.
End user type. Values: individual, business.
Full name (individual) or business name.
Address information (required for most countries).
end_user.registration_number
Business registration number (required for business users).
Array of document objects with type and file. Each document file must be PNG or PDF, with a maximum size of 5 MB.
URL to receive status update webhooks when compliance is approved, rejected, or requires more information.
HTTP method for the callback. Values: GET, POST. Default: POST.
Example
import plivo
client = plivo.RestClient('<auth_id>', '<auth_token>')
response = client.compliances.create(
country_iso="IN",
number_type="local",
end_user={
"type": "business",
"name": "Plivo India Pvt Ltd",
"email": "compliance@plivo.in",
"address": {
"line1": "123 MG Road",
"city": "Bangalore",
"state": "Karnataka",
"postal_code": "560001",
"country": "IN"
},
"registration_number": "U72200KA2020PTC123456"
},
documents=[
{"type": "identity_proof", "file": "/path/to/passport.pdf"},
{"type": "address_proof", "file": "/path/to/utility_bill.png"},
{"type": "business_registration", "file": "/path/to/registration.pdf"}
]
)
print(response)
Response
{
"api_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
"compliance_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"message": "Created successfully"
}
Get Compliance
Retrieve details of a specific compliance record.
GET https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/Compliance/{compliance_id}
Query Parameters
Comma-separated list of objects to expand. Values: documents, end_user, linked_numbers.
Example
import plivo
client = plivo.RestClient('<auth_id>', '<auth_token>')
response = client.compliances.get(
"a1b2c3d4-e5f6-7890-abcd-ef1234567890",
expand="documents,end_user,linked_numbers"
)
print(response)
List Compliance
List all compliance records for an account.
GET https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/Compliance/
Query Parameters
Filter by status. Values: pending_review, approved, rejected, more_info_required.
Number of results per page (max 100, default 20).
Example
import plivo
client = plivo.RestClient('<auth_id>', '<auth_token>')
response = client.compliances.list(
status="approved",
country_iso="DE",
limit=50
)
print(response)
Update Compliance
Update an existing compliance record. Compliance records can be updated when in rejected or more_info_required status. Updating automatically resubmits the record for review.
PATCH https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/Compliance/{compliance_id}
Arguments
Updated friendly name for this compliance record.
Updated end user information.
Updated documents array. Provide only documents to add or replace.
Example
import plivo
client = plivo.RestClient('<auth_id>', '<auth_token>')
# Replace a rejected document
response = client.compliances.update(
"a1b2c3d4-e5f6-7890-abcd-ef1234567890",
documents=[
{"type": "identity_proof", "file": "/path/to/new_passport.pdf"}
]
)
print(response)
Unlike the previous API, rejected compliance records can be updated directly instead of creating a new application. The record is automatically resubmitted for review after an update.
Delete Compliance
Delete a compliance record. Only records that are not approved or linked to phone numbers can be deleted.
DELETE https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/Compliance/{compliance_id}
Approved compliance records linked to phone numbers cannot be deleted. Unlink the numbers first.
Example
import plivo
client = plivo.RestClient('<auth_id>', '<auth_token>')
response = client.compliances.delete("a1b2c3d4-e5f6-7890-abcd-ef1234567890")
print(response)
Link Compliance to Numbers
Once a compliance record is approved, link it to phone numbers using the Update Account Phone Number endpoint. Pass the compliance_id parameter with your approved compliance ID.
The compliance record must match the number’s country and type. One approved compliance record can be linked to multiple numbers in the same country/type.
import plivo
client = plivo.RestClient('<auth_id>', '<auth_token>')
response = client.numbers.update(
number='911140221000',
compliance_id='a1b2c3d4-e5f6-7890-abcd-ef1234567890'
)
print(response)
Status Flow
Create → pending_review → approved
→ rejected → Update → pending_review
→ more_info_required → Update → pending_review
| Status | Description | Actions Available |
|---|
pending_review | Submitted, awaiting review | View, Delete |
approved | Compliance verified | Link to numbers |
rejected | Documents not accepted | Update (auto-resubmits), Delete |
more_info_required | Additional info needed | Update (auto-resubmits), Delete |
Webhooks
Configure webhooks to receive real-time notifications about compliance events.
Webhook Events
| Event | Description |
|---|
compliance.approved | Compliance has been approved |
compliance.rejected | Compliance was rejected with reasons |
compliance.more_info_required | Additional documents or information needed |
Webhook Payload
{
"event": "compliance.approved",
"compliance_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "approved"
}
Rejection Webhook Example
{
"event": "compliance.rejected",
"compliance_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "rejected",
"rejection_reason": "Address proof document is expired. Please upload a document dated within the last 3 months."
}
Error Handling
{
"error": {
"type": "validation_error",
"code": "missing_required_document",
"message": "Address proof is required for German local numbers",
"param": "documents",
"doc_url": "https://www.plivo.com/docs/numbers/compliance#requirements"
}
}
Error Codes
| Code | Type | Description |
|---|
missing_required_document | validation_error | A required document type is missing |
missing_required_field | validation_error | A required field is not provided |
invalid_file | validation_error | File format not supported or exceeds 5 MB size limit |
compliance_not_editable | state_error | Compliance cannot be modified in current status |
compliance_not_approved | state_error | Only approved compliance records can be linked to numbers |
country_mismatch | validation_error | Number country doesn’t match compliance country |
number_type_mismatch | validation_error | Number type doesn’t match compliance type |
HTTP Status Codes
| Code | Description |
|---|
200 | Success |
201 | Created |
400 | Bad Request - Invalid parameters |
401 | Unauthorized - Invalid credentials |
403 | Forbidden - Insufficient permissions |
404 | Not Found - Resource doesn’t exist |
409 | Conflict - Resource state conflict |
422 | Unprocessable Entity - Validation failed |
429 | Too Many Requests - Rate limited |
500 | Internal Server Error |
Rate Limits
| Endpoint | Rate Limit |
|---|
| Requirements Discovery | 100 requests/minute |
| Compliance Operations | 60 requests/minute |
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1705326000
