Compliance - Plivo

The Compliance API lets you manage phone number regulatory compliance in a single streamlined flow. Instead of creating end users, documents, and compliance applications separately, you can do it all in one API call.

Supported Countries: The Compliance API currently supports India only. Support for additional countries will be added in future releases.

API Endpoint

https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/Compliance/

Authentication: HTTP Basic Auth with your Plivo Auth ID as username and Auth Token as password.

The Requirements Object

Describes what documents and fields are needed for compliance in a specific country, number type, and user type combination. Always call this first before creating a compliance application.

Attributes

requirement_id

string

UUID of the compliance requirement.

country_iso

string

ISO 3166-1 alpha-2 country code.

number_type

string

Type of number. Values: local, mobile, tollfree.

user_type

string

Type of end user. Values: individual, business.

document_types

array

List of required document types. Each object includes document_type_id, name, description, proof_required, and required_fields.

Document Type Object

Each entry in document_types:

document_type_id

string

UUID of the document type. Use this when creating a compliance application.

name

string

Document type name (e.g., “Registration Certificate”).

description

string

Description of the document type.

proof_required

boolean

true = file upload required, false = only data fields needed.

required_fields

array

Data fields required for this document type.

Required Field Object

Each entry in required_fields:

field_name

string

Key to use in documents[].data_fields.

friendly_name

string

Human-readable display name.

help_text

string

Guidance on what to enter.

field_type

string

Values: string, date, enum.

required

boolean

Whether this field is mandatory.

format

string

Expected format (e.g., yyyy-mm-dd). Empty if none.

enums

string

Comma-separated allowed values for enum fields. Empty for other types.

min_length

integer

Minimum character length.

max_length

integer

Maximum character length.

Get Requirements

Query compliance requirements before creating a compliance record.

GET https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/Compliance/Requirements

Query Parameters

country_iso

string

required

Two-letter country code (e.g., IN).

number_type

string

required

Values: local, mobile, tollfree.

user_type

string

required

Values: individual, business.

Example

curl "https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/Compliance/Requirements?country_iso=IN&number_type=local&user_type=business" \
  -u '<auth_id>:<auth_token>'

Response (200 OK)

{
  "requirement_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "country_iso": "IN",
  "number_type": "local",
  "user_type": "business",
  "document_types": [
    {
      "document_type_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "name": "Registration Certificate",
      "description": "Certificate of Incorporation or Udyam Registration",
      "proof_required": true,
      "required_fields": [
        {
          "field_name": "business_name",
          "friendly_name": "Business Name",
          "help_text": "Legal name as on the certificate",
          "field_type": "string",
          "required": true,
          "format": "",
          "enums": "",
          "min_length": 1,
          "max_length": 255
        }
      ]
    },
    {
      "document_type_id": "9a8b7c6d-5e4f-3a2b-1c0d-ef9876543210",
      "name": "GST Certificate",
      "description": "GST Registration Certificate (Form GST REG-06)",
      "proof_required": true,
      "required_fields": []
    }
  ]
}

The Compliance Object

Represents a compliance application combining end user information and documents for regulatory review.

Attributes

compliance_id

string

UUID identifier.

alias

string

Friendly name for the compliance record.

status

string

Current status. Values: submitted, accepted, rejected.

country_iso

string

ISO 3166-1 alpha-2 country code.

number_type

string

Type of number.

user_type

string

Values: individual, business.

rejection_reason

string|null

Reason for rejection (only when status=rejected, null otherwise).

created_at

string

ISO 8601 timestamp.

updated_at

string

ISO 8601 timestamp.

end_user

object|null

End user details (only returned with expand=end_user).

documents

array|null

Attached documents (only returned with expand=documents).

linked_numbers

array|null

Linked phone numbers (only returned with expand=linked_numbers).

End User Object

Returned when using expand=end_user.

end_user_id

string

UUID of the end user.

type

string

Values: individual, business.

name

string

Full name or company name.

