Trillet AI logo

Trillet OEM phone numbers

Buy phone numbers for each Trillet OEM tenant, billed to your partner account, or bring your own Twilio account or SIP carrier.

Early access. Trillet OEM is built and in testing with design partners. Contact your account manager to have it enabled for your account. Details may still change.

Each tenant needs at least one number for phone calls. You can buy numbers through Trillet, bring your own, or mix both across tenants.

Endpoints

MethodPathScope
GET/partner/v1/tenants/{tenantId}/numbersresources:read
GET/partner/v1/tenants/{tenantId}/numbers/{numberId}resources:read
POST/partner/v1/tenants/{tenantId}/numbersnumbers:write
POST/partner/v1/tenants/{tenantId}/numbers/externalnumbers:write
DELETE/partner/v1/tenants/{tenantId}/numbers/{numberId}numbers:write

The phone number object

{
  "object": "phone_number",
  "id": "e3e3e3e3e3e3e3e3e3e3e3e3",
  "tenantId": "d9d9d9d9d9d9d9d9d9d9d9d9",
  "phoneNumber": "+15125550142",
  "provider": "telnyx",
  "type": "local",
  "external": false,
  "status": "active",
  "agentId": null,
  "callFlowId": null,
  "billing": {
    "monthlyPrice": 4.99,
    "nextChargeAt": "2026-12-02T10:20:00.000Z",
    "status": "active"
  },
  "createdAt": "2026-11-02T10:20:00.000Z"
}

billing is present for numbers bought through Trillet OEM and null for your own numbers. billing.monthlyPrice is the monthly price in USD, billing.nextChargeAt is when the next month is charged, and billing.status is active or past_due.

GET /numbers/{numberId} for a number that is not in the tenant returns 404 number_not_found.

Buy a number

Find a number with the standard available numbers endpoint, sending the tenant ID in x-workspace-id. Then buy it through Trillet OEM, so it is billed to your partner account instead of a card:

curl -X POST https://api.trillet.ai/partner/v1/tenants/d9d9d9d9d9d9d9d9d9d9d9d9/numbers \
  -H "Authorization: Bearer tpk_live_..." \
  -H "Idempotency-Key: number-cust_8842-1" \
  -H "Content-Type: application/json" \
  -d '{ "phoneNumber": "+15125550142", "country": "US", "type": "local" }'
phoneNumberstringrequired

The number in E.164 format.

countrystringrequired

Two-letter country code.

typestring

local (default) or mobile.

addressSidstring

Regulatory address, for countries that need one.

bundleSidstring

Regulatory bundle, for countries that need one.

Returns 201 with the number. Idempotency-Key is required.

  • Each number costs $4.99 per month, whatever its country and type, unless Trillet has agreed a different number price for your account. The price is fixed on the number when you buy it. A change to your account's agreed price applies from each number's next renewal.
  • The first month is charged to your account when you buy. After that each number renews monthly on the date it was bought. Renewals are processed daily.
  • The 402 below is a check made before the purchase. If the first month's charge then fails after the carrier has sold you the number, the request still returns 201, with billing.status: "past_due". Check billing.status on the response.
  • If a charge cannot be taken, the number keeps working, billing.status becomes past_due, and the charge is retried daily. Each failed renewal attempt sends a number.renewal_failed event, so you get one a day while the number stays past due. Releasing the number is your decision.
  • Number charges appear in usage as phone_number_charge.
StatusCodeWhen
402insufficient_fundsYour account cannot pay for the first month, or a spend cap has been reached
409tenant_suspendedResume the tenant first
400number_purchase_failedThe carrier refused the purchase, for example the number is taken or a regulatory bundle is needed. The message has the reason.

Bring your own numbers

Register a number you or your customer already own. Trillet does not bill these numbers.

curl -X POST https://api.trillet.ai/partner/v1/tenants/d9d9d9d9d9d9d9d9d9d9d9d9/numbers/external \
  -H "Authorization: Bearer tpk_live_..." \
  -H "Idempotency-Key: byo-cust_8842-1" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+15125550199",
    "provider": "sip",
    "credentials": {
      "sipUri": "sip:pbx.example.com",
      "username": "trillet",
      "password": "YOUR_SIP_PASSWORD",
      "ipAddresses": [
        { "id": "carrier-1", "ip": "203.0.113.10", "subnetMask": "32" }
      ]
    }
  }'
phoneNumberstringrequired

The number in E.164 format. A number can be registered only once across Trillet.

providerstringrequired

sip or twilio.

credentialsobjectrequired

For sip: sipUri (where Trillet sends outbound calls), optional username and password, and optional ipAddresses your carrier sends calls from. For twilio: accountSid and authToken.

Each entry in ipAddresses is an object, not a string:

  • id (required): any string you choose, unique in the list
  • ip: the IPv4 address
  • subnetMask: the prefix length as a string, for example "32"

A plain list of IP strings, or an entry without id, is refused with 400 number_registration_failed.

Returns 201 with the number. A refused registration returns 400 number_registration_failed with the reason.

Release a number

curl -X DELETE https://api.trillet.ai/partner/v1/tenants/d9d9d9d9d9d9d9d9d9d9d9d9/numbers/e3e3e3e3e3e3e3e3e3e3e3e3 \
  -H "Authorization: Bearer tpk_live_..."

A bought number goes back to the carrier and stops renewing. Your own number is detached from Trillet. Returns { "object": "phone_number", "id": "...", "released": true }.

Deleting a tenant releases all of its numbers the same way.

Assign a number to an agent

Use the standard assign phone number to agent endpoint, sending the tenant ID in x-workspace-id. It needs resources:write. The agent's call flow must be live, so publish its node flow first.

curl -X POST https://api.trillet.ai/v1/api/agents/e0e0e0e0e0e0e0e0e0e0e0e0/bind/e3e3e3e3e3e3e3e3e3e3e3e3 \
  -H "Authorization: Bearer tpk_live_..." \
  -H "x-workspace-id: d9d9d9d9d9d9d9d9d9d9d9d9" \
  -H "Content-Type: application/json" \
  -d '{ "recordCalls": true }'

Send a JSON body, even an empty {}. Optional fields include recordCalls, officeHours, metadataTags and label. The number must belong to the tenant. POST /v1/api/agents/{agentId}/release/{phoneNumberId} unassigns it.

To change a number's settings later without rebinding it, such as recording, office hours or metadata tags, use the standard update phone number configuration endpoint (PUT /v1/api/twilio/phone-numbers/{phoneNumberId}/config).

Events

Buying or registering a number sends number.provisioned, with phoneNumber and provider in data. Releasing one sends number.released, and so does deleting its tenant, with reason: "tenant_deleted" in data. A failed renewal sends number.renewal_failed. See Events.

A shared partner SIP trunk for all of your tenants is planned.

Last updated on