One submission with files, activity and what can be done
https://api.app2email.com/v1/{number}/submit/submissions/{id} Scope: submissions:manage. By id or by reference. Everything about it: the answers and extra, files (each url fetches the bytes without a key for 7 days), events (the activity list: who did what, every note, reply and automation step), fields (how to label each answer), stages (where it can move, with require_note), actions (the manual automations to run with POST /submit/submissions/{id}/run) and buttons (sent to the submitter, not pressed yet). A deleted submission answers 404.
Path
-
Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only.
e.g.4976659348270 -
The submission's id, or its reference (MR-7Q3M2A).
e.g.MR-7Q3M2A
Responses
Fields
- success boolean
- request_id string
- submission object
What a person sent with a form, and everything that happened to it since. Lists carry the object up to closed; one submission (GET /submit/submissions/{id}) adds files, events, fields, stages, actions and buttons. The data of every submission.* webhook event is this object without events, fields, stages and actions.
34 fields
- id integere.g.
4182 - reference string
The short code the submitter sees: the form's prefix and 6 characters. Every route that takes a submission id takes it too.
e.g.MR-7Q3M2A - form object
The form it was made with.
- channel string
whatsapp: the WhatsApp form. web: the web page. api: POST /submit/submissions. staff: entered by a team member.
whatsappwebapistaff - status string
The key of the stage it is in (the form's stages).
e.g.received - status_name stringe.g.
Received - status_kind string
opendonecancelled - status_color string
greybluegreenamberredpurple - priority string
lownormalhighurgent - due string (date-time) | null
The due time, or null.
- assignee object | null
The member it is assigned to, or null.
- contact object
5 fields
- identity string
The submitter's WhatsApp number (digits, country code first) or business-scoped user id. Empty for a web submission with only an e-mail address.
e.g.61412345678 - name string
- phone string
- email string
- verified boolean
true: the number is proven (sent on WhatsApp, or confirmed from the web page with one message).
- conversation_id integer
The WhatsApp conversation. 0 when there is none.
-
What was asked: field key -> value. The value's JSON type follows the field type (text: string, number and rating: number, yesno and consent: boolean, multiselect: array of choice ids, photo and document: array of file ids, date: YYYY-MM-DD, location: the address text).
-
Everything that was not asked: internal fields, calculated values and values automations saved.
- location object | null
The pin the submitter sent, or null.
- parent string | null
The reference of the submission this one adds to (a follow-up form), or null.
- summary string
One line for lists: the first answers.
- files_count integer
- files_pending integer
Files of the WhatsApp form that are still being fetched. 0 = all stored.
- unread boolean
New, or the submitter added something staff have not opened yet.
- link string
The submitter's own page: status, history, add information. No login; treat it as a secret of the submitter.
- created string (date-time)
- updated string (date-time)
- status_changed string (date-time)
- closed string (date-time) | null
When it reached a done or cancelled stage, or null.
- deleted string (date-time)
Only on a deleted submission: when it was deleted.
- files object[]
One submission only (and webhook events).
9 item fields
- id integer
What a photo or document answer holds.
e.g.9917 - field string
The field it belongs to. Empty: added afterwards.
- name string
- mime string
- size integer
Bytes.
- state string
pending: still being fetched from WhatsApp. failed: could not be fetched.
pendingstoredfailed - source string
flow: the WhatsApp form. chat: sent in the chat afterwards.
flowwebchatstaffapi - url string
Fetches the file's bytes without a key. Valid for 7 days from this answer; read the submission again for a fresh one. Empty until the file is stored.
- created string (date-time)
- events object[]
The activity list, oldest first. One submission only.
7 item fields
- id integer
- kind string
creatededitedstatusassignedprioritytagsduenotereply_outreply_infilelocationbuttonautomationfollowupvieweddeletedrestorederror - actor object
Who did it.
- text string
-
Details by kind, for example {from, to} of a stage change or {state: sent | held | email | failed} of a reply.
- public boolean
true: the submitter sees it on their status page.
- created string (date-time)
- fields object[]
The form's fields, to label answers and extra. One submission 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.
- stages object[]
The stages it can move to. One submission only.
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.
- 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.
-
- actions object[]
The manual automations of its form: POST /submit/submissions/{id}/run with the id. One submission only.
- changed boolean
PATCH only. false: the submission already had these values.
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.
- 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.