last_name

string

Last name (empty for business).

string

Contact email.

address_line1

string

Street address line 1.

address_line2

string

Street address line 2.

city

string

City.

state

string

State or province.

postal_code

string

Postal or ZIP code.

country

string

Two-letter country code.

registration_number

string

Business registration number (e.g., CIN for India).

Address fields are flat (e.g., address_line1, city), not nested under an address object.

Document Object

Returned when using expand=documents.

document_id

string

UUID of the document.

document_type_id

string

UUID of the document type.

document_name

string

Document type name.

file_name

string

Original filename (empty if no file uploaded).

meta_information

object

Key-value pairs submitted with the document.

download_url

string

Presigned S3 URL (expires in 1 hour). Empty if no file.

created_at

string

ISO 8601 timestamp.

Linked Number Object

Returned when using expand=linked_numbers.

number

string

Phone number in E.164 format.

number_type

string

Type of number.

Create a Compliance Application

Create end user, upload documents, and auto-submit the compliance application in a single call.

POST https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/Compliance/

Content-Type: multipart/form-data The request consists of:

A data field containing a JSON string with compliance details
File fields using the pattern documents[0].file, documents[1].file, etc.

File Upload Rules

Required when the document type has proof_required=true (from Requirements response)
Not needed when proof_required=false
Supported formats: PDF, JPEG, PNG (validated server-side by content type, not just extension)
Max file size: 5 MB per file
Max filename length: 99 characters

The `data` JSON Structure

country_iso

string

required

Two-letter country code.

number_type

string

required

Values: local, mobile, tollfree.

alias

string

required

Friendly name (unique per end user, max 99 characters).

end_user

object

required

End user details.

documents

array

required

Array of document objects.

end_user fields:

end_user.type

string

required

Values: individual, business.

end_user.name

string

required

Full name or company name.

end_user.last_name

string

Last name.

end_user.email

string

Contact email.

end_user.address_line1

string

Street address line 1.

end_user.address_line2

string

Street address line 2.

end_user.city

string

City.

end_user.state

string

State or province.

end_user.postal_code

string

Postal or ZIP code.

end_user.country

string

Two-letter country code.

end_user.registration_number

string

Business registration number.

documents[] fields:

documents[].document_type_id

string

required

UUID from the Requirements response.

documents[].data_fields

object

Key-value pairs matching required_fields[].field_name from Requirements.

Example

curl -X POST \
  "https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/Compliance/" \
  -u '<auth_id>:<auth_token>' \
  -F 'data={
    "country_iso": "IN",
    "number_type": "local",
    "alias": "Acme India Compliance",
    "end_user": {
      "type": "business",
      "name": "ACME TECHNOLOGIES PRIVATE LIMITED",
      "email": "compliance@acme.in",
      "address_line1": "123 MG Road",
      "city": "Bangalore",
      "state": "Karnataka",
      "postal_code": "560001",
      "country": "IN",
      "registration_number": "U72200KA2020PTC123456"
    },
    "documents": [
      {
        "document_type_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "data_fields": {
          "business_name": "ACME TECHNOLOGIES PRIVATE LIMITED"
        }
      },
      {
        "document_type_id": "9a8b7c6d-5e4f-3a2b-1c0d-ef9876543210"
      }
    ]
  }' \
  -F 'documents[0].file=@certificate_of_incorporation.pdf' \
  -F 'documents[1].file=@gst_certificate.pdf'

Response (201 Created)

{
  "compliance_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "alias": "Acme India Compliance",
  "status": "submitted",
  "country_iso": "IN",
  "number_type": "local",
  "user_type": "business",
  "rejection_reason": null,
  "created_at": "2026-04-01T10:30:00Z",
  "updated_at": "2026-04-01T10:30:00Z"
}

Get a Compliance Application

Retrieve details of a specific compliance application.

GET https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/Compliance/{compliance_id}

Query Parameters

expand

string

