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

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

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.

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'

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.

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.

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

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

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'.`
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

​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