Purchase Numbers

The Purchase API allows you to acquire phone numbers for your Audian account.

Purchase a Phone Number

Purchase an available phone number.

Endpoint

POST https://api.audian.com:8443/v2/numbers/purchase

Parameters

Parameter	Type	Required	Description
number	string	Yes	Phone number in E.164 format (e.g., "+14155551234")
friendly_name	string	No	User-friendly name for the number

Request Example

curl -X POST 'https://api.audian.com:8443/v2/numbers/purchase' \
  -H 'X-Auth-Token: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "number": "+14155551234",
    "friendly_name": "Support Line"
  }'

Response

{
  "success": true,
  "data": {
    "id": "num_abc123",
    "number": "+14155551234",
    "friendly_name": "Support Line",
    "status": "active",
    "purchased_at": "2024-01-15T10:30:00Z",
    "expires_at": "2025-01-15T10:30:00Z",
    "billing": {
      "monthly_cost": 0.99,
      "next_charge": "2024-02-15T10:30:00Z"
    }
  }
}

Response Fields

Field	Type	Description
id	string	Unique identifier for the purchased number
number	string	Phone number in E.164 format
friendly_name	string	User-friendly name
status	string	Current status (active, suspended, etc.)
purchased_at	string	ISO 8601 timestamp of purchase
expires_at	string	ISO 8601 timestamp of renewal date
billing.monthly_cost	number	Monthly rental cost in USD
billing.next_charge	string	ISO 8601 timestamp of next billing date

List Purchased Numbers

Retrieve all phone numbers purchased by your account.

Endpoint

GET https://api.audian.com:8443/v2/numbers

Parameters

Parameter	Type	Required	Description
limit	integer	No	Maximum number of results (default: 20, max: 100)
offset	integer	No	Pagination offset (default: 0)
status	string	No	Filter by status (active, suspended, etc.)

Request Example

curl -X GET 'https://api.audian.com:8443/v2/numbers?status=active&limit=20' \
  -H 'X-Auth-Token: YOUR_API_KEY'

Response

{
  "success": true,
  "data": {
    "numbers": [
      {
        "id": "num_abc123",
        "number": "+14155551234",
        "friendly_name": "Support Line",
        "status": "active",
        "purchased_at": "2024-01-15T10:30:00Z",
        "expires_at": "2025-01-15T10:30:00Z"
      }
    ],
    "total": 5,
    "limit": 20,
    "offset": 0
  }
}

Get Number Details

Retrieve detailed information about a specific number.

Endpoint

GET https://api.audian.com:8443/v2/numbers/{number_id}

Request Example

curl -X GET 'https://api.audian.com:8443/v2/numbers/num_abc123' \
  -H 'X-Auth-Token: YOUR_API_KEY'

Billing

Purchased numbers are billed monthly:

• Setup fees are charged at purchase time
• Monthly rental fees are charged on your billing date
• Unused credits do not roll over to the next month
• You can cancel a number anytime; charges stop immediately

Best Practices

• Set descriptive friendly_name values for easy identification
• Monitor your account for available credit before purchasing
• Purchase numbers in bulk if you need multiple numbers
• Set up proper configuration immediately after purchase

Common Errors

Error Code	Meaning
NUMBER_UNAVAILABLE	The number is no longer available
INSUFFICIENT_CREDIT	Your account lacks sufficient credit
INVALID_REGION	You don't have access to numbers in this region
PURCHASE_FAILED	The purchase could not be processed