---
title: "Import phone number"
method: POST
path: "/custom-numbers"
tags: ["phoneNumbers"]
---

# Import phone number

`POST /custom-numbers`

Imports a custom phone number into your workspace. This is useful for direct SIP dialing scenarios where your telephony provider does not offer elastic SIP trunking. Set `uac_enabled` to true when your carrier or PBX requires outbound SIP REGISTER traffic, and optionally set `uac_register_expires` (60 to 3600 seconds, default 300). For IP-authenticated providers such as `zoom`, `ringcx`, `five9`, and `8x8`, `termination_uri` is filled automatically. For `8x8`, omit `phone_number` to have Synthflow generate the 12-digit identifier required for SIP routing.

## Headers

- `Authorization` string, required

## Request body

- object
  - `workspace_id` string, required — The workspace ID to associate the phone number with.
  - `phone_number` string — The phone number to import. Required for most providers. For `provider_name=8x8`, omit this field to auto-generate the required 12-digit identifier (0-9 only). If supplied, it must contain only digits and be at least 12 digits long.
  - `friendly_name` string — A human-readable name for the phone number.
  - `provider_name` 'twilio' | 'telnyx' | 'vonage' | 'ring_central' | 'ringcx' | 'custom' | 'zoom' | 'five9' | '8x8' — Phone number provider. Use `8x8` for 8x8 Contact Center (SIP domain `sip.8x8.com`), `zoom` for Zoom, `ringcx` for RingCX, `five9` for Five9, or omit/`custom` for a generic SIP trunk.
  - `trunk_username` string — Optional SIP trunk username for authentication. Required when `uac_enabled` is true. Not used for `five9`, `ringcx`, or `zoom`.
  - `trunk_pwd` string — Optional SIP trunk password for authentication. Required when `uac_enabled` is true. Not used for `five9`, `ringcx`, or `zoom`.
  - `termination_uri` string — SIP domain or termination URI used for outbound calls (maps to `sip_term_uri`). Not required for `zoom`, `ringcx`, `five9`, or `8x8`, which set the SIP domain automatically.
  - `sip_outbound_proxy` string — Optional outbound proxy used for outbound calls and SIP REGISTER requests. For `five9`, Synthflow sets the regional TLS proxy automatically when omitted.
  - `sip_auth_username` string — Optional auth username used for SIP REGISTER requests when it differs from `trunk_username`.
  - `uac_enabled` boolean — When true, Synthflow sends outbound SIP REGISTER traffic to your carrier or PBX so it can authenticate outbound calls. Requires `trunk_username` and `trunk_pwd`. Defaults to false.
  - `uac_register_expires` integer — SIP registration refresh interval in seconds. Only used when `uac_enabled` is true (or for providers that register implicitly, such as RingCentral). Whole numbers only, between 60 and 3600. Defaults to 300.

## Response `200`

200

- PhoneNumbersCreateCustomNumberResponse200
  - `status` string — Whether the request was successful.
  - `response` CustomNumbersPostResponsesContentApplicationJsonSchemaResponse
    - `key` string, uuid — Unique identifier for the custom phone number.
    - `phone_number` string — The imported phone number.

## Other responses

- `400` — Invalid request. Returned when `termination_uri` is missing for a provider that requires it, or when UAC registration fields are invalid.
- `403` — The selected provider import is not enabled for this workspace.

---

[API](https://skmtc.dev/synthflow/apis/platform-api.md) · [All operations](https://skmtc.dev/synthflow/apis/platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/synthflow/platform-api/revisions/6976456ad422/schema)