Change a form: name, on or off, archive, definition
https://api.app2email.com/v1/{number}/submit/forms/{key} Scope: submissions:manage. Not with a sandbox key. Any of name, enabled, archived, position, definition (400 nothing_to_change with none). A definition replaces the whole working copy, so read the form, change it and send all of it back; it is checked as a whole (400 invalid_form, nothing saved). The web page follows the saved definition. WhatsApp keeps showing the published version: call POST /submit/forms/{key}/publish to make a changed definition live there. Submissions already made keep their answers; a removed field stays readable in them.
Path
-
Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only.
e.g.4976659348270 -
The form's key (GET /submit/forms).
e.g.meter_reading
Body application/json required
- name string
- enabled boolean
false: the form stops answering its words and links.
- archived boolean
true: hide the form and stop taking submissions. Its submissions stay.
-
Its place in the lists and in the forms menu, lowest first.
- definition object
The WHOLE new definition: it replaces the working copy.
12 fields
-
The form's public name, 1 to 60 characters.
e.g.Meter reading -
Under the title on the web page and in the forms menu, up to 300 characters.
- prefix string
2 to 4 letters A-Z that start every reference of this form (MR-7Q3M2A). "" = the settings' default_prefix.
e.g.MR -
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.
5 item fields
-
The step's name: a lower case letter, then lower case letters, digits or _ (at most 40 characters). Unique among the steps.
e.g.reading -
The screen's title, 1 to 60 characters (WhatsApp shows the first 30).
e.g.Your reading -
Shown above the fields, up to 500 characters.
-
A rule on fields of EARLIER steps: the step is skipped when it does not hold. null = always.
14 fields
- field string
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.
e.g.amount - equals any
- not_equals any
- in any[]
- not_in any[]
- contains any
- empty boolean
- not_empty boolean
- gt any
- gte any
- lt any
- lte any
- all object[]
A group: every rule in it must hold.
- any object[]
A group: at least one rule in it must hold.
-
1 to 12 fields. Internal and hidden fields count but show nothing.
26 item fields
-
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.
e.g.reading -
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.texttextareanumberemailphonedateselectmultiselectyesnoratingconsentphotodocumentlocationinfohidden -
The question, 1 to 200 characters. A label longer than WhatsApp allows on the input is moved into text above it by itself.
e.g.Meter reading -
A hint with the input, up to 80 characters.
- required boolean
true: must be answered (consent: must be ticked). Default false. Not enforced for a location field: the pin arrives after the form.
-
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.
-
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.
14 fields
- field string
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.
e.g.amount - equals any
- not_equals any
- in any[]
- not_in any[]
- contains any
- empty boolean
- not_empty boolean
- gt any
- gte any
- lt any
- lte any
- all object[]
A group: every rule in it must hold.
- any object[]
A group: at least one rule in it must hold.
- default string
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.
-
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.
-
text, textarea. Fewest characters. 0 = none.
-
text, textarea. Most characters. 0 = the type's limit (text 200, textarea 2,000).
-
text, textarea. A regular expression the whole answer must match, up to 200 characters.
- min number | null
number. Smallest value. null = none.
- max number | null
number: the largest value, null = none. rating: the highest rating, 3 to 10, default 5.
-
number. Decimal places allowed, 0 to 6. Default 0.
- unit string
number. Shown after the value, for example kWh. Up to 20 characters.
e.g.kWh - min_days integer | null
date. Earliest day, counted from today (negative = in the past). null = none.
- max_days integer | null
date. Latest day, counted from today. null = none.
- choices object[]
select: 2 to 200 choices (or use list). multiselect: 2 to 20 choices.
3 item fields
-
What is stored as the answer. Unique in the field.
e.g.gas -
What people see (WhatsApp shows the first 30 characters).
e.g.Gas -
A second line, optional.
-
- list string
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.
e.g.products -
multiselect. Fewest ticks. 0 = none.
-
multiselect. Most ticks. 0 = no limit.
-
photo, document. How many files, 1 to 10.
-
photo. Where the photo may come from.
anycameragallery - kinds string[]
document. What may be sent: ["any"] (default), or some of pdf, image, office.
anypdfimageoffice -
info. The text shown, up to 1,000 characters.
-
-
-
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).
7 item fields
-
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.
e.g.received -
What people see, for example In review. Up to 40 characters.
e.g.Received -
open: still being worked on. done: finished well. cancelled: finished without a result. A form needs at least one open and one done stage.
opendonecancelled - color string
grey, blue, green, amber, red or purple.
greybluegreenamberredpurple - set_by string[]
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.
owneradminmanageragentviewer - require_note boolean
true: a note must come with the move to this stage.
-
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.
-
- who object
Who may submit.
3 fields
-
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.
anyonelisted - numbers string[]
Up to 500 numbers, digits only with country code (6 to 20 digits).
-
A contact tag: contacts carrying it may submit.
-
- trigger object
The message that opens the form on WhatsApp, and the words that send it.
5 fields
-
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).
e.g.["meter"] -
A bold line above the body, optional.
-
The text of the message that carries the form, 1 to 1,000 characters. Left out: Tap the button to open the form.
e.g.Tap the button to send your reading.
-
- after object
What happens right after a submission.
4 fields
-
A last screen that lists the answers before sending.
-
The WhatsApp message after sending, with placeholders ({reference}, {form}, {contact.name} ...). "" = no reply. Left out: a thank-you with the reference.
-
The reply gets an Add more button: text, photos and files the submitter sends in the next 10 minutes are attached to the submission.
-
The reply carries a button to the submitter's status page.
-
- web object
The web page of the form.
4 fields
-
The form has a web page (links.web of the form).
-
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.
offoptionalrequired -
Also ask for an e-mail address at the end.
-
Shown after sending. "" = the standard text.
-
- notify object
The e-mail the business gets.
3 fields
-
E-mail the business for each submission (to the settings' notify_email).
-
Up to 5 more addresses.
-
Attach the submission's files.
-
-
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.
-
0 = keep. Otherwise closed submissions and their files are erased this many days after closing (30 to 3650).
-
Responses
Fields
- success boolean
- request_id string
- form object
A form. GET /submit/forms lists forms without definition and fields; GET /submit/forms/{key} has both.
15 fields
- id integere.g.
7 - key string
The form's name in the API and in its web address.
e.g.meter_reading - name stringe.g.
Meter reading - enabled boolean
false: its words and links answer nothing new; its submissions stay.
- archived boolean
true: hidden from the lists, takes no submissions.
- position integer
- definition object
The working copy. One form only.
12 fields
-
The form's public name, 1 to 60 characters.
e.g.Meter reading -
Under the title on the web page and in the forms menu, up to 300 characters.
- prefix string
2 to 4 letters A-Z that start every reference of this form (MR-7Q3M2A). "" = the settings' default_prefix.
e.g.MR -
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.
5 item fields
-
The step's name: a lower case letter, then lower case letters, digits or _ (at most 40 characters). Unique among the steps.
e.g.reading -
The screen's title, 1 to 60 characters (WhatsApp shows the first 30).
e.g.Your reading - text string
Shown above the fields, up to 500 characters.
- show_if object
A rule on fields of EARLIER steps: the step is skipped when it does not hold. null = always.
e.g.{"all":[{"field":"amount","gt":5000},{"field":"category","in":["plant","vehicle…SubmitRule (not expanded) -
1 to 12 fields. Internal and hidden fields count but show nothing.
-
-
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).
7 item fields
-
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.
e.g.received -
What people see, for example In review. Up to 40 characters.
e.g.Received -
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 string
grey, blue, green, amber, red or purple.
- set_by array
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 boolean
true: a note must come with the move to this stage.
- message string
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.
-
- who object
Who may submit.
3 fields
-
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.
anyonelisted - numbers string[]
Up to 500 numbers, digits only with country code (6 to 20 digits).
-
A contact tag: contacts carrying it may submit.
-
- trigger object
The message that opens the form on WhatsApp, and the words that send it.
5 fields
-
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).
e.g.["meter"] -
A bold line above the body, optional.
-
The text of the message that carries the form, 1 to 1,000 characters. Left out: Tap the button to open the form.
e.g.Tap the button to send your reading.
-
- after object
What happens right after a submission.
4 fields
-
A last screen that lists the answers before sending.
-
The WhatsApp message after sending, with placeholders ({reference}, {form}, {contact.name} ...). "" = no reply. Left out: a thank-you with the reference.
-
The reply gets an Add more button: text, photos and files the submitter sends in the next 10 minutes are attached to the submission.
-
The reply carries a button to the submitter's status page.
-
- web object
The web page of the form.
4 fields
-
The form has a web page (links.web of the form).
-
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.
offoptionalrequired -
Also ask for an e-mail address at the end.
-
Shown after sending. "" = the standard text.
-
- notify object
The e-mail the business gets.
3 fields
-
E-mail the business for each submission (to the settings' notify_email).
-
Up to 5 more addresses.
-
Attach the submission's files.
-
-
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.
-
0 = keep. Otherwise closed submissions and their files are erased this many days after closing (30 to 3650).
-
- published object | null
The version live on WhatsApp, or null when it was never published.
2 fields
- hash stringe.g.
3f9a1c0b7d2e - published_at string (date-time)
- changed boolean
true: the working copy differs from the published version: publish to make it live on WhatsApp. false also while the form was never published (published is null then).
- flow object
The form's state on WhatsApp.
6 fields
- id string
Meta's id of the WhatsApp Flow. Empty until published.
- status string
Meta's status. Only PUBLISHED is sent to customers.
DRAFTPUBLISHEDDEPRECATEDBLOCKEDTHROTTLED - validation_errors any[]
Meta's complaints about the generated form, when there are any.
- checked_at string
When the status was last read from Meta. Empty: never.
- last_error string
Why the last publish failed. Empty when it worked.
- can_send boolean
true: the form can be sent inside WhatsApp now. false: its words and the send route answer with the web link.
- links object
How people reach the form.
- counts object
Its submissions.
- fields object[]
Every field and calculated value as a column. One form only.
8 item fields
- key string
- label string
- type string
texttextareanumberemailphonedateselectmultiselectyesnoratingconsentphotodocumentlocationinfohidden - step string
The key of its step. Empty for a calculated field.
- internal boolean
true: its value is in extra, not in answers.
- unit string
- choices object[]
select and multiselect.
- calculated boolean
true: worked out by a formula.
- created string (date-time)
- updated string (date-time)
-
After POST /submit/forms with preset only: what the preset installed, as in the setup answer (lists, connections, forms, automations, published).
- note string
Errors
- 400 The request is malformed (missing or invalid fields, query parameters or times).
- 401 Missing, invalid, revoked or expired API key.
- 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.
- 404 The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found.
- 415 The body is not JSON.
- 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.
- 500 Unexpected error on app2email's side.
- 503 app2email's connection to the WhatsApp account needs attention, or the request log is not available right now.