Console

Start

Agents

Alerts and status pages

App store purchases

Auth

Builds

Credits

Database

Flags

Generated Assets

Hosting

Jobs and cron

Knowledge

Localization

Monitoring

Network

Notifications

Organizations

Queues

Realtime

Runners

Sandboxes

Storage

Webhooks

Workflows

Getting Started

Installation

Authentication

AI Services

KV Store

Overview

Webhooks

Deploy & Infrastructure

Reference

On this page

Request
Response
ResourceMeta
PhoneNumberSpec
PhoneNumberStatus
PhoneVoicemailRoute
Condition
Errors
Examples

Reference

Connect a phone number

ConnectPhoneNumber: existing provider-managed lines; execution credentials are transient.

Checked 2026-09-28

ConnectPhoneNumber: existing provider-managed lines; execution credentials are transient.

Path POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/phone_numbers:connect
Scope notify:write
Effect write — a successful call changes state.
Collection phone_numbers
Validate-only validate_only=true runs every check and writes nothing

#Request

Field	Type	What it is
`parent`	`string`	Tenant environment. Required.
`phone_number_id`	`string`	Stable caller-chosen id; retries reuse this id. Required.
`phone_number`	`string`	Existing E.164 number. Required.
`provider_session_token`	`string`	Existing provider session, held only for this synchronous request. Never stored, logged, included in command hashes, or refreshed. Issuer lifetime is provider-owned; transient custody does not assert a shorter lifetime. Required. Never returned again.
`validate_only`	`bool`	Validate ownership/config without creating a binding.

#Response

Field	Type	What it is
`name`	`string`	The resource name.
`uid`	`string`	Immutable pnum_ identifier. Output only.
`meta`	`ResourceMeta`	Resource metadata.
`spec`	`PhoneNumberSpec`	The connected line and desired voicemail route. Required.
`status`	`PhoneNumberStatus`	Authoritative observations, with route application separate from incoming verification. Output only.

#ResourceMeta

Field	Type	What it is
`generation`	`int64`	Increases by one on every change to `spec`. Output only.
`etag`	`string`	Strong ETag (AIP-154): changes on any change to spec, status, or metadata. Send it back as `If-Match` or `etag` to make Update and Delete conditional; a mismatch fails with ABORTED / 409 `ETAG_MISMATCH`. Output only.
`create_time`	`timestamp`	When the Resource was created. Output only.
`update_time`	`timestamp`	When the Resource last changed. Output only.
`delete_time`	`timestamp`	Set while the Resource is being deleted. Output only.
`labels`	`map<string, string>`	Caller-writable, indexed labels (AIP-122 label rules).
`annotations`	`map<string, string>`	Caller-writable, unindexed annotations.
`display_name`	`string`	Caller-writable human-readable name.
`creator`	`string`	The principal that created the Resource. Output only.

#PhoneNumberSpec

Field	Type	What it is
`phone_number`	`string`	Existing E.164 number, verified against authenticated provider inventory. Required.
`provider`	`string`	Provider adapter; currently switchboard_free. Required.
`voicemail`	`PhoneVoicemailRoute`	Desired route, admitted only through applyRoute with a durable operation id.

#PhoneNumberStatus

Field	Type	What it is
`observed_generation`	`int64`	Generation represented by these observations. Output only.
`conditions`	`Condition[]`	Connected, RouteApplied and IncomingVerified are independent conditions. Output only.
`provider_principal`	`string`	Opaque hash of the provider-accepted session principal; never its login name. Output only.
`provider_line_id`	`string`	Immutable provider line identity. Output only.
`provider_number_id`	`string`	Immutable provider number identity. Output only.
`observed_voicemail`	`PhoneVoicemailRoute`	Last provider readback, independent of desired state. Output only.
`applied_generation`	`int64`	Generation confirmed by provider readback. Output only.
`incoming_verified_generation`	`int64`	Generation with a scoped incoming voicemail recording delivered to its intended mailbox. Output only.
`last_error`	`string`	Safe error classification; never a provider body or credential. Output only.
`observed_path_digest`	`string`	Safe hash of the full last-observed provider call-path configuration. Output only.
`applied_path_digest`	`string`	Incoming-proof baseline, cleared on observed external path changes. Output only.

#PhoneVoicemailRoute

Field	Type	What it is
`enabled`	`bool`	Whether voicemail is enabled. Required.
`delay_seconds`	`int32`	Provider wait before offering voicemail, in seconds; at most 600. Forced transfer is separate provider configuration and is preserved. Required.
`email_address`	`string`	Intended recording-delivery address. Required.

#Condition

Field	Type	What it is
`type`	`string`	The condition type, for example `Ready`.
`status`	`ConditionStatus`	Whether the condition holds. One of `true`, `false`, `unknown`.
`observed_generation`	`int64`	The generation this observation was made against.
`reason`	`string`	A machine-readable UpperCamelCase reason.
`message`	`string`	A customer-safe human-readable message.
`severity`	`Severity`	How severe a FALSE condition is. One of `info`, `warning`, `error`.
`transition_time`	`timestamp`	When `status` last changed.

#Errors

UNAUTHENTICATED — No valid key or token was presented.
PERMISSION_DENIED — The key lacks the method's permission.
INVALID_FIELD — A field failed validation.
RESOURCE_NOT_FOUND — The named Resource does not exist or is not visible.
RESOURCE_ALREADY_EXISTS — A Resource with this name exists.
INVALID_STATE — The Resource is in a state that forbids the call.
IDEMPOTENCY_KEY_REUSED — An Idempotency-Key was reused with another body.
IDEMPOTENCY_IN_PROGRESS — The first call with this Idempotency-Key is still running.
UNAVAILABLE — The Resource store, the owning service's backend, or the key verifier's snapshot is unavailable; retry after Retry-After.

Every error arrives in the body Errors describes.

#Examples

curl -X POST "https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/phone_numbers:connect" \
  -H "Authorization: Bearer $SYLPHX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone_number":"…","phone_number_id":"…","provider_session_token":"…"}'

Was this page helpful?

Tell us what is missing, wrong, or unclear — this opens a real inbox.

Send feedback

Platform links