---
title: "Purchase numbers"
method: POST
path: "/api/v2/numbers/purchase"
tags: ["Numbers & Inventory"]
---

# Purchase numbers

`POST /api/v2/numbers/purchase`

## Request

- Base URL: `https://app.didlogic.com`
- URL: `https://app.didlogic.com/api/v2/numbers/purchase`
- Auth: HTTP bearer

Purchase one or more DID numbers with identity document association.

**Important notes:**
- Can purchase multiple numbers in a single request
- Identities must contain required documents for the number's country

**When to use:**
- Purchasing numbers with document verification
- Bulk number purchase with identity association

`purchase.purchases[].id` feeds numbers_purchase_update and numbers_purchase_destroy (`id`, `id_in[]`).
`purchase.purchases[].id` feeds purchases_destinations_index and purchases_destinations_create
(`purchase_id`). `purchase.purchases[].number` feeds numbers_purchase_destroy (`did_numbers[]`).
See also: numbers_index.

## Request body

- object
  - `id_in` integer[]: Array of DID IDs to purchase, from numbers_countries_cities_dids_index, numbers_search_show
  - `did_numbers` string[]: Array of DID numbers to purchase, from numbers_countries_cities_dids_index, numbers_search_show
  - `identities` object[]: Array of identity objects with document associations

## Response `200`

purchase DIDs and link documents attached to identity

- object
  - `purchase` object, required: Purchase response object
    - `errors` object, required: Errors that occurred during purchase
    - `purchases` object[], required: Successfully purchased numbers
      - `id` integer, required: DID identifier
      - `number` string, required: Purchased phone number
      - `sms_enabled` boolean, required: Whether SMS is enabled
      - `no_local_cli` boolean, required: Whether local caller ID is disabled
      - `channels` integer, required: Maximum simultaneous calls
      - `country` string, required: Country name
      - `area` string, required: City/area name
      - `free_minutes` integer, required: Free minutes included per month
      - `codec` unknown, required
      - `require_docs` string, required: Comma-separated list of required document type IDs: 1 - Personal ID, 2 - Proof of Address, 3 - Proof of Local Address, 4 - Business Registration, 5 - Local Business Registration, 6 - Letter of Intent
      - `commitment_months` integer: Minimum service term in months (omitted when the commitment policy is disabled)
      - `never_sold` integer, required: Whether number has never been sold before (1=yes, 0=no)
      - `activation` number, float, required: One-time activation fee (USD)
      - `monthly_fee` number, float, required: Monthly recurring fee (USD)
      - `per_minute` number, float, required: Per-minute inbound call rate (USD)
      - `origination_per_min` number, float, required: Per-minute origination rate (USD)

## Other responses

- `400`: returns bad request
- `401`: returns unauthorized
- `422`: returns errors for unprocessed entities

---

[API](https://skmtc.dev/didlogic/apis/get-started.md) · [All operations](https://skmtc.dev/didlogic/apis/get-started/llms.txt) · [OpenAPI document](https://skmtc.dev/didlogic/apis/get-started/revisions/dc972d592b34?raw)