Skip to main content
POST
/
phone-numbers
from dari import Dari

client = Dari(api_key="YOUR_API_KEY")

phone_number = client.purchase_phone_number(label="Support Line")
print(f"Purchased phone number: {phone_number['phone_e164']}")

{
  "id": "phone-uuid",
  "phone_e164": "+18782511407",
  "label": "My Support Line",
  "active": true,
  "created_at": "2025-11-09T22:39:45.689803",
  "updated_at": "2025-11-09T22:39:45.689804"
}
This endpoint allows you to purchase a new Twilio phone number that can be used for SMS-based two-factor authentication. The phone number is automatically configured with SMS webhooks for receiving 2FA codes.

​
Headers

​
X-API-Key
string
required
Your API key for authentication

​
Request Body

​
label
string
required
A descriptive label for this phone number (e.g., “Support Line”, “Main 2FA Number”)

​
Response Fields

​
id
string
The unique identifier of the purchased phone number
​
phone_e164
string
The phone number in E.164 format (e.g., “+18782511407”)
​
label
string
The descriptive label for this phone number
​
active
boolean
Whether this phone number is active (always true for newly purchased numbers)
​
created_at
string
ISO 8601 timestamp of when the phone number was purchased
​
updated_at
string
ISO 8601 timestamp of when the phone number was last updated
from dari import Dari

client = Dari(api_key="YOUR_API_KEY")

phone_number = client.purchase_phone_number(label="Support Line")
print(f"Purchased phone number: {phone_number['phone_e164']}")

{
  "id": "phone-uuid",
  "phone_e164": "+18782511407",
  "label": "My Support Line",
  "active": true,
  "created_at": "2025-11-09T22:39:45.689803",
  "updated_at": "2025-11-09T22:39:45.689804"
}

​
Features

  • Real Purchase: Actually purchases a real Twilio phone number (mobile or local US)
  • Auto-Configuration: Automatically configures SMS webhooks for receiving 2FA codes
  • Immediate Use: Phone number is stored with active=True and ready for use immediately
  • Workspace Limits: Enforces workspace limits based on max_phone_numbers setting

​
Usage Notes

  • API Key: Get your API key from the Dari dashboard in workspace settings
  • Workspace Limits: Your workspace has a maximum number of phone numbers it can purchase
  • Enable Feature: Phone 2FA must be enabled for your workspace (max_phone_numbers > 0)
  • US Numbers: Currently only purchases US phone numbers (mobile or local)
  • Costs: Phone number purchases incur Twilio costs that are billed to your workspace

​
Error Responses

{
  "detail": "Workspace has reached maximum phone numbers"
}

{
  "detail": "Invalid API key"
}

{
  "detail": "Phone 2FA not enabled for workspace"
}

{
  "detail": "Failed to purchase number from Twilio"
}

​
What Happens When You Purchase?

  1. Number Selection: System searches for available mobile or local US numbers
  2. Twilio Purchase: Number is purchased through your workspace’s Twilio account
  3. Webhook Setup: SMS webhooks are automatically configured to receive 2FA codes
  4. Database Storage: Number is saved to your workspace with active=True
  5. Ready to Use: Number can immediately be used for SMS-based 2FA in credentials