One submission with files, activity and what can be done

GET https://api.app2email.com/v1/{number}/submit/submissions/{id}
scope: submissions:manage sandbox: reads MCP: get_submission

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

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

    The submission's id, or its reference (MR-7Q3M2A).

    e.g. MR-7Q3M2A

Responses

200 The submission.
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 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.

        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.

        3 fields
      • text string
      • data object any keys

        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
      • key string required pattern ^[a-z][a-z0-9_]{0,39}$

        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.

        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.

      • message string max 1000 chars

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