---
title: "Create Phone Number"
method: POST
path: "/developer/phone-numbers"
tags: ["Developer", "Developer - Phone Numbers"]
---

# Create Phone Number

`POST /developer/phone-numbers`

## Request

- Base URL: `https://api.openintake.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.openintake.ai/developer/phone-numbers`
- Auth: none declared

Create a new phone number entry for the current customer.

This endpoint is restricted to developer users only.
Creates a phone number or SIP endpoint entry that can be used for inbound call routing.

- **phone_number**: The phone number (e.g., +15551234567) or SIP endpoint (e.g., 1000)
- **label**: Optional friendly label like "Main Line" or "After Hours"
- **is_active**: Whether the number is active (default: true)

## Request body

- PhoneNumberCreate: Schema for creating a phone number.
  - `phone_number` string, required: Phone number or SIP endpoint (e.g., +15551234567 or 1000)
  - `label` string, nullable: Friendly label like 'Main Line' or 'After Hours'
  - `is_active` boolean, required: Whether the number is active
  - `is_test` boolean, required: Whether this is a test number (calls won't make real changes)
  - `provider` 'twilio' | 'daily' | 'vapi', required: Telephony provider (twilio, daily, or vapi)
  - `agent_platform` 'pipecat' | 'vapi': Voice agent platform: 'pipecat' or 'vapi'
  - `inbound_squad_id` string, nullable: Vapi squad ID for inbound assistant-request routing
  - `outbound_squad_id` string, nullable: Vapi squad ID for outbound calls
  - `outbound_squad_id_es` string, nullable: Vapi squad ID for outbound calls to Spanish-language leads (falls back to outbound_squad_id)
  - `business_hours_inbound_squad_id` string, nullable: Vapi squad ID for inbound calls during business hours (used when business_hours_enabled feature flag is on)
  - `after_hours_inbound_squad_id` string, nullable: Vapi squad ID for inbound calls outside business hours (used when business_hours_enabled feature flag is on)
  - `outbound_enabled` boolean: Whether this number is available for automated outbound dialing
  - `provider_bypass_enabled` boolean: Route inbound Twilio calls through our own /telephony/inbound-vapi endpoint instead of Vapi's inbound webhook. Required for attended transfer, which needs Twilio call control to stay on our side
  - `is_bounce_back` boolean: Dedicated bounce-back return line: unanswered transferred calls forwarded back here are matched to their original call and the conversation is injected into the inbound squad
  - `is_staff_transfer` boolean: Dedicated staff-to-AI transfer line: the PBX AI extension forwards here; the caller is matched to the AI call they were transferred out of, which stays canonical and absorbs this leg
  - `bounce_back_intake_squad_id` string, nullable: Vapi squad ID for bounce-backs whose original call was transferred to intake (Intake Dept / On Call); falls back to inbound_squad_id
  - `vapi_phone_number_id` string, nullable: VAPI phone number resource ID (for outbound API calls)
  - `default_greeting_override` string, nullable: Per-number default greeting; overrides the customer-wide default/business-hours greeting selection for calls to this number
  - `contact_greeting_override` string, nullable: Per-number known-contact greeting template ({first_name}/{last_name}); overrides the customer-wide contact greeting for calls to this number

## Response `201`

Successful Response

- PhoneNumberResponse: Schema for phone number response.
  - `phone_number` string, required: Phone number or SIP endpoint (e.g., +15551234567 or 1000)
  - `label` string, nullable: Friendly label like 'Main Line' or 'After Hours'
  - `is_active` boolean, required: Whether the number is active
  - `is_test` boolean, required: Whether this is a test number (calls won't make real changes)
  - `provider` 'twilio' | 'daily' | 'vapi', required: Telephony provider (twilio, daily, or vapi)
  - `agent_platform` 'pipecat' | 'vapi': Voice agent platform: 'pipecat' or 'vapi'
  - `inbound_squad_id` string, nullable: Vapi squad ID for inbound assistant-request routing
  - `outbound_squad_id` string, nullable: Vapi squad ID for outbound calls
  - `outbound_squad_id_es` string, nullable: Vapi squad ID for outbound calls to Spanish-language leads (falls back to outbound_squad_id)
  - `business_hours_inbound_squad_id` string, nullable: Vapi squad ID for inbound calls during business hours (used when business_hours_enabled feature flag is on)
  - `after_hours_inbound_squad_id` string, nullable: Vapi squad ID for inbound calls outside business hours (used when business_hours_enabled feature flag is on)
  - `outbound_enabled` boolean: Whether this number is available for automated outbound dialing
  - `provider_bypass_enabled` boolean: Route inbound Twilio calls through our own /telephony/inbound-vapi endpoint instead of Vapi's inbound webhook. Required for attended transfer, which needs Twilio call control to stay on our side
  - `is_bounce_back` boolean: Dedicated bounce-back return line: unanswered transferred calls forwarded back here are matched to their original call and the conversation is injected into the inbound squad
  - `is_staff_transfer` boolean: Dedicated staff-to-AI transfer line: the PBX AI extension forwards here; the caller is matched to the AI call they were transferred out of, which stays canonical and absorbs this leg
  - `bounce_back_intake_squad_id` string, nullable: Vapi squad ID for bounce-backs whose original call was transferred to intake (Intake Dept / On Call); falls back to inbound_squad_id
  - `vapi_phone_number_id` string, nullable: VAPI phone number resource ID (for outbound API calls)
  - `default_greeting_override` string, nullable: Per-number default greeting; overrides the customer-wide default/business-hours greeting selection for calls to this number
  - `contact_greeting_override` string, nullable: Per-number known-contact greeting template ({first_name}/{last_name}); overrides the customer-wide contact greeting for calls to this number
  - `phone_number_id` string, uuid, required: Phone number ID
  - `customer_id` string, uuid, required: Customer ID
  - `created_at` string, required: Creation timestamp
  - `type` 'PSTN' | 'SIP', required: Derived phone number type based on format.

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-14** `5d668a9fc9dd`: 2 info
  - added the new optional request property `is_staff_transfer`
  - added the optional property `is_staff_transfer` to the response with the `201` status
- **2026-10-05** `40f22baa60d7`: 2 info
  - added the new optional request property `bounce_back_intake_squad_id`
  - added the optional property `bounce_back_intake_squad_id` to the response with the `201` status
- **2026-10-04** `9b68080e1bb5`: 2 info
  - added the new optional request property `outbound_squad_id_es`
  - added the optional property `outbound_squad_id_es` to the response with the `201` status
- **2026-10-01** `a98bb982d178`: 2 warning, 2 info
  - removed the request property `call_transport`
  - removed the optional property `call_transport` from the response with the `201` status
  - the `agent_platform` request property default value changed from `pipecat` to `vapi`
  - the `agent_platform` response's property default value changed from `pipecat` to `vapi` for the status `201`

[Operation history](https://skmtc.dev/openintake/apis/openintake-api/changes/developer/phone-numbers/post.md)

---

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