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

# Share a Phone Number Between Agents

> Let several DialNexa agents call from one phone number, with callbacks routed to the agent that last called each person.

Changes state - verify before retry

Share a phone number between agents when several agents need to call leads from the same caller ID. A shared number has any number of outbound agents and no inbound agent. When someone calls the number back, DialNexa connects them to the most recent agent that called them from this number and is still linked to it.

## When to use this

* **One caller ID, several campaigns**: a sales agent and a renewals agent both call from your main business number.
* **Callbacks that reach the right agent**: a lead who calls back talks to the agent that called them, not a generic inbound agent.

Keep the number unshared if it needs one fixed inbound agent, for example a support line that anyone can call.

## How callbacks are routed on a shared number

| Situation | What happens to the inbound call |
| - | - |
| One linked agent called this person | The call goes to that agent, on its latest published version. |
| Several linked agents called this person | The call goes to the agent that called most recently. |
| The agent that called most recently was detached from the number | The call goes to the next most recent agent that called this person and is still linked. |
| No agent that is still linked has called this person | The call is rejected before it is answered, so the caller hears no message. The call log shows `end_reason: "agent_not_found"` and `json_output.failure_reason: "no_linked_dialler"`, so you can see the caller's number and call them back. |

A call counts as calling the person when it reached their phone: answered, busy, or not picked up. A call that failed before ringing does not count.

A default number can be shared so several agents call from it, but it never answers inbound calls, so every callback to it is refused.

## Workflows on a shared number

* **Voice Call steps keep their agent.** Turning sharing on sets the number's outbound agent as `configured_agent_id` on every workflow Voice Call step that uses the number and names no agent. Attaching a second outbound agent does the same first. Those steps keep calling as that agent after more agents join.
* **Steps on a number with several agents name their agent.** A Voice Call step on a shared number with more than one agent must set `configured_agent_id` to one of them, or the workflow cannot be activated.
* **Callbacks from workflow leads.** When a workflow lead calls a shared number back, the lead moves to the workflow's first Voice Call step on that number that calls as the agent answering. If the workflow has no such step, the call is answered and the workflow does not move.

## Before you begin

