The submissions, filtered and paged (JSON or CSV)
https://api.app2email.com/v1/{number}/submit/submissions Scope: submissions:manage. Latest change first; deleted ones are left out. Filter by form, stage (status, or status_kind open / done / cancelled), assignee, priority, tag, channel, contact, a search text, the creation time or the parent. form, status, status_kind, assignee, priority, tag and channel take several values with commas. To keep another system in step, poll with updated_after set to the largest updated you have seen and sort=updated_asc, or use the submission.* webhook events and skip polling. Page with next_cursor (the same filter and sort). format=csv (or the header Accept: text/csv) answers the same page as CSV, one column per field when one form is given; the next cursor is then in the header X-Next-Cursor. Lists leave out files and activity: GET /submit/submissions/{id} has them. A filter value that cannot be read answers 400 invalid_submission and names it; an unknown parent answers an empty list.
Path
-
Your app2email WhatsApp number - the number the message is sent FROM. Full number with country code, digits only.
e.g.4976659348270
Query
- form string
Only this form (its key). Several: keys with commas.
e.g.meter_reading - status string
Only these stages: stage keys of the form, with commas.
e.g.received - status_kind string
Only stages of this kind: open, done or cancelled (several with commas).
e.g.open - assignee string
Only what these members hold: member ids with commas. 0 = not assigned.
e.g.12 - priority string
low, normal, high or urgent; several with commas.
e.g.high,urgent - tag string
Only submissions with one of these tags (commas).
e.g.north - channel string
whatsapp, web, api or staff; several with commas.
e.g.whatsapp - contact string
Only this person's (number with country code, or business-scoped user id).
e.g.61412345678 - q string
The reference, a name or an answer contains this text.
e.g.A-1182 - created_from string
Created on or after this day (YYYY-MM-DD) or ISO 8601 time.
e.g.2026-11-01 - created_to string
Created up to and including this day (YYYY-MM-DD), or before this ISO 8601 time.
e.g.2026-11-30 - updated_after string (date-time)
Changed after this ISO 8601 time: for syncing.
e.g.2026-11-13T04:00:00Z - parent string
Only the follow-ups of this submission (id or reference).
e.g.QR-4HT9XC -
updated (default), created, due or priority; add _asc for the opposite order.
updatedcreatedduepriorityupdated_asccreated_ascdue_ascpriority_asc - format string
csv: a text/csv answer.
jsoncsv -
How many (1 to 200, default 50).
- cursor string
The next_cursor of the previous answer, unchanged. Leave out for the first page.
Responses
- X-Next-Cursor string
CSV only: the cursor of the next page. Left out on the last page.
Fields
- success boolean
- request_id string
- submissions object[]
34 item 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.
- source string
flow: the WhatsApp form. chat: sent in the chat afterwards.
- 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
- events object[]
The activity list, oldest first. One submission only.
- fields object[]
The form's fields, to label answers and extra. One submission only.
- 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.
- 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.
-
- actions object[]
The manual automations of its form: POST /submit/submissions/{id}/run with the id. One submission only.
- next_cursor string
Pass it as cursor for the next page, with the same filter and sort. Left out on the last page.
- count integer
How many are in this page.
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.