> ## Documentation Index > Fetch the complete documentation index at: https://help.withallo.com/llms.txt > Use this file to discover all available pages before exploring further. # Save call flow draft > Creates or updates the working draft of a phone number's call flow. The draft is validated leniently and is not live until published. Optimistic concurrency: pass the `lock_version` returned by a previous read to detect a concurrent edit, and `base_published_version` to detect a publish that happened mid-edit. **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](/en/v2/api-reference/phone-numbers/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_MISMATCH` — `schema_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. ## OpenAPI ````yaml PUT /v2/api/numbers/{number}/call_flow/draft openapi: 3.0.3 info: title: Allo API description: >- Allo API provides programmatic access to your Allo account, allowing you to manage webhooks, retrieve calls and contacts, and send SMS messages. All requests to `/v1/api/**` endpoints automatically go through quota checking and scope validation. version: 1.0.0 contact: name: Allo Support servers: - url: https://api.withallo.com description: Production server security: [] tags: - name: Summary Templates description: >- Manage call summary templates that control how AI-generated call summaries are structured for your team. - name: Webhooks description: >- Manage webhook endpoints to receive real-time notifications about events in your Allo account. Each endpoint subscribes to one or more event topics and is verified with a signing secret. - name: Calls description: >- Retrieve and search call records with filtering and pagination. Filter calls by your Allo phone number. - name: Contacts description: >- Search and retrieve contact information with sorting and pagination. Includes engagement level tracking. - name: SMS description: Send SMS messages to phone numbers using your Allo numbers. - name: Phone Numbers description: Retrieve information about your Allo phone numbers. - name: Analytics description: Pre-computed call metrics, team performance, and outbound dial funnel - name: CRM description: Manage people, companies, and deals in your CRM. - name: Notes description: >- Internal team notes on conversations and CRM people, with @mention support. Notes are never visible to the contact. - name: Threads description: >- Team discussion threads attached to a conversation item (call, SMS, or conversation note). One thread per item. paths: /v2/api/numbers/{number}/call_flow/draft: put: tags: - Phone Numbers summary: Save call flow draft description: >- Creates or updates the working draft of a phone number's call flow. The draft is validated leniently and is not live until published. Optimistic concurrency: pass the `lock_version` returned by a previous read to detect a concurrent edit, and `base_published_version` to detect a publish that happened mid-edit. operationId: saveCallFlowDraft parameters: - name: number in: path required: true description: Allo phone number in E.164 format schema: type: string example: '+14155551234' requestBody: required: true content: application/json: schema: type: object required: - definition - schema_version properties: definition: type: object description: The call flow tree document (opaque; camelCase keys). additionalProperties: true schema_version: type: integer description: Must match the server's current call flow schema version. example: 1 lock_version: type: integer nullable: true description: >- The `lock_version` of the draft you are updating; omit or null to upsert without a concurrency check. base_published_version: type: integer nullable: true description: >- The published version your edit is based on; a mismatch means someone published mid-edit (409). engine_subset: type: string nullable: true enum: - NESTED_IVR - FULL_FLOW description: >- Force the engine subset; inferred from the definition when omitted. responses: '200': description: The saved draft content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/CallFlow' '400': $ref: '#/components/responses/ApiValidationError' '401': $ref: '#/components/responses/ApiUnauthorized' '404': $ref: '#/components/responses/ApiNotFound' '409': $ref: '#/components/responses/ApiConflict' '429': $ref: '#/components/responses/ApiRateLimited' security: - ApiKeyAuth: [] components: schemas: CallFlow: type: object description: A version of a phone number's call flow. properties: id: type: string nullable: true description: >- The call flow version ID. Null for a synthesized (never-persisted) flow. example: cflv-abc123 flow_id: type: string nullable: true description: The parent call flow ID. Null for a synthesized flow. example: cflw-abc123 version: type: integer description: Monotonic version number within the flow. example: 3 status: type: string enum: - DRAFT - PUBLISHED - SYNTHESIZED description: >- DRAFT (working copy), PUBLISHED (live), or SYNTHESIZED (in-memory representation of a legacy IVR-only line). example: PUBLISHED lock_version: type: integer description: Optimistic-concurrency token; pass it back on the next draft save. example: 0 schema_version: type: integer description: The call flow schema version this definition conforms to. example: 1 engine_subset: type: string enum: - NESTED_IVR - FULL_FLOW example: FULL_FLOW number: type: string nullable: true description: >- E.164 of the line this flow routes. Null for a never-persisted SYNTHESIZED flow. example: '+14155551234' confirmation_url: type: string nullable: true description: >- A link where a signed-in user reviews this draft and publishes it. Present only on a `DRAFT` (a `PUBLISHED` or `SYNTHESIZED` version has nothing to confirm). Because the public API cannot publish, this is how a draft you compose reaches a human to go live. Treat it as opaque — pass it through verbatim; never construct or parse it. example: https://app.withallo.com/call-flow-draft/cflv-abc123 entry_node_id: type: string description: The id of the entry node in `definition.nodes`. example: node-22 definition: type: object description: The call flow tree document (opaque; camelCase keys). additionalProperties: true ApiError: type: object properties: error: type: object properties: type: type: string code: type: string message: type: string retryable: type: boolean request_id: type: string retry_after_seconds: type: integer nullable: true responses: ApiValidationError: description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/ApiError' ApiUnauthorized: description: Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/ApiError' ApiNotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ApiError' ApiConflict: description: Conflict with existing resource content: application/json: schema: $ref: '#/components/schemas/ApiError' ApiRateLimited: description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ApiError' securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization ````