API Reference
The DIDfarm REST API lets you programmatically search, order, configure and manage DID numbers across 70+ countries. All responses are JSON. TLS is required on all requests.
Base URL:
https://api.didfarm.com/v1
· Authenticate with Authorization: Bearer YOUR_API_KEY
· Get your API key →
Authentication
All API requests require a Bearer token in the Authorization header. Create API keys in your portal. Keys can be scoped to read-only or full access.
# Example request
curl https://api.didfarm.com/v1/numbers \
-H "Authorization: Bearer df_live_sk_..." \
-H "Content-Type: application/json"
Search Available Numbers
GET
/numbers/search
Find available numbers by country and type
Returns a list of available DID numbers matching the given criteria.
| Parameter | Type | Required | Description |
|---|---|---|---|
| country_code | string | required | ISO 3166-1 alpha-2 country code (e.g. GB, US) |
| number_type | string | required | local, toll_free, mobile, or national |
| limit | integer | optional | Max results (default: 20, max: 100) |
// Response
{
"data": [
{
"number": "+44 20 7946 0831",
"country_code": "GB",
"type": "local",
"monthly_price": 2.00,
"setup_fee": 1.00,
"features": ["voice", "sms"],
"available": true
}
],
"meta": { "total": 48, "limit": 20 }
}
200 OK
400 Bad Request
401 Unauthorised
Order a Number
POST
/numbers
Purchase and instantly provision a number
Orders and provisions a number. The number will be live within 60 seconds. Payment must be configured in your portal.
| Parameter | Type | Required | Description |
|---|---|---|---|
| number | string | required | E.164 number from search results |
| billing_cycle | string | optional | monthly (default), quarterly, or annual |
| forwarding | string | optional | SIP URI or E.164 forwarding destination |
// Request body
{
"number": "+44 20 7946 0831",
"billing_cycle": "monthly",
"forwarding": "sip:user@pbx.example.com"
}
Webhook Events
DIDfarm sends POST requests to your webhook URL when events occur. Configure your endpoint in the portal.
Node.js SDK
# Install
npm install @didfarm/sdk
// Usage
const DIDfarm = require('@didfarm/sdk');
const client = new DIDfarm({ apiKey: 'df_live_sk_...' });
// Search numbers
const numbers = await client.numbers.search({
countryCode: 'GB',
numberType: 'local',
limit: 10
});
// Order a number
const order = await client.numbers.order({
number: '+44 20 7946 0831',
billingCycle: 'monthly'
});
Python SDK
# Install
pip install didfarm
# Usage
import didfarm
client = didfarm.Client(api_key="df_live_sk_...")
# Search numbers
numbers = client.numbers.search(
country_code="GB",
number_type="local"
)
# Order a number
order = client.numbers.order(
number="+44 20 7946 0831",
billing_cycle="monthly"
)