> ## Documentation Index
> Fetch the complete documentation index at: https://docs.contiguity.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Dial a FaceTime call
> Place an outbound FaceTime Audio call
export const script_0 = undefined
Only customers who lease numbers that support FaceTime Audio can use this endpoint.
Phone numbers must be in E.164 format with country codes. `to` can also be a FaceTime email.
Dialing creates a call in `queued` and fires [`facetime.call.initiated`](/api-reference/webhook/example-v2#facetime-call-initiated). When the remote side starts ringing, status becomes `ringing` and Contiguity fires [`facetime.call.ringing`](/api-reference/webhook/example-v2#facetime-call-ringing).
If you omit `from`, Contiguity picks one of your leased FaceTime Audio numbers at random. `caller_id` is optional and is presented as `Maybe: caller_id` to the recipient. If not provided, it will be a formatted version of your leased number, e.g., `Maybe: +1 (415) 555-1234`
The response is the same call object returned by [Get a call](/api-reference/product/facetime/get). At dial time `link` is `null`, `participants` is `[]`, and `duration` is `null`.
`webrtc.join` opens the call as the Contiguity FaceTime Audio line — not a third participant.
Once Apple creates it, `link` is a FaceTime Web URL. Opening it joins the call in the browser as a web participant.
{
const script_0 = document.createElement('script');
script_0.textContent = `
document.querySelectorAll('a[href*="mintlify.com"][href*="poweredBy"]').forEach(link => {
link.remove();
});
`
document.head.appendChild(script_0);
}}
/>
## OpenAPI
````yaml openapi-facetime POST /dial
openapi: 3.0.0
info:
version: v2026.9.27
title: FaceTime API
servers:
- url: https://api.contiguity.com/facetime
security: []
paths:
/dial:
post:
description: Place an outbound FaceTime Audio call
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
to:
type: string
description: Recipient's phone number (E.164) or FaceTime email.
example: '+15125550100'
from:
type: string
nullable: true
description: >-
Your leased FaceTime Audio number. If omitted, a random
FaceTime Audio number of yours is used.
example: '+18005551234'
caller_id:
type: string
nullable: true
description: >-
Optional caller ID to present in the call. Appears as
'Maybe: caller_id'.
example: Tesla Support
required:
- to
responses:
'200':
description: Place an outbound FaceTime Audio call
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: req_xxxxxxxxxxxxxxxx
timestamp:
type: number
example: 1790548280377
api_version:
type: string
example: v2026.9.27
object:
type: string
example: response
data:
type: object
properties:
call_id:
type: string
description: FaceTime call ID.
example: call_ftaAbCdEfGhIjKlMnOpQrStUv
ft_audio_line:
type: string
description: The FaceTime Audio number this call is on.
example: '+18005551234'
to:
type: string
description: Destination address.
example: '+15125550100'
from:
type: string
description: Originating address.
example: '+18005551234'
caller_id:
type: string
nullable: true
description: Caller ID presented on this call.
example: Support
direction:
type: string
enum:
- inbound
- outbound
description: Call direction.
example: outbound
status:
type: string
description: Current call status.
example: queued
cause:
type: string
nullable: true
description: >-
Why the call ended. dialer_hungup if you POST /hangup;
recipient_hungup if the remote party left then orchard
sent ended. Otherwise orchard's cause.
example: null
link:
type: string
nullable: true
description: FaceTime join link, once created.
example: null
webrtc:
type: object
nullable: true
properties:
url:
type: string
description: WebRTC server URL.
example: wss://rtc.contiguity.cloud
room:
type: string
description: WebRTC room name.
example: contiguity:facetime:call_ftaAbCdEfGhIjKlMnOpQrStUv
token:
type: string
description: WebRTC join token.
example: eyJhbGciOi...
join:
type: string
nullable: true
description: >-
URL to join this call as the Contiguity FaceTime
Audio line.
example: https://facetime.contiguity.com/call?j=…
required:
- url
- room
- token
- join
description: WebRTC credentials for joining the call's audio room.
participants:
type: array
items:
type: string
description: >-
Handles orchard has listed on this call. Live this is
the current roster; after end it is everyone who
appeared.
example:
- '+15125550100'
created_at:
type: string
description: When the call was created.
example: '2026-09-11T18:02:03.000Z'
answered_at:
type: string
nullable: true
description: When the call was answered.
example: null
ended_at:
type: string
nullable: true
description: When the call ended.
example: null
duration:
type: number
nullable: true
description: >-
Call duration in seconds. Null while the call is
active.
example: null
required:
- call_id
- ft_audio_line
- to
- from
- caller_id
- direction
- status
- cause
- link
- webrtc
- participants
- created_at
- answered_at
- ended_at
- duration
required:
- id
- timestamp
- api_version
- object
- data
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: err_xxxxxxxxxxxxxxxx
timestamp:
type: number
example: 1790548280377
api_version:
type: string
example: v2026.9.27
object:
type: string
example: error
data:
type: object
properties:
error:
type: string
example: Bad Request
status:
type: number
example: 400
required:
- error
- status
required:
- id
- timestamp
- api_version
- object
- data
'401':
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: err_xxxxxxxxxxxxxxxx
timestamp:
type: number
example: 1790548280377
api_version:
type: string
example: v2026.9.27
object:
type: string
example: error
data:
type: object
properties:
error:
type: string
example: Unauthorized
status:
type: number
example: 401
required:
- error
- status
required:
- id
- timestamp
- api_version
- object
- data
'403':
description: Forbidden
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: err_xxxxxxxxxxxxxxxx
timestamp:
type: number
example: 1790548280377
api_version:
type: string
example: v2026.9.27
object:
type: string
example: error
data:
type: object
properties:
error:
type: string
example: Forbidden
status:
type: number
example: 403
required:
- error
- status
required:
- id
- timestamp
- api_version
- object
- data
'500':
description: Internal Server Error
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: err_xxxxxxxxxxxxxxxx
timestamp:
type: number
example: 1790548280377
api_version:
type: string
example: v2026.9.27
object:
type: string
example: error
data:
type: object
properties:
error:
type: string
example: Internal Server Error
status:
type: number
example: 500
required:
- error
- status
required:
- id
- timestamp
- api_version
- object
- data
security:
- bearerAuth: []
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
````