Comma-separated list of objects to include. Values: end_user, documents, linked_numbers.

Without expand, only top-level fields are returned (faster response). With expand, the corresponding nested objects are included.

Example

curl "https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/Compliance/{compliance_id}?expand=end_user,documents,linked_numbers" \
  -u '<auth_id>:<auth_token>'

Response (200 OK)

{
  "compliance_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "alias": "Acme India Compliance",
  "status": "accepted",
  "country_iso": "IN",
  "number_type": "local",
  "user_type": "business",
  "rejection_reason": null,
  "created_at": "2026-04-01T10:30:00Z",
  "updated_at": "2026-04-01T12:00:00Z",
  "end_user": {
    "end_user_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "type": "business",
    "name": "ACME TECHNOLOGIES PRIVATE LIMITED",
    "last_name": "",
    "email": "compliance@acme.in",
    "address_line1": "123 MG Road",
    "address_line2": "",
    "city": "Bangalore",
    "state": "Karnataka",
    "postal_code": "560001",
    "country": "IN",
    "registration_number": "U72200KA2020PTC123456"
  },
  "documents": [
    {
      "document_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "document_type_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "document_name": "Registration Certificate",
      "file_name": "certificate_of_incorporation.pdf",
      "meta_information": {
        "business_name": "ACME TECHNOLOGIES PRIVATE LIMITED"
      },
      "download_url": "https://s3.amazonaws.com/...",
      "created_at": "2026-04-01T10:30:00Z"
    },
    {
      "document_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
      "document_type_id": "9a8b7c6d-5e4f-3a2b-1c0d-ef9876543210",
      "document_name": "GST Certificate",
      "file_name": "gst_certificate.pdf",
      "meta_information": {},
      "download_url": "https://s3.amazonaws.com/...",
      "created_at": "2026-04-01T10:30:00Z"
    }
  ],
  "linked_numbers": [
    {
      "number": "+912212345678",
      "number_type": "local"
    }
  ]
}

List Compliance Applications

Returns a paginated list of compliance applications for the account.

GET https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/Compliance/

Query Parameters

limit

integer

Max results per page (max 100). Default: 20.

offset

integer

Pagination offset. Default: 0.

status

string

Filter by status. Values: submitted, accepted, rejected.

country_iso

string

Filter by country code (e.g., IN).

number_type

string

Filter by number type. Values: local, mobile, tollfree.

user_type

string

Filter by user type. Values: individual, business.

alias

string

Filter by alias.

expand

string

Comma-separated: end_user, documents, linked_numbers.

Example

curl "https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/Compliance/?status=accepted&country_iso=IN&limit=10" \
  -u '<auth_id>:<auth_token>'

Response (200 OK)

{
  "meta": {
    "limit": 10,
    "offset": 0,
    "total_count": 3,
    "next": null,
    "previous": null
  },
  "objects": [
    {
      "compliance_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "alias": "Acme India Compliance",
      "status": "accepted",
      "country_iso": "IN",
      "number_type": "local",
      "user_type": "business",
      "rejection_reason": null,
      "created_at": "2026-04-01T10:30:00Z",
      "updated_at": "2026-04-01T12:00:00Z"
    }
  ]
}

Update a Compliance Application

Update a rejected compliance application and automatically resubmit it for review.

PATCH https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/Compliance/{compliance_id}

Content-Type: multipart/form-data (same format as Create)

Restrictions

Only applications with status=rejected can be updated. Any other status returns error code compliance_not_editable.
end_user.type cannot be changed.
Documents are fully replaced. All previously uploaded documents are removed and new ones are created. You must re-upload all documents, not just the ones that need correction.

Arguments

alias

string

Updated friendly name (max 99 characters).

end_user

object

Partial end user update (same fields as Create, minus type).

documents

array

Full replacement document set.

Example