* Get the number's `phn_` ID from [List Phone Numbers](https://dialnexa.com/docs/api-reference/v1/phone-numbers/list.md).
* Turning sharing on removes the number's inbound agent. Check `inbound_agent_id` with [Get Phone Number Details](https://dialnexa.com/docs/api-reference/v1/phone-numbers/get.md) and move that agent to another number first if it must keep answering calls.
* Wait for live inbound calls on the number to end. They block the change.
* Turning sharing off needs at most one outbound agent. Detach the others with [Detach Agent Phone Number](https://dialnexa.com/docs/api-reference/v1/agents/detach-phone-number.md) first.

## Share a phone number request

```bash theme={null}
curl -X PUT "https://api.dialnexa.com/v1/organization-phone-numbers/phn_mfk3p8z2c4v6bn/shared-outbound" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'
```

Then attach each agent to the number with [Attach Agent Phone Number](https://dialnexa.com/docs/api-reference/v1/agents/attach-phone-number.md) and `"direction": "outbound"`. On a shared number the link is added next to the existing agents, and `move` is ignored.

Send `{ "enabled": false }` to stop sharing. The number then has no inbound agent until you attach one.

## Verify the result

A `200` response returns the phone number in `data`, with:

* `shared_outbound` set to the value you sent.
* `outbound_agent_ids` listing every agent that can call from the number, newest link first.
* `inbound_agent_id` set to null when sharing is on.
* `detached_inbound_agent_id` naming the agent that stopped answering this number, or null when there was none.

If the request times out, read the number with [Get Phone Number Details](https://dialnexa.com/docs/api-reference/v1/phone-numbers/get.md) before retrying.

## Errors and recovery

Refusals carry a code in `data.code`.

| Status | Code | Cause and fix |
| - | - | - |
| `400` | none | `enabled` is missing or not a boolean. |
| `404` | none | The number is not in this workspace. |
| `409` | `PHONE_NUMBER_HAS_LIVE_CALLS` | An inbound call is live on the number while you turn sharing on. Retry once it ends. |
| `409` | `MULTIPLE_OUTBOUND_AGENTS` | Two or more agents still call from the number (`data.agent_ids`) while you turn sharing off. Detach all but one, then retry. |

## Related endpoints

* [Get Phone Number Details](https://dialnexa.com/docs/api-reference/v1/phone-numbers/get.md)
* [Attach Agent Phone Number](https://dialnexa.com/docs/api-reference/v1/agents/attach-phone-number.md)
* [Detach Agent Phone Number](https://dialnexa.com/docs/api-reference/v1/agents/detach-phone-number.md)
* [Phone numbers overview](https://dialnexa.com/docs/api-reference/v1/phone-numbers/overview.md)


## OpenAPI

````yaml PUT /v1/organization-phone-numbers/{id}/shared-outbound
openapi: 3.0.0
info:
  title: DialNexa API
  description: Public `/v1` REST API for the DialNexa voice AI platform.
  version: 1.0.0
servers:
  - url: https://api.dialnexa.com
    description: DialNexa production API
security:
  - bearer: []
tags:
  - name: Agents
  - name: Batch Calls
  - name: Calls
  - name: Knowledge Base
  - name: Languages
  - name: LLMs
  - name: Phone Numbers
  - name: Organization Folders
  - name: Transcribers
  - name: Webhooks
  - name: Voices
  - name: Workflows
  - name: Workflow Leads
  - name: Authentication
  - name: Agent Builder
  - name: Agent Evaluations
paths:
  /v1/organization-phone-numbers/{id}/shared-outbound:
    put:
      tags:
        - Phone Numbers
      summary: Share Phone Number Between Agents
      description: >-
        Turns shared outbound mode on or off for a workspace phone number. A
        shared number can be dialed from by several agents and has no inbound
        agent: each inbound call goes to the most recent agent that called the
        caller from this number and is still linked to it. Turning it on removes
        the number's inbound agent in the same request.
      operationId: setPhoneNumberSharedOutbound
      parameters:
        - name: id
          required: true
          in: path
          description: Phone number ID
          schema:
            type: string
            example: phn_abc123
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetSharedOutboundRequest'
            examples:
              enable:
                summary: Share the number
                value:
                  enabled: true
              disable:
                summary: Stop sharing
                value:
                  enabled: false
      responses:
        '200':
          description: >-
            Sharing updated. Returns the phone number with
            detached_inbound_agent_id.
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - error
                  - statusCode
                  - message
                  - data
                  - timestamp
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  error:
                    type: boolean
                    enum:
                      - false
                  statusCode:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: Success
                  data:
                    allOf:
                      - $ref: '#/components/schemas/PhoneNumberRecord'
                      - type: object
                        properties:
                          detached_inbound_agent_id:
                            type: string
                            nullable: true
                            description: >-
                              The agent that stopped answering this number
                              because sharing was turned on; null when it had no
                              inbound agent or sharing was turned off.
                        required:
                          - detached_inbound_agent_id
                  timestamp:
                    type: string
                    format: date-time
              examples:
                success:
                  summary: Successful response
                  value:
                    success: true
                    error: false
                    statusCode: 200
                    message: Success
                    data:
                      id: phn_mfk3p8z2c4v6bn
                      phone_number: '9876543210'
                      status: active
                      country_iso: '91'
                      telephony_provider_id: mh00mke5j83neo
                      organization_id: o14XKPP84rt22g
                      inbound_agent_id: null
                      outbound_agent_id: agent_2g7Xy3tY53gRlp
                      outbound_agent_ids:
                        - agent_2g7Xy3tY53gRlp
                      shared_outbound: true
                      rental_start_date: '2026-09-17'
                      rental_end_date: '2026-10-17'
                      rental_status: active
                      sip_trunk_enabled: false
                      nickname: null
                      is_deleted: false
                      deleted_at: null
                      deleted_by: null
                      created_at: '2026-09-17T05:52:18.634Z'
                      updated_at: '2026-09-17T05:52:18.634Z'
                      detached_inbound_agent_id: agent_7h2Kq9Lm4Np3Rs
                    timestamp: '2026-09-07T06:00:00.000Z'
        '400':
          description: 'The body is invalid: enabled is missing or not a boolean.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 401 Unauthorized
                  value:
                    statusCode: 401
                    error: true
                    success: false
                    data: []
                    message: Invalid API key
                    errors: []
        '404':
          description: Phone number not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 404 Not Found
                  value:
                    statusCode: 404
                    error: true
                    success: false
                    data: []
                    message: >-
                      Failed to fetch phone number: Phone number not found or
                      does not belong to your organization
                    errors: []
        '409':
          description: >-
            Sharing cannot change right now: an inbound call is live on the
            number, or two or more agents still call from it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CodedErrorResponse'
              examples:
                liveCalls:
                  value:
                    statusCode: 409
                    error: true
                    success: false
                    data:
                      code: PHONE_NUMBER_HAS_LIVE_CALLS
                      live_calls: 1
                      batches: []
                    message: >-
                      1 call(s) are in progress on this number. Wait for them to
                      finish, then retry.
                    errors: []
                multipleOutboundAgents:
                  value:
                    statusCode: 409
                    error: true
                    success: false
                    data:
                      code: MULTIPLE_OUTBOUND_AGENTS
                      agent_ids:
                        - agent_2g7Xy3tY53gRlp
                        - agent_7h2Kq9Lm4Np3Rs
                    message: >-
                      2 agents call from this number. Detach all but one before
                      you stop sharing it.
                    errors: []
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 500 Internal Server Error
                  value:
                    statusCode: 500
                    error: true
                    success: false
                    data: []
                    message: Internal server error
                    errors: []
      security:
        - bearer: []
components:
  schemas:
    SetSharedOutboundRequest:
      type: object
      properties:
        enabled:
          type: boolean
          example: true
          description: >-
            true lets several agents dial from this number. Its inbound agent is
            detached and each callback goes to the agent that last called the
            person; calls from people no linked agent has called are not
            answered.
      required:
        - enabled
    PhoneNumberRecord:
      type: object
      description: >-
        A phone number owned by the workspace, as stored. Returned by the list
        and get endpoints.
      properties:
        id:
          type: string
          example: phn_mfk3p8z2c4v6bn
          description: Signed phone number ID.
        phone_number:
          type: string
          example: '9876543210'
          pattern: ^[0-9]+$
          description: >-
            National number without the country calling code or a plus sign, as
            a string of digits. Build the E.164 form as + followed by
            country_iso and phone_number.
        status:
          type: string
          enum:
            - pending
            - active
          description: Provisioning status of the number.
        country_iso:
          type: string
          example: '91'
          description: >-
            Country calling code without the plus sign, for example 91 or 1.
            This is not an ISO country code.
        telephony_provider_id:
          type: string
          description: Telephony provider the number belongs to.
        organization_id:
          type: string
          description: Owning organization.
        inbound_agent_id:
          type: string
          nullable: true
          description: >-
            Agent that answers inbound calls on this number, on its latest
            published version; null when none is linked. Always null when
            shared_outbound is true.
        outbound_agent_id:
          type: string
          nullable: true
          deprecated: true
          description: >-
            Deprecated: read outbound_agent_ids. The agent with the newest
            outbound link to this number (outbound_agent_ids[0]); null when none
            is linked.
        outbound_agent_ids:
          type: array
          items:
            type: string
          example:
            - agent_2g7Xy3tY53gRlp
          description: >-
            Every agent that can call from this number, newest link first. Holds
            more than one agent only when shared_outbound is true.
        shared_outbound:
          type: boolean
          default: false
          description: >-
            When true, several agents can call from this number and it has no
            inbound agent. An inbound call goes to the most recent agent that
            called the caller from this number and is still linked to it;
            callers no linked agent has called are refused.
        rental_start_date:
          type: string
          format: date
          nullable: true
          example: '2026-09-17'
        rental_end_date:
          type: string
          format: date
          nullable: true
          example: '2026-10-17'
        rental_status:
          type: string
          nullable: true
          enum:
            - active
            - expired
            - available_for_reassignment
        sip_trunk_enabled:
          type: boolean
          description: Whether a SIP trunk is linked to this number.
        nickname:
          type: string
          nullable: true
          description: Label set in the dashboard.
        is_deleted:
          type: boolean
        deleted_at:
          type: string
          format: date-time
          nullable: true
        deleted_by:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - phone_number
        - status
    ErrorResponse:
      type: object
      description: Error body on endpoints without response filtering.
      properties:
        statusCode:
          type: integer
          example: 404
        error:
          type: boolean
          enum:
            - true
        success:
          type: boolean
          enum:
            - false
        data:
          oneOf:
            - type: object
              properties:
                code:
                  type: string
                  description: Machine-readable refusal code.
            - type: array
              items: {}
          description: >-
            For a coded refusal, an object with code and the details listed for
            that code. Otherwise an empty array.
        message:
          type: string
        errors:
          type: array
          items:
            type: string
          description: Validation messages for a 400. Empty for other errors.
        validation_errors:
          type: array
          description: >-
            Present when uploaded rows fail number validation (batch and
            workflow lead uploads): one group per distinct error.
          items:
            type: object
            properties:
              error:
                type: string
              rows:
                type: array
                items:
                  type: integer
                description: Row numbers with this error.
              phone_numbers:
                type: array
                items:
                  type: string
        invalid_row_count:
          type: integer
          description: 'Present with validation_errors: how many rows failed.'
      required:
        - statusCode
        - error
        - success
        - data
        - message
        - errors
    CodedErrorResponse:
      type: object
      description: Error body for a coded refusal; data carries code and its details.
      properties:
        statusCode:
          type: integer
          example: 404
        error:
          type: boolean
          enum:
            - true
        success:
          type: boolean
          enum:
            - false
        data:
          oneOf:
            - type: object
              properties:
                code:
                  type: string
                  description: Machine-readable refusal code.
            - type: array
              items: {}
          description: >-
            For a coded refusal, an object with code and the details listed for
            that code. Otherwise an empty array.
        message:
          type: string
        errors:
          type: array
          items:
            type: string
          description: Validation messages for a 400. Empty for other errors.
        validation_errors:
          type: array
          description: >-
            Present when uploaded rows fail number validation (batch and
            workflow lead uploads): one group per distinct error.
          items:
            type: object
            properties:
              error:
                type: string
              rows:
                type: array
                items:
                  type: integer
                description: Row numbers with this error.
              phone_numbers:
                type: array
                items:
                  type: string
        invalid_row_count:
          type: integer
          description: 'Present with validation_errors: how many rows failed.'
      required:
        - statusCode
        - error
        - success
        - data
        - message
        - errors
  securitySchemes:
    bearer:
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.