Skip to main content
POST
Purchase a workspace phone number

Authorizations

Authorization
string
header
required

Workspace API key or delegated OAuth access token with /v1 resource audience. Administrative routes require the Better Auth browser session instead.

Headers

Idempotency-Key
string
required

Reuse for the same logical action and identical body; changed input returns 409.

Required string length: 1 - 200

Body

application/json
country
string
required
Pattern: ^[A-Z]{2}$
phoneNumber
string
required
Pattern: ^\+[1-9]\d{6,14}$
monthlyCost
string
default:3.00
Pattern: ^\d+(\.\d+)?$
upfrontCost
string
default:0.00
Pattern: ^\d+(\.\d+)?$
currency
string
default:USD
Pattern: ^[A-Z]{3}$
agentId
string
Minimum string length: 1

Response

Successful JSON response

id
string
required
Minimum string length: 1
status
enum<string>
required

Operation state. Completed sends mean provider acceptance, not recipient delivery. Poll pending or unknown operations; do not resend with a new key.

Available options:
pending,
unknown,
completed,
failed
numberId
string | null
required
Minimum string length: 1
error
string | null
required
statusUrl
string
required