> ## Documentation Index
> Fetch the complete documentation index at: https://www.bolna.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Add number to SIP trunk API
> Add a phone number from your carrier to a SIP trunk via POST /trunk/trunks/{trunk_id}/numbers, optionally with the agent that answers it.
`e164` must be in E.164 format with the plus. Set `destination_key` to the called number exactly as your carrier sends it in the SIP Request-URI, without a leading `+`; for most carriers that is the E.164 digits.
## Next steps
* [Assign an agent](/docs/api-reference/trunks/assign_agent) to answer inbound calls to the number.
* To call out from the number, set the agent's telephony provider to `trunk` with the [Update agent API](/docs/api-reference/agent/v2/patch_update) and pass the number as `from_phone_number` to [`POST /call`](/docs/api-reference/calls/make).
## OpenAPI
````yaml POST /trunk/trunks/{trunk_id}/numbers
openapi: 3.1.0
info:
title: Bolna API
description: >-
Use and leverage Bolna Voice AI using APIs through HTTP requests from any
language in your applications and workflows.
license:
name: MIT
version: 1.0.0
servers:
- url: https://api.bolna.ai
description: Production server
security:
- bearerAuth: []
tags:
- name: SIP trunks
description: >-
Bring-your-own-carrier SIP trunks, their gateways, carrier IPs and
numbers.
paths:
/trunk/trunks/{trunk_id}/numbers:
post:
tags:
- SIP trunks
description: >
Adds a phone number from your carrier to a trunk. The number answers
inbound calls with its agent (or the trunk's `default_inbound_agent_id`)
and can be used as `from_phone_number` for outbound calls from agents
whose telephony provider is `trunk`.
A number can be live on only one trunk on Bolna at a time; adding one
that is already on a trunk returns `409 number_taken`.
parameters:
- in: path
name: trunk_id
required: true
schema:
type: string
format: uuid
description: The trunk's `id`
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TrunkNumberRequest'
example:
e164: '+12025550143'
destination_key: '12025550143'
agent_id: 123e4567-e89b-12d3-a456-426614174000
responses:
'200':
description: The added number
content:
application/json:
schema:
$ref: '#/components/schemas/TrunkNumber'
'400':
description: '`agent_id` is not one of your agents'
content:
application/json:
schema:
$ref: '#/components/schemas/TrunkMessageError'
example:
message: agent not in tenant
'404':
description: No live trunk with this ID belongs to your account
content:
application/json:
schema:
$ref: '#/components/schemas/TrunkMessageError'
'409':
description: >-
The `e164` or `destination_key` is already live on a trunk
(`number_taken`)
content:
application/json:
schema:
$ref: '#/components/schemas/TrunkCodedError'
example:
detail:
code: number_taken
message: This number is already on a trunk.
'422':
description: >-
`e164` is not E.164 (a plus, then 7 to 15 digits, the first of which
is not 0), `destination_key` is missing or empty, or the body has an
unknown field
content:
application/json:
schema:
$ref: '#/components/schemas/TrunkValidationError'
example:
detail:
- loc:
- body
- e164
msg: Value error, e164 must be +
type: value_error
components:
schemas:
TrunkNumberRequest:
type: object
required:
- e164
- destination_key
properties:
e164:
type: string
pattern: ^\+[1-9]\d{6,14}$
description: >-
The number in E.164 format, a plus then 7 to 15 digits. Used as the
caller ID on outbound calls from this number.
example: '+12025550143'
destination_key:
type: string
minLength: 1
description: >
The called number exactly as your carrier puts it in the SIP
Request-URI of an inbound call, without a leading `+`. Required by
the API; for most carriers it is the E.164 number's digits
(`12025550143`), which is what the dashboard fills in. An inbound
call matches the number on its E.164 form first, then on this key.
example: '12025550143'
agent_id:
type: string
nullable: true
description: >-
Agent that answers inbound calls to this number. Must be one of your
agents. Leave out to use the trunk's `default_inbound_agent_id`.
TrunkNumber:
type: object
properties:
id:
type: string
format: uuid
example: 5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9
trunk_id:
type: string
format: uuid
example: 3f2b8c1e-6d4a-4f7b-9e2c-1a5d7b9c0e21
e164:
type: string
example: '+12025550143'
destination_key:
type: string
example: '12025550143'
agent_id:
type: string
nullable: true
description: >-
Agent that answers inbound calls to this number. When `null`, the
trunk's `default_inbound_agent_id` answers.
example: 123e4567-e89b-12d3-a456-426614174000
last_inbound_at:
type: string
format: date-time
nullable: true
description: >-
When this number last took an inbound call, updated at most once a
minute.
last_outbound_at:
type: string
format: date-time
nullable: true
description: >-
When an outbound call was last placed from this number, updated at
most once a minute.
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
is_deleted:
type: boolean
deleted_at:
type: string
format: date-time
nullable: true
TrunkMessageError:
type: object
description: >-
Error body for `400`, `403` and `404` responses from the SIP trunk
endpoints.
required:
- message
properties:
message:
type: string
description: >-
Human-readable reason. On a `404` it names the ID that was not
found.
TrunkCodedError:
type: object
description: >-
Error body for `409` responses from the SIP trunk endpoints.
`detail.code` is stable and machine-readable.
required:
- detail
properties:
detail:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- number_taken
- gateway_conflict
- convert_in_progress
- conflict
description: >
- `number_taken`: the number is already live on a trunk.
- `gateway_conflict`: a gateway is shared with another trunk
without carrier credentials on both.
- `convert_in_progress`: the trunk is mid-migration from a
legacy SIP trunk.
- `conflict`: the change clashes with an existing record.
message:
type: string
description: Human-readable reason.
TrunkValidationError:
type: object
description: >-
Error body for `422` responses from the SIP trunk endpoints. The
rejected input is never echoed back.
properties:
detail:
type: array
items:
type: object
properties:
loc:
type: array
items:
oneOf:
- type: string
- type: integer
description: Where the error is, such as `["body", "channels"]`.
msg:
type: string
description: What is wrong.
type:
type: string
description: >-
Pydantic error type, such as `value_error` or
`less_than_equal`.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.