Purchase Number

Rent a virtual number from the available inventory.

POSThttps://api.identitycall.ai/api/v1/public/virtual_numbers/purchase

Purchases a phone number through our phone-number provider, attaches it to the account (and the key's project, if project-scoped), and enables inbound call recording.

Requires write permission

Scopes

API key scope	Behavior
Account-wide	Number is created without a project. Assign one later via the dashboard or by patching the resource.
Project-scoped	Number is automatically attached to the key’s bound project.

Request Body

Body Parameters (application/json)

Name	Type	Required	Default	Description
`phone_number`	string	Yes	-	E.164 number to purchase (typically copied from /virtual_numbers/available)
`country_code`	string	No	-	ISO 3166-1 alpha-2 country code
`number_type`	string	No	-	mobile \| local \| toll-free \| national
`name`	string	No	-	Display name to assign to the new virtual number
`requirement_group_id`	integer	No	-	ID of an approved RegulatoryRequirementGroup, if the country requires regulatory documentation
`upfront_cost`	string	No	-	Upfront cost recorded against the number (informational)
`monthly_cost`	string	No	-	Monthly cost recorded against the number (informational)

Request

cURL


curl -X POST "https://api.identitycall.ai/api/v1/public/virtual_numbers/purchase" \
  -H "Authorization: Bearer $IDENTITYCALL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+15551234567",
    "country_code": "US",
    "number_type": "local",
    "name": "US Sales Line"
  }'

Python


import requests
import os
 
API_KEY = os.environ.get("IDENTITYCALL_API_KEY")
 
response = requests.post(
    "https://api.identitycall.ai/api/v1/public/virtual_numbers/purchase",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "phone_number": "+15551234567",
        "country_code": "US",
        "number_type": "local",
        "name": "US Sales Line"
    }
)
 
vn = response.json()["data"]
print(f"Purchased {vn['phone_number']} (id={vn['id']})")

Node.js


const API_KEY = process.env.IDENTITYCALL_API_KEY;
 
const response = await fetch(
  'https://api.identitycall.ai/api/v1/public/virtual_numbers/purchase',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      phone_number: '+15551234567',
      country_code: 'US',
      number_type: 'local',
      name: 'US Sales Line'
    })
  }
);
 
const { data: vn } = await response.json();
console.log(`Purchased ${vn.phone_number} (id=${vn.id})`);

Response

Response201 Created

{
"data": {
  "id": 9,
  "phone_number": "+15551234567",
  "name": "US Sales Line",
  "country_code": "US",
  "active": true,
  "ai_receptionist_enabled": false,
  "operators": [],
  "operators_count": 0
}
}

The newly purchased number has recording: true enabled by default. Attach operators via Add Operator before routing live traffic.

Errors

Status	Error	Description
422	”phone_number is required”	The `phone_number` body field was missing or blank
422	”Requirement group must be approved before purchasing”	The supplied `requirement_group_id` is not in `approved` status
422	Provider error	The upstream provider rejected the purchase (number no longer available, regulatory block, etc.)

Try It

API Key

Body

phone_number*

country_code

number_type

name

Purchase Number

Scopes

Request Body

Body Parameters (application/json)

Request

cURL

Python

Node.js

Response

Errors

See Also

Try It

Try It