Skip to content
API docs
Sign inOpen app

Responses

List responses

GET/v1/submissions

List the workspace's responses, newest first, or only one form's or brand's. Filter them by state, ending, time and text. A key limited to some brands only gets those brands' responses. See Pagination, Response states, Brand access and Plan history and retention.

Query parameters

  • workspaceIdstring

    Optional. Your API key already belongs to one workspace.

  • formIdstring

    Only this form's responses. Every sort except createdAt needs it, and so does endingId.

  • brandIdstring

    Only this brand's responses.

  • statusenum

    complete for responses where the person finished the form, partial for the rest. Use state to tell people still filling it in from people who left.

    One of "partial", "complete"

  • stateenum

    started for people still filling in the form, left for people who left without finishing, finished for people who finished. See Response states.

    One of "started", "left", "finished"

  • endingIdstring

    Only finished responses that reached this ending. Use an ending id of the form, and pass formId too.

    1–64 chars

  • consentenum

    Only responses with this consent. agreed for people who agreed to be called and texted, not_agreed for people the form asked who haven't agreed, not_asked for forms with no consent field. See Consent.

    One of "agreed", "not_agreed", "not_asked"

  • fromnumber

    Only responses created at or after this time, in milliseconds since the epoch.

  • tonumber

    Only responses created before this time, in milliseconds since the epoch.

  • searchstring

    Words to find in the contact details or in any answer. It looks at the name, email and phone, the answers, the labels of picked options and file names. Every word must match, and case and accents don't matter. Digits also match phone numbers written in any format. With a search, each page checks limit responses and returns the ones that match. A page can be short or even empty while nextCursor is not null, so keep paging until it is null.

    max 200 chars

  • sortenum

    How to order the responses. createdAt is the default and sorts by when they were created. status puts left responses first, then started, then finished, and asc reverses that. ending sorts by the ending's name, with unfinished responses at one end. contact sorts by the person's name, or their email or phone when there's no name. Ties go by creation time. Every sort except createdAt needs formId.

    One of "createdAt", "status", "ending", "contact"

  • orderenum

    desc is the default. With the default sort, desc lists the newest responses first.

    One of "desc", "asc"

  • cursorstring

    The nextCursor from the previous page. Leave it out for the first page, and keep the same filters and sort on every page. See Pagination.

  • limitinteger

    How many responses a page holds, from 1 to 200. The default is 50. With a search, it's how many responses each page checks.

    1–200