curl -X PATCH \
  "https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/Compliance/{compliance_id}" \
  -u '<auth_id>:<auth_token>' \
  -F 'data={
    "documents": [
      {
        "document_type_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "data_fields": {
          "business_name": "ACME TECHNOLOGIES PRIVATE LIMITED"
        }
      },
      {
        "document_type_id": "9a8b7c6d-5e4f-3a2b-1c0d-ef9876543210"
      }
    ]
  }' \
  -F 'documents[0].file=@corrected_certificate.pdf' \
  -F 'documents[1].file=@gst_certificate.pdf'

Response (202 Accepted)

Returns the updated compliance object with status: "submitted".

{
  "compliance_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "alias": "Acme India Compliance",
  "status": "submitted",
  "country_iso": "IN",
  "number_type": "local",
  "user_type": "business",
  "rejection_reason": null,
  "created_at": "2026-04-01T10:30:00Z",
  "updated_at": "2026-04-03T14:00:00Z"
}

Delete a Compliance Application

Soft-delete a compliance application.

DELETE https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/Compliance/{compliance_id}

Restrictions

Applications with status=expired cannot be deleted.
All other statuses (submitted, accepted, rejected) can be deleted.

Deleting an accepted application that has linked numbers will unlink those numbers. Ensure numbers are re-linked to a different compliance application if needed.

Example

curl -X DELETE \
  "https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/Compliance/{compliance_id}" \
  -u '<auth_id>:<auth_token>'

Response

204 No Content (no response body)

Bulk Link Numbers to Compliance

Link multiple phone numbers to their respective compliance applications in a single request.

POST https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/Compliance/Link/

Content-Type: application/json

Requirements

Compliance application must be in accepted status
Phone number country and type must match the compliance requirement
Application must use the latest requirement version

Arguments

numbers

array

required

Array of number-to-compliance mappings.

numbers[].number

string

required

Phone number in E.164 format.

numbers[].compliance_application_id

string

required

UUID of an accepted compliance application.

Example

