Skip to main content
PUT
Save call flow draft
Required scope: PHONE_NUMBERS_WRITE

Behavior

Creates or updates the working draft of a phone number’s call flow. The draft is validated leniently and does not affect live routing until you publish it. The {number} path parameter is the Allo phone number in E.164 format. Send the full definition document and the schema_version it conforms to.

Going live

Saving a draft never changes live routing. There are two ways to put it on the air:
  • Publish it yourself with Publish call flow, passing the lock_version from this response. This changes live inbound routing immediately.
  • Hand it to a person using the confirmation_url in this response: a link where a signed-in user opens this draft, reviews it, and publishes it. Prefer this when a human should approve the change.
Treat confirmation_url as opaque — pass it through verbatim; never build it from a hardcoded app host or parse it. (It is present only while the response status is DRAFT.)

Concurrency

  • lock_version — pass the value from the draft you read. Omit it (or send null) to upsert the draft without a concurrency check. A stale value returns 409 CALL_FLOW_STALE_LOCK.
  • base_published_version — the published version your edit is based on. If someone published a new version while you were editing, this returns 409 CALL_FLOW_CONCURRENT_EDIT.

Errors

  • 400 CALL_FLOW_SCHEMA_VERSION_MISMATCHschema_version does not match the server’s current version.
  • 400 CALL_FLOW_INVALID — the definition is malformed or failed validation.
  • 404 PHONE_NUMBER_NOT_FOUND — the number is not one of your account’s numbers.
  • 409 CALL_FLOW_STALE_LOCK / 409 CALL_FLOW_CONCURRENT_EDIT — see Concurrency above.

Authorizations

Authorization
string
header
required

Path Parameters

number
string
required

Allo phone number in E.164 format

Example:

"+14155551234"

Body

application/json
definition
object
required

The call flow tree document (opaque; camelCase keys).

schema_version
integer
required

Must match the server's current call flow schema version.

Example:

1

lock_version
integer | null

The lock_version of the draft you are updating; omit or null to upsert without a concurrency check.

base_published_version
integer | null

The published version your edit is based on; a mismatch means someone published mid-edit (409).

engine_subset
enum<string> | null

Force the engine subset; inferred from the definition when omitted.

Available options:
NESTED_IVR,
FULL_FLOW

Response

The saved draft

data
object

A version of a phone number's call flow.