# Provision a SIP trunk pair for the customer's voice platform

Source: https://docs.usetone.ai/reference/numbers/provisionSip

> Vobiz numbers only.

`POST /v1/numbers/{id}/sip`
Vobiz numbers only. Inbound calls are sent to `sipUri`; outbound termination credentials are returned ONCE in this response and never stored. The number switches to byo_sip.

Requires the `admin` scope.

## Parameters

| Name | In | | Meaning |
|---|---|---|---|
| `id` | path | required | The number's id. |

## Request body

| Field | Type | | Meaning |
|---|---|---|---|
| `sipUri` | string | required | Your voice platform SIP ingress, for example sip:agent@sip.example.com;transport=tls. The host must be publicly reachable. |
| `transport` | string | optional | Transport for the trunk. Leave it on tls unless your platform cannot terminate it. |

### Example request

```json
{
  "sipUri": "sip:agent@sip.example.com;transport=tls",
  "transport": "tls"
}
```

## Response

| Field | Type | | Meaning |
|---|---|---|---|
| `number` | object | required | The number the trunk was provisioned for, as it now stands. |
| `number.agentId` | string | null | required | The agent that answers calls TO this number. Null on BYO numbers. |
| `number.capabilities` | object | required | What the carrier says this number can carry. |
| `number.capabilities.sms` | boolean | optional | Whether the carrier reports SMS capability. Reported for completeness — Tone does not send SMS. |
| `number.capabilities.voice` | boolean | optional | Whether this number can carry calls. Every number Tone sells can. |
| `number.createdAt` | string | required | When you bought this number, RFC 3339 UTC. Also the rental anniversary the monthly charge falls on. |
| `number.currency` | string | required | Currency for the amounts on this number. INR today. |
| `number.e164` | string | required | E.164, with the country code and a leading `+`. |
| `number.environment` | string | required | `live` or `test`. |
| `number.id` | string | required | The number's id. Use it on every route that addresses this number. |
| `number.inbound` | string | required | Whether a call TO this number can actually be answered right now. `ready` — yes. `no_agent` — routed but nobody assigned. `no_endpoint` — a BYO number with no media endpoint. `unrouted` — no carrier flow, so nothing will ever arrive. |
| `number.label` | string | null | required | Your own name for it. |
| `number.mediaEndpoint` | object | null | required | Where call audio goes when this number routes to your own stack. Null unless routingMode is byo_ws. The endpoint credential is referenced by id, never returned here. |
| `number.nextRentalAt` | string | null | required | When the next month’s rental falls due. Null for sandbox numbers. |
| `number.numberType` | string | null | required | What kind of number this is. Open set — handle an unrecognised value rather than throwing. Today: `landline`, `mobile`, `tollfree`. |
| `number.provider` | string | required | Which carrier operates it. Open set — handle an unrecognised value rather than throwing. Today: `exotel`, `vobiz`, `sandbox`. |
| `number.purchasedAt` | string | null | required | When the number was bought. RFC 3339, UTC. |
| `number.recordCalls` | boolean | required | Per-number recording switch. It can only turn recording OFF — it never enables it where the platform has it disabled. |
| `number.region` | string | null | required | Telecom circle code, e.g. `KA`. |
| `number.releasedAt` | string | null | required | When the number was released back to the carrier. RFC 3339, UTC. Releasing is permanent — the number goes back into general inventory. |
| `number.rentalPaise` | integer | null | required | Monthly rental, in paise. |
| `number.routed` | boolean | required | Whether a carrier flow is attached, as far as our records go. For "can this take a call?", read `inbound` instead. |
| `number.routingMode` | string | required | Who answers the media: a Tone agent, your own WebSocket endpoint, or your SIP platform. Open set — handle an unrecognised value rather than throwing. Today: `tone_agent`, `byo_ws`, `byo_sip`. |
| `number.series` | string | required | Numbering series. Open set — handle an unrecognised value rather than throwing. Today: `regular`, `140`, `160`. |
| `number.setupPaise` | integer | null | required | One-off provisioning charge for this number, in paise. |
| `number.sipTrunk` | object | null | required | The provisioned SIP trunk pair, when this number routes to your own SIP platform. The termination password is shown once at provisioning and never again. |
| `number.status` | string | required | Lifecycle. `suspended` still HOLDS the number — unpaid rent is not a release — and it returns to `active` automatically once the wallet covers what is owed. Open set — handle an unrecognised value rather than throwing. Today: `pending`, `active`, `released`, `failed`, `suspended`. |
| `termination` | object | required | The credentials your voice platform authenticates with. The password appears in this response only — it is not stored in a readable form and cannot be fetched again. |
| `termination.domain` | string | required | The SIP domain to send traffic to. |
| `termination.password` | string | required | Shown exactly once — at provisioning. Store it now. |
| `termination.realm` | string | null | required | Authentication realm, when your platform needs it stated explicitly. |
| `termination.username` | string | required | The SIP username for this trunk. |

### Example response

```json
{
  "data": {
    "number": {
      "agentId": "9f1c2d84-4e3a-4f6c-b902-7d1e8a33c451",
      "capabilities": {
        "sms": false,
        "voice": true
      },
      "createdAt": "2026-08-25T09:14:22Z",
      "currency": "INR",
      "e164": "+918045678901",
      "environment": "live",
      "id": "4b7c1a02-9de5-4f31-bb07-2c1a5e9f0d43",
      "inbound": "ready",
      "label": "Support line — Bengaluru",
      "mediaEndpoint": {
        "authSecretId": "3f1a7f6e-2b4c-4d1e-9a8b-5c6d7e8f9a0b",
        "customParameters": {
          "tenant": "acme"
        },
        "format": "linear16",
        "sampleRate": 16000,
        "type": "static",
        "url": "wss://media.acme.example/tone"
      },
      "nextRentalAt": "2026-09-01T06:30:00Z",
      "numberType": "landline",
      "provider": "exotel",
      "purchasedAt": "2026-08-01T06:30:00Z",
      "recordCalls": true,
      "region": "KA",
      "releasedAt": null,
      "rentalPaise": 50000,
      "routed": true,
      "routingMode": "tone_agent",
      "series": "regular",
      "setupPaise": 50000,
      "sipTrunk": {
        "credentialId": "cred_5a1b",
        "inboundTrunkId": "tin_2c7d",
        "originationSipUri": "sip:acme@sip.livekit.cloud",
        "originationUriId": "ouri_9f2c",
        "outboundTrunkId": "tout_8e3f",
        "provider": "vobiz",
        "terminationDomain": "acme.sip.vobiz.example",
        "terminationRealm": "vobiz.example",
        "terminationUsername": "acme-out",
        "transport": "tls"
      },
      "status": "pending"
    },
    "termination": {
      "domain": "acme.sip.vobiz.example",
      "password": "K7x2QpL9vR4nT1cW",
      "realm": "vobiz.example",
      "username": "acme-out"
    }
  }
}
```