{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Fetching submissions","description":"Build integrations, automate workflows, and manage forms and responses programmatically with the forms.app API.","siteUrl":"https://developers.forms.app","image":"/assets/formsapp-developer-docs.6ffba4f5ff7d394698661bcdb0ed2a8452f27acaf4e82754e5d0f4109563471c.9c1bb791.png","lang":"en-US","projectTitle":"forms.app Developer Docs","llmstxt":{"sections":[{"title":"llmtxt for forms app documents","includeFiles":["**/*"],"excludeFiles":[]}],"hide":false,"excludeFiles":[]},"jsonLd":{"@context":"https://schema.org","@type":"Organization","additionalType":"https://en.wikipedia.org/wiki/Software_as_a_service","url":"https://forms.app","name":"forms.app","logo":"https://cdn.forms.app/icons/all/brands/formsapp-logo-dark.svg","description":"forms.app is a free online form builder designed for teams. forms.app offers a modern, easy-to-use form builder and allows unlimited responses and team members.","foundingDate":"2018","sameAs":"https://linkedin.com/company/formsapp","contactPoint":{"@type":"ContactPoint","contactType":"Customer service","email":"support@forms.app","url":"https://forms.app/en/contact-us"}}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"fetching-submissions","__idx":0},"children":["Fetching submissions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This tutorial shows how to retrieve submitted answers for a form using paginated requests."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":1},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/quickstart#step-1-create-an-api-key"},"children":["API key"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A form ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["_id"]}," from ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/tutorials/fetching-forms"},"children":["Fetching forms"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All examples use the base URL ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.forms.app"]}," and the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Api-Key"]}," header."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"endpoint-overview","__idx":2},"children":["Endpoint overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Submissions are returned in pages:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"GET /v1/form/{id}/answer/p/{pageNumber}\n"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Form ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["_id"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pageNumber"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Page to retrieve, starts at ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1"]},", increment by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1"]}," for each next page"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Because a form can have thousands of submissions, the API delivers results in pages rather than all at once."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"fetch-the-first-page","__idx":3},"children":["Fetch the first page"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Replace ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FORM_ID"]}," with your form's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["_id"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -s https://api.forms.app/v1/form/FORM_ID/answer/p/1 \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"response-structure","__idx":4},"children":["Response structure"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"success\": true,\n  \"data\": {\n    \"totalCount\": 142,\n    \"result\": [\n      {\n        \"answers\": [\n          {\n            \"q\": \"q1\",\n            \"t\": \"Jane Doe\"\n          }\n        ],\n        \"createDate\": \"2024-06-15T09:30:00.000Z\",\n        \"publicId\": \"abc123\"\n      }\n    ],\n    \"searchAfter\": [1718443800000]\n  },\n  \"errors\": []\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["totalCount"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Total number of submissions for this form"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["result"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Array of answer objects on this page"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["searchAfter"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cursor pointing to the last record on this page"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"walk-through-all-pages","__idx":5},"children":["Walk through all pages"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Follow this flow to collect every submission:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Request page ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Process each item in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.result"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Increment ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pageNumber"]}," and request the next page."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Stop when you have collected ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["totalCount"]}," records, or when ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["result"]}," is empty."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-loop-pseudocode","__idx":6},"children":["Example loop (pseudocode)"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"const formId = \"FORM_ID\";\nconst apiKey = process.env.FORMS_APP_API_KEY;\nlet pageNumber = 1;\nlet collected = 0;\nlet totalCount = Infinity;\n\nwhile (collected < totalCount) {\n  const response = await fetch(\n    `https://api.forms.app/v1/form/${formId}/answer/p/${pageNumber}`,\n    { headers: { \"X-Api-Key\": apiKey } }\n  );\n  const body = await response.json();\n\n  if (!body.success) {\n    throw new Error(body.errors[0]?.errorMessage ?? \"Request failed\");\n  }\n\n  totalCount = body.data.totalCount;\n  const page = body.data.result;\n\n  if (page.length === 0) break;\n\n  for (const answer of page) {\n    // Process each submission\n    console.log(answer.createDate, answer.answers);\n  }\n\n  collected += page.length;\n  pageNumber += 1;\n}\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Rate limits"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When syncing large forms, add a short delay between page requests to avoid hitting ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/the-essentials#rate-limiting"},"children":["rate limits"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"understanding-answer-objects","__idx":7},"children":["Understanding answer objects"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each item in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["result"]}," represents one submission:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["answers"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Per-question replies (see below)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["userInfo"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional respondent info (for example, full name)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["point"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Total score when the form uses calculator / quiz scoring"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["answerFiles"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Metadata for file attachments"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fileToken"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Token to download attached files"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["publicId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Public-facing submission identifier"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["createDate"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ISO 8601 timestamp of when the answer was submitted"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"answer-field-shorthand","__idx":8},"children":["Answer field shorthand"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each entry in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["answers"]}," array uses short field names:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["q"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Question ID (matches the question ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["_id"]}," from the form)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["t"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Text value"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["n"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Number value"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["d"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Date value"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["b"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Boolean value"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["c"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Choice selections (with text, value, and order)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fn"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Name fields (first, last, middle, prefix, suffix)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["a"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Address fields"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ph"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Phone fields"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["f"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Uploaded files"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ac"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Acceptance (for example, terms checkbox)"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Match ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["q"]}," values against question IDs from ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/tutorials/fetching-forms"},"children":["Fetching forms"]}," to interpret each reply."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-handling","__idx":9},"children":["Error handling"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Status"},"children":["Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Cause"},"children":["Cause"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invalid or missing API key"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Form does not exist or belongs to another account"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Rate limit exceeded, wait and retry"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"typical-integration-pattern","__idx":10},"children":["Typical integration pattern"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Fetch the form structure to map question IDs to labels."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Page through all submissions on a schedule (for example, every 15 minutes)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Track the last synced ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["createDate"]}," or page to avoid reprocessing."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Store answers in your database or forward them to another system."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"whats-next","__idx":11},"children":["What's next?"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/tutorials/fetching-forms"},"children":["Fetching forms"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis"},"children":["API reference"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/faq"},"children":["Frequently asked questions"]}]}]}]},"headings":[{"value":"Fetching submissions","id":"fetching-submissions","depth":1},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"Endpoint overview","id":"endpoint-overview","depth":2},{"value":"Fetch the first page","id":"fetch-the-first-page","depth":2},{"value":"Response structure","id":"response-structure","depth":3},{"value":"Walk through all pages","id":"walk-through-all-pages","depth":2},{"value":"Example loop (pseudocode)","id":"example-loop-pseudocode","depth":3},{"value":"Understanding answer objects","id":"understanding-answer-objects","depth":2},{"value":"Answer field shorthand","id":"answer-field-shorthand","depth":3},{"value":"Error handling","id":"error-handling","depth":2},{"value":"Typical integration pattern","id":"typical-integration-pattern","depth":2},{"value":"What's next?","id":"whats-next","depth":2}],"frontmatter":{"seo":{"title":"Fetching submissions"}},"lastModified":"2026-06-22T14:59:37.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/tutorials/fetching-submissions","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}