curl -X POST \
  "https://api.plivo.com/v1/Account/{auth_id}/PhoneNumber/Compliance/Link/" \
  -u '<auth_id>:<auth_token>' \
  -H "Content-Type: application/json" \
  -d '{
    "numbers": [
      {
        "number": "+912212345678",
        "compliance_application_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      },
      {
        "number": "+912212345679",
        "compliance_application_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      }
    ]
  }'

Response (200 OK)

{
  "total_count": 2,
  "updated_count": 1,
  "report": [
    {
      "number": "+912212345678",
      "status": "success",
      "remarks": "Compliance linked successfully"
    },
    {
      "number": "+912212345679",
      "status": "failed",
      "remarks": "Country mismatch"
    }
  ]
}

Status Flow

Create (POST) --> submitted --> accepted --> Link numbers
                            --> rejected --> Update (PATCH) --> submitted --> ...

Status	Description	Available Actions
`submitted`	Under review by compliance team	Get, List, Delete
`accepted`	Approved. Phone numbers can be linked	Get, List, Delete, Bulk Link
`rejected`	Not accepted. Check `rejection_reason`	Get, List, Delete, Update (auto-resubmits)

The draft, suspended, and expired statuses exist internally but are not settable via the public API.

Error Handling

Error Response Format

The Compliance API uses a flat error object format, different from the standard Plivo {"api_id": "...", "error": "..."} pattern used by other Plivo APIs.

{
  "type": "validation_error",
  "code": "missing_required_field",
  "message": "end_user.name is required",
  "param": "end_user.name"
}

type

string

Error category.

code

string

Machine-readable error code.

message

string

Human-readable description.

param

string

Request field that caused the error (omitted for non-field errors).

Error Types

Type	Description
`validation_error`	Request validation failed
`not_found`	Resource does not exist
`invalid_request`	Request cannot be completed (duplicates, restrictions)
`state_error`	Action not allowed in the current compliance status
`forbidden`	Account not permitted
`server_error`	Internal error

Error Codes

Code	Type	Description
`missing_required_field`	validation_error	Required field not provided
`invalid_field_value`	validation_error	Field value is invalid or exceeds limits
`missing_required_document`	validation_error	Required document type not included
`invalid_file`	validation_error	Unsupported file format or exceeds 5 MB
`duplicate_alias`	invalid_request	Alias already in use for this end user
`duplicate_end_user`	invalid_request	End user with same name, last name, and type exists
`compliance_not_editable`	state_error	Only `rejected` applications can be updated
`requirement_restricted`	invalid_request	Phone numbers for this country/type are restricted
`requirement_not_found`	not_found	No requirement for the given country/number type/user type
`not_found`	not_found	Compliance application not found
`expired`	invalid_request	Cannot delete an expired application

HTTP Status Codes

Code	Meaning
`200`	Success (Get, List, Bulk Link)
`201`	Created (Create)
`202`	Accepted (Update, resubmitted for review)
`204`	No Content (Delete)
`400`	Validation or state error
`401`	Authentication failed
`403`	Forbidden
`404`	Not found
`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

Rate limit headers are included in all responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1705326000

India Requirements

For Indian local business numbers (country_iso=IN, number_type=local, user_type=business), the following documents are required:

1. Registration Certificate (file upload required)

Certificate of Incorporation issued by the Ministry of Corporate Affairs (MCA). Udyam Registration Certificates are also accepted for MSMEs. Required data field: business_name — legal business name exactly as it appears on the certificate.

2. GST Registration Certificate (file upload required)

Form GST REG-06 issued by the Goods and Services Tax Network (GSTN). No additional data fields required.

Validation Rules

The business name must match exactly across both documents and the end_user.name / business_name data field
Both documents must be valid and not expired
Documents must be clear, legible PDFs or images
Submitting the same file for both document slots will be rejected

Regulatory Compliance - Overview and Console guide
Phone Numbers - Search and buy numbers
Account Phone Numbers - Manage your numbers

Concepts

API Reference

​The Requirements Object

​Attributes

​Document Type Object

​Required Field Object

​Get Requirements

​Query Parameters

​Example

​Response (200 OK)

​The Compliance Object

​Attributes

​End User Object

​Document Object

​Linked Number Object

​Create a Compliance Application

​File Upload Rules

​The data JSON Structure

​Example

​Response (201 Created)

​Get a Compliance Application

​Query Parameters

​Example

​Response (200 OK)

​List Compliance Applications

​Query Parameters

​Example

​Response (200 OK)

​Update a Compliance Application

​Restrictions

​Arguments

​Example

​Response (202 Accepted)

​Delete a Compliance Application

​Restrictions

​Example

​Response

​Bulk Link Numbers to Compliance

​Requirements

​Arguments

​Example

​Response (200 OK)

​Status Flow

​Error Handling

​Error Response Format

​Error Types

​Error Codes

​HTTP Status Codes

​Rate Limits

​India Requirements

​1. Registration Certificate (file upload required)

​2. GST Registration Certificate (file upload required)

​Validation Rules

​Related

The Requirements Object

Attributes

Document Type Object

Required Field Object

Get Requirements

Query Parameters

Example

Response (200 OK)

The Compliance Object

Attributes

End User Object

Document Object

Linked Number Object

Create a Compliance Application

File Upload Rules

The `data` JSON Structure

Example

Response (201 Created)

Get a Compliance Application

Query Parameters

Example

Response (200 OK)

List Compliance Applications

Query Parameters

Example

Response (200 OK)

Update a Compliance Application

Restrictions

Arguments

Example

Response (202 Accepted)

Delete a Compliance Application

Restrictions

Example

Response

Bulk Link Numbers to Compliance

Requirements

Arguments

Example

Response (200 OK)

Status Flow

Error Handling

Error Response Format

Error Types

Error Codes

HTTP Status Codes

Rate Limits

India Requirements

1. Registration Certificate (file upload required)

2. GST Registration Certificate (file upload required)

Validation Rules

Related