---
title: "Register your own number"
description: "Trillet OEM API: Registers a number you or your customer already own, over a SIP trunk or a Twilio account."
openapi: /public/openapi/trillet-oem.yaml POST /partner/v1/tenants/{tenantId}/numbers/external
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/external`

Registers a number you or your customer already own, over a SIP trunk or a Twilio account.
Trillet does not bill these numbers. 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. A number can be registered only once across Trillet.
    - `provider` (string, required, one of: sip, twilio)
    - `credentials` (object, required) — For `sip`: `sipUri` (where Trillet sends outbound calls), optional `username` and `password`, and optional `ipAddresses` your carrier sends calls from. Each entry in `ipAddresses` is an object: `id` (required, any string you choose, unique in the list), `ip`, and `subnetMask` (the prefix length as a string, for example `"32"`). A plain list of IP strings is refused with `400` `number_registration_failed`. For `twilio`: `accountSid` and `authToken`.

## 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_registration_failed` with the reason.
  - 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 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

Conflict with the current state of the resource.
  - 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
