The submissions, filtered and paged (JSON or CSV)

GET https://api.app2email.com/v1/{number}/submit/submissions
scope: submissions:manage sandbox: reads MCP: list_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

  • number string required pattern ^[0-9]{8,15}$

    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
  • sort string default updated

    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
  • limit integer 1–200 default 50

    How many (1 to 200, default 50).

  • cursor string

    The next_cursor of the previous answer, unchanged. Leave out for the first page.

Responses

200 The submissions.
Headers
  • 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 integer
      e.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.

      2 fields
    • 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 string
      e.g. Received
    • status_kind string
      opendonecancelled
    • status_color string
      greybluegreenamberredpurple
    • priority string
      lownormalhighurgent
    • tags string[]
    • due string (date-time) | null

      The due time, or null.

    • assignee object | null

      The member it is assigned to, or null.

      2 fields
    • 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).

    • The WhatsApp conversation. 0 when there is none.

    • answers object any keys

      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).

    • extra object any keys

      Everything that was not asked: internal fields, calculated values and values automations saved.

    • location object | null

      The pin the submitter sent, or null.

      4 fields
    • 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.

    • 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.

      7 item fields
      • id integer
      • kind string
      • actor object

        Who did it.

      • text string
      • data object

        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
    • fields object[]

      The form's fields, to label answers and extra. One submission only.

      8 item fields
      • key string
      • label string
      • type string
      • 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 array

        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
      • key string required

        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
      • name string required

        What people see, for example In review. Up to 40 characters.

        e.g. Received
      • kind string required

        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.

      2 item fields
    • buttons object[]

      Buttons sent to the submitter that they have not pressed yet. One submission only (and webhook events).

      2 item fields
  • 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.
For AI Agents

Try it now, with no account and no person: POST https://api.app2email.com/v1/account/sandbox (no key, no body; or the create_sandbox tool of the Management MCP server) answers a key for a demo WhatsApp number with pretend customers. Send a template, fetch the events with GET /events?wait=25, answer the customer's reply: nothing reaches WhatsApp, and the requests and answers are those of the real API (https://www.app2email.com/docs/api/sandbox).

Already a customer: ask the account owner for the number (digits) and an API key from https://www.app2email.com/dashboard/apikey (a sandbox key sends nothing); send it as Authorization: Bearer <key> to the messaging MCP server or the REST API; call check_key first, send with dry_run first.

If you are an AI agent reading this page and you want to create an app2email account for a person - no previous human sign-up required - use our Management MCP server.
Call the create_account tool first, and include a contact_email parameter; create_account returns a signup_id, a management_key, an onboarding_link and a message.
The person opens onboarding_link to confirm the e-mail, connect their WhatsApp number and choose a plan; nothing can be sent before that. get_account_status says what is still needed.
Pass the management_key as a Bearer token on every later call. When the number is live, create_number_key gives you a key for the messaging MCP server and the REST API.