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. Every response includes an api_id field for request tracing.

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)

{
  "api_id": "a83657dc-31a5-11f1-ab48-d2d6f5435dea",
  "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: draft, submitted, accepted, rejected, suspended, expired.

country_iso

string

ISO 3166-1 alpha-2 country code.

number_type

string

Type of number.

user_type

string

Values: individual, business.

callback_url

string

Webhook URL for status change notifications. Present only if configured.

callback_method

string

HTTP method for the callback. Values: GET, POST. Present only if configured.

rejection_reason

string|null

Reason for rejection. Present only when status is rejected.

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.

callback_url

string

HTTPS URL to receive status change notifications (accepted, rejected). Plivo sends a v3 signature in the request header for verification.

callback_method

string

HTTP method for the callback. Values: GET, POST. Default: POST. Requires callback_url to be set.

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"
      }
    ],
    "callback_url": "https://example.com/compliance-webhook",
    "callback_method": "POST"
  }' \
  -F 'documents[0].file=@certificate_of_incorporation.pdf' \
  -F 'documents[1].file=@gst_certificate.pdf'

Response (201 Created)

{
  "api_id": "ad88a992-31aa-11f1-ab48-d2d6f5435dea",
  "compliance_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "Compliance application created and submitted for review."
}

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)

Without expand:

{
  "api_id": "a93cf456-31aa-11f1-bf86-d2d6f5435dea",
  "compliance": {
    "compliance_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "alias": "Acme India Compliance",
    "status": "accepted",
    "country_iso": "IN",
    "number_type": "local",
    "user_type": "business",
    "callback_url": "https://example.com/compliance-webhook",
    "callback_method": "POST",
    "created_at": "2026-04-01T10:30:00Z",
    "updated_at": "2026-04-01T12:00:00Z"
  }
}

With expand=end_user,documents,linked_numbers:

{
  "api_id": "aa1e6a4e-31aa-11f1-ab48-d2d6f5435dea",
  "compliance": {
    "compliance_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "alias": "Acme India Compliance",
    "status": "accepted",
    "country_iso": "IN",
    "number_type": "local",
    "user_type": "business",
    "callback_url": "https://example.com/compliance-webhook",
    "callback_method": "POST",
    "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: draft, submitted, accepted, rejected, suspended, expired.

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)

{
  "api_id": "acd86b7c-31aa-11f1-ab48-d2d6f5435dea",
  "meta": {
    "limit": 10,
    "offset": 0,
    "total_count": 3,
    "next": null,
    "previous": null
  },
  "compliances": [
    {
      "compliance_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "alias": "Acme India Compliance",
      "status": "accepted",
      "country_iso": "IN",
      "number_type": "local",
      "user_type": "business",
      "callback_url": "https://example.com/compliance-webhook",
      "callback_method": "POST",
      "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.

callback_url

string

Updated webhook URL (HTTPS only).

callback_method

string

Updated HTTP method. Values: GET, POST.

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 (200 OK)

Returns the updated compliance object with status: "submitted" (auto-resubmitted for review).

{
  "api_id": "ef28ebe6-31a5-11f1-bf86-d2d6f5435dea",
  "message": "Compliance application updated and resubmitted for review.",
  "compliance": {
    "compliance_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "alias": "Acme India Compliance",
    "status": "submitted",
    "country_iso": "IN",
    "number_type": "local",
    "user_type": "business",
    "callback_url": "https://example.com/compliance-webhook",
    "callback_method": "POST",
    "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, suspended) 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 (200 OK)

{
  "api_id": "2195a48e-31a6-11f1-ab48-d2d6f5435dea",
  "compliance_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "message": "Compliance application deleted."
}

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)

{
  "api_id": "afd51000-31aa-11f1-ab48-d2d6f5435dea",
  "total_count": 2,
  "updated_count": 1,
  "report": [
    {
      "number": "+912212345678",
      "status": "success",
      "remarks": "Number linked to compliance application."
    },
    {
      "number": "+912212345679",
      "status": "failed",
      "remarks": "Number not found on your account. Only rented numbers can be linked."
    }
  ]
}

Status Flow

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

Status	Description	Available Actions
`draft`	Saved but not yet submitted	Get, List, Delete
`submitted`	Under review by the 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)
`suspended`	Suspended by the compliance team	Get, List, Delete
`expired`	No longer valid — create a new application	Get, List

Error Handling

Error Response Format

All error responses use a flat two-field format with api_id for request tracing and error containing an actionable message. This is consistent with the standard Plivo API error pattern.

{
  "api_id": "a407c522-31a7-11f1-ab48-d2d6f5435dea",
  "error": "country_iso is required. Use a two-letter ISO country code (e.g., IN, DE, US)."
}

api_id

string

Unique request identifier for tracing.

error

string

Human-readable, actionable error message.

Common Error Messages

Scenario	Error message
Missing required field	`country_iso is required. Use a two-letter ISO country code (e.g., IN, DE, US).`
Application not found	`Compliance application 'xxx' not found.`
Wrong status for update	`Compliance application must be in 'rejected' status. Current status: 'submitted'.`
Expired application delete	`Expired compliance applications cannot be deleted.`
Invalid expand value	`Invalid expand value. Allowed values: end_user, documents, linked_numbers.`
Number not on account	`Number not found on your account. Only rented numbers can be linked.`
Application not accepted for linking	`Compliance application must be in 'accepted' status. Current status: 'submitted'.`
Server error	`Something went wrong while processing the request. Please try again later. If the issue persists, contact support@plivo.com.`

HTTP Status Codes

Code	Meaning
`200`	Success (Get, List, Update, Delete, Bulk Link)
`201`	Created (Create)
`400`	Validation or state error
`401`	Authentication failed
`403`	Forbidden
`404`	Not found
`500`	Internal server error

Callbacks

When you provide a callback_url during creation or update, Plivo sends a webhook notification when the compliance application status changes (for example, from submitted to accepted or rejected).

Method: Uses the callback_method you specified (GET or POST, default POST).
Signature: Plivo includes a v3 signature in the request header for verification. Use Plivo’s signature validation to verify the callback is authentic.
HTTPS required: The callback_url must use HTTPS.

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 (200 OK)

​Delete a Compliance Application

​Restrictions

​Example

​Response (200 OK)

​Bulk Link Numbers to Compliance

​Requirements

​Arguments

​Example

​Response (200 OK)

​Status Flow

​Error Handling

​Error Response Format

​Common Error Messages

​HTTP Status Codes

​Callbacks

​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 (200 OK)

Delete a Compliance Application

Restrictions

Example

Response (200 OK)

Bulk Link Numbers to Compliance

Requirements

Arguments

Example

Response (200 OK)

Status Flow

Error Handling

Error Response Format

Common Error Messages

HTTP Status Codes

Callbacks

Rate Limits

India Requirements

1. Registration Certificate (file upload required)

2. GST Registration Certificate (file upload required)

Validation Rules

Related