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. Subaccounts: To file an application for one of your subaccounts, use your main account credentials and set subaccount in the data JSON. Get and List take the same parameter as a filter. 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

string

UUID of the compliance requirement.

string

ISO 3166-1 alpha-2 country code.

string

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

string

Type of end user. Values: individual, business.

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:

string

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

string

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

string

Description of the document type.

boolean

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

array

Data fields required for this document type.

Required Field Object

Each entry in required_fields:

string

Key to use in documents[].data_fields.

string

Human-readable display name.

string

Guidance on what to enter.

string

Values: string, date, enum.

boolean

Whether this field is mandatory.

string

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

string

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

integer

Minimum character 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

string

required

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

string

required

Values: local, mobile, tollfree.

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

string

UUID identifier.

string

Friendly name for the compliance record.

string

Current status. Values: draft, submitted, accepted, rejected, suspended, expired.

string

ISO 3166-1 alpha-2 country code.

string

Type of number.

string

Values: individual, business.

string

Auth ID of the subaccount this application was filed for. Not returned for applications filed for your main account, or if the subaccount has since been deleted.

string

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

string

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

string|null

Reason for rejection. Present only when status is rejected.

string

ISO 8601 timestamp.

string

ISO 8601 timestamp.

object|null

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

array|null

Attached documents (only returned with expand=documents).

array|null

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

End User Object

Returned when using expand=end_user.

string

UUID of the end user.

string

Values: individual, business.

string

Full name or company name.

string

Last name (empty for business).

string

Contact email.

string

Street address line 1.

string

Street address line 2.

string

City.

string

State or province.

string

Postal or ZIP code.

string

Two-letter country code.

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.

string

UUID of the document.

string

UUID of the document type.

string

Document type name.

string

Original filename (empty if no file uploaded).

object

Key-value pairs submitted with the document.

string

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

string

ISO 8601 timestamp.

Linked Number Object

Returned when using expand=linked_numbers.

string

Phone number in E.164 format.

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

string

required

Two-letter country code.

string

required

Values: local, mobile, tollfree.

string

required

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

object

required

End user details.

array

required

Array of document objects.

string

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

string

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

string

Auth ID of one of your subaccounts. Files the application, and its end user, for that subaccount instead of your main account. Use your main account credentials. If omitted, the application is filed for your main account.

end_user fields:

string

required

Values: individual, business.

string

required

Full name or company name.

string

Last name.

string

Contact email.

string

Street address line 1.

string

Street address line 2.

string

City.

string

State or province.

string

Postal or ZIP code.

string

Two-letter country code.

string

Business registration number.

documents[] fields:

string

required

UUID from the Requirements response.

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'

To file the application for one of your subaccounts, add "subaccount": "SAXXXXXXXXXXXXXXXXXX" to the data JSON and call with your main account credentials. The response is the same.

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

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.

string

Auth ID of a subaccount. Use your main account credentials.

A subaccount’s Auth ID: returns the application only if it was filed for that subaccount; otherwise returns 404.
Empty value (subaccount=): returns the application only if it was filed for your main account.

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

integer

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

integer

Pagination offset. Default: 0.

string

Filter by status. Values: draft, submitted, accepted, rejected, suspended, expired.

string

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

string

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

string

Filter by user type. Values: individual, business.

string

Filter by alias.

string

Comma-separated: end_user, documents, linked_numbers.

string

Filter by the account an application was filed for. Use your main account credentials.

A subaccount’s Auth ID: only applications filed for that subaccount.
Empty value (subaccount=): only your main account’s applications.
Omitted: all applications, including those filed for your subaccounts.

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.
subaccount cannot be changed. Leave it out, or pass the value the application already has.
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

string

Updated friendly name (max 99 characters).

object

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

array

Full replacement document set.

string

Updated webhook URL (HTTPS only).

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
An application filed for a subaccount can be linked only to that subaccount’s numbers

Arguments

array

required

Array of number-to-compliance mappings.

string

required

Phone number in E.164 format.

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

Status flow

CreatePOST
SubmittedUnder review
Accepted
Accepted
Link Numbers

If an application is rejected, update it (PATCH) to fix the flagged details — this auto-resubmits it for review.

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)."
}

string

Unique request identifier for tracing.

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'.`
Subaccount not found, or not one of yours (`404`)	`There is no subaccount with auth_id SAXXXXXXXXXXXXXXXXXX`
`subaccount` is your main account’s own Auth ID (Create, `400`)	`There is no subaccount with auth_id MAXXXXXXXXXXXXXXXXXX`
Subaccount could not be verified	`Something went wrong while verifying the subaccount. Please try again later. If the issue persists, contact support@plivo.com.`
Changing `subaccount` on Update	`subaccount cannot be changed on a compliance application.`
Bulk Link: application filed for another subaccount (in `remarks`)	`Compliance application xxx was filed for another sub-account. Use one filed for this number's sub-account, or one of the account's own.`
Server error while checking the subaccount (Get)	`Something went wrong while fetching the compliance application. Please try again later. If the issue persists, contact support@plivo.com.`
Server error while checking the subaccount (List)	`Something went wrong while listing compliance applications. Please try again later. If the issue persists, contact support@plivo.com.`
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.
No subaccount in the payload: Callbacks don’t include subaccount. To route callbacks per customer, set a different callback_url on each subaccount’s application when you create it.

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

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 `data` JSON Structure