---
title: "Buy a number"
description: "Trillet OEM API: Buys a number for the tenant, billed to your partner account at the standard Trillet number price."
openapi: /public/openapi/trillet-oem.yaml POST /partner/v1/tenants/{tenantId}/numbers
lastUpdated: "2026-10-28"
---

> **For AI agents:** the complete documentation index is at [llms.txt](https://trillet-ai.jamdesk.app/llms.txt). Append `.md` to any page URL for its markdown version.

`POST https://api.trillet.ai/partner/v1/tenants/{tenantId}/numbers`

Buys a number for the tenant, billed to your partner account at $4.99 per month whatever the
country and type, or at the price agreed for your account. The first month is charged when
you buy, then the number renews monthly. If the first month's charge fails after the
carrier purchase, the response is still `201`, with `billing.status: past_due`.
Find numbers first with `GET /v1/api/twilio/available-numbers` and the tenant ID in
`x-workspace-id`. Needs `numbers:write`. `Idempotency-Key` is required.

## Authentication

- `partnerKey` — http bearer (tpk_live_...)

## Header parameters

- `Idempotency-Key` (string, required) — 1 to 255 printable ASCII characters, no spaces. A retry with the same key and request returns the stored response for 24 hours instead of running again. Failed responses are stored too, except `5xx`, `401`, `403`, `409` and `429`: after fixing the cause of a `4xx` such as `402` `insufficient_funds`, retry with a new key.

## Request body

- Content type: `application/json`
  - request body (object)
    - `phoneNumber` (string, required) — E.164 format.
    - `country` (string, required) — Two-letter country code.
    - `type` (string, one of: local, mobile, default: "local")
    - `addressSid` (string) — Regulatory address, for countries that need one.
    - `bundleSid` (string) — Regulatory bundle, for countries that need one.

## Response 201

The number.
  - response (object)
    - `object` (string, required)
    - `id` (string, required) — Use it as `phoneNumberId` when binding the number to an agent.
    - `tenantId` (string, required)
    - `phoneNumber` (string, required) — E.164 format.
    - `provider` (string | null)
    - `type` (string | null)
    - `external` (boolean, required) — `true` for numbers you registered yourself.
    - `status` (string | null)
    - `agentId` (string | null)
    - `callFlowId` (string | null)
    - `billing` — Present for numbers bought through Trillet OEM, `null` for your own numbers.
      - (oneOf)
        - value (null)
        - value (object)
          - `monthlyPrice` (number | null) — Monthly price in USD.
          - `nextChargeAt` (string | null, date-time)
          - `status` (string, one of: active, past_due)
    - `createdAt` (string | null, date-time)

## Response 400

`invalid_request`, or `number_purchase_failed` when the carrier refused the purchase.
  - response (object)
    - `error` (object, required)
      - `type` (string, required, one of: invalid_request_error, authentication_error, permission_error, conflict_error, rate_limit_error, api_error, idempotency_error)
      - `code` (string, required) — A stable code. Handle errors by `code`, not by `message`.
      - `message` (string, required)
      - `param` (string) — The request field the error is about, when there is one.
      - `requestId` (string | null) — Include it when you contact support. Not present on idempotency errors.

## Response 401

Authentication failed. A key that is unknown or revoked returns `invalid_api_key`, an
account without Trillet OEM returns `partner_not_enabled`, and a user session or user API
key returns `partner_key_required`. Handle a `401` by status, not only by `error.code`.
  - response
    - (oneOf)
      - value (object)
        - `error` (object, required)
          - `type` (string, required, one of: invalid_request_error, authentication_error, permission_error, conflict_error, rate_limit_error, api_error, idempotency_error)
          - `code` (string, required) — A stable code. Handle errors by `code`, not by `message`.
          - `message` (string, required)
          - `param` (string) — The request field the error is about, when there is one.
          - `requestId` (string | null) — Include it when you contact support. Not present on idempotency errors.
      - value (object)
        - `error` (string, required)

## Response 402

`insufficient_funds`: your account cannot pay for the first month, or a spend cap has been reached.
  - response (object)
    - `error` (object, required)
      - `type` (string, required, one of: invalid_request_error, authentication_error, permission_error, conflict_error, rate_limit_error, api_error, idempotency_error)
      - `code` (string, required) — A stable code. Handle errors by `code`, not by `message`.
      - `message` (string, required)
      - `param` (string) — The request field the error is about, when there is one.
      - `requestId` (string | null) — Include it when you contact support. Not present on idempotency errors.

## Response 403

`missing_scope`, or `key_restricted` on webhook endpoint routes.
  - response (object)
    - `error` (object, required)
      - `type` (string, required, one of: invalid_request_error, authentication_error, permission_error, conflict_error, rate_limit_error, api_error, idempotency_error)
      - `code` (string, required) — A stable code. Handle errors by `code`, not by `message`.
      - `message` (string, required)
      - `param` (string) — The request field the error is about, when there is one.
      - `requestId` (string | null) — Include it when you contact support. Not present on idempotency errors.

## Response 404

Not found, or not yours. For example `tenant_not_found`.
  - response (object)
    - `error` (object, required)
      - `type` (string, required, one of: invalid_request_error, authentication_error, permission_error, conflict_error, rate_limit_error, api_error, idempotency_error)
      - `code` (string, required) — A stable code. Handle errors by `code`, not by `message`.
      - `message` (string, required)
      - `param` (string) — The request field the error is about, when there is one.
      - `requestId` (string | null) — Include it when you contact support. Not present on idempotency errors.

## Response 409

`tenant_suspended`, or an idempotency conflict.
  - response (object)
    - `error` (object, required)
      - `type` (string, required, one of: invalid_request_error, authentication_error, permission_error, conflict_error, rate_limit_error, api_error, idempotency_error)
      - `code` (string, required) — A stable code. Handle errors by `code`, not by `message`.
      - `message` (string, required)
      - `param` (string) — The request field the error is about, when there is one.
      - `requestId` (string | null) — Include it when you contact support. Not present on idempotency errors.

## Response 422

`idempotency_key_reused`: the same `Idempotency-Key` was sent with a different request.
  - response (object)
    - `error` (object, required)
      - `type` (string, required, one of: invalid_request_error, authentication_error, permission_error, conflict_error, rate_limit_error, api_error, idempotency_error)
      - `code` (string, required) — A stable code. Handle errors by `code`, not by `message`.
      - `message` (string, required)
      - `param` (string) — The request field the error is about, when there is one.
      - `requestId` (string | null) — Include it when you contact support. Not present on idempotency errors.


---

📦 **OpenAPI specs:** Every OpenAPI specification referenced by this documentation is available as a single download — https://trillet-ai.jamdesk.app/api-specs.zip
