> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unpod.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Attach Numbers to Trunk

> Map one or more numbers to a SIP trunk and get the origin endpoint

Map one or more numbers to this trunk - the **Leg-A** (BYO carrier) path. The bridge is
auto-resolved and hidden. The response returns the trunk-level **origin endpoint**: the
shared SBC ingress your carrier sends inbound calls to, the mapped DIDs, and the accepted
source IPs.

<Note>
  **Prerequisites:** API Token + Org-Handle. See [Authentication](/api/get-started/authentication).
</Note>

### Headers

| Name          | Type   | Required | Description                                                      |
| ------------- | ------ | -------- | ---------------------------------------------------------------- |
| Authorization | string | Yes      | `Token <your-api-key>`                                           |
| Org-Handle    | string | Yes      | Organization domain handle                                       |
| Product-Id    | string | No       | Product scope for the auto-resolved bridge (default `unpod.dev`) |
| Content-Type  | string | Yes      | `application/json`                                               |

### Path parameters

| Name | Type    | Required | Description |
| ---- | ------- | -------- | ----------- |
| id   | integer | Yes      | Trunk id    |

### Request body

| Field        | Type       | Required | Description                                 |
| ------------ | ---------- | -------- | ------------------------------------------- |
| number\_ids  | integer\[] | Yes      | Numbers to map (deduped, order preserved)   |
| bridge\_slug | string     | No       | Explicit bridge; auto-resolved when omitted |
| region       | string     | No       | Region hint (e.g. `IN`)                     |

### Origin endpoint

| Field                 | Type      | Description                              |
| --------------------- | --------- | ---------------------------------------- |
| ingress               | string    | SBC ingress URI your carrier dials in to |
| dids                  | string\[] | The numbers successfully mapped          |
| accepted\_source\_ips | string\[] | The trunk's source-IP allow-list         |
| region                | string    | Resolved bridge region                   |

### Partial success

`201` if at least one number maps, else `400`. Each `data.numbers` entry reports
`ok`/`error` independently.

<ResponseExample>
  ```json 201 theme={null}
  {
    "status_code": 201,
    "message": "Numbers mapped to trunk.",
    "data": {
      "trunk_id": 21,
      "origin_endpoint": {
        "ingress": "sip:sip.unpod.tel",
        "dids": ["+15551234567"],
        "accepted_source_ips": ["1.2.3.4", "5.6.7.0/24"],
        "region": "us-east"
      },
      "numbers": [
        { "number_id": 501, "number": "+15551234567", "connection_state": "NOT_LINKED", "ok": true }
      ]
    }
  }
  ```

  ```json 400 theme={null}
  {
    "status_code": 400,
    "message": "No numbers could be mapped.",
    "data": {
      "trunk_id": 21,
      "origin_endpoint": { "ingress": "sip:sip.unpod.tel", "dids": [], "accepted_source_ips": ["1.2.3.4"], "region": null },
      "numbers": [
        { "number_id": 501, "ok": false, "error": "Number not found or not available to this organization." }
      ]
    }
  }
  ```
</ResponseExample>

```bash cURL theme={null}
curl -s -X POST "https://unpod.ai/api/v2/platform/telephony/trunks/21/attach-numbers/" \
  -H "Authorization: Token <your-api-key>" \
  -H "Org-Handle: <your-org-handle>" \
  -H "Product-Id: unpod.dev" \
  -H "Content-Type: application/json" \
  -d '{"number_ids": [501]}'
```


## OpenAPI

````yaml POST /api/v2/platform/telephony/trunks/{id}/attach-numbers/
openapi: 3.0.3
info:
  title: Unpod API
  description: REST API for Unpod Voice AI Platform
  version: 2.0.0
servers:
  - url: https://unpod.ai/
    description: QA
  - url: https://unpod.ai/
    description: Production
security: []
tags:
  - name: Organisation
  - name: Spaces
  - name: Agents
  - name: Tasks
  - name: Runs
  - name: Call Logs
  - name: Analytics
  - name: Providers
  - name: Bridges
  - name: Numbers
  - name: Trunks
  - name: Telephony
  - name: Billing
paths:
  /api/v2/platform/telephony/trunks/{id}/attach-numbers/:
    post:
      tags:
        - Trunks
      summary: Attach Numbers to Trunk
      operationId: attachNumbersToTrunk
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            example: 21
        - $ref: '#/components/parameters/OrgHandle'
        - $ref: '#/components/parameters/ProductId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - number_ids
              properties:
                number_ids:
                  type: array
                  items:
                    type: integer
                  example:
                    - 501
                bridge_slug:
                  type: string
                  description: Optional explicit bridge; auto-resolved when omitted.
                region:
                  type: string
                  example: IN
            example:
              number_ids:
                - 501
      responses:
        '201':
          description: Numbers mapped to trunk; origin endpoint returned
          content:
            application/json:
              example:
                status_code: 201
                message: Numbers mapped to trunk.
                data:
                  trunk_id: 21
                  origin_endpoint:
                    ingress: sip:sip.unpod.tel
                    dids:
                      - '+15551234567'
                    accepted_source_ips:
                      - 1.2.3.4
                      - 5.6.7.0/24
                    region: us-east
                  numbers:
                    - number_id: 501
                      number: '+15551234567'
                      connection_state: NOT_LINKED
                      ok: true
        '400':
          description: No numbers could be mapped
          content:
            application/json:
              example:
                status_code: 400
                message: No numbers could be mapped.
                data:
                  trunk_id: 21
                  origin_endpoint:
                    ingress: sip:sip.unpod.tel
                    dids: []
                    accepted_source_ips:
                      - 1.2.3.4
                      - 5.6.7.0/24
                    region: null
                  numbers:
                    - number_id: 501
                      ok: false
                      error: Number not found or not available to this organization.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: Trunk not found
          content:
            application/json:
              example:
                status_code: 404
                message: Trunk not found.
      security:
        - TokenAuth: []
components:
  parameters:
    OrgHandle:
      name: Org-Handle
      in: header
      required: true
      schema:
        type: string
        example: unpod.tv
      description: Organization domain handle
    ProductId:
      name: Product-Id
      in: header
      required: false
      schema:
        type: string
        example: unpod.dev
      description: Product scope for the auto-resolved bridge (default unpod.dev)
  responses:
    Unauthorized:
      description: Unauthorized - Invalid or missing API token
      content:
        application/json:
          example:
            status_code: 401
            message: Authentication credentials were not provided.
  securitySchemes:
    TokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Format: Token <your-api-key>'

````