# The Submit-Info guide for agents: every key, rule and example

HTML: https://www.app2email.com/docs/api/submit-info/get-submit-guide · Index: https://www.app2email.com/docs/api/llms.txt

`GET https://api.app2email.com/v1/{number}/submit/guide`

Scope: `submissions:manage`. Start here. One JSON document with everything needed to set Submit-Info up without reading anything else: every key of a form definition with its default and limit, the field types and how WhatsApp shows each, stage rules, rule operators, the automation triggers and actions with their keys and an example each, placeholders, formula functions, connection kinds, roles and abilities, limits, the presets, and three complete worked setups. `this_number` names the forms, lists and connections the number already has, so nothing is replaced by accident. Next: write a setup document and send it to POST /submit/setup with `dry_run` true.

|  |  |
| --- | --- |
| Scope | `submissions:manage` |
| Sandbox key | reads (https://www.app2email.com/docs/api/sandbox.md) |
| MCP tool | `get_submit_guide` on https://api.app2email.com/mcp |

## Parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `number` | path | string | yes | Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only.; eg `4976659348270` |

## Responses

| Status | Meaning | error.code |
| --- | --- | --- |
| 200 | The guide. The example is shortened. |  |
| 400 | The request is malformed (missing or invalid fields, query parameters or times). | `invalid_number_in_url`, `invalid_json`, `unsupported_message_type`, `invalid_to`, `too_many_recipients`, `missing_template_name`, `missing_template_language`, `invalid_components`, `to_and_recipients`, `invalid_recipients`, `duplicate_recipients`, `invalid_idempotency_key`, `missing_message_id`, `invalid_number`, `missing_numbers`, `too_many_numbers`, `invalid_numbers`, `missing_url`, `invalid_events`, `too_many_webhooks`, `invalid_template_name`, `invalid_template_language`, `invalid_template_category`, `invalid_template_components`, `invalid_reply_to`, `free_form_single_recipient`, `missing_text`, `invalid_text`, `invalid_send_at`, `send_at_in_past`, `send_at_too_far`, `invalid_time`, `invalid_limit`, `invalid_cursor`, `invalid_direction`, `invalid_status`, `invalid_phone`, `invalid_range`, `range_too_large`, `invalid_months`, `invalid_media_type`, `missing_file`, `missing_media`, `nothing_to_change`, `invalid_setting`, `segment_and_recipients`, `segment_empty`, `invalid_owner`, `invalid_contacts`, `invalid_segment`, `invalid_csv`, `too_many_segments`, `missing_interactive`, `invalid_interactive`, `invalid_test_event`, `invalid_keep_old_for_hours`, `invalid_contact_email`, `invalid_plan`, `invalid_key_request`, `invalid_estimate`, `invalid_analytics_query`, `invalid_conversion_events`, `invalid_booking`, `invalid_service`, `invalid_start`, `invalid_answers`, `invalid_addons`, `invalid_guests`, `invalid_series`, `invalid_block`, `invalid_note`, `invalid_link`, `invalid_slug`, `invalid_call_settings`, `invalid_call_request`, `invalid_wait`, `invalid_event_type`, `invalid_flow_id`, `invalid_flow_name`, `invalid_flow_categories`, `invalid_flow_json`, `invalid_flow_field`, `invalid_public_key`, `invalid_media_id`, `invalid_location`, `invalid_contacts_message`, `invalid_reaction`, `invalid_callback_data`, `caption_not_supported`, `invalid_marketing_api`, `invalid_users`, `invalid_bsuid`, `invalid_identity_key_hash`, `invalid_profile`, `invalid_display_name`, `invalid_oba_request`, `invalid_compliance_info`, `invalid_username`, `invalid_conversation_starters`, `invalid_qr_code`, `invalid_catalog_id`, `invalid_client_request`, `invalid_onboarding_request`, `invalid_redirect_url`, `invalid_partner_settings`, `invalid_payment`, `invalid_coupon`, `invalid_poll`, `shop_invalid`, `invalid_form`, `invalid_submission`, `invalid_automation`, `invalid_connection`, `invalid_member`, `invalid_list`, `invalid_setup`, `invalid_settings`, `template_language_required`, `invalid_template_field`, `invalid_optimization_spec`, `invalid_template_ids`, `too_many_templates`, `invalid_compare_days`, `invalid_auth_template`, `invalid_template_preview`, `invalid_library_filter`, `template_insights_confirm_required`, `invalid_insights_request`, `invalid_ticket_event`, `invalid_ticket_order`, `invalid_ticket_code`, `invalid_ticket_check_in`, `invalid_webhook_headers`, `invalid_webhook_format`, `invalid_webhook_secret`, `too_many_catchers` |
| 401 | Missing, invalid, revoked or expired API key. | `missing_api_key`, `invalid_authorization_header`, `invalid_api_key`, `api_key_old_format`, `api_key_revoked`, `api_key_expired` |
| 403 | The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. | `api_key_number_mismatch`, `insufficient_scope`, `ip_not_allowed`, `plan_not_allowed`, `service_not_live`, `recipient_opted_out`, `recipient_not_opted_in`, `template_name_reserved`, `whatsapp_payment_issue`, `whatsapp_account_locked`, `whatsapp_account_restricted`, `sandbox_key`, `recipient_stopped_marketing`, `messaging_limit_restricted`, `display_name_not_approved`, `username_not_eligible`, `account_not_confirmed`, `account_deactivated`, `booking_not_enabled`, `link_not_usable`, `call_permission_required`, `not_in_instant_sandbox`, `flow_blocked_by_integrity`, `whatsapp_permission_missing`, `partner_suspended`, `partner_closed`, `client_not_editable`, `shop_not_enabled`, `submit_not_enabled`, `tickets_not_enabled` |
| 404 | The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. | `number_not_found`, `template_not_found`, `template_language_not_found`, `message_not_found`, `broadcast_not_found`, `webhook_not_found`, `delivery_not_found`, `optin_not_found`, `request_not_found`, `conversation_not_found`, `contact_not_found`, `segment_not_found`, `approval_not_found`, `media_not_found`, `route_not_found`, `key_not_found`, `dataset_not_found`, `waitlist_not_found`, `booking_not_found`, `block_not_found`, `note_not_found`, `link_not_found`, `hold_not_found`, `flow_not_found`, `flow_json_not_found`, `qr_code_not_found`, `client_not_found`, `payment_not_found`, `package_not_found`, `poll_not_found`, `shop_not_found`, `form_not_found`, `submission_not_found`, `automation_not_found`, `connection_not_found`, `member_not_found`, `list_not_found`, `ticket_event_not_found`, `ticket_date_not_found`, `ticket_type_not_found`, `ticket_order_not_found`, `ticket_not_found`, `ticket_code_not_found`, `ticket_check_in_not_found`, `catcher_not_found` |
| 429 | A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. | `monthly_limit_reached`, `too_many_messages_to_recipient`, `whatsapp_rate_limit`, `rate_limited`, `daily_cap_reached`, `monthly_cap_reached`, `too_many_tests`, `register_limit_reached`, `too_many_signups`, `media_lookups_paused`, `too_many_invites` |
| 500 | Unexpected error on app2email's side. | `internal_error`, `background_start_failed`, `schedule_failed`, `shop_failed` |
| 503 | app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. | `whatsapp_connection_problem`, `whatsapp_number_not_registered`, `request_log_unavailable`, `whatsapp_unavailable`, `whatsapp_maintenance`, `block_list_busy`, `account_service_unavailable`, `sandbox_unavailable`, `partner_service_unavailable`, `shop_not_ready`, `submit_not_ready` |

### 200

```json
{
  "success": true,
  "request_id": "g1gde",
  "guide": {
    "product": "Submit-Info",
    "summary": "A form is a plain list of questions in steps. app2email turns it into a WhatsApp Flow and a web page with the same steps. Each filled-in form is a submission: answers, files, a reference and a public status page. A submission moves through the form's stages, can be assigned, noted, answered and exported. Automations (when - if - do) react to what happens: they reply, e-mail, change the stage, calculate, and call outside systems. Outside systems are reached through connections: a plain HTTP request, an operation of an OpenAPI document, or a tool of an MCP server.",
    "how_to": [
      "1. GET /guide (this document). Pick a preset from `presets` (GET /presets?key=<key> returns its complete setup document) or write your own.",
      "2. POST /setup with \"dry_run\": true: nothing is saved; `problems` lists every problem with its path and a fix.",
      "3. POST /setup without dry_run when `problems` is empty. Existing forms, lists and connections with the same key are replaced.",
      "4. POST /forms/{key}/publish uploads the generated Flow to WhatsApp and publishes it (or list the keys under \"publish\" in the setup document).",
      "5. Share links.wa_me or links.web of the form (GET /forms/{key}), or send it to a contact with POST /forms/{key}/send."
    ],
    "form": {
      "keys": {
        "title": "required. 1-60 characters. the form's public name",
        "stages": "2-12 stages; the first is where a new submission starts. left out = New, In progress, Done"
      },
      "key_rule": "keys of steps, fields, stages and calculated values: a lower-case letter, then up to 39 of a-z, 0-9 and _. fields and calculated values share one set of keys",
      "field_keys": {
        "key": "required. a lower-case letter, then up to 39 of a-z, 0-9 and _; unique in the form; not a reserved word",
        "required": "true = must be answered. default false"
      },
      "field_types": [
        {
          "type": "number",
          "value": "number",
          "keys": {
            "min": "a number or null",
            "max": "a number or null",
            "decimals": "0-6; 0 = whole numbers",
            "unit": "shown after the value, max 20 characters"
          },
          "whatsapp": "TextInput (number)",
          "notes": "A number. With decimals the phone shows a text keyboard and the server checks the number."
        }
      ],
      "internal_types": [
        "text",
        "textarea",
        "number",
        "email",
        "phone",
        "date",
        "select",
        "multiselect",
        "yesno",
        "rating"
      ],
      "reserved_keys": [
        "reference",
        "status",
        "status_name",
        "form",
        "form_key",
        "channel",
        "contact",
        "link",
        "id",
        "created",
        "updated",
        "assignee",
        "priority",
        "tags",
        "due",
        "files",
        "flow_token",
        "screen",
        "error_message",
        "error",
        "answers",
        "extra",
        "submission",
        "note",
        "button",
        "business",
        "desk_link",
        "status_kind",
        "verified",
        "files_count",
        "prefill",
        "confirm",
        "true",
        "false",
        "null",
        "and",
        "or",
        "not"
      ],
      "whatsapp": "the Flow is generated: one screen per step (a step with several photo / document fields is split, one picker per screen).",
      "stage": {
        "keys": {
          "key": "required. a lower-case letter, then up to 39 of a-z, 0-9 and _",
          "kind": "open | done | cancelled. at least one open and one done stage"
        },
        "example": {
          "key": "approved",
          "name": "Approved",
          "kind": "done",
          "color": "green",
          "set_by": [
            "manager"
          ],
          "require_note": true,
          "message": "Your application {reference} is approved. {note}"
        }
      },
      "rule": {
        "shape": "{ \"field\": \"<key>\", <operator>: <value> } with one or more operators (every one must hold), or { \"all\": [rules] }, or { \"any\": [rules] }.",
        "operators": [
          "equals",
          "not_equals",
          "in",
          "not_in",
          "contains",
          "empty",
          "not_empty",
          "gt",
          "gte",
          "lt",
          "lte"
        ],
        "groups": "all | any",
        "in_show_if": "`field` is a field of an EARLIER step that is asked or hidden",
        "in_automations": "`field` is any field key or extra key, or status, status_kind, channel, form, priority, tags, assignee, verified, files_count, contact.name, contact.phone",
        "example": {
          "all": [
            {
              "field": "category",
              "in": [
                "outage",
                "safety"
              ]
            },
            {
              "field": "amount",
              "gt": 5000
            }
          ]
        }
      }
    },
    "automation": {
      "keys": {
        "name": "required. within one form a name is unique: setup replaces the automation with the same name",
        "actions": "1-20 actions, run in order"
      },
      "triggers": [
        {
          "trigger": "status_changed",
          "when": "the stage changed",
          "options": {
            "to": [],
            "from": []
          }
        }
      ],
      "trigger_options": {
        "status_changed.to": "stage keys the submission moved to; [] = any",
        "overdue.minutes": "5 to 43200"
      },
      "actions": [
        {
          "type": "set_status",
          "does": "moves the submission to a stage",
          "keys": {
            "status": "a stage key",
            "note": "kept with the change; placeholders"
          },
          "example": {
            "type": "set_status",
            "status": "approved",
            "note": ""
          }
        }
      ],
      "placeholders": [
        {
          "name": "{reference}",
          "is": "the submission's reference, for example MR-7Q3M2A"
        }
      ],
      "placeholder_notes": "a name that is not known stays as typed. in JSON bodies and arguments a string that is exactly one placeholder keeps the value's type (a number stays a number). in addresses each inserted value is percent-encoded",
      "formula": {
        "language": "numbers, 'texts', field keys, + - * / %, comparisons == != > >= < <=, and / or / not, brackets and the functions below.",
        "functions": [
          {
            "name": "round",
            "usage": "round(x, decimals)",
            "does": "x rounded (half away from zero); decimals 0-10, default 0"
          }
        ],
        "examples": [
          "reading - previous('reading')",
          "round(quantity * lookup('prices', product, 'price'), 2)"
        ]
      },
      "json_path": "in `save`: $ = the whole answer, $.a.b[0].c = a value inside it, $text = the answer as text (MCP: the first text content)",
      "limits": "a failed outside call is tried again after 1 minute, 10 minutes and 1 hour, then the webhook event submit.automation_failed is sent."
    },
    "connection": {
      "keys": {
        "kind": "http | openapi | mcp",
        "base_url": "https only. for mcp: the server's address"
      },
      "kinds": [
        {
          "kind": "http",
          "use": "a plain HTTP API: the action names method, path, query, headers and a JSON body"
        }
      ],
      "auth_types": [
        {
          "type": "bearer",
          "use": "Authorization: Bearer <secret>"
        }
      ],
      "limits": {
        "timeout_seconds": 15,
        "answer_kb": 256,
        "request_kb": 256,
        "extra_headers": 5,
        "functions": 300,
        "params_per_function": 40,
        "calls_per_minute": 60,
        "calls_per_day": 2000,
        "addresses": "https only; private, loopback, link-local and metadata addresses are refused; redirects are not followed"
      },
      "example": {
        "key": "billing",
        "name": "Billing",
        "kind": "http",
        "base_url": "https://billing.example.com/api",
        "auth": {
          "type": "bearer",
          "secret": "<your token>"
        },
        "headers": {},
        "enabled": true
      }
    },
    "member": {
      "keys": {
        "email": "required: the invitation goes there",
        "role": "admin | manager | agent | viewer: a starting set of abilities"
      },
      "roles": {
        "owner": [
          "note",
          "reply",
          "edit",
          "stage",
          "assign",
          "files",
          "export",
          "delete",
          "run",
          "forms",
          "automations",
          "team"
        ],
        "admin": [
          "note",
          "reply",
          "edit",
          "stage",
          "assign",
          "files",
          "export",
          "delete",
          "run",
          "forms",
          "automations",
          "team"
        ],
        "manager": [
          "note",
          "reply",
          "edit",
          "stage",
          "assign",
          "files",
          "export",
          "delete",
          "run"
        ],
        "agent": [
          "note",
          "reply",
          "edit",
          "stage",
          "files",
          "run"
        ],
        "viewer": []
      },
      "abilities": [
        "note",
        "reply",
        "edit",
        "stage",
        "assign",
        "files",
        "export",
        "delete",
        "run",
        "forms",
        "automations",
        "team"
      ],
      "notes": "seeing submissions is implied. an agent may assign to themselves only"
    },
    "settings": {
      "enabled": "true switches Submit-Info on for the number",
      "config": {
        "default_prefix": "2-4 letters, default SI",
        "retention_days": "0 = keep; else 30-3650"
      }
    },
    "limits": {
      "forms": 100,
      "steps_per_form": 12,
      "fields_per_step": 12,
      "fields_per_form": 60,
      "definition_kb": 64,
      "stages_per_form": 12,
      "lists": 50,
      "items_per_list": 1000,
      "list_kb": 200,
      "list_items_shown_in_a_select": 200,
      "automations": 200,
      "actions_per_automation": 20,
      "connections": 30,
      "members": 200,
      "files_per_submission": 60,
      "file_mb_whatsapp": 25,
      "file_mb_web_and_api": 10,
      "answers_kb": 64,
      "note_or_reply_characters": 4000,
      "tags_per_submission": 20,
      "tag_characters": 40,
      "page": 50,
      "page_max": 200,
      "run_log_days": 30
    },
    "setup": {
      "shape": "{ dry_run, settings: { enabled, config }, lists: [...], connections: [...], forms: [{ key, name, definition }], automations: [...], publish: [form keys] }. every part is optional",
      "order": "lists and connections are applied first, then forms, then automations. with any problem nothing is written",
      "replaces": "forms, lists and connections by key; automations by name within the same form"
    },
    "presets": [
      {
        "key": "quote",
        "name": "Quote request",
        "description": "What is needed, quantity, photos and address. Staff enter the amount; the customer accepts or declines with a button.",
        "category": "Customers"
      },
      {
        "key": "meter_reading",
        "name": "Meter reading",
        "description": "Meter number, reading and a photo. The usage since the last reading is calculated; odd readings are queried.",
        "category": "Customers"
      },
      {
        "key": "job_completed",
        "name": "Job completed",
        "description": "Field staff log a finished job: the job from a list, work done, parts, hours, photos and the location.",
        "category": "Field staff"
      }
    ],
    "examples": [
      {
        "title": "A quote request the customer accepts or declines with a button",
        "setup": {
          "dry_run": true,
          "settings": {
            "enabled": true
          },
          "lists": [
            {
              "key": "products",
              "name": "Products",
              "items": [
                {
                  "id": "pump-s",
                  "title": "Pump, small",
                  "description": "Up to 40 l/min",
                  "price": 240
                },
                {
                  "id": "pump-l",
                  "title": "Pump, large",
                  "description": "Up to 120 l/min",
                  "price": 610
                }
              ]
            }
          ],
          "connections": [
            {
              "name": "ERP",
              "kind": "http",
              "base_url": "https://erp.example.com/api",
              "auth": {
                "type": "bearer",
                "secret": "YOUR_ERP_TOKEN"
              },
              "headers": {
                "X-Tenant": "acme"
              },
              "enabled": true,
              "key": "erp"
            }
          ],
          "forms": [
            {
              "key": "quote",
              "name": "Quote request",
              "definition": {
                "title": "Quote request",
                "description": "Tell us what you need and we will send a price.",
                "prefix": "QR",
                "steps": [
                  {
                    "key": "need",
                    "title": "What you need",
                    "text": "",
                    "show_if": null,
                    "fields": [
                      {
                        "key": "product",
                        "type": "select",
                        "label": "Product",
                        "required": true,
                        "list": "products"
                      },
                      {
                        "key": "quantity",
                        "type": "number",
                        "label": "How many?",
                        "required": true,
                        "min": 1,
                        "max": 10000,
                        "decimals": 0
                      },
                      {
                        "key": "notes",
                        "type": "textarea",
                        "label": "Anything we should know?",
                        "required": false,
                        "max_length": 1000
                      },
                      {
                        "key": "photos",
                        "type": "photo",
                        "label": "Photos of the site (optional)",
                        "required": false,
                        "max_files": 3,
                        "source": "any"
                      },
                      {
                        "key": "quote_amount",
                        "type": "number",
                        "label": "Quote amount",
                        "internal": true,
                        "decimals": 2,
                        "unit": "USD"
                      }
                    ]
                  },
                  {
                    "key": "delivery",
                    "title": "Delivery",
                    "text": "",
                    "show_if": null,
                    "fields": [
                      {
                        "key": "deliver",
                        "type": "yesno",
                        "label": "Do you need delivery?",
                        "required": true
                      }
                    ]
                  },
                  {
                    "key": "delivery_address",
                    "title": "Delivery address",
                    "text": "",
                    "show_if": {
                      "field": "deliver",
                      "equals": true
                    },
                    "fields": [
                      {
                        "key": "address",
                        "type": "textarea",
                        "label": "Where should we deliver?",
                        "required": true,
                        "max_length": 300
                      }
                    ]
                  }
                ],
                "stages": [
                  {
                    "key": "new",
                    "name": "New",
                    "kind": "open",
                    "color": "blue",
                    "set_by": [],
                    "require_note": false,
                    "message": ""
                  },
                  {
                    "key": "quoted",
                    "name": "Quoted",
                    "kind": "open",
                    "color": "amber",
                    "set_by": [],
                    "require_note": false,
                    "message": ""
                  },
                  {
                    "key": "accepted",
                    "name": "Accepted",
                    "kind": "done",
                    "color": "green",
                    "set_by": [],
                    "require_note": false,
                    "message": "Thank you. We will be in touch about {reference} shortly."
                  },
                  {
                    "key": "declined",
                    "name": "Declined",
                    "kind": "cancelled",
                    "color": "grey",
                    "set_by": [],
                    "require_note": false,
                    "message": ""
                  }
                ],
                "trigger": {
                  "words": [
                    "quote"
                  ],
                  "header": "",
                  "body": "Tap the button to ask for a quote.",
                  "button": "Get a quote",
                  "footer": ""
                },
                "after": {
                  "review_step": true,
                  "reply": "Thanks {contact.name}. Your request {reference} is with us; the price follows shortly.",
                  "allow_additions": true,
                  "status_page": true
                },
                "calculated": [
                  {
                    "key": "estimate",
                    "label": "Estimate",
                    "formula": "quantity * lookup('products', product, 'price')",
                    "unit": "USD",
                    "decimals": 2
                  }
                ]
              }
            }
          ],
          "automations": [
            {
              "name": "Price a quote request in the ERP",
              "form": "quote",
              "enabled": true,
              "trigger": "submitted",
              "options": {},
              "conditions": {
                "all": [
                  {
                    "field": "quantity",
                    "gt": 0
                  }
                ]
              },
              "actions": [
                {
                  "type": "http",
                  "connection": "erp",
                  "method": "POST",
                  "path": "/quotes",
                  "query": {},
                  "headers": {
                    "X-Source": "whatsapp"
                  },
                  "body": {
                    "reference": "{reference}",
                    "customer": {
                      "name": "{contact.name}",
                      "phone": "{contact.phone}"
                    },
                    "product": "{product}",
                    "quantity": "{quantity}",
                    "photos": "{files.photos}"
                  },
                  "save": {
                    "erp_id": "$.id",
                    "quote_amount": "$.total"
                  },
                  "on_fail": "retry"
                },
                {
                  "type": "set_status",
                  "status": "quoted",
                  "note": "Priced by the ERP"
                },
                {
                  "type": "reply",
                  "text": "Your quote {reference}: {quote_amount} USD for {quantity} x {product}. Shall we go ahead?",
                  "buttons": [
                    {
                      "id": "accept",
                      "title": "Accept",
                      "set_status": "accepted"
                    },
                    {
                      "id": "decline",
                      "title": "Decline",
                      "set_status": "declined"
                    }
                  ],
                  "file": "",
                  "link": true
                }
              ]
            },
            {
              "name": "Tell the owner when a quote is accepted",
              "form": "quote",
              "enabled": true,
              "trigger": "status_changed",
              "options": {
                "to": [
                  "accepted"
                ],
                "from": []
              },
              "conditions": null,
              "actions": [
                {
                  "type": "email",
                  "to": [
                    "owner"
                  ],
                  "subject": "Quote {reference} accepted: {quote_amount} USD",
                  "body": "{contact.name} ({contact.phone}) accepted.\n\n{answers}\n\n{desk_link}",
                  "attach_files": false
                }
              ]
            }
          ],
          "publish": [
            "quote"
          ]
        }
      }
    ],
    "this_number": {
      "enabled": true,
      "forms": [
        "meter_reading"
      ],
      "lists": [
        "products"
      ],
      "connections": [
        "erp"
      ]
    }
  }
}
```

## Errors

[`api_key_expired`](https://www.app2email.com/docs/api/errors#api_key_expired), [`api_key_number_mismatch`](https://www.app2email.com/docs/api/errors#api_key_number_mismatch), [`api_key_old_format`](https://www.app2email.com/docs/api/errors#api_key_old_format), [`api_key_revoked`](https://www.app2email.com/docs/api/errors#api_key_revoked), [`insufficient_scope`](https://www.app2email.com/docs/api/errors#insufficient_scope), [`internal_error`](https://www.app2email.com/docs/api/errors#internal_error), [`invalid_api_key`](https://www.app2email.com/docs/api/errors#invalid_api_key), [`invalid_authorization_header`](https://www.app2email.com/docs/api/errors#invalid_authorization_header), [`invalid_number_in_url`](https://www.app2email.com/docs/api/errors#invalid_number_in_url), [`ip_not_allowed`](https://www.app2email.com/docs/api/errors#ip_not_allowed), [`missing_api_key`](https://www.app2email.com/docs/api/errors#missing_api_key), [`number_not_found`](https://www.app2email.com/docs/api/errors#number_not_found), [`plan_not_allowed`](https://www.app2email.com/docs/api/errors#plan_not_allowed), [`rate_limited`](https://www.app2email.com/docs/api/errors#rate_limited), [`service_not_live`](https://www.app2email.com/docs/api/errors#service_not_live), [`submit_not_ready`](https://www.app2email.com/docs/api/errors#submit_not_ready)

## Example

```bash
curl "https://api.app2email.com/v1/YOUR_NUMBER/submit/guide" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## OpenAPI

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "app2email WhatsApp API",
    "version": "1.4.0"
  },
  "servers": [
    {
      "url": "https://api.app2email.com"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/v1/{number}/submit/guide": {
      "get": {
        "tags": [
          "Submit-Info"
        ],
        "operationId": "getSubmitGuide",
        "summary": "The Submit-Info guide for agents: every key, rule and example",
        "description": "Scope: `submissions:manage`. Start here. One JSON document with everything needed to set Submit-Info up without reading anything else: every key of a form definition with its default and limit, the field types and how WhatsApp shows each, stage rules, rule operators, the automation triggers and actions with their keys and an example each, placeholders, formula functions, connection kinds, roles and abilities, limits, the presets, and three complete worked setups. `this_number` names the forms, lists and connections the number already has, so nothing is replaced by accident. Next: write a setup document and send it to POST /submit/setup with `dry_run` true.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Number"
          }
        ],
        "responses": {
          "200": {
            "description": "The guide. The example is shortened.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubmitGuideResponse"
                },
                "example": {
                  "success": true,
                  "request_id": "g1gde",
                  "guide": {
                    "product": "Submit-Info",
                    "summary": "A form is a plain list of questions in steps. app2email turns it into a WhatsApp Flow and a web page with the same steps. Each filled-in form is a submission: answers, files, a reference and a public status page. A submission moves through the form's stages, can be assigned, noted, answered and exported. Automations (when - if - do) react to what happens: they reply, e-mail, change the stage, calculate, and call outside systems. Outside systems are reached through connections: a plain HTTP request, an operation of an OpenAPI document, or a tool of an MCP server.",
                    "how_to": [
                      "1. GET /guide (this document). Pick a preset from `presets` (GET /presets?key=<key> returns its complete setup document) or write your own.",
                      "2. POST /setup with \"dry_run\": true: nothing is saved; `problems` lists every problem with its path and a fix.",
                      "3. POST /setup without dry_run when `problems` is empty. Existing forms, lists and connections with the same key are replaced.",
                      "4. POST /forms/{key}/publish uploads the generated Flow to WhatsApp and publishes it (or list the keys under \"publish\" in the setup document).",
                      "5. Share links.wa_me or links.web of the form (GET /forms/{key}), or send it to a contact with POST /forms/{key}/send."
                    ],
                    "form": {
                      "keys": {
                        "title": "required. 1-60 characters. the form's public name",
                        "stages": "2-12 stages; the first is where a new submission starts. left out = New, In progress, Done"
                      },
                      "key_rule": "keys of steps, fields, stages and calculated values: a lower-case letter, then up to 39 of a-z, 0-9 and _. fields and calculated values share one set of keys",
                      "field_keys": {
                        "key": "required. a lower-case letter, then up to 39 of a-z, 0-9 and _; unique in the form; not a reserved word",
                        "required": "true = must be answered. default false"
                      },
                      "field_types": [
                        {
                          "type": "number",
                          "value": "number",
                          "keys": {
                            "min": "a number or null",
                            "max": "a number or null",
                            "decimals": "0-6; 0 = whole numbers",
                            "unit": "shown after the value, max 20 characters"
                          },
                          "whatsapp": "TextInput (number)",
                          "notes": "A number. With decimals the phone shows a text keyboard and the server checks the number."
                        }
                      ],
                      "internal_types": [
                        "text",
                        "textarea",
                        "number",
                        "email",
                        "phone",
                        "date",
                        "select",
                        "multiselect",
                        "yesno",
                        "rating"
                      ],
                      "reserved_keys": [
                        "reference",
                        "status",
                        "status_name",
                        "form",
                        "form_key",
                        "channel",
                        "contact",
                        "link",
                        "id",
                        "created",
                        "updated",
                        "assignee",
                        "priority",
                        "tags",
                        "due",
                        "files",
                        "flow_token",
                        "screen",
                        "error_message",
                        "error",
                        "answers",
                        "extra",
                        "submission",
                        "note",
                        "button",
                        "business",
                        "desk_link",
                        "status_kind",
                        "verified",
                        "files_count",
                        "prefill",
                        "confirm",
                        "true",
                        "false",
                        "null",
                        "and",
                        "or",
                        "not"
                      ],
                      "whatsapp": "the Flow is generated: one screen per step (a step with several photo / document fields is split, one picker per screen).",
                      "stage": {
                        "keys": {
                          "key": "required. a lower-case letter, then up to 39 of a-z, 0-9 and _",
                          "kind": "open | done | cancelled. at least one open and one done stage"
                        },
                        "example": {
                          "key": "approved",
                          "name": "Approved",
                          "kind": "done",
                          "color": "green",
                          "set_by": [
                            "manager"
                          ],
                          "require_note": true,
                          "message": "Your application {reference} is approved. {note}"
                        }
                      },
                      "rule": {
                        "shape": "{ \"field\": \"<key>\", <operator>: <value> } with one or more operators (every one must hold), or { \"all\": [rules] }, or { \"any\": [rules] }.",
                        "operators": [
                          "equals",
                          "not_equals",
                          "in",
                          "not_in",
                          "contains",
                          "empty",
                          "not_empty",
                          "gt",
                          "gte",
                          "lt",
                          "lte"
                        ],
                        "groups": "all | any",
                        "in_show_if": "`field` is a field of an EARLIER step that is asked or hidden",
                        "in_automations": "`field` is any field key or extra key, or status, status_kind, channel, form, priority, tags, assignee, verified, files_count, contact.name, contact.phone",
                        "example": {
                          "all": [
                            {
                              "field": "category",
                              "in": [
                                "outage",
                                "safety"
                              ]
                            },
                            {
                              "field": "amount",
                              "gt": 5000
                            }
                          ]
                        }
                      }
                    },
                    "automation": {
                      "keys": {
                        "name": "required. within one form a name is unique: setup replaces the automation with the same name",
                        "actions": "1-20 actions, run in order"
                      },
                      "triggers": [
                        {
                          "trigger": "status_changed",
                          "when": "the stage changed",
                          "options": {
                            "to": [],
                            "from": []
                          }
                        }
                      ],
                      "trigger_options": {
                        "status_changed.to": "stage keys the submission moved to; [] = any",
                        "overdue.minutes": "5 to 43200"
                      },
                      "actions": [
                        {
                          "type": "set_status",
                          "does": "moves the submission to a stage",
                          "keys": {
                            "status": "a stage key",
                            "note": "kept with the change; placeholders"
                          },
                          "example": {
                            "type": "set_status",
                            "status": "approved",
                            "note": ""
                          }
                        }
                      ],
                      "placeholders": [
                        {
                          "name": "{reference}",
                          "is": "the submission's reference, for example MR-7Q3M2A"
                        }
                      ],
                      "placeholder_notes": "a name that is not known stays as typed. in JSON bodies and arguments a string that is exactly one placeholder keeps the value's type (a number stays a number). in addresses each inserted value is percent-encoded",
                      "formula": {
                        "language": "numbers, 'texts', field keys, + - * / %, comparisons == != > >= < <=, and / or / not, brackets and the functions below.",
                        "functions": [
                          {
                            "name": "round",
                            "usage": "round(x, decimals)",
                            "does": "x rounded (half away from zero); decimals 0-10, default 0"
                          }
                        ],
                        "examples": [
                          "reading - previous('reading')",
                          "round(quantity * lookup('prices', product, 'price'), 2)"
                        ]
                      },
                      "json_path": "in `save`: $ = the whole answer, $.a.b[0].c = a value inside it, $text = the answer as text (MCP: the first text content)",
                      "limits": "a failed outside call is tried again after 1 minute, 10 minutes and 1 hour, then the webhook event submit.automation_failed is sent."
                    },
                    "connection": {
                      "keys": {
                        "kind": "http | openapi | mcp",
                        "base_url": "https only. for mcp: the server's address"
                      },
                      "kinds": [
                        {
                          "kind": "http",
                          "use": "a plain HTTP API: the action names method, path, query, headers and a JSON body"
                        }
                      ],
                      "auth_types": [
                        {
                          "type": "bearer",
                          "use": "Authorization: Bearer <secret>"
                        }
                      ],
                      "limits": {
                        "timeout_seconds": 15,
                        "answer_kb": 256,
                        "request_kb": 256,
                        "extra_headers": 5,
                        "functions": 300,
                        "params_per_function": 40,
                        "calls_per_minute": 60,
                        "calls_per_day": 2000,
                        "addresses": "https only; private, loopback, link-local and metadata addresses are refused; redirects are not followed"
                      },
                      "example": {
                        "key": "billing",
                        "name": "Billing",
                        "kind": "http",
                        "base_url": "https://billing.example.com/api",
                        "auth": {
                          "type": "bearer",
                          "secret": "<your token>"
                        },
                        "headers": {},
                        "enabled": true
                      }
                    },
                    "member": {
                      "keys": {
                        "email": "required: the invitation goes there",
                        "role": "admin | manager | agent | viewer: a starting set of abilities"
                      },
                      "roles": {
                        "owner": [
                          "note",
                          "reply",
                          "edit",
                          "stage",
                          "assign",
                          "files",
                          "export",
                          "delete",
                          "run",
                          "forms",
                          "automations",
                          "team"
                        ],
                        "admin": [
                          "note",
                          "reply",
                          "edit",
                          "stage",
                          "assign",
                          "files",
                          "export",
                          "delete",
                          "run",
                          "forms",
                          "automations",
                          "team"
                        ],
                        "manager": [
                          "note",
                          "reply",
                          "edit",
                          "stage",
                          "assign",
                          "files",
                          "export",
                          "delete",
                          "run"
                        ],
                        "agent": [
                          "note",
                          "reply",
                          "edit",
                          "stage",
                          "files",
                          "run"
                        ],
                        "viewer": []
                      },
                      "abilities": [
                        "note",
                        "reply",
                        "edit",
                        "stage",
                        "assign",
                        "files",
                        "export",
                        "delete",
                        "run",
                        "forms",
                        "automations",
                        "team"
                      ],
                      "notes": "seeing submissions is implied. an agent may assign to themselves only"
                    },
                    "settings": {
                      "enabled": "true switches Submit-Info on for the number",
                      "config": {
                        "default_prefix": "2-4 letters, default SI",
                        "retention_days": "0 = keep; else 30-3650"
                      }
                    },
                    "limits": {
                      "forms": 100,
                      "steps_per_form": 12,
                      "fields_per_step": 12,
                      "fields_per_form": 60,
                      "definition_kb": 64,
                      "stages_per_form": 12,
                      "lists": 50,
                      "items_per_list": 1000,
                      "list_kb": 200,
                      "list_items_shown_in_a_select": 200,
                      "automations": 200,
                      "actions_per_automation": 20,
                      "connections": 30,
                      "members": 200,
                      "files_per_submission": 60,
                      "file_mb_whatsapp": 25,
                      "file_mb_web_and_api": 10,
                      "answers_kb": 64,
                      "note_or_reply_characters": 4000,
                      "tags_per_submission": 20,
                      "tag_characters": 40,
                      "page": 50,
                      "page_max": 200,
                      "run_log_days": 30
                    },
                    "setup": {
                      "shape": "{ dry_run, settings: { enabled, config }, lists: [...], connections: [...], forms: [{ key, name, definition }], automations: [...], publish: [form keys] }. every part is optional",
                      "order": "lists and connections are applied first, then forms, then automations. with any problem nothing is written",
                      "replaces": "forms, lists and connections by key; automations by name within the same form"
                    },
                    "presets": [
                      {
                        "key": "quote",
                        "name": "Quote request",
                        "description": "What is needed, quantity, photos and address. Staff enter the amount; the customer accepts or declines with a button.",
                        "category": "Customers"
                      },
                      {
                        "key": "meter_reading",
                        "name": "Meter reading",
                        "description": "Meter number, reading and a photo. The usage since the last reading is calculated; odd readings are queried.",
                        "category": "Customers"
                      },
                      {
                        "key": "job_completed",
                        "name": "Job completed",
                        "description": "Field staff log a finished job: the job from a list, work done, parts, hours, photos and the location.",
                        "category": "Field staff"
                      }
                    ],
                    "examples": [
                      {
                        "title": "A quote request the customer accepts or declines with a button",
                        "setup": {
                          "dry_run": true,
                          "settings": {
                            "enabled": true
                          },
                          "lists": [
                            {
                              "key": "products",
                              "name": "Products",
                              "items": [
                                {
                                  "id": "pump-s",
                                  "title": "Pump, small",
                                  "description": "Up to 40 l/min",
                                  "price": 240
                                },
                                {
                                  "id": "pump-l",
                                  "title": "Pump, large",
                                  "description": "Up to 120 l/min",
                                  "price": 610
                                }
                              ]
                            }
                          ],
                          "connections": [
                            {
                              "name": "ERP",
                              "kind": "http",
                              "base_url": "https://erp.example.com/api",
                              "auth": {
                                "type": "bearer",
                                "secret": "YOUR_ERP_TOKEN"
                              },
                              "headers": {
                                "X-Tenant": "acme"
                              },
                              "enabled": true,
                              "key": "erp"
                            }
                          ],
                          "forms": [
                            {
                              "key": "quote",
                              "name": "Quote request",
                              "definition": {
                                "title": "Quote request",
                                "description": "Tell us what you need and we will send a price.",
                                "prefix": "QR",
                                "steps": [
                                  {
                                    "key": "need",
                                    "title": "What you need",
                                    "text": "",
                                    "show_if": null,
                                    "fields": [
                                      {
                                        "key": "product",
                                        "type": "select",
                                        "label": "Product",
                                        "required": true,
                                        "list": "products"
                                      },
                                      {
                                        "key": "quantity",
                                        "type": "number",
                                        "label": "How many?",
                                        "required": true,
                                        "min": 1,
                                        "max": 10000,
                                        "decimals": 0
                                      },
                                      {
                                        "key": "notes",
                                        "type": "textarea",
                                        "label": "Anything we should know?",
                                        "required": false,
                                        "max_length": 1000
                                      },
                                      {
                                        "key": "photos",
                                        "type": "photo",
                                        "label": "Photos of the site (optional)",
                                        "required": false,
                                        "max_files": 3,
                                        "source": "any"
                                      },
                                      {
                                        "key": "quote_amount",
                                        "type": "number",
                                        "label": "Quote amount",
                                        "internal": true,
                                        "decimals": 2,
                                        "unit": "USD"
                                      }
                                    ]
                                  },
                                  {
                                    "key": "delivery",
                                    "title": "Delivery",
                                    "text": "",
                                    "show_if": null,
                                    "fields": [
                                      {
                                        "key": "deliver",
                                        "type": "yesno",
                                        "label": "Do you need delivery?",
                                        "required": true
                                      }
                                    ]
                                  },
                                  {
                                    "key": "delivery_address",
                                    "title": "Delivery address",
                                    "text": "",
                                    "show_if": {
                                      "field": "deliver",
                                      "equals": true
                                    },
                                    "fields": [
                                      {
                                        "key": "address",
                                        "type": "textarea",
                                        "label": "Where should we deliver?",
                                        "required": true,
                                        "max_length": 300
                                      }
                                    ]
                                  }
                                ],
                                "stages": [
                                  {
                                    "key": "new",
                                    "name": "New",
                                    "kind": "open",
                                    "color": "blue",
                                    "set_by": [],
                                    "require_note": false,
                                    "message": ""
                                  },
                                  {
                                    "key": "quoted",
                                    "name": "Quoted",
                                    "kind": "open",
                                    "color": "amber",
                                    "set_by": [],
                                    "require_note": false,
                                    "message": ""
                                  },
                                  {
                                    "key": "accepted",
                                    "name": "Accepted",
                                    "kind": "done",
                                    "color": "green",
                                    "set_by": [],
                                    "require_note": false,
                                    "message": "Thank you. We will be in touch about {reference} shortly."
                                  },
                                  {
                                    "key": "declined",
                                    "name": "Declined",
                                    "kind": "cancelled",
                                    "color": "grey",
                                    "set_by": [],
                                    "require_note": false,
                                    "message": ""
                                  }
                                ],
                                "trigger": {
                                  "words": [
                                    "quote"
                                  ],
                                  "header": "",
                                  "body": "Tap the button to ask for a quote.",
                                  "button": "Get a quote",
                                  "footer": ""
                                },
                                "after": {
                                  "review_step": true,
                                  "reply": "Thanks {contact.name}. Your request {reference} is with us; the price follows shortly.",
                                  "allow_additions": true,
                                  "status_page": true
                                },
                                "calculated": [
                                  {
                                    "key": "estimate",
                                    "label": "Estimate",
                                    "formula": "quantity * lookup('products', product, 'price')",
                                    "unit": "USD",
                                    "decimals": 2
                                  }
                                ]
                              }
                            }
                          ],
                          "automations": [
                            {
                              "name": "Price a quote request in the ERP",
                              "form": "quote",
                              "enabled": true,
                              "trigger": "submitted",
                              "options": {},
                              "conditions": {
                                "all": [
                                  {
                                    "field": "quantity",
                                    "gt": 0
                                  }
                                ]
                              },
                              "actions": [
                                {
                                  "type": "http",
                                  "connection": "erp",
                                  "method": "POST",
                                  "path": "/quotes",
                                  "query": {},
                                  "headers": {
                                    "X-Source": "whatsapp"
                                  },
                                  "body": {
                                    "reference": "{reference}",
                                    "customer": {
                                      "name": "{contact.name}",
                                      "phone": "{contact.phone}"
                                    },
                                    "product": "{product}",
                                    "quantity": "{quantity}",
                                    "photos": "{files.photos}"
                                  },
                                  "save": {
                                    "erp_id": "$.id",
                                    "quote_amount": "$.total"
                                  },
                                  "on_fail": "retry"
                                },
                                {
                                  "type": "set_status",
                                  "status": "quoted",
                                  "note": "Priced by the ERP"
                                },
                                {
                                  "type": "reply",
                                  "text": "Your quote {reference}: {quote_amount} USD for {quantity} x {product}. Shall we go ahead?",
                                  "buttons": [
                                    {
                                      "id": "accept",
                                      "title": "Accept",
                                      "set_status": "accepted"
                                    },
                                    {
                                      "id": "decline",
                                      "title": "Decline",
                                      "set_status": "declined"
                                    }
                                  ],
                                  "file": "",
                                  "link": true
                                }
                              ]
                            },
                            {
                              "name": "Tell the owner when a quote is accepted",
                              "form": "quote",
                              "enabled": true,
                              "trigger": "status_changed",
                              "options": {
                                "to": [
                                  "accepted"
                                ],
                                "from": []
                              },
                              "conditions": null,
                              "actions": [
                                {
                                  "type": "email",
                                  "to": [
                                    "owner"
                                  ],
                                  "subject": "Quote {reference} accepted: {quote_amount} USD",
                                  "body": "{contact.name} ({contact.phone}) accepted.\n\n{answers}\n\n{desk_link}",
                                  "attach_files": false
                                }
                              ]
                            }
                          ],
                          "publish": [
                            "quote"
                          ]
                        }
                      }
                    ],
                    "this_number": {
                      "enabled": true,
                      "forms": [
                        "meter_reading"
                      ],
                      "lists": [
                        "products"
                      ],
                      "connections": [
                        "erp"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "app2email's connection to the WhatsApp account needs attention, or the request log is not available right now. Possible error.code values: whatsapp_connection_problem, whatsapp_number_not_registered, request_log_unavailable, whatsapp_unavailable, whatsapp_maintenance, block_list_busy, account_service_unavailable, sandbox_unavailable, partner_service_unavailable, shop_not_ready, submit_not_ready.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "x-a2e-webhook-events": [],
        "x-a2e-error-codes": [
          "api_key_expired",
          "api_key_number_mismatch",
          "api_key_old_format",
          "api_key_revoked",
          "insufficient_scope",
          "internal_error",
          "invalid_api_key",
          "invalid_authorization_header",
          "invalid_number_in_url",
          "ip_not_allowed",
          "missing_api_key",
          "number_not_found",
          "plan_not_allowed",
          "rate_limited",
          "service_not_live",
          "submit_not_ready"
        ],
        "x-a2e-sandbox": "read",
        "x-a2e-scope": "submissions:manage",
        "x-a2e-mcp-tool": "get_submit_guide",
        "x-a2e-needs": null
      }
    }
  },
  "components": {
    "parameters": {
      "Number": {
        "name": "number",
        "in": "path",
        "required": true,
        "description": "Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only.",
        "schema": {
          "type": "string",
          "pattern": "^[0-9]{8,15}$",
          "example": "4976659348270"
        }
      }
    },
    "schemas": {
      "AudioContent": {
        "type": "object",
        "description": "aac, amr, mp3, m4a or ogg (OPUS), up to 16 MB. No caption.",
        "properties": {
          "link": {
            "type": "string",
            "format": "uri",
            "description": "Public http(s) URL. app2email downloads the file and uploads it to WhatsApp."
          },
          "data": {
            "type": "string",
            "format": "byte",
            "description": "The file, base64 encoded."
          },
          "id": {
            "type": "string",
            "description": "A media id from POST /media."
          },
          "filename": {
            "type": "string"
          },
          "mime_type": {
            "type": "string"
          },
          "voice": {
            "type": "boolean",
            "description": "true: a voice message (play button, transcript). Ogg with the OPUS codec only; app2email does not convert."
          }
        }
      },
      "Component": {
        "type": "object",
        "required": [
          "type"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "header",
              "body",
              "button",
              "carousel",
              "limited_time_offer"
            ]
          },
          "sub_type": {
            "type": "string",
            "enum": [
              "url",
              "quick_reply",
              "copy_code",
              "flow",
              "catalog",
              "mpm",
              "spm",
              "order_details"
            ],
            "description": "Buttons only."
          },
          "index": {
            "type": "string",
            "example": "0",
            "description": "Buttons only: position of the button in the template, starting at 0."
          },
          "parameters": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Parameter"
            }
          },
          "cards": {
            "type": "array",
            "description": "type 'carousel': one entry per card of the approved template, {card_index, components: [header, body, button...]}.",
            "items": {
              "type": "object",
              "properties": {
                "card_index": {
                  "type": "integer"
                },
                "components": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Component"
                  }
                }
              }
            }
          }
        }
      },
      "ContactCard": {
        "type": "object",
        "required": [
          "name"
        ],
        "description": "One vCard, as WhatsApp Cloud API.",
        "properties": {
          "name": {
            "type": "object",
            "required": [
              "formatted_name"
            ],
            "properties": {
              "formatted_name": {
                "type": "string",
                "example": "Jane Citizen"
              },
              "first_name": {
                "type": "string"
              },
              "last_name": {
                "type": "string"
              },
              "middle_name": {
                "type": "string"
              },
              "prefix": {
                "type": "string"
              },
              "suffix": {
                "type": "string"
              }
            }
          },
          "phones": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "phone": {
                  "type": "string"
                },
                "type": {
                  "type": "string",
                  "example": "CELL"
                },
                "wa_id": {
                  "type": "string"
                }
              }
            }
          },
          "emails": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "email": {
                  "type": "string"
                },
                "type": {
                  "type": "string"
                }
              }
            }
          },
          "addresses": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "org": {
            "type": "object",
            "properties": {
              "company": {
                "type": "string"
              },
              "department": {
                "type": "string"
              },
              "title": {
                "type": "string"
              }
            }
          },
          "urls": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "url": {
                  "type": "string"
                },
                "type": {
                  "type": "string"
                }
              }
            }
          },
          "birthday": {
            "type": "string",
            "example": "1990-01-31"
          }
        }
      },
      "Currency": {
        "type": "object",
        "properties": {
          "fallback_value": {
            "type": "string",
            "example": "$10.50"
          },
          "code": {
            "type": "string",
            "example": "USD"
          },
          "amount_1000": {
            "type": "integer",
            "example": 10500
          }
        }
      },
      "DateTime": {
        "type": "object",
        "properties": {
          "fallback_value": {
            "type": "string",
            "example": "February 25, 2026"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "code",
          "message",
          "how_to_fix"
        ],
        "properties": {
          "code": {
            "type": "string",
            "enum": [
              "account_deactivated",
              "account_not_confirmed",
              "account_service_error",
              "account_service_unavailable",
              "api_key_expired",
              "api_key_number_mismatch",
              "api_key_old_format",
              "api_key_revoked",
              "approval_already_resolved",
              "approval_body_too_large",
              "approval_expired",
              "approval_not_found",
              "automation_not_found",
              "background_start_failed",
              "block_list_busy",
              "block_list_full",
              "block_not_found",
              "block_users_error",
              "block_users_failed",
              "booking_cancelled",
              "booking_not_enabled",
              "booking_not_found",
              "booking_slot_taken",
              "broadcast_cancelled",
              "broadcast_not_cancellable",
              "broadcast_not_found",
              "bsuid_not_supported",
              "call_permission_required",
              "caption_not_supported",
              "caption_too_long",
              "catcher_not_found",
              "client_exists",
              "client_not_editable",
              "client_not_found",
              "connection_failed",
              "connection_in_use",
              "connection_not_found",
              "contact_book_error",
              "contact_not_found",
              "conversation_not_found",
              "daily_cap_reached",
              "dataset_not_found",
              "delivery_in_progress",
              "delivery_not_found",
              "display_name_not_approved",
              "duplicate_recipients",
              "email_not_sent",
              "encryption_key_managed",
              "flow_blocked_by_integrity",
              "flow_cannot_publish",
              "flow_json_download_failed",
              "flow_json_not_found",
              "flow_json_too_large",
              "flow_name_taken",
              "flow_not_deletable",
              "flow_not_editable",
              "flow_not_found",
              "flow_not_published",
              "flow_rejected",
              "form_exists",
              "form_has_submissions",
              "form_not_found",
              "form_not_published",
              "free_form_single_recipient",
              "hold_expired",
              "hold_not_found",
              "idempotency_key_reused",
              "idempotency_request_in_progress",
              "idempotency_request_interrupted",
              "insufficient_scope",
              "internal_error",
              "invalid_addons",
              "invalid_analytics_query",
              "invalid_answers",
              "invalid_api_key",
              "invalid_auth_template",
              "invalid_authorization_header",
              "invalid_automation",
              "invalid_base64",
              "invalid_block",
              "invalid_booking",
              "invalid_bsuid",
              "invalid_call_request",
              "invalid_call_settings",
              "invalid_callback_data",
              "invalid_catalog_id",
              "invalid_client_request",
              "invalid_compare_days",
              "invalid_compliance_info",
              "invalid_components",
              "invalid_connection",
              "invalid_contact_email",
              "invalid_contacts",
              "invalid_contacts_message",
              "invalid_conversation_starters",
              "invalid_conversion_events",
              "invalid_coupon",
              "invalid_csv",
              "invalid_cursor",
              "invalid_direction",
              "invalid_display_name",
              "invalid_email",
              "invalid_estimate",
              "invalid_event_type",
              "invalid_events",
              "invalid_flow_categories",
              "invalid_flow_field",
              "invalid_flow_id",
              "invalid_flow_json",
              "invalid_flow_name",
              "invalid_form",
              "invalid_guests",
              "invalid_idempotency_key",
              "invalid_identity_key_hash",
              "invalid_insights_request",
              "invalid_interactive",
              "invalid_json",
              "invalid_keep_old_for_hours",
              "invalid_key_request",
              "invalid_library_filter",
              "invalid_limit",
              "invalid_link",
              "invalid_list",
              "invalid_location",
              "invalid_marketing_api",
              "invalid_media_id",
              "invalid_media_link",
              "invalid_media_type",
              "invalid_member",
              "invalid_months",
              "invalid_note",
              "invalid_number",
              "invalid_number_in_url",
              "invalid_numbers",
              "invalid_oba_request",
              "invalid_onboarding_request",
              "invalid_optimization_spec",
              "invalid_owner",
              "invalid_partner_settings",
              "invalid_payment",
              "invalid_phone",
              "invalid_plan",
              "invalid_poll",
              "invalid_profile",
              "invalid_public_key",
              "invalid_qr_code",
              "invalid_range",
              "invalid_reaction",
              "invalid_recipients",
              "invalid_redirect_url",
              "invalid_reply_to",
              "invalid_segment",
              "invalid_send_at",
              "invalid_series",
              "invalid_service",
              "invalid_setting",
              "invalid_settings",
              "invalid_setup",
              "invalid_slug",
              "invalid_start",
              "invalid_status",
              "invalid_submission",
              "invalid_template_category",
              "invalid_template_components",
              "invalid_template_field",
              "invalid_template_ids",
              "invalid_template_language",
              "invalid_template_name",
              "invalid_template_preview",
              "invalid_test_event",
              "invalid_text",
              "invalid_ticket_check_in",
              "invalid_ticket_code",
              "invalid_ticket_event",
              "invalid_ticket_order",
              "invalid_time",
              "invalid_to",
              "invalid_username",
              "invalid_users",
              "invalid_wait",
              "invalid_webhook_format",
              "invalid_webhook_headers",
              "invalid_webhook_secret",
              "invalid_webhook_url",
              "ip_not_allowed",
              "key_limit_reached",
              "key_limits_unavailable",
              "key_not_found",
              "link_not_found",
              "link_not_usable",
              "list_not_found",
              "marketing_disabled_on_cloud_api",
              "marketing_per_user_limit",
              "marketing_status_lookup_failed",
              "media_delete_failed",
              "media_download_error",
              "media_download_failed",
              "media_lookup_failed",
              "media_lookups_paused",
              "media_not_found",
              "media_too_large",
              "media_type_not_allowed",
              "media_upload_error",
              "media_upload_failed",
              "member_not_found",
              "message_not_found",
              "message_too_old",
              "messaging_limit_restricted",
              "missing_api_key",
              "missing_file",
              "missing_interactive",
              "missing_media",
              "missing_message_id",
              "missing_numbers",
              "missing_template_language",
              "missing_template_name",
              "missing_text",
              "missing_url",
              "monthly_cap_reached",
              "monthly_limit_reached",
              "not_in_instant_sandbox",
              "note_not_found",
              "nothing_to_change",
              "number_already_verified",
              "number_not_found",
              "number_not_live",
              "optin_not_found",
              "outside_24h_window",
              "package_not_found",
              "parameter_value_invalid",
              "partner_closed",
              "partner_service_unavailable",
              "partner_suspended",
              "payment_link_failed",
              "payment_not_found",
              "payment_provider_error",
              "payments_not_connected",
              "plan_already_active",
              "plan_not_allowed",
              "plan_not_available",
              "poll_not_found",
              "profile_photo_failed",
              "qr_code_not_found",
              "range_too_large",
              "rate_limited",
              "reaction_too_old",
              "recipient_identity_changed",
              "recipient_in_experiment",
              "recipient_is_sender",
              "recipient_not_allowed",
              "recipient_not_opted_in",
              "recipient_opted_out",
              "recipient_stopped_marketing",
              "recipient_unreachable",
              "refund_not_possible",
              "register_limit_reached",
              "request_log_unavailable",
              "request_not_found",
              "request_too_large",
              "required_parameter_missing",
              "route_not_found",
              "sandbox_key",
              "sandbox_recipient",
              "sandbox_unavailable",
              "schedule_failed",
              "segment_and_recipients",
              "segment_empty",
              "segment_exists",
              "segment_not_found",
              "send_at_in_past",
              "send_at_too_far",
              "service_not_live",
              "shop_changed",
              "shop_failed",
              "shop_invalid",
              "shop_limit",
              "shop_not_enabled",
              "shop_not_found",
              "shop_not_ready",
              "shop_not_tracked",
              "shop_order_problems",
              "shop_payment_failed",
              "shop_sku_taken",
              "slug_taken",
              "stage_not_allowed",
              "submission_not_found",
              "submit_not_enabled",
              "submit_not_ready",
              "template_already_exists",
              "template_archive_failed",
              "template_category_locked",
              "template_compare_unavailable",
              "template_delete_failed",
              "template_disabled",
              "template_format_policy",
              "template_insights_confirm_required",
              "template_insights_not_enabled",
              "template_insights_unavailable",
              "template_language_not_found",
              "template_language_required",
              "template_limit_reached",
              "template_lookup_failed",
              "template_name_reserved",
              "template_not_approved",
              "template_not_editable",
              "template_not_found",
              "template_not_marketing",
              "template_parameter_count_mismatch",
              "template_parameter_format_mismatch",
              "template_parameter_invalid",
              "template_parameters_invalid",
              "template_paused",
              "template_rejected",
              "template_sample_media_failed",
              "template_text_too_long",
              "template_unarchive_failed",
              "test_event_too_large",
              "text_too_long",
              "ticket_check_in_not_found",
              "ticket_code_not_found",
              "ticket_date_not_found",
              "ticket_event_not_found",
              "ticket_event_not_publishable",
              "ticket_limit_reached",
              "ticket_not_allowed",
              "ticket_not_found",
              "ticket_order_not_found",
              "ticket_seat_not_available",
              "ticket_type_not_found",
              "tickets_not_enabled",
              "tickets_not_on_sale",
              "tickets_sold_out",
              "to_and_recipients",
              "too_late",
              "too_many_catchers",
              "too_many_invites",
              "too_many_messages_to_recipient",
              "too_many_numbers",
              "too_many_recipients",
              "too_many_segments",
              "too_many_signups",
              "too_many_templates",
              "too_many_tests",
              "too_many_webhooks",
              "unsupported_content_type",
              "unsupported_message_type",
              "username_account_not_linked",
              "username_change_limit",
              "username_not_available",
              "username_not_eligible",
              "username_taken",
              "voice_needs_ogg_opus",
              "waitlist_not_found",
              "waitlist_not_offered",
              "waitlist_not_set_up",
              "webhook_not_found",
              "webhook_url_in_use",
              "whatsapp_account_locked",
              "whatsapp_account_restricted",
              "whatsapp_connection_problem",
              "whatsapp_error",
              "whatsapp_flow_failed",
              "whatsapp_maintenance",
              "whatsapp_number_not_registered",
              "whatsapp_parameter_error",
              "whatsapp_payment_issue",
              "whatsapp_permission_missing",
              "whatsapp_rate_limit",
              "whatsapp_unavailable"
            ],
            "description": "Stable error code, safe to use in your own logic."
          },
          "message": {
            "type": "string",
            "description": "What is wrong, in plain words."
          },
          "how_to_fix": {
            "type": "string",
            "description": "What to change to make the request work."
          },
          "documentation_url": {
            "type": "string",
            "example": "https://www.app2email.com/docs/api/errors#template_not_found",
            "description": "Where this error is explained."
          },
          "is_retriable": {
            "type": "boolean",
            "description": "true: the same request can work later without a change (limits, caps, trouble on our side or WhatsApp's, a request with the same Idempotency-Key still running)."
          },
          "retry_after_seconds": {
            "type": "integer",
            "description": "How long to wait before trying again, when known (also the Retry-After header)."
          },
          "details": {
            "type": "object",
            "additionalProperties": true,
            "description": "Extra information, eg the problems found, available templates or languages."
          },
          "example_request": {
            "$ref": "#/components/schemas/SendTemplateRequest"
          },
          "whatsapp_error": {
            "$ref": "#/components/schemas/WhatsAppError"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "request_id": {
            "type": "string",
            "example": "kxrkf",
            "description": "Quote this when contacting support."
          },
          "error": {
            "$ref": "#/components/schemas/Error"
          }
        }
      },
      "FreeFormMedia": {
        "type": "object",
        "description": "Give exactly one of: link, data or id. 'filename' is shown to the recipient for documents.",
        "properties": {
          "link": {
            "type": "string",
            "format": "uri",
            "example": "https://example.com/photo.jpg",
            "description": "Public http(s) URL. app2email downloads the file and uploads it to WhatsApp."
          },
          "data": {
            "type": "string",
            "format": "byte",
            "description": "The file, base64 encoded. A 'data:<mime>;base64,' prefix is accepted."
          },
          "id": {
            "type": "string",
            "description": "A media id from POST /media (or uploaded to WhatsApp for this number)."
          },
          "filename": {
            "type": "string",
            "example": "invoice.pdf",
            "description": "Needed with 'data' for documents."
          },
          "mime_type": {
            "type": "string",
            "example": "application/pdf",
            "description": "Optional. The type is detected from the file where possible."
          },
          "caption": {
            "type": "string",
            "maxLength": 1024,
            "example": "Your parcel",
            "description": "Optional text under the image, video or document."
          }
        }
      },
      "FreeFormText": {
        "type": "object",
        "required": [
          "body"
        ],
        "properties": {
          "body": {
            "type": "string",
            "example": "Thanks, it arrives on Friday.",
            "description": "The text. Up to 4096 characters."
          },
          "preview_url": {
            "type": "boolean",
            "default": false,
            "description": "true: show a preview of a link in the text."
          }
        }
      },
      "Interactive": {
        "type": "object",
        "required": [
          "type",
          "action"
        ],
        "description": "WhatsApp's interactive object. type button: action.buttons, up to 3 reply buttons (title up to 20 characters; the shortcut \"buttons\": [\"Confirm\", \"Change\"] works too). type list: action.button (the text that opens the list) and action.sections with rows (up to 10 rows in all; a row can be a plain title). type cta_url: action.parameters {display_text, url}. header: text (60 characters), or image / video / document (link, data or id) for button and cta_url. body.text up to 1024 characters, footer.text up to 60. Also (WhatsApp Cloud API's objects): carousel (action.cards: 2 to 10, image or video header, one URL button or quick replies each; or product cards {card_index, type: 'product', action: {product_retailer_id, catalog_id}}), location_request_message, request_contact_info, flow (action.parameters: flow_message_version '3', flow_id or flow_name, flow_cta), product and product_list (a connected catalog), catalog_message, call_permission_request and voice_call (Calling), address_message (India; optional text header), order_details and order_status (payments). The fixed action.name of a kind is filled in when left out.",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "button",
              "list",
              "cta_url",
              "carousel",
              "location_request_message",
              "request_contact_info",
              "flow",
              "product",
              "product_list",
              "catalog_message",
              "call_permission_request",
              "voice_call",
              "address_message",
              "order_details",
              "order_status"
            ]
          },
          "header": {
            "type": "object",
            "additionalProperties": true,
            "example": {
              "type": "text",
              "text": "Booking"
            }
          },
          "body": {
            "type": "object",
            "required": [
              "text"
            ],
            "properties": {
              "text": {
                "type": "string",
                "maxLength": 1024,
                "example": "Confirm your booking for Friday 10:00?"
              }
            }
          },
          "footer": {
            "type": "object",
            "properties": {
              "text": {
                "type": "string",
                "maxLength": 60
              }
            }
          },
          "action": {
            "type": "object",
            "additionalProperties": true,
            "example": {
              "buttons": [
                {
                  "type": "reply",
                  "reply": {
                    "id": "yes",
                    "title": "Confirm"
                  }
                },
                {
                  "type": "reply",
                  "reply": {
                    "id": "no",
                    "title": "Change"
                  }
                }
              ]
            }
          }
        }
      },
      "Language": {
        "type": "object",
        "required": [
          "code"
        ],
        "description": "Required when the template exists in more than one language.",
        "properties": {
          "code": {
            "type": "string",
            "example": "en",
            "description": "Template language code, eg 'en', 'en_US', 'nl'."
          }
        }
      },
      "Location": {
        "type": "object",
        "required": [
          "latitude",
          "longitude"
        ],
        "properties": {
          "latitude": {
            "type": "string",
            "example": "-33.8688"
          },
          "longitude": {
            "type": "string",
            "example": "151.2093"
          },
          "name": {
            "type": "string"
          },
          "address": {
            "type": "string"
          }
        }
      },
      "LocationContent": {
        "type": "object",
        "required": [
          "latitude",
          "longitude"
        ],
        "properties": {
          "latitude": {
            "type": "number",
            "minimum": -90,
            "maximum": 90,
            "example": -33.8568
          },
          "longitude": {
            "type": "number",
            "minimum": -180,
            "maximum": 180,
            "example": 151.2153
          },
          "name": {
            "type": "string",
            "example": "Sydney Opera House"
          },
          "address": {
            "type": "string",
            "example": "Bennelong Point, Sydney NSW 2000"
          }
        }
      },
      "Media": {
        "type": "object",
        "description": "Give exactly one of: link, data or id. To send the template's own sample media instead, leave the header component out.",
        "properties": {
          "link": {
            "type": "string",
            "format": "uri",
            "example": "https://example.com/photo.jpg",
            "description": "Public http(s) URL. app2email downloads the file (no login, no private network addresses) and uploads it to WhatsApp."
          },
          "data": {
            "type": "string",
            "format": "byte",
            "description": "The file, base64 encoded. A 'data:<mime>;base64,' prefix is accepted."
          },
          "id": {
            "type": "string",
            "description": "A media id already uploaded to WhatsApp for this number."
          },
          "filename": {
            "type": "string",
            "example": "invoice.pdf",
            "description": "Shown to the recipient for documents. Also helps detect the file type."
          },
          "mime_type": {
            "type": "string",
            "example": "application/pdf",
            "description": "Optional. The type is detected from the file where possible."
          }
        }
      },
      "Parameter": {
        "type": "object",
        "required": [
          "type"
        ],
        "description": "One value. Set 'type' and the matching field, eg {\"type\":\"text\",\"text\":\"John\"} or {\"type\":\"image\",\"image\":{\"link\":\"https://...\"}}.",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "text",
              "image",
              "video",
              "document",
              "location",
              "currency",
              "date_time",
              "payload",
              "coupon_code",
              "action",
              "product",
              "limited_time_offer"
            ]
          },
          "parameter_name": {
            "type": "string",
            "description": "For templates with NAMED placeholders, eg 'first_name' for {{first_name}}."
          },
          "text": {
            "type": "string",
            "description": "type 'text'. No new lines, tabs or more than 4 spaces in a row."
          },
          "image": {
            "$ref": "#/components/schemas/Media"
          },
          "video": {
            "$ref": "#/components/schemas/Media"
          },
          "document": {
            "$ref": "#/components/schemas/Media"
          },
          "location": {
            "$ref": "#/components/schemas/Location"
          },
          "currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "date_time": {
            "$ref": "#/components/schemas/DateTime"
          },
          "payload": {
            "type": "string",
            "description": "type 'payload': quick reply button payload."
          },
          "coupon_code": {
            "type": "string",
            "description": "type 'coupon_code': copy code button value."
          },
          "action": {
            "type": "object",
            "additionalProperties": true,
            "description": "type 'action': flow / catalog button data, as WhatsApp Cloud API."
          },
          "product": {
            "type": "object",
            "properties": {
              "product_retailer_id": {
                "type": "string"
              },
              "catalog_id": {
                "type": "string"
              }
            },
            "description": "type 'product': a product header."
          },
          "limited_time_offer": {
            "type": "object",
            "properties": {
              "expiration_time_ms": {
                "type": "integer",
                "example": 1767225600000
              }
            },
            "description": "type 'limited_time_offer': when the offer ends (ms since 1970)."
          }
        }
      },
      "ReactionContent": {
        "type": "object",
        "required": [
          "message_id",
          "emoji"
        ],
        "properties": {
          "message_id": {
            "type": "string",
            "example": "wamid.HBgLNjE0MTIzNDU2NzgVAgASGBQzQUZCMTY0MDc2MUYwNzBDNTY5MAA=",
            "description": "A message the contact sent, up to 30 days old."
          },
          "emoji": {
            "type": "string",
            "example": "👍",
            "description": "One emoji. \"\" removes your reaction."
          }
        }
      },
      "Recipient": {
        "type": "object",
        "required": [
          "to"
        ],
        "properties": {
          "to": {
            "type": "string",
            "example": "61412345678",
            "description": "One number, with country code."
          },
          "components": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Component"
            },
            "description": "Only what differs for this number, eg its body values. The rest comes from template.components."
          },
          "recipient_identity_key_hash": {
            "type": "string",
            "maxLength": 200,
            "description": "Optional: this contact's identity_key_hash (see the request's)."
          }
        }
      },
      "SendTemplateRequest": {
        "type": "object",
        "description": "A WhatsApp message in the format of WhatsApp Cloud API (Meta's exact body works unchanged): a template (type 'template', the default, any time), or within 24 hours of the contact's last message a free-form text, image, video, document, audio, sticker, location, contacts, reaction or interactive message. Meta's mark-read body {messaging_product, status: 'read', message_id, typing_indicator?} marks a message as read. Give 'to' or 'recipients' (templates only).",
        "properties": {
          "messaging_product": {
            "type": "string",
            "enum": [
              "whatsapp"
            ],
            "description": "Optional. Always 'whatsapp'."
          },
          "recipient_type": {
            "type": "string",
            "enum": [
              "individual"
            ],
            "description": "Optional. Always 'individual'."
          },
          "to": {
            "type": "string",
            "example": "61412345678",
            "description": "Recipient's WhatsApp number with country code. Digits only is best (spaces, '+', '-' are removed). Several recipients: separate the numbers with commas, eg \"61412345678,61498765432\" (semicolons and new lines work too), or send a JSON array of numbers. Each number gets its own message, and the response lists the result per number in 'results'. A free-form message (not 'template') goes to one number. A business-scoped user id (eg 61.AbC123, from from_user_id) is accepted as it is."
          },
          "recipient": {
            "type": "string",
            "example": "61.AbC123xyz",
            "description": "Optional, instead of 'to': one contact, a phone number or a business-scoped user id (BSUID). Sent to WhatsApp as 'recipient'."
          },
          "segment": {
            "type": "string",
            "example": "VIP, consented",
            "description": "Optional, app2email only, instead of 'to' / 'recipients': the id or name of a saved segment (GET /segments). Templates only. Each contact's named template parameters without a value are filled from its custom_fields ('name' from the contact's name). Recorded as a broadcast."
          },
          "type": {
            "type": "string",
            "enum": [
              "template",
              "text",
              "image",
              "video",
              "document",
              "interactive",
              "audio",
              "sticker",
              "location",
              "contacts",
              "reaction"
            ],
            "default": "template",
            "description": "'template' (default): an approved template. Otherwise a free-form message within the 24 hour window; the field of the same name holds it. Left out with status 'read': mark as read."
          },
          "interactive": {
            "$ref": "#/components/schemas/Interactive",
            "description": "type 'interactive': reply buttons, a list, or a URL button."
          },
          "template": {
            "$ref": "#/components/schemas/Template"
          },
          "text": {
            "$ref": "#/components/schemas/FreeFormText",
            "description": "type 'text': the message."
          },
          "image": {
            "$ref": "#/components/schemas/FreeFormMedia",
            "description": "type 'image': link, data+filename or id, and an optional caption."
          },
          "video": {
            "$ref": "#/components/schemas/FreeFormMedia",
            "description": "type 'video': link, data+filename or id, and an optional caption."
          },
          "document": {
            "$ref": "#/components/schemas/FreeFormMedia",
            "description": "type 'document': link, data+filename or id, and an optional caption."
          },
          "reply_to": {
            "type": "string",
            "example": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA=",
            "description": "Optional, free-form only: the message_id of one of the contact's messages, quoted by this one. Meta's 'context': {\"message_id\": ...} works too."
          },
          "send_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-11-02T09:00:00+11:00",
            "description": "Optional, templates only: send later. ISO 8601 with a time zone ('Z' or '+11:00'), 1 minute to 29 days ahead. The answer is HTTP 202 with status 'scheduled'."
          },
          "campaign_name": {
            "type": "string",
            "maxLength": 100,
            "example": "October newsletter",
            "description": "Optional, app2email only. Several numbers in 'to' (or 'recipients'): the name of the broadcast this list is recorded as (Activity Log under Broadcasts). Default \"API: <template name>\". Not used for one number."
          },
          "recipients": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Recipient"
            },
            "description": "Optional, app2email only, instead of 'to': each number with its own values. Each entry's components replace the shared template.components of the same type (a button: the same index). Every number is checked before anything is sent."
          },
          "dry_run": {
            "type": "boolean",
            "default": false,
            "description": "Optional, app2email only. true: check everything and answer with the exact WhatsApp message per number, without sending, logging or counting anything."
          },
          "background": {
            "type": "boolean",
            "default": false,
            "description": "Optional, app2email only. true: answer HTTP 202 once everything is checked and the media uploaded, then send. Progress: broadcast.status_url (GET /v1/{number}/broadcasts/{code}) or the broadcast.completed webhook event."
          },
          "audio": {
            "$ref": "#/components/schemas/AudioContent",
            "description": "type 'audio'."
          },
          "sticker": {
            "$ref": "#/components/schemas/StickerContent",
            "description": "type 'sticker'."
          },
          "location": {
            "$ref": "#/components/schemas/LocationContent",
            "description": "type 'location'."
          },
          "contacts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ContactCard"
            },
            "description": "type 'contacts': 1 to 20 cards."
          },
          "reaction": {
            "$ref": "#/components/schemas/ReactionContent",
            "description": "type 'reaction'."
          },
          "context": {
            "type": "object",
            "properties": {
              "message_id": {
                "type": "string"
              }
            },
            "description": "Meta's form of reply_to."
          },
          "callback_data": {
            "type": "string",
            "maxLength": 512,
            "example": "order-1234",
            "description": "Optional. Sent to WhatsApp as biz_opaque_callback_data; back as data.callback_data in this message's message.status events. Meta's own field name works too."
          },
          "recipient_identity_key_hash": {
            "type": "string",
            "maxLength": 200,
            "example": "DF2lS5v2W6x=",
            "description": "Optional, one recipient (per number: in recipients[]): delivered only while the contact's identity key has this hash (message.received data.identity_key_hash); else message.failed, 137000 recipient_identity_changed. Needs PUT /settings/identity-check."
          },
          "marketing_api": {
            "type": "string",
            "enum": [
              "auto",
              "cloud_api",
              "mm_api"
            ],
            "description": "Optional, MARKETING templates: the path for this send (true = mm_api, false = cloud_api). Default: the number's setting messages.marketing_route (auto)."
          },
          "product_policy": {
            "type": "string",
            "enum": [
              "CLOUD_API_FALLBACK",
              "STRICT"
            ],
            "description": "Optional, Marketing Messages API only: STRICT = no fallback to the Cloud API. Default CLOUD_API_FALLBACK."
          },
          "message_activity_sharing": {
            "type": "boolean",
            "description": "Optional, Marketing Messages API only: share read and click activity with Meta for this message."
          },
          "status": {
            "type": "string",
            "enum": [
              "read"
            ],
            "description": "Meta's mark-read body: 'read' with message_id (no type)."
          },
          "message_id": {
            "type": "string",
            "description": "Meta's mark-read body: the received message."
          },
          "typing_indicator": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "text"
                ]
              }
            },
            "description": "Meta's mark-read body: also show the typing indicator."
          }
        }
      },
      "StickerContent": {
        "type": "object",
        "description": "WebP only: up to 100 KB static, 500 KB animated. No caption.",
        "properties": {
          "link": {
            "type": "string",
            "format": "uri",
            "description": "Public http(s) URL. app2email downloads the file and uploads it to WhatsApp."
          },
          "data": {
            "type": "string",
            "format": "byte",
            "description": "The file, base64 encoded."
          },
          "id": {
            "type": "string",
            "description": "A media id from POST /media."
          },
          "filename": {
            "type": "string"
          },
          "mime_type": {
            "type": "string"
          }
        }
      },
      "SubmitAction": {
        "type": "object",
        "required": [
          "type"
        ],
        "additionalProperties": true,
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "set_status",
              "assign",
              "set_field",
              "calculate",
              "tag",
              "set_priority",
              "set_due",
              "reply",
              "ask_location",
              "send_form",
              "email",
              "notify",
              "http",
              "openapi",
              "mcp",
              "wait",
              "stop"
            ],
            "description": "What the action does. `set_status`: Move the submission to a stage. Keys: status, note. `assign`: Set the assignee. Keys: to. `set_field`: Store a value on the submission. Keys: key, value. `calculate`: Store the result of a formula. Keys: key, formula. `tag`: Add or remove tags. Keys: add, remove. `set_priority`: Set the priority. Keys: priority. `set_due`: Set the due time. Keys: minutes. `reply`: Message the submitter on WhatsApp (by e-mail when they gave only an e-mail address). Outside WhatsApp's reply window the message is held and announced like any reply from the Inbox. Keys: text, buttons, file, link. `ask_location`: Ask the submitter for their location with WhatsApp's Send location request. The pin is stored on the submission. Keys: text. `send_form`: Send another form as a follow-up. Its submission gets parent = this one, and customer_replied fires here when it arrives. Keys: form, text, prefill. `email`: Send an e-mail. Keys: to, subject, body, attach_files. `notify`: E-mail team members. Keys: to, text. `http`: Call an outside system with a plain HTTP request. Keys: connection, method, path, url, query, headers, body, save, on_fail. `openapi`: Call an operation of an imported OpenAPI document. Keys: connection, operation, params, body, save, on_fail. `mcp`: Call a tool of an MCP server. Keys: connection, tool, arguments, save, on_fail. `wait`: Pause. The rest runs later, and only if the conditions still hold then. Keys: minutes. `stop`: End the run here."
          },
          "status": {
            "type": "string",
            "description": "set_status. The stage key."
          },
          "note": {
            "type": "string",
            "description": "set_status. The note of the change (needed when the stage has require_note)."
          },
          "to": {
            "description": "assign: member:<id> = that member. role:<role> = the members with that role in turn (round robin). least_busy:<role> = the member with that role who has the fewest open submissions. none = nobody. email: A list of up to 10: owner, assignee, submitter, an address, or a placeholder that holds an address. notify: assignee, role:<role> or all."
          },
          "key": {
            "type": "string",
            "description": "set_field, calculate. An internal field of the form, or any other name that is not one of the form's questions and not a reserved word: it is stored in extra."
          },
          "value": {
            "description": "set_field. The value, with placeholders."
          },
          "formula": {
            "type": "string",
            "maxLength": 500,
            "description": "calculate. The formula (see the automation's description for the language)."
          },
          "add": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "tag. Tags to add."
          },
          "remove": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "tag. Tags to remove."
          },
          "priority": {
            "type": "string",
            "enum": [
              "low",
              "normal",
              "high",
              "urgent"
            ],
            "description": "set_priority."
          },
          "minutes": {
            "type": "integer",
            "minimum": 0,
            "maximum": 525600,
            "description": "set_due: minutes from now, 0 to 525600 (0 takes the due time off). wait: how long to pause, 1 to 43200."
          },
          "text": {
            "type": "string",
            "description": "reply, ask_location, send_form, notify: the message, with placeholders."
          },
          "buttons": {
            "type": "array",
            "maxItems": 3,
            "description": "reply. 0 to 3 buttons: [{id (a-z, 0-9 and _, up to 20 characters, unique in the reply), title (up to 20 characters), set_status}]. Pressing one moves the submission to set_status (when given) and fires the button trigger.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "example": "accept"
                },
                "title": {
                  "type": "string",
                  "maxLength": 20,
                  "example": "Accept"
                },
                "set_status": {
                  "type": "string",
                  "example": "accepted",
                  "description": "The stage the submission moves to when it is pressed. Left out: only the button trigger fires."
                }
              },
              "required": [
                "id",
                "title"
              ]
            }
          },
          "file": {
            "type": "string",
            "description": "reply. The key of a photo or document field whose files are sent along, or \"\"."
          },
          "link": {
            "type": "boolean",
            "description": "reply. true: add a button that opens the submitter's status page."
          },
          "form": {
            "type": "string",
            "description": "send_form. The key of the form to send."
          },
          "prefill": {
            "type": "object",
            "additionalProperties": true,
            "description": "send_form. Values for the new form: {\"<field key>\": value}, with placeholders. Up to 30 values."
          },
          "subject": {
            "type": "string",
            "description": "email."
          },
          "body": {
            "description": "email: the text. http, openapi: Any JSON; sent as application/json. A string that is exactly one placeholder keeps the value's type: \"{quantity}\" sends a number, \"{submission}\" the whole submission object."
          },
          "attach_files": {
            "type": "boolean",
            "description": "email. true: attach the submission's files (up to 15 MB in all; above that their links are listed). Default false."
          },
          "connection": {
            "type": "string",
            "description": "http, openapi, mcp. The connection's key (GET /submit/connections). http only: \"\" with a full url."
          },
          "method": {
            "type": "string",
            "enum": [
              "GET",
              "POST",
              "PUT",
              "PATCH",
              "DELETE"
            ],
            "description": "http."
          },
          "path": {
            "type": "string",
            "example": "/quotes",
            "description": "http. With a connection: added to its base address, for example /orders/{reference}. Each value a placeholder inserts is percent-encoded."
          },
          "url": {
            "type": "string",
            "description": "http. Without a connection: the full https address. Placeholders may stand in the path and the query, not in the host name."
          },
          "query": {
            "type": "object",
            "additionalProperties": true,
            "description": "http. Query parameters: {name: value}, up to 30."
          },
          "headers": {
            "type": "object",
            "additionalProperties": true,
            "description": "http. Extra headers: {name: value}, up to 10, each value up to 1,000 characters. Sign-in headers come from the connection only. Not allowed: Host, Content-Length, Transfer-Encoding, Connection, Cookie, Authorization, and names starting X-App2email-, Proxy-, X-Forwarded- or Content-."
          },
          "operation": {
            "type": "string",
            "example": "createTicket",
            "description": "openapi. A function id of the connection (GET /submit/connections/{key}/functions)."
          },
          "params": {
            "type": "object",
            "additionalProperties": true,
            "description": "openapi. The operation's parameters by name: {name: value}. Path, query and header parameters go where the document says; body parameters build the JSON body."
          },
          "tool": {
            "type": "string",
            "description": "mcp. The tool's name (GET /submit/connections/{key}/functions)."
          },
          "arguments": {
            "type": "object",
            "additionalProperties": true,
            "description": "mcp. The tool's arguments: {name: value}, typed like a JSON body."
          },
          "save": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "example": {
              "erp_id": "$.id",
              "quote_amount": "$.total"
            },
            "description": "http, openapi, mcp. Up to 20 values taken from the answer and stored in the submission's extra: {\"<extra key or internal field>\": \"<JSON path>\"}. A JSON path is $ (the whole answer), $.a.b[0].c, or $text (the whole answer as text; for mcp the first text content)."
          },
          "on_fail": {
            "type": "string",
            "enum": [
              "retry",
              "continue",
              "stop"
            ],
            "default": "retry",
            "description": "http, openapi, mcp. retry (default): try again after 1 minute, 10 minutes and 1 hour, then the run fails and submit.automation_failed is sent. A failure that cannot get better is not tried again: a 4xx answer other than 408, 425 and 429, a refused address, a redirect. continue: note the failure and go on with the next action. stop: end the run as failed (submit.automation_failed is sent)."
          }
        },
        "example": {
          "type": "http",
          "connection": "erp",
          "method": "POST",
          "path": "/quotes",
          "query": {},
          "headers": {
            "X-Source": "whatsapp"
          },
          "body": {
            "reference": "{reference}",
            "customer": {
              "name": "{contact.name}",
              "phone": "{contact.phone}"
            },
            "product": "{product}",
            "quantity": "{quantity}",
            "photos": "{files.photos}"
          },
          "save": {
            "erp_id": "$.id",
            "quote_amount": "$.total"
          },
          "on_fail": "retry"
        },
        "description": "One step of an automation: `type` and that type's keys. Every text takes placeholders. `set_status`: Move the submission to a stage. Keys: status = The stage key. note = The note of the change (needed when the stage has require_note). `assign`: Set the assignee. Keys: to = member:<id> = that member. role:<role> = the members with that role in turn (round robin). least_busy:<role> = the member with that role who has the fewest open submissions. none = nobody. `set_field`: Store a value on the submission. Keys: key = An internal field of the form, or any other name that is not one of the form's questions and not a reserved word: it is stored in extra. value = The value, with placeholders. `calculate`: Store the result of a formula. Keys: key = Where the result goes (extra): the same rule as the key of set_field. formula = The formula, up to 500 characters. `tag`: Add or remove tags. Keys: add = Tags to add. remove = Tags to remove. At least one tag in add or remove. `set_priority`: Set the priority. Keys: priority = low, normal, high or urgent. `set_due`: Set the due time. Keys: minutes = Minutes from now, 0 to 525600 (a year). 0 takes the due time off. `reply`: Message the submitter on WhatsApp (by e-mail when they gave only an e-mail address). Outside WhatsApp's reply window the message is held and announced like any reply from the Inbox. Keys: text = The message, up to 4,000 characters. buttons = 0 to 3 buttons: [{id (a-z, 0-9 and _, up to 20 characters, unique in the reply), title (up to 20 characters), set_status}]. Pressing one moves the submission to set_status (when given) and fires the button trigger. file = The key of a photo or document field whose files are sent along, or \"\". link = true: add a button that opens the submitter's status page. `ask_location`: Ask the submitter for their location with WhatsApp's Send location request. The pin is stored on the submission. Keys: text = The message. `send_form`: Send another form as a follow-up. Its submission gets parent = this one, and customer_replied fires here when it arrives. Keys: form = The key of the form to send. text = The message with the form button. prefill = Values for the new form: {\"<field key>\": value}, with placeholders. Up to 30 values. `email`: Send an e-mail. Keys: to = A list of up to 10: owner, assignee, submitter, an address, or a placeholder that holds an address. subject = The subject, up to 200 characters. body = The text, up to 10,000 characters. {answers} gives every answer as Label: value lines. attach_files = true: attach the submission's files (up to 15 MB in all; above that their links are listed). Default false. `notify`: E-mail team members. Keys: to = assignee, role:<role> or all. text = The text, up to 4,000 characters. `http`: Call an outside system with a plain HTTP request. Keys: connection = The key of a connection (kind http or openapi): its base address and sign-in are used. Or \"\" with a full url. method = GET, POST, PUT, PATCH or DELETE. Left out: POST with a body, else GET. path = With a connection: added to its base address, for example /orders/{reference}. Each value a placeholder inserts is percent-encoded. url = Without a connection: the full https address. Placeholders may stand in the path and the query, not in the host name. query = Query parameters: {name: value}, up to 30. headers = Extra headers: {name: value}, up to 10, each value up to 1,000 characters. Sign-in headers come from the connection only. body = Any JSON; sent as application/json. A string that is exactly one placeholder keeps the value's type: \"{quantity}\" sends a number, \"{submission}\" the whole submission object. save = Up to 20 values taken from the answer and stored in the submission's extra: {\"<extra key or internal field>\": \"<JSON path>\"}. A JSON path is $ (the whole answer), $.a.b[0].c, or $text (the whole answer as text; for mcp the first text content). on_fail = retry (default): try again after 1 minute, 10 minutes and 1 hour, then the run fails and submit.automation_failed is sent. A failure that cannot get better is not tried again: a 4xx answer other than 408, 425 and 429, a refused address, a redirect. continue: note the failure and go on with the next action. stop: end the run as failed (submit.automation_failed is sent). `openapi`: Call an operation of an imported OpenAPI document. Keys: connection = The key of an openapi connection. operation = A function id of the connection (GET /submit/connections/{key}/functions). params = The operation's parameters by name: {name: value}. Path, query and header parameters go where the document says; body parameters build the JSON body. body = The whole JSON body, instead of body parameters. save = Up to 20 values taken from the answer and stored in the submission's extra: {\"<extra key or internal field>\": \"<JSON path>\"}. A JSON path is $ (the whole answer), $.a.b[0].c, or $text (the whole answer as text; for mcp the first text content). on_fail = retry (default): try again after 1 minute, 10 minutes and 1 hour, then the run fails and submit.automation_failed is sent. A failure that cannot get better is not tried again: a 4xx answer other than 408, 425 and 429, a refused address, a redirect. continue: note the failure and go on with the next action. stop: end the run as failed (submit.automation_failed is sent). `mcp`: Call a tool of an MCP server. Keys: connection = The key of an mcp connection. tool = The tool's name (GET /submit/connections/{key}/functions). arguments = The tool's arguments: {name: value}, typed like a JSON body. save = Up to 20 values taken from the answer and stored in the submission's extra: {\"<extra key or internal field>\": \"<JSON path>\"}. A JSON path is $ (the whole answer), $.a.b[0].c, or $text (the whole answer as text; for mcp the first text content). on_fail = retry (default): try again after 1 minute, 10 minutes and 1 hour, then the run fails and submit.automation_failed is sent. A failure that cannot get better is not tried again: a 4xx answer other than 408, 425 and 429, a refused address, a redirect. continue: note the failure and go on with the next action. stop: end the run as failed (submit.automation_failed is sent). `wait`: Pause. The rest runs later, and only if the conditions still hold then. Keys: minutes = 1 to 43200 (30 days). `stop`: End the run here."
      },
      "SubmitAutomationInput": {
        "type": "object",
        "required": [
          "name",
          "trigger",
          "actions"
        ],
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 80,
            "example": "Large quotes go to a manager",
            "description": "What it is called in the list, up to 80 characters. POST /submit/setup replaces an automation with the same name on the same form."
          },
          "form": {
            "type": "string",
            "example": "quote",
            "description": "The key of the form it belongs to, or \"\" for every form."
          },
          "enabled": {
            "type": "boolean",
            "default": true
          },
          "position": {
            "type": "integer",
            "minimum": 0,
            "description": "Its place in the list, lowest first."
          },
          "trigger": {
            "type": "string",
            "enum": [
              "submitted",
              "status_changed",
              "assigned",
              "updated",
              "note_added",
              "file_added",
              "customer_replied",
              "button",
              "overdue",
              "due",
              "manual"
            ],
            "description": "When it runs. `submitted`: A submission is complete: its files are stored (or 3 minutes passed without them, which is noted on the submission). `status_changed`: The stage changed. Options - to: Stage keys it moved to. [] = any. from: Stage keys it moved from. [] = any. `assigned`: The assignee changed. `updated`: Answers or internal fields were edited. Options - fields: Only when one of these field keys changed. [] = any. `note_added`: A member or the API wrote a note. `file_added`: A file was added after the submission was made. `customer_replied`: The submitter added text or files: after tapping Add more, with a follow-up form, or on their status page. `button`: The submitter pressed a button of a reply. Options - button: The button's id (a-z, 0-9 and _, up to 20 characters). \"\" = any button. `overdue`: The submission is still in the same stage after this long. Fires once per stay in a stage. Options - minutes: Needed: 5 to 43200 (30 days). stages: Only in these stage keys. [] = every open stage. `due`: The due time passed while the submission is open. Fires once per due time. `manual`: A member presses its button on the submission, or POST /submit/submissions/{id}/run names it. Options - label: The button's text, up to 30 characters. Left out: the automation's name."
          },
          "options": {
            "type": "object",
            "additionalProperties": true,
            "example": {
              "to": [
                "accepted"
              ],
              "from": []
            },
            "description": "The trigger's options (see trigger). {} when it has none."
          },
          "conditions": {
            "$ref": "#/components/schemas/SubmitRule",
            "nullable": true,
            "description": "Must hold for the actions to run. In an automation a rule's field may also be status, status_kind, channel, form, priority, tags, assignee, verified, files_count, contact.name, contact.phone. null = always."
          },
          "actions": {
            "type": "array",
            "minItems": 1,
            "maxItems": 20,
            "items": {
              "$ref": "#/components/schemas/SubmitAction"
            },
            "description": "1 to 20 actions, run in order."
          }
        },
        "example": {
          "name": "Price a quote request in the ERP",
          "form": "quote",
          "enabled": true,
          "trigger": "submitted",
          "options": {},
          "conditions": {
            "all": [
              {
                "field": "quantity",
                "gt": 0
              }
            ]
          },
          "actions": [
            {
              "type": "http",
              "connection": "erp",
              "method": "POST",
              "path": "/quotes",
              "query": {},
              "headers": {
                "X-Source": "whatsapp"
              },
              "body": {
                "reference": "{reference}",
                "customer": {
                  "name": "{contact.name}",
                  "phone": "{contact.phone}"
                },
                "product": "{product}",
                "quantity": "{quantity}",
                "photos": "{files.photos}"
              },
              "save": {
                "erp_id": "$.id",
                "quote_amount": "$.total"
              },
              "on_fail": "retry"
            },
            {
              "type": "set_status",
              "status": "quoted",
              "note": "Priced by the ERP"
            },
            {
              "type": "reply",
              "text": "Your quote {reference}: {quote_amount} USD for {quantity} x {product}. Shall we go ahead?",
              "buttons": [
                {
                  "id": "accept",
                  "title": "Accept",
                  "set_status": "accepted"
                },
                {
                  "id": "decline",
                  "title": "Decline",
                  "set_status": "declined"
                }
              ],
              "file": "",
              "link": true
            }
          ]
        },
        "description": "An automation: when (`trigger` with its `options`) - if (`conditions`, a rule or null) - do (`actions`, in order). Only the keys listed here are accepted: an unknown key in the document, in `options` or in an action is a problem (`unknown_key`), so a misspelt key is never ignored. Every run is logged step by step, with what was sent and what came back (GET /submit/runs). A change an automation makes can set off other automations, at most 3 levels deep; one submission gets at most 30 runs an hour. Outside calls refuse private and loopback addresses, do not follow redirects, wait at most 15 seconds and read at most 256 KB; a number makes at most 60 a minute and 2,000 a day. Every text of an action, a stage message and the form's reply takes placeholders in curly brackets; a name that is not known stays as typed. {<field key>}: The answer to that field, an internal field, a calculated value or a value an automation saved (any key of answers or extra). {reference}: The submission's reference, for example MR-7Q3M2A. {form}: The form's name. {form_key}: The form's key. {status}: The stage key. {status_name}: The stage's name. {channel}: whatsapp, web, api or staff. {priority}: low, normal, high or urgent. {tags}: The tags, comma separated. {created}: When it was submitted, in the business's local time (yyyy-MM-dd HH:mm). {updated}: When it last changed (local time). {due}: The due time (local time), empty when there is none. {contact.name}: The submitter's name. {contact.phone}: Their number. {contact.email}: Their e-mail address. {assignee.name}: The assigned member's name. {assignee.email}: Their e-mail address. {link}: The submitter's own status page. {desk_link}: The submission in the staff inbox. {answers}: Every answer as Label: value lines. {files}: A link to every file, one per line. Another system can fetch a link for 7 days. {files.<field key>}: The links of that field's files, as one text with a link per line. {note}: The note of the stage change, or the note that set the automation off. {button}: The id of the button the submitter pressed. {business}: The business name. {submission}: In a JSON body or in arguments only: the whole submission object (its times are ISO 8601). {id}, {status_kind}, {verified}, {files_count}, {contact.identity}, {assignee.id}, {prefill.<key>}, {location.address}: More values of the submission that can be read the same way. {= formula }: The result of a formula, for example {= round(quantity * 1.1, 2) }. Formulas (calculated fields, the calculate action, and {= ... } inside any text): numbers, 'texts' in single quotes, field keys, + - * / %, the comparisons == != > >= < <=, and / or / not, brackets, and the functions if(condition, then, else): then when the condition holds, otherwise else (null without an else). min(a, b, ...): The smallest number. max(a, b, ...): The largest number. round(x, decimals): x rounded, half away from zero; decimals 0 to 10, default 0. abs(x): x without its sign. num(x): x as a number, null when it is not one. len(x): The length of a text, or the number of items of a list. coalesce(a, b, ...): The first value that is not empty. lower(x): x in lower case. upper(x): x in upper case. concat(a, b, ...): The values joined as one text. lookup('<list>', id, '<column>'): A column of the item with that id in a list of the number, for example a price. previous('<field>'): The same contact's last value of that field in this form. count_files('<field>'): How many files a photo or document field holds. days_since(date): Whole days from a date (YYYY-MM-DD) to today; negative for a date to come. No loops and no assignment; at most 500 characters; a division by zero or a missing number gives null. Examples: reading - previous('reading'); quantity * lookup('products', product, 'price'); if(usage < 0, 'check', 'ok'); round(amount * 1.2, 2); days_since(purchase_date) > 30 and count_files('receipt') == 0. A rule is {\"field\": \"<key>\", <operator>: <value>} with the operators equals, not_equals, in, not_in, contains, empty, not_empty, gt, gte, lt, lte. Every operator written in one rule must hold. When the field's value is an array (multiselect, tags) a rule holds when any item matches, except not_equals and not_in, which need every item. Rules combine as {\"all\": [rule, ...]} (every one) or {\"any\": [rule, ...]} (at least one); groups nest 2 deep with up to 10 rules each. null = no condition. Examples: {\"field\": \"deliver\", \"equals\": true}; {\"all\": [{\"field\": \"amount\", \"gt\": 5000}, {\"field\": \"category\", \"in\": [\"plant\", \"vehicle\"]}]}."
      },
      "SubmitConnectionInput": {
        "type": "object",
        "example": {
          "name": "ERP",
          "kind": "http",
          "base_url": "https://erp.example.com/api",
          "auth": {
            "type": "bearer",
            "secret": "YOUR_ERP_TOKEN"
          },
          "headers": {
            "X-Tenant": "acme"
          },
          "enabled": true
        },
        "description": "An outside system automations can call. A new connection needs name and kind; a later PUT without kind changes only the keys it names. `http`: A base address and a sign-in. An http action names the method, path, query, headers and JSON body. `openapi`: An OpenAPI 3.0 or 3.1 document in JSON (spec_url, or spec posted once; up to 2 MB; YAML and Swagger 2 are not read). app2email keeps a short list of its operations; an openapi action picks one and fills its parameters. `mcp`: An MCP server on streamable HTTP (base_url) with a token or no sign-in (OAuth and SSE-only servers are not supported). app2email lists its tools; an mcp action picks one and fills its arguments. Sign-in (auth.type): `none`: No sign-in. `bearer`: Authorization: Bearer <secret>. `header`: The header called name carries the secret. `basic`: Basic sign-in with username and the secret as the password. `query`: The query parameter called name carries the secret. The secret is stored encrypted and never returned: leave auth.secret out of a later PUT to keep it; when the address changes (scheme, host or port) the secret must be sent again. Every address must be https and public: private, loopback, link-local and cloud metadata addresses are refused (checked after the name is looked up), redirects are not followed, a call waits at most 15 seconds and reads at most 256 KB. A connection keeps at most 300 functions with 40 parameters each.",
        "properties": {
          "name": {
            "type": "string",
            "example": "ERP"
          },
          "kind": {
            "type": "string",
            "enum": [
              "http",
              "openapi",
              "mcp"
            ],
            "description": "`http`: A base address and a sign-in. An http action names the method, path, query, headers and JSON body. `openapi`: An OpenAPI 3.0 or 3.1 document in JSON (spec_url, or spec posted once; up to 2 MB; YAML and Swagger 2 are not read). app2email keeps a short list of its operations; an openapi action picks one and fills its parameters. `mcp`: An MCP server on streamable HTTP (base_url) with a token or no sign-in (OAuth and SSE-only servers are not supported). app2email lists its tools; an mcp action picks one and fills its arguments."
          },
          "base_url": {
            "type": "string",
            "example": "https://erp.example.com/api",
            "description": "https only. http: the base every path is added to. openapi: the API's base; left empty, the document's first server is used. mcp: the server's address."
          },
          "headers": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "example": {
              "X-Tenant": "acme"
            },
            "description": "Up to 5 fixed headers sent with every call. Not secret: they are shown again."
          },
          "spec_url": {
            "type": "string",
            "example": "https://erp.example.com/openapi.json",
            "description": "openapi only: where the OpenAPI document (JSON) is read from."
          },
          "enabled": {
            "type": "boolean",
            "default": true,
            "description": "false: actions that use it fail without calling out."
          },
          "auth": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "none",
                  "bearer",
                  "header",
                  "basic",
                  "query"
                ],
                "description": "`none`: No sign-in. `bearer`: Authorization: Bearer <secret>. `header`: The header called name carries the secret. `basic`: Basic sign-in with username and the secret as the password. `query`: The query parameter called name carries the secret."
              },
              "name": {
                "type": "string",
                "description": "header: the header's name. query: the parameter's name."
              },
              "username": {
                "type": "string",
                "description": "basic only."
              },
              "secret": {
                "type": "string",
                "description": "The token, key or password. Write-only: never shown again. Left out: the stored one is kept."
              }
            },
            "required": [
              "type"
            ]
          },
          "spec": {
            "type": "object",
            "additionalProperties": true,
            "description": "openapi only: the OpenAPI document itself, posted once instead of spec_url."
          }
        }
      },
      "SubmitFormDefinition": {
        "type": "object",
        "required": [
          "title",
          "steps"
        ],
        "properties": {
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 60,
            "example": "Meter reading",
            "description": "The form's public name, 1 to 60 characters."
          },
          "description": {
            "type": "string",
            "maxLength": 300,
            "description": "Under the title on the web page and in the forms menu, up to 300 characters."
          },
          "prefix": {
            "type": "string",
            "example": "MR",
            "description": "2 to 4 letters A-Z that start every reference of this form (MR-7Q3M2A). \"\" = the settings' default_prefix."
          },
          "steps": {
            "type": "array",
            "minItems": 1,
            "maxItems": 12,
            "items": {
              "$ref": "#/components/schemas/SubmitFormStep"
            },
            "description": "1 to 12 steps, in the order they are asked. One step is one screen; app2email splits a step over several screens by itself when WhatsApp's limits demand it."
          },
          "stages": {
            "type": "array",
            "minItems": 2,
            "maxItems": 12,
            "items": {
              "$ref": "#/components/schemas/SubmitFormStage"
            },
            "description": "2 to 12 stages a submission moves through. The first one is where a new submission starts. At least one of kind open and one of kind done. Left out: New (open), In progress (open), Done (done)."
          },
          "who": {
            "type": "object",
            "properties": {
              "mode": {
                "type": "string",
                "enum": [
                  "anyone",
                  "listed"
                ],
                "default": "anyone",
                "description": "listed: only the numbers below, or contacts with the tag, may submit (a form for field staff). listed needs at least one number or a tag."
              },
              "numbers": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Up to 500 numbers, digits only with country code (6 to 20 digits)."
              },
              "tag": {
                "type": "string",
                "maxLength": 40,
                "description": "A contact tag: contacts carrying it may submit."
              }
            },
            "description": "Who may submit."
          },
          "trigger": {
            "type": "object",
            "properties": {
              "words": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "maxItems": 10,
                "example": [
                  "meter"
                ],
                "description": "A contact who sends one of these words gets the form. Up to 10 words, 30 characters each. A word that another form of the number or an enabled Book-and-Pay word already uses is refused (word_taken)."
              },
              "header": {
                "type": "string",
                "maxLength": 60,
                "description": "A bold line above the body, optional."
              },
              "body": {
                "type": "string",
                "maxLength": 1000,
                "example": "Tap the button to send your reading.",
                "description": "The text of the message that carries the form, 1 to 1,000 characters. Left out: Tap the button to open the form."
              },
              "button": {
                "type": "string",
                "maxLength": 20,
                "example": "Open form",
                "description": "The button's text, 1 to 20 characters. Left out: Open form."
              },
              "footer": {
                "type": "string",
                "maxLength": 60,
                "description": "A small grey line, optional."
              }
            },
            "description": "The message that opens the form on WhatsApp, and the words that send it."
          },
          "after": {
            "type": "object",
            "properties": {
              "review_step": {
                "type": "boolean",
                "default": true,
                "description": "A last screen that lists the answers before sending."
              },
              "reply": {
                "type": "string",
                "maxLength": 1000,
                "description": "The WhatsApp message after sending, with placeholders ({reference}, {form}, {contact.name} ...). \"\" = no reply. Left out: a thank-you with the reference."
              },
              "allow_additions": {
                "type": "boolean",
                "default": false,
                "description": "The reply gets an Add more button: text, photos and files the submitter sends in the next 10 minutes are attached to the submission."
              },
              "status_page": {
                "type": "boolean",
                "default": true,
                "description": "The reply carries a button to the submitter's status page."
              }
            },
            "description": "What happens right after a submission."
          },
          "web": {
            "type": "object",
            "properties": {
              "enabled": {
                "type": "boolean",
                "default": true,
                "description": "The form has a web page (links.web of the form)."
              },
              "verify": {
                "type": "string",
                "enum": [
                  "off",
                  "optional",
                  "required"
                ],
                "default": "optional",
                "description": "Proving the WhatsApp number of a web submission with one message. optional: offered as Get updates on WhatsApp. required: the submission counts only once proven. off: never asked."
              },
              "ask_email": {
                "type": "boolean",
                "default": false,
                "description": "Also ask for an e-mail address at the end."
              },
              "success_text": {
                "type": "string",
                "maxLength": 500,
                "description": "Shown after sending. \"\" = the standard text."
              }
            },
            "description": "The web page of the form."
          },
          "notify": {
            "type": "object",
            "properties": {
              "email": {
                "type": "boolean",
                "default": true,
                "description": "E-mail the business for each submission (to the settings' notify_email)."
              },
              "to": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "maxItems": 5,
                "description": "Up to 5 more addresses."
              },
              "attach_files": {
                "type": "boolean",
                "default": true,
                "description": "Attach the submission's files."
              }
            },
            "description": "The e-mail the business gets."
          },
          "calculated": {
            "type": "array",
            "maxItems": 20,
            "description": "0 to 20 calculated fields: values worked out from the answers each time they change, stored in extra. Formulas (calculated fields, the calculate action, and {= ... } inside any text): numbers, 'texts' in single quotes, field keys, + - * / %, the comparisons == != > >= < <=, and / or / not, brackets, and the functions if(condition, then, else): then when the condition holds, otherwise else (null without an else). min(a, b, ...): The smallest number. max(a, b, ...): The largest number. round(x, decimals): x rounded, half away from zero; decimals 0 to 10, default 0. abs(x): x without its sign. num(x): x as a number, null when it is not one. len(x): The length of a text, or the number of items of a list. coalesce(a, b, ...): The first value that is not empty. lower(x): x in lower case. upper(x): x in upper case. concat(a, b, ...): The values joined as one text. lookup('<list>', id, '<column>'): A column of the item with that id in a list of the number, for example a price. previous('<field>'): The same contact's last value of that field in this form. count_files('<field>'): How many files a photo or document field holds. days_since(date): Whole days from a date (YYYY-MM-DD) to today; negative for a date to come. No loops and no assignment; at most 500 characters; a division by zero or a missing number gives null. Examples: reading - previous('reading'); quantity * lookup('products', product, 'price'); if(usage < 0, 'check', 'ok'); round(amount * 1.2, 2); days_since(purchase_date) > 30 and count_files('receipt') == 0.",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string",
                  "example": "usage",
                  "description": "Its name in extra, rules and placeholders. Same rules as a field key."
                },
                "label": {
                  "type": "string",
                  "maxLength": 60,
                  "example": "Usage"
                },
                "formula": {
                  "type": "string",
                  "maxLength": 500,
                  "example": "reading - previous('reading')"
                },
                "unit": {
                  "type": "string"
                },
                "decimals": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 6
                }
              },
              "required": [
                "key",
                "formula"
              ]
            }
          },
          "retention_days": {
            "type": "integer",
            "default": 0,
            "description": "0 = keep. Otherwise closed submissions and their files are erased this many days after closing (30 to 3650)."
          }
        },
        "example": {
          "title": "Meter reading",
          "description": "Send us this month's reading.",
          "prefix": "MR",
          "steps": [
            {
              "key": "reading",
              "title": "Your reading",
              "text": "",
              "show_if": null,
              "fields": [
                {
                  "key": "meter_no",
                  "type": "text",
                  "label": "Meter number",
                  "help": "On the front of the meter",
                  "required": true,
                  "default": "{contact.meter_no}",
                  "max_length": 20
                },
                {
                  "key": "reading",
                  "type": "number",
                  "label": "Meter reading",
                  "required": true,
                  "min": 0,
                  "max": 999999,
                  "decimals": 0,
                  "unit": "kWh"
                },
                {
                  "key": "photo",
                  "type": "photo",
                  "label": "Photo of the meter",
                  "required": true,
                  "max_files": 1,
                  "source": "camera"
                },
                {
                  "key": "moving",
                  "type": "yesno",
                  "label": "Are you moving out?",
                  "required": true
                },
                {
                  "key": "billing_ref",
                  "type": "text",
                  "label": "Billing reference",
                  "internal": true
                }
              ]
            },
            {
              "key": "move",
              "title": "Your move",
              "text": "We will close the account on that day.",
              "show_if": {
                "field": "moving",
                "equals": true
              },
              "fields": [
                {
                  "key": "move_date",
                  "type": "date",
                  "label": "Moving date",
                  "required": true,
                  "min_days": -30,
                  "max_days": 90
                },
                {
                  "key": "new_address",
                  "type": "textarea",
                  "label": "New address for the final bill",
                  "required": false,
                  "max_length": 300
                }
              ]
            }
          ],
          "stages": [
            {
              "key": "received",
              "name": "Received",
              "kind": "open",
              "color": "blue",
              "set_by": [],
              "require_note": false,
              "message": ""
            },
            {
              "key": "queried",
              "name": "Queried",
              "kind": "open",
              "color": "amber",
              "set_by": [],
              "require_note": true,
              "message": "We have a question about your reading {reference}: {note}"
            },
            {
              "key": "checked",
              "name": "Checked",
              "kind": "done",
              "color": "green",
              "set_by": [
                "manager"
              ],
              "require_note": false,
              "message": "Thanks {contact.name}, your reading of {reading} kWh is recorded."
            }
          ],
          "who": {
            "mode": "anyone",
            "numbers": [],
            "tag": ""
          },
          "trigger": {
            "words": [
              "meter",
              "reading"
            ],
            "header": "",
            "body": "Tap the button to send your reading.",
            "button": "Open form",
            "footer": ""
          },
          "after": {
            "review_step": true,
            "reply": "Thanks {contact.name}. We have your {form} - reference {reference}.",
            "allow_additions": false,
            "status_page": true
          },
          "web": {
            "enabled": true,
            "verify": "optional",
            "ask_email": false,
            "success_text": ""
          },
          "notify": {
            "email": true,
            "to": [],
            "attach_files": true
          },
          "calculated": [
            {
              "key": "usage",
              "label": "Usage",
              "formula": "reading - previous('reading')",
              "unit": "kWh",
              "decimals": 0
            }
          ],
          "retention_days": 0
        },
        "description": "A form as one document. The same JSON drives the WhatsApp form (app2email generates it: there is nothing to draw), the web page, the checks on every answer, the inbox columns and the exports. `steps` hold the fields; `stages` are the states a submission moves through; `who`, `trigger`, `after`, `web`, `notify`, `calculated` and `retention_days` are optional and take their defaults when left out. Limits: 12 steps, 12 fields in a step, 60 fields in a form, one location field, 64 KB of JSON. A save is checked as a whole: with any problem nothing is saved and the 400 answer lists each one with its path and a fix. The saved form comes back normalized, with every default filled in. Saving changes the working copy; WhatsApp keeps showing the published version until POST /submit/forms/{key}/publish is called again. Conditions: a step or a field with `show_if` appears only when its rule holds, and the rule may only look at fields of earlier steps. A rule is {\"field\": \"<key>\", <operator>: <value>} with the operators equals, not_equals, in, not_in, contains, empty, not_empty, gt, gte, lt, lte. Every operator written in one rule must hold. When the field's value is an array (multiselect, tags) a rule holds when any item matches, except not_equals and not_in, which need every item. Rules combine as {\"all\": [rule, ...]} (every one) or {\"any\": [rule, ...]} (at least one); groups nest 2 deep with up to 10 rules each. null = no condition. Examples: {\"field\": \"deliver\", \"equals\": true}; {\"all\": [{\"field\": \"amount\", \"gt\": 5000}, {\"field\": \"category\", \"in\": [\"plant\", \"vehicle\"]}]}."
      },
      "SubmitFormField": {
        "type": "object",
        "required": [
          "key",
          "type",
          "label"
        ],
        "properties": {
          "key": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9_]{0,39}$",
            "example": "reading",
            "description": "The field's name in answers, rules, placeholders, formulas and exports: a lower case letter, then lower case letters, digits or _ (at most 40 characters). Unique in the form, not a reserved word, not starting with _. Reserved: reference, status, status_name, form, form_key, channel, contact, link, id, created, updated, assignee, priority, tags, due, files, flow_token, screen, error_message, error, answers, extra, submission, note, button, business, desk_link, status_kind, verified, files_count, prefill, confirm, true, false, null, and, or, not."
          },
          "type": {
            "type": "string",
            "enum": [
              "text",
              "textarea",
              "number",
              "email",
              "phone",
              "date",
              "select",
              "multiselect",
              "yesno",
              "rating",
              "consent",
              "photo",
              "document",
              "location",
              "info",
              "hidden"
            ],
            "description": "The field type decides the answer's JSON type, the keys that apply and how WhatsApp shows it. `text` (value: string; on WhatsApp: text input): min_length, max_length, pattern. `textarea` (value: string; on WhatsApp: text area): min_length, max_length, pattern. `number` (value: number; on WhatsApp: number input): min, max, decimals, unit. `email` (value: string; on WhatsApp: e-mail input). `phone` (value: string; on WhatsApp: phone input). 6 to 20 digits. `date` (value: string, YYYY-MM-DD; on WhatsApp: date picker): min_days, max_days. `select` (value: string: the id of the choice; on WhatsApp: radio buttons up to 8 choices, a dropdown above that): choices, list. While its list is empty a select is not required and not checked. `multiselect` (value: array of strings: the ids of the choices; on WhatsApp: checkboxes): choices, min_choices, max_choices. `yesno` (value: boolean; on WhatsApp: Yes / No radio buttons). `rating` (value: number, 1 to max; on WhatsApp: radio buttons 1 to max): max. `consent` (value: boolean; on WhatsApp: a tick box). The label is the sentence to agree to (at most 120 characters). required true = it must be ticked. `photo` (value: array of file ids; on WhatsApp: photo picker): max_files, source. WhatsApp allows one photo or document picker on a screen: a step with several is split into several screens by itself. `document` (value: array of file ids; on WhatsApp: document picker): max_files, kinds. One picker on a screen, as for photo. `location` (value: string: the address text; the pin is the submission's location {lat, lng, name, address}; on WhatsApp: asked after the form with WhatsApp's own Send location request). On the web page: a Use my location button and an address line. One location field in a form; required is not enforced for it. `info` (value: nothing is stored; on WhatsApp: a heading (the label) and text): text. `hidden` (value: string; on WhatsApp: nothing is shown). The value is the field's default (usually {prefill.<key>}), or the prefill value given under the field's own key: a job number or an account that arrives with the link or the send call."
          },
          "label": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200,
            "example": "Meter reading",
            "description": "The question, 1 to 200 characters. A label longer than WhatsApp allows on the input is moved into text above it by itself."
          },
          "help": {
            "type": "string",
            "maxLength": 80,
            "description": "A hint with the input, up to 80 characters."
          },
          "required": {
            "type": "boolean",
            "description": "true: must be answered (consent: must be ticked). Default false. Not enforced for a location field: the pin arrives after the form."
          },
          "internal": {
            "type": "boolean",
            "default": false,
            "description": "true: never asked. Staff, the API or an automation fill it (a quote amount, a decision reason, an id another system returned). Its value is stored in the submission's extra and shows in the inbox and in exports. Only for the types text, textarea, number, email, phone, date, select, multiselect, yesno and rating; an internal field is never required and has no show_if. Default false."
          },
          "show_if": {
            "$ref": "#/components/schemas/SubmitRule",
            "nullable": true,
            "description": "A rule on fields of EARLIER steps: the field is asked only when the rule holds. The rule may look at fields that are asked or hidden, not at internal or info fields. A field that is not shown counts as empty for the rules after it. null = always."
          },
          "default": {
            "type": "string",
            "description": "The starting value, up to 500 characters: a literal, or the placeholders {contact.name}, {contact.phone}, {contact.<custom field>}, {prefill.<key>} (prefill = the values given when the form is sent). Not for photo, document, location and info."
          },
          "sensitive": {
            "type": "boolean",
            "default": false,
            "description": "true: the value is masked in WhatsApp's own summary of the form. Only for the types text, textarea, number, email, phone, date, select, multiselect, yesno and rating. Default false."
          },
          "min_length": {
            "type": "integer",
            "minimum": 0,
            "description": "text, textarea. Fewest characters. 0 = none."
          },
          "max_length": {
            "type": "integer",
            "minimum": 0,
            "description": "text, textarea. Most characters. 0 = the type's limit (text 200, textarea 2,000)."
          },
          "pattern": {
            "type": "string",
            "maxLength": 200,
            "description": "text, textarea. A regular expression the whole answer must match, up to 200 characters."
          },
          "min": {
            "type": "number",
            "nullable": true,
            "description": "number. Smallest value. null = none."
          },
          "max": {
            "type": "number",
            "nullable": true,
            "description": "number: the largest value, null = none. rating: the highest rating, 3 to 10, default 5."
          },
          "decimals": {
            "type": "integer",
            "minimum": 0,
            "maximum": 6,
            "default": 0,
            "description": "number. Decimal places allowed, 0 to 6. Default 0."
          },
          "unit": {
            "type": "string",
            "example": "kWh",
            "description": "number. Shown after the value, for example kWh. Up to 20 characters."
          },
          "min_days": {
            "type": "integer",
            "nullable": true,
            "description": "date. Earliest day, counted from today (negative = in the past). null = none."
          },
          "max_days": {
            "type": "integer",
            "nullable": true,
            "description": "date. Latest day, counted from today. null = none."
          },
          "choices": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "maxLength": 40,
                  "example": "gas",
                  "description": "What is stored as the answer. Unique in the field."
                },
                "title": {
                  "type": "string",
                  "maxLength": 80,
                  "example": "Gas",
                  "description": "What people see (WhatsApp shows the first 30 characters)."
                },
                "description": {
                  "type": "string",
                  "maxLength": 300,
                  "description": "A second line, optional."
                }
              },
              "required": [
                "id",
                "title"
              ]
            },
            "description": "select: 2 to 200 choices (or use list). multiselect: 2 to 20 choices."
          },
          "list": {
            "type": "string",
            "example": "products",
            "description": "select. Instead of choices: the key of a list of the number (GET /submit/lists). The list is read each time the form opens, so changing it needs no publish. At most 200 items are shown."
          },
          "min_choices": {
            "type": "integer",
            "minimum": 0,
            "default": 0,
            "description": "multiselect. Fewest ticks. 0 = none."
          },
          "max_choices": {
            "type": "integer",
            "minimum": 0,
            "default": 0,
            "description": "multiselect. Most ticks. 0 = no limit."
          },
          "max_files": {
            "type": "integer",
            "minimum": 1,
            "maximum": 10,
            "default": 1,
            "description": "photo, document. How many files, 1 to 10."
          },
          "source": {
            "type": "string",
            "enum": [
              "any",
              "camera",
              "gallery"
            ],
            "default": "any",
            "description": "photo. Where the photo may come from."
          },
          "kinds": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "any",
                "pdf",
                "image",
                "office"
              ]
            },
            "description": "document. What may be sent: [\"any\"] (default), or some of pdf, image, office."
          },
          "text": {
            "type": "string",
            "maxLength": 1000,
            "description": "info. The text shown, up to 1,000 characters."
          }
        },
        "description": "One question, or one value that is carried along. Every type takes key, type, label, help, required, internal, show_if, default and sensitive; the other keys belong to one or two types and a key that does not apply is dropped when the form is saved.",
        "example": {
          "key": "reading",
          "type": "number",
          "label": "Meter reading",
          "required": true,
          "min": 0,
          "max": 999999,
          "decimals": 0,
          "unit": "kWh"
        }
      },
      "SubmitFormStage": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9_]{0,39}$",
            "example": "received",
            "description": "The stage's name in the API (the submission's status): a lower case letter, then lower case letters, digits or _ (at most 40 characters). Unique in the form."
          },
          "name": {
            "type": "string",
            "example": "Received",
            "description": "What people see, for example In review. Up to 40 characters."
          },
          "kind": {
            "type": "string",
            "enum": [
              "open",
              "done",
              "cancelled"
            ],
            "description": "open: still being worked on. done: finished well. cancelled: finished without a result. A form needs at least one open and one done stage."
          },
          "color": {
            "type": "string",
            "enum": [
              "grey",
              "blue",
              "green",
              "amber",
              "red",
              "purple"
            ],
            "description": "grey, blue, green, amber, red or purple."
          },
          "set_by": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "owner",
                "admin",
                "manager",
                "agent",
                "viewer"
              ]
            },
            "description": "The roles that may choose this stage: some of owner, admin, manager, agent, viewer. [] = anyone who may change stages. Owners, admins, automations and API keys always may."
          },
          "require_note": {
            "type": "boolean",
            "description": "true: a note must come with the move to this stage."
          },
          "message": {
            "type": "string",
            "maxLength": 1000,
            "description": "Sent to the submitter when the submission arrives in this stage, up to 1,000 characters, with placeholders ({note} = the note of the change). \"\" = nothing is sent."
          }
        },
        "required": [
          "key",
          "name",
          "kind"
        ],
        "description": "A stage of a form. Inside a submission the stages come without message."
      },
      "SubmitFormStep": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9_]{0,39}$",
            "example": "reading",
            "description": "The step's name: a lower case letter, then lower case letters, digits or _ (at most 40 characters). Unique among the steps."
          },
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 60,
            "example": "Your reading",
            "description": "The screen's title, 1 to 60 characters (WhatsApp shows the first 30)."
          },
          "text": {
            "type": "string",
            "maxLength": 500,
            "description": "Shown above the fields, up to 500 characters."
          },
          "show_if": {
            "$ref": "#/components/schemas/SubmitRule",
            "nullable": true,
            "description": "A rule on fields of EARLIER steps: the step is skipped when it does not hold. null = always."
          },
          "fields": {
            "type": "array",
            "minItems": 1,
            "maxItems": 12,
            "items": {
              "$ref": "#/components/schemas/SubmitFormField"
            },
            "description": "1 to 12 fields. Internal and hidden fields count but show nothing."
          }
        },
        "required": [
          "key",
          "title",
          "fields"
        ],
        "description": "One step of a form: a title and its fields."
      },
      "SubmitGuide": {
        "type": "object",
        "additionalProperties": true,
        "description": "Everything an agent needs to configure Submit-Info, as one JSON document. product, summary; how_to (the five steps in order); form {keys (every key of the definition), key_rule, field_keys (the keys every field takes), field_types [{type, value, keys, whatsapp, notes}], internal_types, reserved_keys, whatsapp, stage {keys, example}, rule {shape, operators, groups, comparing, in_show_if, in_automations, example}}; automation {keys, triggers [{trigger, when, options}], trigger_options, actions [{type, does, keys, example}], placeholders [{name, is}], placeholder_notes, formula {language, functions [{name, usage, does}], examples}, json_path, limits}; connection {keys, kinds [{kind, use}], auth_types [{type, use}], limits, example}; member {keys, roles {role: [abilities]}, abilities, notes}; settings {enabled, config}; limits; setup {shape, order, replaces}; presets [{key, name, description, category}]; examples (three complete setup documents: a meter reading form that posts to a billing API, a quote request, a field job report that calls an MCP tool); this_number (what the number already has). Keys may be added over time.",
        "properties": {
          "product": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "how_to": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "form": {
            "type": "object",
            "additionalProperties": true
          },
          "automation": {
            "type": "object",
            "additionalProperties": true
          },
          "connection": {
            "type": "object",
            "additionalProperties": true
          },
          "member": {
            "type": "object",
            "additionalProperties": true
          },
          "settings": {
            "type": "object",
            "additionalProperties": true
          },
          "limits": {
            "type": "object",
            "additionalProperties": true
          },
          "setup": {
            "type": "object",
            "additionalProperties": true
          },
          "presets": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SubmitPreset"
            }
          },
          "examples": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "title": {
                  "type": "string"
                },
                "setup": {
                  "$ref": "#/components/schemas/SubmitSetup"
                }
              }
            }
          },
          "this_number": {
            "type": "object",
            "properties": {
              "enabled": {
                "type": "boolean"
              },
              "forms": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "lists": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "connections": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "description": "The keys already in use on this number."
          }
        }
      },
      "SubmitGuideResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "request_id": {
            "type": "string"
          },
          "guide": {
            "$ref": "#/components/schemas/SubmitGuide"
          }
        }
      },
      "SubmitListItem": {
        "type": "object",
        "required": [
          "id",
          "title"
        ],
        "additionalProperties": true,
        "description": "One choice. Any other key is a column that formulas read with lookup('<list>', id, '<column>'), for example price. PUT also takes a plain text as an item: it becomes the id and the title.",
        "properties": {
          "id": {
            "type": "string",
            "example": "pump-s",
            "description": "What is stored as the answer. Unique in the list."
          },
          "title": {
            "type": "string",
            "example": "Pump, small"
          },
          "description": {
            "type": "string"
          }
        }
      },
      "SubmitPreset": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "example": "quote"
          },
          "name": {
            "type": "string",
            "example": "Quote request"
          },
          "description": {
            "type": "string"
          },
          "category": {
            "type": "string"
          }
        },
        "description": "A ready-made solution: forms, stages and automations for one kind of work."
      },
      "SubmitRule": {
        "type": "object",
        "additionalProperties": true,
        "description": "A rule is {\"field\": \"<key>\", <operator>: <value>} with the operators equals, not_equals, in, not_in, contains, empty, not_empty, gt, gte, lt, lte. Every operator written in one rule must hold. When the field's value is an array (multiselect, tags) a rule holds when any item matches, except not_equals and not_in, which need every item. Rules combine as {\"all\": [rule, ...]} (every one) or {\"any\": [rule, ...]} (at least one); groups nest 2 deep with up to 10 rules each. null = no condition. Examples: {\"field\": \"deliver\", \"equals\": true}; {\"all\": [{\"field\": \"amount\", \"gt\": 5000}, {\"field\": \"category\", \"in\": [\"plant\", \"vehicle\"]}]}. In a form (show_if) the field must belong to an EARLIER step. `equals`: The value is this. `not_equals`: The value is not this. `in`: The value is one of these (an array). `not_in`: The value is none of these (an array). `contains`: The text contains this (case does not matter), or the array has this item. `empty`: true: there is no value. `not_empty`: true: there is a value. `gt`: Greater than (numbers, dates). `gte`: Greater than or equal. `lt`: Less than. `lte`: Less than or equal.",
        "properties": {
          "field": {
            "type": "string",
            "example": "amount",
            "description": "A field key (or an extra key). Automations may also name status, status_kind, channel, form, priority, tags, assignee, verified, files_count, contact.name, contact.phone."
          },
          "equals": {},
          "not_equals": {},
          "in": {
            "type": "array",
            "items": {}
          },
          "not_in": {
            "type": "array",
            "items": {}
          },
          "contains": {},
          "empty": {
            "type": "boolean"
          },
          "not_empty": {
            "type": "boolean"
          },
          "gt": {},
          "gte": {},
          "lt": {},
          "lte": {},
          "all": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            },
            "description": "A group: every rule in it must hold."
          },
          "any": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            },
            "description": "A group: at least one rule in it must hold."
          }
        },
        "example": {
          "all": [
            {
              "field": "amount",
              "gt": 5000
            },
            {
              "field": "category",
              "in": [
                "plant",
                "vehicle"
              ]
            }
          ]
        }
      },
      "SubmitSettings": {
        "type": "object",
        "additionalProperties": true,
        "example": {
          "business_name": "",
          "default_prefix": "SI",
          "menu_words": [
            "form",
            "forms",
            "report",
            "submit"
          ],
          "menu_text": "What would you like to send us?",
          "status_words": [
            "status"
          ],
          "other_words_limit": 10,
          "notify_email": "",
          "timezone": "",
          "brand": {
            "color": "#2DAE5C",
            "background": "#FFFFFF",
            "hide_branding": false
          },
          "views": [
            {
              "key": "urgent",
              "name": "Urgent",
              "filter": {
                "priority": [
                  "urgent"
                ],
                "status_kind": [
                  "open"
                ]
              }
            }
          ],
          "retention_days": 0
        },
        "description": "The number's Submit-Info settings.",
        "properties": {
          "business_name": {
            "type": "string",
            "description": "The {business} placeholder and the name on the web pages. \"\" = the number's verified name."
          },
          "default_prefix": {
            "type": "string",
            "example": "SI",
            "description": "2 to 4 letters A-Z: the reference prefix of forms that have none."
          },
          "menu_words": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "maxItems": 10,
            "description": "A contact who sends one of these gets the form (one form) or a menu of the forms (several). [] = no menu."
          },
          "menu_text": {
            "type": "string",
            "description": "The text above the menu."
          },
          "status_words": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "maxItems": 5,
            "description": "A contact with a submission of the last 90 days who sends one of these gets its stage."
          },
          "other_words_limit": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "default": 10,
            "description": "A form's word starts the form only when the message has fewer than this many other words, so a long message never starts a form. 0 = a message of any length. Menu and status words also need a message of at most 5 words."
          },
          "notify_email": {
            "type": "string",
            "description": "Where the business's e-mails go. \"\" = the number's Default To address. \"off\" = none."
          },
          "timezone": {
            "type": "string",
            "example": "Australia/Sydney",
            "description": "\"\" = the number's time zone."
          },
          "brand": {
            "type": "object",
            "properties": {
              "color": {
                "type": "string",
                "example": "#2DAE5C"
              },
              "background": {
                "type": "string",
                "example": "#FFFFFF"
              },
              "hide_branding": {
                "type": "boolean"
              }
            },
            "description": "The look of the web form and the status page."
          },
          "views": {
            "type": "array",
            "maxItems": 20,
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "filter": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            },
            "description": "Saved inbox views the whole team shares."
          },
          "retention_days": {
            "type": "integer",
            "default": 0,
            "description": "For forms that set none: 0 = keep, else closed submissions are erased after this many days (30 to 3650)."
          }
        }
      },
      "SubmitSetup": {
        "type": "object",
        "example": {
          "dry_run": true,
          "settings": {
            "enabled": true
          },
          "lists": [
            {
              "key": "products",
              "name": "Products",
              "items": [
                {
                  "id": "pump-s",
                  "title": "Pump, small",
                  "description": "Up to 40 l/min",
                  "price": 240
                },
                {
                  "id": "pump-l",
                  "title": "Pump, large",
                  "description": "Up to 120 l/min",
                  "price": 610
                }
              ]
            }
          ],
          "connections": [
            {
              "name": "ERP",
              "kind": "http",
              "base_url": "https://erp.example.com/api",
              "auth": {
                "type": "bearer",
                "secret": "YOUR_ERP_TOKEN"
              },
              "headers": {
                "X-Tenant": "acme"
              },
              "enabled": true,
              "key": "erp"
            }
          ],
          "forms": [
            {
              "key": "quote",
              "name": "Quote request",
              "definition": {
                "title": "Quote request",
                "description": "Tell us what you need and we will send a price.",
                "prefix": "QR",
                "steps": [
                  {
                    "key": "need",
                    "title": "What you need",
                    "text": "",
                    "show_if": null,
                    "fields": [
                      {
                        "key": "product",
                        "type": "select",
                        "label": "Product",
                        "required": true,
                        "list": "products"
                      },
                      {
                        "key": "quantity",
                        "type": "number",
                        "label": "How many?",
                        "required": true,
                        "min": 1,
                        "max": 10000,
                        "decimals": 0
                      },
                      {
                        "key": "notes",
                        "type": "textarea",
                        "label": "Anything we should know?",
                        "required": false,
                        "max_length": 1000
                      },
                      {
                        "key": "photos",
                        "type": "photo",
                        "label": "Photos of the site (optional)",
                        "required": false,
                        "max_files": 3,
                        "source": "any"
                      },
                      {
                        "key": "quote_amount",
                        "type": "number",
                        "label": "Quote amount",
                        "internal": true,
                        "decimals": 2,
                        "unit": "USD"
                      }
                    ]
                  },
                  {
                    "key": "delivery",
                    "title": "Delivery",
                    "text": "",
                    "show_if": null,
                    "fields": [
                      {
                        "key": "deliver",
                        "type": "yesno",
                        "label": "Do you need delivery?",
                        "required": true
                      }
                    ]
                  },
                  {
                    "key": "delivery_address",
                    "title": "Delivery address",
                    "text": "",
                    "show_if": {
                      "field": "deliver",
                      "equals": true
                    },
                    "fields": [
                      {
                        "key": "address",
                        "type": "textarea",
                        "label": "Where should we deliver?",
                        "required": true,
                        "max_length": 300
                      }
                    ]
                  }
                ],
                "stages": [
                  {
                    "key": "new",
                    "name": "New",
                    "kind": "open",
                    "color": "blue",
                    "set_by": [],
                    "require_note": false,
                    "message": ""
                  },
                  {
                    "key": "quoted",
                    "name": "Quoted",
                    "kind": "open",
                    "color": "amber",
                    "set_by": [],
                    "require_note": false,
                    "message": ""
                  },
                  {
                    "key": "accepted",
                    "name": "Accepted",
                    "kind": "done",
                    "color": "green",
                    "set_by": [],
                    "require_note": false,
                    "message": "Thank you. We will be in touch about {reference} shortly."
                  },
                  {
                    "key": "declined",
                    "name": "Declined",
                    "kind": "cancelled",
                    "color": "grey",
                    "set_by": [],
                    "require_note": false,
                    "message": ""
                  }
                ],
                "trigger": {
                  "words": [
                    "quote"
                  ],
                  "header": "",
                  "body": "Tap the button to ask for a quote.",
                  "button": "Get a quote",
                  "footer": ""
                },
                "after": {
                  "review_step": true,
                  "reply": "Thanks {contact.name}. Your request {reference} is with us; the price follows shortly.",
                  "allow_additions": true,
                  "status_page": true
                },
                "calculated": [
                  {
                    "key": "estimate",
                    "label": "Estimate",
                    "formula": "quantity * lookup('products', product, 'price')",
                    "unit": "USD",
                    "decimals": 2
                  }
                ]
              }
            }
          ],
          "automations": [
            {
              "name": "Price a quote request in the ERP",
              "form": "quote",
              "enabled": true,
              "trigger": "submitted",
              "options": {},
              "conditions": {
                "all": [
                  {
                    "field": "quantity",
                    "gt": 0
                  }
                ]
              },
              "actions": [
                {
                  "type": "http",
                  "connection": "erp",
                  "method": "POST",
                  "path": "/quotes",
                  "query": {},
                  "headers": {
                    "X-Source": "whatsapp"
                  },
                  "body": {
                    "reference": "{reference}",
                    "customer": {
                      "name": "{contact.name}",
                      "phone": "{contact.phone}"
                    },
                    "product": "{product}",
                    "quantity": "{quantity}",
                    "photos": "{files.photos}"
                  },
                  "save": {
                    "erp_id": "$.id",
                    "quote_amount": "$.total"
                  },
                  "on_fail": "retry"
                },
                {
                  "type": "set_status",
                  "status": "quoted",
                  "note": "Priced by the ERP"
                },
                {
                  "type": "reply",
                  "text": "Your quote {reference}: {quote_amount} USD for {quantity} x {product}. Shall we go ahead?",
                  "buttons": [
                    {
                      "id": "accept",
                      "title": "Accept",
                      "set_status": "accepted"
                    },
                    {
                      "id": "decline",
                      "title": "Decline",
                      "set_status": "declined"
                    }
                  ],
                  "file": "",
                  "link": true
                }
              ]
            },
            {
              "name": "Tell the owner when a quote is accepted",
              "form": "quote",
              "enabled": true,
              "trigger": "status_changed",
              "options": {
                "to": [
                  "accepted"
                ],
                "from": []
              },
              "conditions": null,
              "actions": [
                {
                  "type": "email",
                  "to": [
                    "owner"
                  ],
                  "subject": "Quote {reference} accepted: {quote_amount} USD",
                  "body": "{contact.name} ({contact.phone}) accepted.\n\n{answers}\n\n{desk_link}",
                  "attach_files": false
                }
              ]
            }
          ],
          "publish": [
            "quote"
          ]
        },
        "description": "A whole solution in one document: settings, lists, connections, forms and automations, applied in that order. Every part is optional. What already exists under the same key is REPLACED: lists, connections and forms by `key`, automations by `name` within the same form. Parts and keys the document does not name are left alone. The document is checked as a whole (each form, each automation, and the links between them: a select's list, an action's connection, form, stage and field keys). With any problem nothing is written. `preset` in place of the parts installs a ready-made solution (GET /submit/presets).",
        "properties": {
          "dry_run": {
            "type": "boolean",
            "default": false,
            "description": "true: check only. The answer lists every problem and what would be written; nothing is changed."
          },
          "replace": {
            "type": "boolean",
            "default": true,
            "description": "Left out or true: a form whose key already exists is replaced by the one in the document. false: such a form is not overwritten - the answer is 409 `form_exists` and nothing is written. Lists, connections and automations of the same key / name are always replaced."
          },
          "preset": {
            "type": "string",
            "example": "quote",
            "description": "A preset's key, instead of lists, connections, forms and automations."
          },
          "settings": {
            "type": "object",
            "properties": {
              "enabled": {
                "type": "boolean",
                "description": "true switches Submit-Info on for the number."
              },
              "config": {
                "$ref": "#/components/schemas/SubmitSettings"
              }
            },
            "description": "As PUT /submit/settings."
          },
          "lists": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string",
                  "example": "products"
                },
                "name": {
                  "type": "string"
                },
                "items": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/SubmitListItem"
                  }
                }
              },
              "required": [
                "key",
                "name",
                "items"
              ]
            },
            "description": "As PUT /submit/lists/{key}, with the key inside."
          },
          "connections": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SubmitConnectionInput"
            },
            "description": "As PUT /submit/connections/{key}, with `key` inside each one."
          },
          "forms": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string",
                  "example": "quote"
                },
                "name": {
                  "type": "string",
                  "example": "Quote request"
                },
                "definition": {
                  "$ref": "#/components/schemas/SubmitFormDefinition"
                }
              },
              "required": [
                "key",
                "name",
                "definition"
              ]
            },
            "description": "As POST /submit/forms."
          },
          "automations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SubmitAutomationInput"
            },
            "description": "As POST /submit/automations."
          },
          "publish": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "quote"
            ],
            "description": "Form keys to publish to WhatsApp after everything was written without a problem. Ignored by a dry run."
          }
        }
      },
      "Template": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "example": "order_update",
            "description": "Exact name of an APPROVED template."
          },
          "language": {
            "$ref": "#/components/schemas/Language"
          },
          "components": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Component"
            },
            "description": "Values for the template's placeholders and media. Leave out for templates without parameters."
          }
        }
      },
      "WhatsAppError": {
        "type": "object",
        "description": "WhatsApp's (Meta's) own error, when the error came from WhatsApp.",
        "properties": {
          "code": {
            "type": "integer",
            "example": 132000
          },
          "message": {
            "type": "string"
          },
          "details": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "fbtrace_id": {
            "type": "string"
          }
        }
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Authorization: Bearer <your API key>"
      }
    }
  }
}
```

