Skip to main content

Documentation Index

Fetch the complete documentation index at: https://plivo.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

The Verified Caller ID API lets you authenticate phone numbers before using them as caller ID for outbound calls. This is required when using numbers you don’t own through Plivo.

​
API Endpoint

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

​
The Verified Caller ID Object

AttributeTypeDescription
phone_numberstringVerified phone number in E.164 format
aliasstringFriendly name for the caller ID
countrystringCountry code (e.g., US)
verification_uuidstringUnique identifier for verification
created_atstringWhen the verification was created

​
Example Response

{
    "api_id": "870e2ded-58b0-41bc-8c1c-ba00c6a90741",
    "phone_number": "+12025551234",
    "alias": "US Mainland",
    "country": "US",
    "verification_uuid": "f87836bd-f3c0-41bb-9498-125e6faaa4d4",
    "created_at": "2024-02-09T03:52:22.880097813Z"
}

​
Initiate Verification

Start the verification process for a phone number. An OTP will be sent via SMS or voice call. 
POST https://api.plivo.com/v1/Account/{auth_id}/VerifiedCallerId/

​
Parameters

ParameterTypeRequiredDescription
phone_numberstringYesPhone number in E.164 format
aliasstringNoFriendly name for the caller ID
channelstringNoOTP delivery method: sms or call. Default: sms
subaccountstringNoSubaccount Auth ID to associate
import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')

response = client.verify_callerids.initiate_verify(
    phone_number='+12025551234',
    alias='Main Office',
    channel='sms'
)
print(response)

​
Response

{
    "api_id": "654a7ca7-b9cc-4285-86f7-cf581f50409f",
    "message": "Verification code is sent to number +12025551234 which is valid for 15 minutes",
    "verification_uuid": "f87836bd-f3c0-41bb-9498-125e6faaa4d4"
}

​
Complete Verification

Submit the OTP received to complete verification. 
POST https://api.plivo.com/v1/Account/{auth_id}/VerifiedCallerId/Verification/{verification_uuid}/

​
Parameters

ParameterTypeRequiredDescription
otpstringYesThe verification code received
response = client.verify_callerids.verify_caller_id(
    verification_uuid='f87836bd-f3c0-41bb-9498-125e6faaa4d4',
    otp='123456'
)

​
Retrieve a Verified Caller ID

Get details of a specific verified caller ID. 
GET https://api.plivo.com/v1/Account/{auth_id}/VerifiedCallerId/{phone_number}/

response = client.verify_callerids.get_verified_caller_id('+12025551234')

​
List All Verified Caller IDs

Get all verified caller IDs for your account. 
GET https://api.plivo.com/v1/Account/{auth_id}/VerifiedCallerId/

​
Query Parameters

ParameterTypeDescription
limitintegerResults per page (max 20)
offsetintegerPagination offset
countrystringFilter by country code
subaccountstringFilter by subaccount
response = client.verify_callerids.list_verified_caller_id(
    limit=10,
    country='US'
)

​
Update a Verified Caller ID

Update the alias or subaccount of a verified caller ID. 
POST https://api.plivo.com/v1/Account/{auth_id}/VerifiedCallerId/{phone_number}/

​
Parameters

ParameterTypeDescription
aliasstringNew alias name
subaccountstringNew subaccount Auth ID
response = client.verify_callerids.update_verified_caller_id(
    '+12025551234',
    alias='New Name'
)

​
Delete a Verified Caller ID

Remove a verified caller ID from your account. 
DELETE https://api.plivo.com/v1/Account/{auth_id}/VerifiedCallerId/{phone_number}/

client.verify_callerids.delete_verified_caller_id('+12025551234')
Response: HTTP 204 No Content

​
Verification Flow

  1. Initiate - Call the initiate endpoint with the phone number
  2. Receive OTP - OTP is sent via SMS or voice call (valid for 15 minutes)
  3. Verify - Submit the OTP to complete verification
  4. Use - The number can now be used as caller ID

​
Use Cases

ScenarioDescription
Personal NumbersUse your mobile number as caller ID
Business LinesVerify existing business phone numbers
InternationalUse local numbers in different countries
SubaccountsAssign verified IDs to specific subaccounts