Phone Numbers

Purchase a number

Purchases a number found via search and bills your wallet for the first month at your plan's rate (no setup fee; an included Pro Bundle number costs nothing). Voice and messaging webhooks can be provisioned in the same call, so the number is fully wired the moment it activates — no dashboard visit needed.

type is optional and derived from the number itself (8NN prefixes are toll-free). Purchasing is idempotent on the number: re-purchasing a number you already own returns 200 with the existing record instead of billing twice. A number you previously released is automatically restored from the recycle bin rather than re-ordered.

A2P messaging registration provisions asynchronously after purchase — the number's messaging.ready flag flips to true when it can send SMS/MMS.

post/api/v1/numbers

Request

  • Base URL: https://api.callnode.io
  • URL: https://api.callnode.io/api/v1/numbers
  • Auth: API key in header X-Api-Key and API key in header X-Timestamp and API key in header X-Signature

Request body

phoneNumberstring required

Plus sign followed by 7–15 digits.

type'local' | 'tollfree'

Optional — derived from the number itself when omitted.

friendlyNamestring
tagsstring[]

Your own labels for the number. Trimmed, de-duplicated case-insensitively, returned on every number, filterable on the dashboard. PATCH replaces the whole list; send [] to clear.

Example request

{
  "phoneNumber": "+16135551234",
  "tags": [
    "support",
    "east-coast"
  ]
}

Response

Idempotent replay — you already own this number; nothing was billed.

chargednumber

Amount deducted from your wallet. 0 for included-in-plan numbers and idempotent replays.

includedInSubscriptionboolean
idempotencyReplayboolean

True when you already owned this number and nothing was billed.

Example response

{
  "number": {
    "id": "cmpxeh9o60002pp4h7oznictb",
    "phoneNumber": "+16135551234",
    "status": "active",
    "tags": [
      "support",
      "east-coast"
    ],
    "monthlyRate": 1.99,
    "perMinuteRate": 0.02
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.