API Overview

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>')

const plivo = require('plivo');

const client = new plivo.Client('<auth_id>', '<auth_token>');

require 'plivo'

api = Plivo::RestClient.new('<auth_id>', '<auth_token>')

<?php
require 'vendor/autoload.php';
use Plivo\RestClient;

$client = new RestClient('<auth_id>', '<auth_token>');

import com.plivo.api.Plivo;

Plivo.init("<auth_id>", "<auth_token>");

using Plivo;

var api = new PlivoApi("<auth_id>", "<auth_token>");

package main

import "github.com/plivo/plivo-go/v7"

func main() {
    client, _ := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})
}

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

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

Troubleshooting Common Errors

Code	Common Causes	Solution
`400`	Missing required parameter (src, dst, text), invalid phone number format	Check all required parameters are included. Use E.164 format for numbers (+14155551234)
`401`	Invalid Auth ID or Auth Token, missing authentication header	Verify credentials at Console → API Keys. Ensure Basic Auth header is included
`404`	Invalid Message UUID, number not in account, typo in endpoint URL	Verify the resource UUID exists. Check endpoint spelling
`429`	API rate limit exceeded	Implement exponential backoff. Contact support to increase limits
`500`	Temporary server issue	Retry 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": [...]
}

Parameter	Description
`limit`	Results per page (1-20). Default: 20
`offset`	Number of results to skip. Default: 0

API Resources

Core Resources

Resource	Description
Messages	Send SMS, MMS, and WhatsApp messages
Media	Upload and manage media for MMS

Powerpack Resources

Resource	Description
Powerpack	Manage Powerpacks for traffic distribution
Number Pool	Manage numbers in Powerpack pools

Compliance Resources

Resource	Description
10DLC	Register brands and campaigns for US A2P messaging
Toll-free Verification	Verify 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.

Quickstart - Get started with Messaging API
Concepts - Messaging fundamentals
XML Reference - Messaging XML elements

Getting Started

Concepts

API Reference

XML Reference

Tutorials

Migration Guides

Troubleshooting

API Overview

Base URL

Authentication

Request Format

Response Format

HTTP Status Codes

Troubleshooting Common Errors

API Resources

Core Resources

Powerpack Resources

Compliance Resources

Rate Limits

​Base URL

​Authentication

​Request Format

​Response Format

​HTTP Status Codes

​Troubleshooting Common Errors

​Pagination

​API Resources

​Core Resources

​Powerpack Resources

​Compliance Resources

​Rate Limits

​Related

Base URL

Authentication

Request Format

Response Format

HTTP Status Codes

Troubleshooting Common Errors

Pagination

API Resources

Core Resources

Powerpack Resources

Compliance Resources

Rate Limits

Related