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
| Method | Path | Scope |
|---|---|---|
GET | /partner/v1/tenants/{tenantId}/numbers | resources:read |
GET | /partner/v1/tenants/{tenantId}/numbers/{numberId} | resources:read |
POST | /partner/v1/tenants/{tenantId}/numbers | numbers:write |
POST | /partner/v1/tenants/{tenantId}/numbers/external | numbers: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" }'
phoneNumberstringrequiredThe number in E.164 format.
countrystringrequiredTwo-letter country code.
typestringlocal (default) or mobile.
addressSidstringRegulatory address, for countries that need one.
bundleSidstringRegulatory 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
402below 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 returns201, withbilling.status: "past_due". Checkbilling.statuson the response. - If a charge cannot be taken, the number keeps working,
billing.statusbecomespast_due, and the charge is retried daily. Each failed renewal attempt sends anumber.renewal_failedevent, 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.
| Status | Code | When |
|---|---|---|
402 | insufficient_funds | Your account cannot pay for the first month, or a spend cap has been reached |
409 | tenant_suspended | Resume the tenant first |
400 | number_purchase_failed | The 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" }
]
}
}'phoneNumberstringrequiredThe number in E.164 format. A number can be registered only once across Trillet.
providerstringrequiredsip or twilio.
credentialsobjectrequiredFor 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 listip: the IPv4 addresssubnetMask: 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