Change a submission: stage, assignee, tags, answers
https://api.app2email.com/v1/{number}/submit/submissions/{id} Scope: submissions:manage. Not with a sandbox key. Any of: status (a stage key; with note when the stage has require_note, else 409 stage_not_allowed), priority, assignee (a member id; 0 or null = nobody), due (null takes it off), tags / tags_add / tags_remove, answers and extra (only the keys given change, null removes one; calculated values are worked out again) and location. A note without status is written as an internal note. 400 nothing_to_change when the body names none of them; changed false when the submission already had these values. Each change is written to the activity list under the key's name. Moving to a stage sends that stage's message to the submitter, when it has one. Events: submission.status_changed, submission.assigned, submission.updated, submission.note_added, one per kind of change; the form's automations run on them.
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
Body application/json required
- status string
A stage key of the submission's form.
e.g.checked -
With status: the note of the change (needed when the stage has require_note; a stage's message can show it to the submitter as {note}). Alone: written as an internal note.
- priority string
lownormalhighurgent - assignee integer | null
A member's id (GET /submit/members). 0 or null = nobody.
e.g.12 - due string (date-time) | null
ISO 8601. null or an empty text takes the due time off.
-
Answers to change: only the keys given are changed; null removes a value. Checked like a customer's answers.
-
Internal fields and other values to change: only the keys given are changed; null removes a value.
- location object
Where it is: a pin and / or an address. lat and lng come together.
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.
- 409 Idempotency-Key: the first request with this key is still running, or did not finish. Or a conflict: the template name exists, the webhook URL is used by another webhook, the broadcast cannot be cancelled, the booking slot is taken or the booking is already cancelled, or the Flow is not published.
- 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.