Purchase phone number

curl -X POST https://api.talkif.ai/api/v1/phone/numbers/twilio/purchase \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "phoneNumber": "+15551234567",
  "providerId": "550e8400-e29b-41d4-a716-446655440000"
}'

{
  "accountId": "550e8400-e29b-41d4-a716-446655440000",
  "billingStatus": "active",
  "canInitiateCalls": true,
  "capabilities": [
    "SMS"
  ],
  "channelType": "pstn",
  "createdAt": "2026-01-15T10:30:00Z",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "isVerified": true,
  "monthlyCost": "1.00",
  "phoneNumber": "+15551234567",
  "providerId": "550e8400-e29b-41d4-a716-446655440000",
  "providerPhoneId": "PN1234567890abcdef1234567890abcdef",
  "purchasedAt": "2026-01-15T10:30:00Z",
  "recordingOverride": "do-not-record",
  "status": "ACTIVE",
  "twilioEdge": "ashburn",
  "twilioRegion": "us1",
  "updatedAt": "2026-01-15T10:30:00Z",
  "connectedAt": "2024-01-15T09:30:00Z",
  "connectedFlow": null,
  "friendlyName": "string",
  "nextBillingDate": "2024-01-15T09:30:00Z",
  "releasedAt": "2024-01-15T09:30:00Z",
  "verifiedAt": "2024-01-15T09:30:00Z"
}

POST /api/v1/phone/numbers/twilio/purchase

Authentication

AuthorizationBearer

Pass a JWT access token or an API key (prefixed with tif_live_) as a Bearer token.

Request

This endpoint expects an object.

phoneNumberstringRequired

Phone number to purchase in E.164 format

providerIdstringRequired

ID of the provider to purchase through

friendlyNamestring or nullOptional

Optional friendly name for the number

Response

Phone number purchased

accountIdstringformat: "uuid"

Account that owns this phone number

billingStatusstring

Current billing status (active, processing, past_due, suspended)

canInitiateCallsboolean

Whether this number can place outbound calls (WhatsApp numbers are receive-only)

capabilitieslist of enums

Supported capabilities (voice, SMS, MMS)

channelTypeenum

Routing channel of this number (pstn or whatsapp)

createdAtdatetime

Timestamp when the record was created

idstringformat: "uuid"

Unique identifier of the phone number

isVerifiedboolean

Whether the phone number has been verified via caller ID validation

monthlyCoststring

Monthly recurring cost formatted as a decimal string

phoneNumberstring

Phone number in E.164 format

providerIdstringformat: "uuid"

Provider through which this number was provisioned

providerPhoneIdstring

Provider-specific phone number identifier (e.g. Twilio SID)

purchasedAtdatetime

Timestamp when the number was purchased

recordingOverridestring

Recording override setting for calls on this number

statusenum

Current status of the phone number

twilioEdgestring

Twilio edge location for SIP signaling (e.g. ashburn, frankfurt)

twilioRegionstring

Twilio API region (us1 or ie1)

updatedAtdatetime

Timestamp when the record was last updated

connectedAtdatetime or nullOptional

Timestamp when a flow was connected to this number

connectedFlowobject or nullOptional

Connected flow information (populated when flow is connected)

friendlyNamestring or nullOptional

User-assigned friendly name for the number

nextBillingDatedatetime or nullOptional

Next scheduled billing date for the monthly charge

releasedAtdatetime or nullOptional

Timestamp when the number was released, if applicable

verifiedAtdatetime or nullOptional

Timestamp when the number was verified

Errors

400

Bad Request Error

401

Unauthorized Error

402

Payment Required Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

429

Too Many Requests Error

500

Internal Server Error