API Documentation

Version 1.0.0

Welcome to the BirdSMS Developer API. This API allows you to programmatically request virtual phone numbers and retrieve incoming SMS messages. Currently, this API is strictly reserved for high-volume, Diamond-tier users.

Notice: The public API is currently under maintenance. Please use the Dashboard for number allocations.

Authentication

All API requests must include your unique API key in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Endpoints

1. Get Available Services

GET /api/v1/services

Returns a list of available countries and categories with their current rates.

2. Request a Number

POST /api/v1/numbers/request

Allocates a new virtual phone number for a specific service.

{
  "categoryId": "cat_123",
  "countryId": "c_456"
}

3. Get Messages

GET /api/v1/numbers/{assignmentId}/messages

Retrieves all incoming SMS messages for the active assignment.

Rate Limits

The API is rate-limited to 60 requests per minute per user. Exceeding this limit will result in a 429 Too Many Requests response.

Webhooks

For real-time message delivery without polling, you can configure a Webhook URL in your Dashboard settings. We will send a POST request with the SMS payload as soon as it arrives.