Skip to main content
The Plivo Messaging API lets you programmatically send and receive SMS, MMS, and WhatsApp messages. The API uses standard HTTP methods and returns JSON responses.

​
Base URL

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

​
Authentication

All API requests use HTTP Basic Authentication with your Plivo credentials:
  • Username: Your Auth ID
  • Password: Your Auth Token
Find your credentials on the Plivo Console Dashboard.
cURL
curl -i --user AUTH_ID:AUTH_TOKEN \
    https://api.plivo.com/v1/Account/{auth_id}/Message/

import plivo

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

​
Request Format

  • Content-Type: application/json for POST requests
  • Content-Type: multipart/form-data for media uploads
  • All request parameters should be JSON-encoded
curl -i --user AUTH_ID:AUTH_TOKEN \
    -H "Content-Type: application/json" \
    -d '{"src": "+14155551234", "dst": "+14155559876", "text": "Hello!"}' \
    https://api.plivo.com/v1/Account/{auth_id}/Message/

​
Response Format

All responses are JSON with an api_id for request tracking: 
{
  "api_id": "db342550-7f1d-11e1-8ea7-1231380bc196",
  "message": "message(s) queued",
  "message_uuid": ["db3ce55a-7f1d-11e1-8ea7-1231380bc196"]
}

​
HTTP Status Codes

CodeDescription
200Request executed successfully
201Resource created
202Resource modified
204Resource deleted
400Invalid or missing parameter
401Authentication failed
404Resource not found
405HTTP method not allowed
429Rate limit exceeded
500Server error

​
Troubleshooting Common Errors

CodeCommon CausesSolution
400Missing required parameter (src, dst, text), invalid phone number formatCheck all required parameters are included. Use E.164 format for numbers (+14155551234)
401Invalid Auth ID or Auth Token, missing authentication headerVerify credentials at Console → API Keys. Ensure Basic Auth header is included
404Invalid Message UUID, number not in account, typo in endpoint URLVerify the resource UUID exists. Check endpoint spelling
429API rate limit exceededImplement exponential backoff. Contact support to increase limits
500Temporary server issueRetry after a few seconds. Check status.plivo.com for outages

​
Pagination

List endpoints return paginated results: 
{
  "meta": {
    "limit": 20,
    "offset": 0,
    "total_count": 100,
    "previous": null,
    "next": "/v1/Account/{auth_id}/Message/?limit=20&offset=20"
  },
  "objects": [...]
}
ParameterDescription
limitResults per page (1-20). Default: 20
offsetNumber of results to skip. Default: 0

​
API Resources

​
Core Resources

ResourceDescription
MessagesSend SMS, MMS, and WhatsApp messages
MediaUpload and manage media for MMS

​
Powerpack Resources

ResourceDescription
PowerpackManage Powerpacks for traffic distribution
Number PoolManage numbers in Powerpack pools

​
Compliance Resources

ResourceDescription
10DLCRegister brands and campaigns for US A2P messaging
Toll-free VerificationVerify toll-free numbers for messaging

​
Rate Limits

API requests are rate limited. If you exceed the limit, you’ll receive a 429 response. Implement exponential backoff for retries.