{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"The essentials","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":"the-essentials","__idx":0},"children":["The essentials"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This page covers the core concepts you need before building an integration: authentication, response format, and rate limits."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"base-url","__idx":1},"children":["Base URL"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All API requests use this base URL:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"https://api.forms.app\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"authentication","__idx":2},"children":["Authentication"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every request must be authenticated with ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["exactly one"]}," of the two methods below. Sending both in the same request returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401 Unauthorized"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"option-1-api-key","__idx":3},"children":["Option 1: API key"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Pass your API key in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Api-Key"]}," header:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"X-Api-Key: <your_api_key>\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is the simplest option for server-to-server integrations. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/quickstart"},"children":["Quick start"]}," for how to create a key."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"option-2-oauth-20-bearer-token","__idx":4},"children":["Option 2: OAuth 2.0 bearer token"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Obtain a JWT through the forms.app OAuth 2.0 flow and pass it in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]}," header:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"Authorization: Bearer <your_token>\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use OAuth when your integration acts on behalf of a user through a third-party app."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Use one method per request"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Never send both ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Api-Key"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization: Bearer"]}," in the same request. The API rejects the call with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401 Unauthorized"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"response-envelope","__idx":5},"children":["Response envelope"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All endpoints return a consistent JSON envelope."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"success--2xx-","__idx":6},"children":["Success (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2xx"]},")"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"success\": true,\n  \"data\": { },\n  \"errors\": []\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," field holds the endpoint payload, an array, object, or paginated result depending on the route."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"error--4xx--5xx-","__idx":7},"children":["Error (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["4xx"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["5xx"]},")"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"success\": false,\n  \"data\": null,\n  \"errors\": [\n    {\n      \"errorCode\": 1001,\n      \"errorMessage\": \"Unauthorized\"\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each entry in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors"]}," includes:"]},{"$$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":["errorCode"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Machine-readable code identifying the failure"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errorMessage"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Human-readable description"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Always check ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["success"]}," before reading ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]},". When ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["success"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]},", inspect ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors"]}," for details."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"common-http-status-codes","__idx":8},"children":["Common HTTP status codes"]},{"$$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":"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":["200"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Request succeeded"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Bad request, check your parameters"]}]},{"$$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":["Unauthorized, missing or invalid credentials, or both auth methods supplied"]}]},{"$$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":["Not found, the 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":["Too many requests, rate limit exceeded"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["500"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Internal server error"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"rate-limiting","__idx":9},"children":["Rate limiting"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Requests are rate-limited per API key or token. When you exceed the limit, the API returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429 Too Many Requests"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you receive a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]},":"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Wait briefly before retrying."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Avoid tight retry loops, space out requests or use exponential backoff."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Cache form structure when possible instead of re-fetching on every sync."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"read-only-access","__idx":10},"children":["Read-only access"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The API provides read-only access to your forms and submissions. You can:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["List forms in your account"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Fetch a form's full structure (questions, design, settings)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Page through submitted answers"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You cannot create, update, or delete forms or submissions through the API."]},{"$$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"]},": list forms and retrieve full structure"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/tutorials/fetching-submissions"},"children":["Fetching submissions"]},": page through answers"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/faq"},"children":["Frequently asked questions"]},": common integration questions"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis"},"children":["API reference"]},": full endpoint and schema documentation"]}]}]},"headings":[{"value":"The essentials","id":"the-essentials","depth":1},{"value":"Base URL","id":"base-url","depth":2},{"value":"Authentication","id":"authentication","depth":2},{"value":"Option 1: API key","id":"option-1-api-key","depth":3},{"value":"Option 2: OAuth 2.0 bearer token","id":"option-2-oauth-20-bearer-token","depth":3},{"value":"Response envelope","id":"response-envelope","depth":2},{"value":"Success ( 2xx )","id":"success--2xx-","depth":3},{"value":"Error ( 4xx / 5xx )","id":"error--4xx--5xx-","depth":3},{"value":"Common HTTP status codes","id":"common-http-status-codes","depth":2},{"value":"Rate limiting","id":"rate-limiting","depth":2},{"value":"Read-only access","id":"read-only-access","depth":2},{"value":"What's next?","id":"whats-next","depth":2}],"frontmatter":{"seo":{"title":"The essentials"}},"lastModified":"2026-06-22T14:59:37.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/the-essentials","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}