Provisioning virtual phone numbers via API gives developers full programmatic control over number acquisition, call routing, SMS, and webhooks — without touching a dashboard. This guide covers everything you need to get started with the PBXme REST API.

Why Provision Phone Numbers via API?

Manual number management works at small scale — but when you’re building a SaaS platform, a multi-tenant call center, an AI voice agent, or a communication app, you need to provision and release numbers programmatically. The PBXme REST API lets you:

• Search and provision virtual numbers in 145+ countries instantly
• Configure call forwarding and routing rules per number
• Send and receive SMS on supported numbers
• Receive real-time call and SMS events via webhooks
• Release numbers when no longer needed

All of this is available via standard HTTP requests — no SDK required, though the API works with any language.

Authentication

The PBXme API uses token-based authentication. Send your credentials to the login endpoint to receive an account_token, then include it as a Bearer token in all subsequent requests. Python:

import requests

response = requests.post("https://newsip.pbxme.com/api/login", json={
    "email": "your@email.com",
    "password": "yourpassword"
})
token = response.json()["account_token"]
headers = {"Authorization": f"Bearer {token}"}

Node.js:

const axios = require('axios');

const { data } = await axios.post('https://newsip.pbxme.com/api/login', {
  email: 'your@email.com',
  password: 'yourpassword'
});
const headers = { Authorization: `Bearer ${data.account_token}` };

cURL:

curl -X POST https://newsip.pbxme.com/api/login \
  -H "Content-Type: application/json" \
  -d '{"email":"your@email.com","password":"yourpassword"}'

Searching Available Numbers

Once authenticated, query available numbers by country code and optionally filter by area code or number type (local, toll-free, mobile).

available = requests.get(
    "https://newsip.pbxme.com/api/dids/available",
    params={
        "country_code": "GB",    # ISO 2-letter country code
        "area_code": "207"       # optional: London area code
    },
    headers=headers
)
print(available.json())

The response returns a list of available DIDs with their number, country, monthly rate, and capabilities (voice, SMS, fax).

Provisioning a Number

Once you’ve selected a number from the available list, provision it to your account:

provision = requests.post(
    "https://newsip.pbxme.com/api/dids/provision",
    headers=headers,
    json={
        "did": "+442071234567",
        "label": "UK Sales Line"
    }
)
print(provision.json())

The number is live immediately after provisioning. No waiting period, no manual approval.

Configuring Call Forwarding

After provisioning, set where inbound calls to that number should be routed — a SIP address, a mobile number, a webhook, or your PBX extension:

routing = requests.post(
    "https://newsip.pbxme.com/api/dids/routing",
    headers=headers,
    json={
        "did": "+442071234567",
        "forward_to": "sip:agent@your-pbx.example.com",
        "type": "sip"
    }
)
print(routing.json())

Routing options include: sip, pstn (forward to a regular phone number), webhook, or ivr (route to a PBX IVR menu).

Receiving Call Events via Webhook

To handle inbound calls or call status updates in real time, register a webhook URL. PBXme will POST a JSON payload to your URL on each call event — inbound call, answer, hangup, voicemail, and more.

webhook = requests.post(
    "https://newsip.pbxme.com/api/webhooks/register",
    headers=headers,
    json={
        "did": "+442071234567",
        "url": "https://your-app.example.com/call-events",
        "events": ["inbound", "answer", "hangup"]
    }
)
print(webhook.json())

See the full Webhooks documentation for all event types and payload formats.

Sending SMS via API

For numbers with SMS capability, send outbound text messages with a single POST request:

sms = requests.post(
    "https://newsip.pbxme.com/api/sms/send",
    headers=headers,
    json={
        "from": "+442071234567",
        "to": "+447700900123",
        "message": "Your appointment is confirmed for tomorrow at 10am."
    }
)
print(sms.json())

Inbound SMS messages are delivered to your registered webhook URL. See the SMS API documentation for full details.

Releasing a Number

When a number is no longer needed, release it via API to stop billing:

requests.delete(
    "https://newsip.pbxme.com/api/dids/release",
    headers=headers,
    json={"did": "+442071234567"}
)

API Capabilities Summary

Frequently Asked Questions

Can I provision virtual numbers in any country via the PBXme API?

Yes. The PBXme API supports number provisioning in 145+ countries. Use the /api/dids/available endpoint with a country code to see what’s available in any market.

Is there a sandbox environment for testing?

Yes. PBXme provides an API sandbox where you can test provisioning and call flows without affecting live numbers or incurring charges.

What happens to calls when a number has no routing configured?

Calls will follow the default behavior set in your account — typically going to voicemail. It is recommended to configure routing immediately after provisioning.

Can I receive inbound SMS via webhook?

Yes. Inbound SMS messages are delivered to your webhook URL as POST requests in JSON format, the same way call events are delivered.

Is the API rate limited?

The API has rate limits in place to ensure fair usage. For high-volume provisioning needs, contact PBXme support to discuss your requirements.

Explore the API Sandbox →