{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Fetching forms","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":[]}]},"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-forms","__idx":0},"children":["Fetching forms"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This tutorial shows how to list the forms in your account and retrieve the complete structure of a single form."]},{"$$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 tool to send HTTP requests (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["curl"]},", Postman, or your preferred HTTP client)"]}]},{"$$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":"list-all-forms","__idx":2},"children":["List all forms"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/form"]}," to get every form in your account:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -s https://api.forms.app/v1/form \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"response","__idx":3},"children":["Response"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"success\": true,\n  \"data\": [\n    {\n      \"_id\": \"64f1a2b3c4d5e6f7a8b9c0d1\",\n      \"title\": \"Customer feedback\"\n    },\n    {\n      \"_id\": \"64f1a2b3c4d5e6f7a8b9c0d2\",\n      \"title\": \"Event registration\"\n    }\n  ],\n  \"errors\": []\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each item contains:"]},{"$$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":["_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unique form identifier (use this in other endpoints)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["title"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Display name of the form"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The list includes forms of any visibility state (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["public"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unlisted"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["private"]},") that belong to your account and are not trashed or archived."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"get-a-form-by-id","__idx":4},"children":["Get a form by ID"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["_id"]}," from the list to fetch the full form structure:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -s https://api.forms.app/v1/form/64f1a2b3c4d5e6f7a8b9c0d1 \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"what-the-response-includes","__idx":5},"children":["What the response includes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A single form object with everything needed to understand or reproduce the form:"]},{"$$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":"Section"},"children":["Section"]},{"$$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":["questions"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ordered list of questions with type, label, settings, and choices"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["baseSettings"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Behaviour: captcha, drafts, multi-step navigation, duplicate prevention"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["designSettings"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Visual theme: colours, fonts, border radius, background image"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["logo"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Logo image URL, alignment, and display options"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["thankYouPages"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Post-submission screens, redirects, and sharing options"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["submitButton"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Submit button label and alignment"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["state"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Visibility: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["public"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unlisted"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["private"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["supportedLanguages"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Language codes the form supports"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["calculators"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["conditions"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Scoring rules and conditional logic"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["createDate"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["updateDate"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ISO 8601 timestamps"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-reading-questions","__idx":6},"children":["Example: reading questions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each question in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["questions"]}," array includes a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["questionType"]}," (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ShortText"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MultipleSelection"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Email"]},") along with type-specific settings. Use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["_id"]}," on each question when matching answers in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/tutorials/fetching-submissions"},"children":["Fetching submissions"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"success\": true,\n  \"data\": {\n    \"_id\": \"64f1a2b3c4d5e6f7a8b9c0d1\",\n    \"title\": \"Customer feedback\",\n    \"state\": \"public\",\n    \"questions\": [\n      {\n        \"_id\": \"q1\",\n        \"questionType\": \"ShortText\",\n        \"label\": \"What is your name?\",\n        \"required\": true\n      }\n    ]\n  },\n  \"errors\": []\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The actual response contains the full question object with all settings for each type."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-handling","__idx":7},"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":"p","attributes":{},"children":["When the API returns an error, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["success"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]}," and details appear in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors"]}," array. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/the-essentials#response-envelope"},"children":["The essentials"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"typical-integration-pattern","__idx":8},"children":["Typical integration pattern"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/form"]}," periodically to discover forms and their IDs."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/form/{id}"]}," for each form you need to sync."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Store the form structure in your system."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use the question IDs when processing submissions in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/tutorials/fetching-submissions"},"children":["Fetching submissions"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"whats-next","__idx":9},"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-submissions"},"children":["Fetching submissions"]}]},{"$$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 forms","id":"fetching-forms","depth":1},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"List all forms","id":"list-all-forms","depth":2},{"value":"Response","id":"response","depth":3},{"value":"Get a form by ID","id":"get-a-form-by-id","depth":2},{"value":"What the response includes","id":"what-the-response-includes","depth":3},{"value":"Example: reading questions","id":"example-reading-questions","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 forms"}},"lastModified":"2026-06-22T14:59:37.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/tutorials/fetching-forms","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}