---
title: "Create phone number"
method: POST
path: "/phone-numbers"
tags: ["Phone Numbers"]
---

# Create phone number

`POST /phone-numbers`

## Request

- Base URL: `https://app.freyavoice.ai/api/v2`
- URL: `https://app.freyavoice.ai/api/v2/phone-numbers`
- Auth: HTTP bearer

Registers a new phone number with optional agent/workflow configuration for inbound and outbound calls.

## Request body

- object
  - `number` string, required
  - `friendlyName` string
  - `workspaceId` string, uuid, required
  - `userId` string, uuid, required
  - `config` object
    - `capabilities` object
      - `voice` string
      - `sms` boolean
    - `voiceConfig` string
    - `messagingConfig` string
    - `emergencyCalls` boolean
    - `configType` 'agents' | 'workflows'
    - `inboundAgentId` string
    - `outboundAgentId` string
    - `inboundWorkflowId` string
    - `outboundWorkflowId` string
    - `originationUri` string
    - `sipInbound` object
      - `enabled` boolean, required
    - `sipOutbound` object
      - `enabled` boolean, required
      - `endpoint` string
      - `port` number
      - `username` string
      - `password` string
      - `transportProtocol` 'UDP' | 'TCP' | 'TLS'
      - `secureMedia` boolean
      - `headers` object[]
        - `key` string, required
        - `value` string, required

## Response `200`

Phone number created

- object
  - `success` true, required
  - `data` object, required
    - `message` string, required
    - `result` object, required
      - `phoneNumber` object, required
        - `id` string, required
        - `number` string, required
        - `friendlyName` string, nullable
        - `workspaceId` string, required
        - `userId` string, required
        - `config` object, nullable
          - `capabilities` object
            - `voice` string
            - `sms` boolean
          - `voiceConfig` string
          - `messagingConfig` string
          - `emergencyCalls` boolean
          - `configType` 'agents' | 'workflows'
          - `inboundAgentId` string
          - `outboundAgentId` string
          - `inboundWorkflowId` string
          - `outboundWorkflowId` string
          - `originationUri` string
          - `sipInbound` object
            - `enabled` boolean, required
          - `sipOutbound` object
            - `enabled` boolean, required
            - `endpoint` string
            - `port` number
            - `username` string
            - `password` string
            - `transportProtocol` 'UDP' | 'TCP' | 'TLS'
            - `secureMedia` boolean
            - `headers` object[]
              - …
        - `createdAt` string, required
        - `updatedAt` string, required
        - `inboundAgentName` string, nullable
        - `outboundAgentName` string, nullable
        - `inboundWorkflowName` string, nullable
        - `outboundWorkflowName` string, nullable

## Other responses

- `400`: Validation error
- `401`: Missing or invalid token
- `500`: Server error

---

[API](https://skmtc.dev/freyavoice/apis/freyavoice-api.md) - [All operations](https://skmtc.dev/freyavoice/apis/freyavoice-api/llms.txt) - [OpenAPI document](https://skmtc.dev/freyavoice/apis/freyavoice-api/revisions/153d120f0c73?raw)