---
title: "Create or edit a WhatsApp form"
method: POST
path: "/api/v1/tools/create_whatsapp_form"
---

# Create or edit a WhatsApp form

`POST /api/v1/tools/create_whatsapp_form`

## Request

- Base URL: `https://whatsync.app`
- URL: `https://whatsync.app/api/v1/tools/create_whatsapp_form`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Save a WhatsApp form (a Meta Flow: screens of fields that open inside the chat) as a DRAFT on the connected Business account. Nothing is sent. Pass form_id to replace the definition of an existing draft. Write definition as Flow JSON: {"version":"7.2","screens":[{"id":"DETAILS","title":"...","data":{},"layout":{"type":"SingleColumnLayout","children":[...]}}]}. Screen IDs use letters and underscores; SUCCESS is reserved. Components: TextHeading, TextSubheading, TextBody, TextCaption, TextInput (input-type text, number, email, password, passcode, phone), TextArea, Dropdown, RadioButtonsGroup, CheckboxGroup, ChipsSelector (data-source: [{id,title}]), DatePicker, CalendarPicker, OptIn, EmbeddedLink, Image, PhotoPicker, DocumentPicker, If, Switch. Inputs need a unique name and label. Every screen ends with a Footer whose on-click-action is navigate ({"name":"navigate","next":{"type":"screen","name":"NEXT_ID"},"payload":{}}) or, on the last screen ("terminal": true, "success": true), complete with a payload that collects the answers: "${form.field}" for this screen, "${screen.OTHER_ID.form.field}" for earlier screens. Only the complete payload is returned as answers. Meta returns validation_errors; fix them and save again with form_id. Then share preview_url. Reference: https://developers.facebook.com/docs/whatsapp/flows/reference/flowjson

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `idempotencyKey` string, required: Unique key for this intended action. Reuse exactly on retries; use a new key only for a new action.
  - `form_id` string: An existing DRAFT form to replace; omit to create a new form
  - `name` string, required: Internal form name, unique on the account
  - `categories` string[], required
  - `definition` union, required: Flow JSON object (or the same as a JSON string)
    - object
    - string

## Response `200`

JSON result. Every response includes X-Request-Id.

- object

## Other responses

- `400`: API error
- `401`: API error
- `403`: API error
- `404`: API error
- `409`: API error
- `413`: API error
- `415`: API error
- `422`: API error
- `429`: API error
- `503`: API error

---

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