Buy a number

POST

Buy a number and make it an SMS channel in the same call. The purchase follows the same rules as POST /v1/phone-numbers, including regulatory requirements, and the number comes back with SMS on. There is no separate assign step. Where it lands: when the project's default channel group has no number yet, the number joins that group (and becomes the project's first channel and default when there is none); otherwise it gets a channel group of its own.

While the number is in regulatory review (number.regulatoryStatus: pending_review) it is attached but cannot send, and channels can be empty until it is approved. If the purchase succeeded but turning SMS on failed, the number is still bought and billed; the response says so in setupError rather than failing the call.

Authorization

Authorizationheaderrequired
Bearer YOUR_API_KEY. Create a key in the dashboard.

Body

application/json

phoneNumberstringrequired
Phone number in E.164 format.
namestring
Optional custom name for the phone number.
Limitsmax length 100
typestring
Type the number was found under in GET /v2/numbers/available. Used to look the number up and to keep regulatory information for reuse. Required when regulatoryRequirements is sent. toll_free is accepted as an alias of tollFree. A number not listed under this type is refused with 400 number_unavailable saying so.
One oflocalnationaltollFreemobile
regulatoryRequirementsobject[]
Regulatory information, for numbers whose requirements list is not empty. Get the list with GET /v1/phone-numbers/requirements?phoneNumber=... and send one entry per requirement id, except action requirements, which take no value. Every required id must be present, once, and no unknown id may be sent; otherwise the purchase is refused with 400 invalid_request before anything is charged.
The information is kept for your project under the number's country and type. A later purchase there may omit this field if what is kept still covers that number's requirements. Omit it for numbers without requirements.
Limitsmax items 50
2 properties
- requirementTypestringrequired
  A requirementTypes[].id from GET /v1/phone-numbers/requirements. Each id may appear only once.
  Limitsmin length 1 · max length 200
- fieldValuestringrequired
  Depends on the requirement's type: the text itself for textual; for address, the id of an address created in this project with POST /v1/addresses; for document, the id of a document created with POST /v1/documents. An address or document from another project, or one rejected in review, is refused.
  Limitsmin length 1 · max length 1000

Responses

201Bought.

numberobjectrequired
10 properties
- idstringrequired
- phoneNumberstringrequired
- namestring
  Optional custom name for the phone number.
- capabilitiesstring[]required
- statusstringrequired
  Billing state of an owned number, separate from regulatoryStatus. pending is legacy and is not written to numbers today.
  One ofactivesuspendedpendingreleasingreleased
- pricingobjectrequired
  4 properties
  - monthlyPricenumber
    Monthly price in USD.
  - upfrontCostnumber
    One-time purchase cost in cents.
  - monthlyCostnumber
    Monthly cost in cents.
  - isFreeNumberboolean
    Whether this is a free number.
- regulatoryStatusstringrequired
  Regulatory review state. Numbers that need no review are approved immediately. A number bought with regulatory information is owned and billed from purchase and starts pending_review; it cannot send messages or place calls until this is approved, and its channels entry can be absent until then. The state is re-checked every 6 hours.
  One ofapprovedpending_reviewrejected
- nextRenewalDatestring<date-time>
- createdAtstring<date-time>required
- updatedAtstring<date-time>
channelsobject[]required
The entries of the new number (sms, once routed).
4 properties
- addressstringrequired
  The address the recipient sees: an E.164 number (sms, voice, whatsapp), an email address (lowercase), @botname (telegram), @username (instagram), the Facebook Page id (messenger), or the literal sms_oneway (one-way SMS goes out from shared system numbers, and messages on it store this same literal as from).
- typestringrequired
  A transport a message travels on.
  One ofsmssms_onewaywhatsapptelegramemailinstagrammessengervoice
- activebooleanrequired
  It can send right now. A connected transport that is switched off is listed with active: false; turn it on with POST /v2/channels/{address}/{type}/activate. sms, sms_oneway and voice have no switch and are always active.
- v1SenderIdstringrequired
  Read-only. The /v1 sender behind this entry, usable as the Zavu-Sender header on /v1. Entries with the same v1SenderId are one channel group. On /v2 it is accepted as from only when two entries of different groups share an address (see 409 ambiguous_from).
setupErrorobject
Present only when the purchase succeeded and turning SMS on did not. details.recommendation says how to retry.
3 properties
- codestringrequired
- messagestringrequired
- detailsobject
  Machine-readable context. Keys that mean the same thing everywhere: - errors: present on every 400 invalid_request for an invalid body or query parameter, [{path, message, ...}], path naming the field (["to"], ["contacts", 2, "recipient"], ["limit"]). - recommendation: one sentence saying what to do next. - dashboardUrl: the dashboard screen that fixes it. - connect: on 409 no_channel, the channels this project can connect to reach the recipient, each {type, request, note, available, dashboardUrl?}; request is the exact call (POST /v2/channels with its body, or POST /v2/numbers), or null for a channel connected from the dashboard (WhatsApp, Instagram, Messenger). available: false says why in note (one-way SMS closed until business verification is approved). - address / from: the address the error is about, under the name the request used for it.
  1 properties
  - errorsobject[]
    3 properties
    pathobject[]required
    messagestringrequired
    codestring

400`number_unavailable`, `regulatory_compliance_required`, `invalid_request`.

codestringrequired
messagestringrequired
detailsobject
Machine-readable context. Keys that mean the same thing everywhere: - errors: present on every 400 invalid_request for an invalid body or query parameter, [{path, message, ...}], path naming the field (["to"], ["contacts", 2, "recipient"], ["limit"]). - recommendation: one sentence saying what to do next. - dashboardUrl: the dashboard screen that fixes it. - connect: on 409 no_channel, the channels this project can connect to reach the recipient, each {type, request, note, available, dashboardUrl?}; request is the exact call (POST /v2/channels with its body, or POST /v2/numbers), or null for a channel connected from the dashboard (WhatsApp, Instagram, Messenger). available: false says why in note (one-way SMS closed until business verification is approved). - address / from: the address the error is about, under the name the request used for it.
1 properties
- errorsobject[]
  3 properties
  - pathobject[]required
  - messagestringrequired
  - codestring

401Unauthorized.

codestringrequired
messagestringrequired
detailsobject
Machine-readable context. Keys that mean the same thing everywhere: - errors: present on every 400 invalid_request for an invalid body or query parameter, [{path, message, ...}], path naming the field (["to"], ["contacts", 2, "recipient"], ["limit"]). - recommendation: one sentence saying what to do next. - dashboardUrl: the dashboard screen that fixes it. - connect: on 409 no_channel, the channels this project can connect to reach the recipient, each {type, request, note, available, dashboardUrl?}; request is the exact call (POST /v2/channels with its body, or POST /v2/numbers), or null for a channel connected from the dashboard (WhatsApp, Instagram, Messenger). available: false says why in note (one-way SMS closed until business verification is approved). - address / from: the address the error is about, under the name the request used for it.
1 properties
- errorsobject[]
  3 properties
  - pathobject[]required
  - messagestringrequired
  - codestring

402`insufficient_balance` or `paid_plan_required`.

codestringrequired
messagestringrequired
detailsobject
Machine-readable context. Keys that mean the same thing everywhere: - errors: present on every 400 invalid_request for an invalid body or query parameter, [{path, message, ...}], path naming the field (["to"], ["contacts", 2, "recipient"], ["limit"]). - recommendation: one sentence saying what to do next. - dashboardUrl: the dashboard screen that fixes it. - connect: on 409 no_channel, the channels this project can connect to reach the recipient, each {type, request, note, available, dashboardUrl?}; request is the exact call (POST /v2/channels with its body, or POST /v2/numbers), or null for a channel connected from the dashboard (WhatsApp, Instagram, Messenger). available: false says why in note (one-way SMS closed until business verification is approved). - address / from: the address the error is about, under the name the request used for it.
1 properties
- errorsobject[]
  3 properties
  - pathobject[]required
  - messagestringrequired
  - codestring

502`requirements_unavailable`; nothing charged.

codestringrequired
messagestringrequired
detailsobject
Machine-readable context. Keys that mean the same thing everywhere: - errors: present on every 400 invalid_request for an invalid body or query parameter, [{path, message, ...}], path naming the field (["to"], ["contacts", 2, "recipient"], ["limit"]). - recommendation: one sentence saying what to do next. - dashboardUrl: the dashboard screen that fixes it. - connect: on 409 no_channel, the channels this project can connect to reach the recipient, each {type, request, note, available, dashboardUrl?}; request is the exact call (POST /v2/channels with its body, or POST /v2/numbers), or null for a channel connected from the dashboard (WhatsApp, Instagram, Messenger). available: false says why in note (one-way SMS closed until business verification is approved). - address / from: the address the error is about, under the name the request used for it.
1 properties
- errorsobject[]
  3 properties
  - pathobject[]required
  - messagestringrequired
  - codestring


curl -X POST "https://api.zavu.dev/v2/numbers" \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "phoneNumber": "+15551234567"
}'


{
  "number": {
    "id": "string",
    "phoneNumber": "+15551234567",
    "name": "string",
    "capabilities": [
      "sms",
      "voice"
    ],
    "status": "active",
    "pricing": {
      "monthlyPrice": 1,
      "upfrontCost": 1,
      "monthlyCost": 1,
      "isFreeNumber": true
    },
    "regulatoryStatus": "approved",
    "nextRenewalDate": "2026-01-01T00:00:00Z",
    "createdAt": "2026-01-01T00:00:00Z",
    "updatedAt": "2026-01-01T00:00:00Z"
  },
  "channels": [
    {
      "address": "+13125551212",
      "type": "sms",
      "active": true,
      "v1SenderId": "string"
    }
  ],
  "setupError": {
    "code": "invalid_request",
    "message": "string",
    "details": {
      "errors": [
        {
          "path": {},
          "message": {},
          "code": {}
        }
      ]
    }
  }
}