Response

  • itemsarray of objectrequired

    The responses on this page, in the order you asked for.

    Show 30 fields
    • idstringrequired

      The response's id.

    • formIdstringrequired

      The form the person answered.

    • brandIdstringrequired

      The form's brand.

    • versionnumberrequired

      The number of the published version the person answered.

    • sessionIdstringrequired

      The visitor's session on the page.

    • statusenumrequired

      complete once the person finishes the form, otherwise partial. For a partial response, leftAt tells you whether the person is still filling it in or left. See Response states.

      One of "partial", "complete"

    • endingone of 2required

      The ending the person reached. Null until they finish.

      Show 2 options

      • Option 1

        • idstringrequired

          The ending's id in the form. Pass it as endingId to filter GET /v1/submissions.

        • namestringrequired

          The ending's name at the time the response reached it, such as "Order placed".

        • countsAsLeadbooleanrequired

          Whether reaching this ending counts as a lead for ad tracking. Reaching an ending that doesn't count means the person was disqualified.

      • null

    • answersobjectrequired

      The answers by field id, as stored. Choices are their option values, not labels. A money answer is a plain number in its currency's major unit, and currencies names the currency. A file_upload answer is a list of files, each with fileId, name, size, type and apiUrl. Call the apiUrl with your API key to get a download link.

    • currenciesobjectrequired

      The currency of each money answer by field id, as an ISO 4217 code, such as { "tip": "USD" }. It is the currency the form used when the person answered. The answer itself is a plain number in that currency's major unit.

    • contactobjectrequired

      The contact details the form's contact questions collected.

      Show 6 fields
      • emailstring
      • phonestring
      • telegramstring

        The Telegram username, without the "@".

      • firstNamestring
      • lastNamestring
      • addressobject
        Show 6 fields
        • line1stringrequired
        • citystringrequired
        • statestringrequired

          The region, such as a state, province or county.

        • zipstringrequired

          The postal code.

        • line2string
        • countrystring

          The country as an ISO 3166-1 alpha-2 code. Missing on responses saved before addresses had a country.

    • attributionanyrequired

      Where the visitor came from. It holds the UTM parameters, landing page, referrer and ad click IDs.

    • leadidTokenstring or nullrequired

      The Jornaya LeadiD token, or null.

    • trustedFormCertUrlstring or nullrequired

      The TrustedForm certificate URL, which starts with https://cert.trustedform.com/. It is set when the brand has TrustedForm on, or the page runs it, and its script had loaded. Null otherwise.

    • trustedFormPingUrlstring or nullrequired

      The TrustedForm ping URL. It is set under the same conditions as trustedFormCertUrl, and null otherwise.

    • eventIdstringrequired

      The Meta event id sent with the lead. Meta uses it to match the browser and server events for the same lead.

    • phoneVerifiedbooleanrequired

      Whether the phone was verified with a code.

    • emailCheckenum or nullrequired

      The result of checking email fields marked validate. valid means the address exists and invalid means it doesn't. disposable is a throwaway address. catchall means the domain accepts any address. unknown means its mail server didn't answer. skipped means it wasn't checked, because the workspace was out of credits or the check was unavailable. With several emails, you get the least sure result. A check never turns a lead away. Null when the response has no checked email or is unfinished.

    • telegramCheckenum or nullrequired

      The result of checking Telegram fields marked check. found is a personal account. not_found means Telegram didn't find it, which doesn't prove it doesn't exist. channel, group and bot say what the username belongs to. skipped means it wasn't checked, because the workspace was out of credits or Telegram didn't answer. With several usernames, you get the least sure result. Null when the response has no checked username or is unfinished.

    • ipstring or nullrequired

      The visitor's IP address, or null.

    • userAgentstring or nullrequired

      The visitor's browser user agent, or null.

    • createdAtnumberrequired

      Created, in milliseconds since the epoch.

    • completedAtnumber or nullrequired

      When the person finished, in milliseconds since the epoch. Null until then.

    • leftAtnumber or nullrequired

      When the person left without finishing, in milliseconds since the epoch. A person has left when they close the page or do nothing for 5 minutes. Null while they're still filling it in, and once the response is complete. See Response states.

    • earlierSubmissionIdstring or nullrequired

      An earlier unfinished response on this form from the same email or phone, within the last 30 days. Null when there is none. It's only a link, and neither response is changed.

    • updatedAtnumberrequired

      The last time the person's answers were saved, in milliseconds since the epoch.

    • readableAnswersobjectrequired

      Each answer as the person saw it, by field id, from the version of the form they answered. For example { "crust": { "question": "Which crust?", "type": "single_choice", "answer": "Thin crust" } }. Choices show their option labels rather than values, with several joined by ", ". Yes/no answers read "Yes" or "No". Names and addresses are one line, and files are their names.

    • consentenumrequired

      Whether the person agreed to be called and texted. agreed means they agreed to every consent they got to. not_agreed means the form asks for consent and they haven't given it: they left before submitting that step, changed the number since, or left a box unticked. not_asked means the form asks for none. It says nothing about the phone being verified: that's phoneVerified. See Consent.

      One of "agreed", "not_agreed", "not_asked"

    • consentAtnumber or nullrequired

      When the person agreed, in milliseconds since the epoch. With several consent fields, it's the last one they agreed to. Null unless consent is agreed.

    • consentTextstring or nullrequired

      The wording the person agreed to, exactly as shown. With several consent fields, each one in form order with a blank line between. Null unless consent is agreed.

    • consentsarray of objectrequired

      Each consent the person agreed to. A phone consent counts only for the number still answered, and a box they unticked again is left out.

      Show 5 fields
      • fieldIdstringrequired

        The field that asked: a phone question with consent, or a consent question.

      • atnumberrequired

        When the person agreed, in milliseconds since the epoch.

      • textstringrequired

        The wording, exactly as shown.

      • byenumrequired

        How they agreed. checkbox means they ticked the box. submit means they submitted its step with Continue, Submit or Enter.

        One of "checkbox", "submit"

      • phonestring or nullrequired

        The number the consent covers, in E.164 format. For a phone question, the number they agreed for. For a consent question, the response's phone at that moment, or null.

  • nextCursorstring or nullrequired

    Send it as cursor to get the next page, with the same filters and sort. It is null on the last page.

  • olderHiddenbooleanrequired

    True on an empty first page when the form, brand or workspace has responses older than the plan shows. The plan's history is retentionDays in GET /v1/workspaces/{workspaceId}/entitlements. Older responses are kept, and they come back on a plan that shows them. See Plan history and retention.

Errors answer with a status and the error shape.