{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Frequently asked questions","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":"frequently-asked-questions","__idx":0},"children":["Frequently asked questions"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"general","__idx":1},"children":["General"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"what-is-the-api-base-url","__idx":2},"children":["What is the API base URL?"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"https://api.forms.app\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"which-forms-are-returned-when-i-list-my-account","__idx":3},"children":["Which forms are returned when I list my account?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The list includes all forms that belong to your authenticated account, regardless of visibility (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["public"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unlisted"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["private"]},"), as long as they are not in the trash or archived."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"authentication","__idx":4},"children":["Authentication"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"should-i-use-an-api-key-or-oauth","__idx":5},"children":["Should I use an API key or OAuth?"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["API key"]},": best for server-side scripts, cron jobs, and backend integrations you control."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["OAuth bearer token"]},": best when a third-party app needs access on behalf of a user."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For most getting-started scenarios, an API key is enough."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"can-i-use-both-an-api-key-and-a-bearer-token-in-one-request","__idx":6},"children":["Can I use both an API key and a bearer token in one request?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["No. The API requires exactly one authentication method per request. Sending both returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401 Unauthorized"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"i-lost-my-api-key-can-i-retrieve-it","__idx":7},"children":["I lost my API key. Can I retrieve it?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["No. Keys are shown only once at creation. Revoke the old key in ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Account Settings → API Keys"]}," and create a new one."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"how-many-api-keys-can-i-create","__idx":8},"children":["How many API keys can I create?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can create multiple keys (for example, one per environment or integration) and revoke any of them individually."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"responses-and-errors","__idx":9},"children":["Responses and errors"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"what-does-the-response-envelope-look-like","__idx":10},"children":["What does the response envelope look like?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every response wraps the payload in a consistent structure. On success, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["success"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}," and the payload is in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]},". On failure, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["success"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]},", and details are in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors"]},". See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/the-essentials#response-envelope"},"children":["The essentials"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"how-do-i-handle-errors-in-code","__idx":11},"children":["How do I handle errors in code?"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check the HTTP status code."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Parse the JSON body."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["success"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]},", read the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors"]}," array for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errorCode"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errorMessage"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"why-am-i-getting-404-not-found-for-a-form","__idx":12},"children":["Why am I getting ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404 Not Found"]}," for a form?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The form may not exist, or it may belong to a different account. Confirm you are using the correct ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["_id"]}," from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/form"]}," and the same credentials that own the form."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"submissions","__idx":13},"children":["Submissions"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"how-does-pagination-work-for-submissions","__idx":14},"children":["How does pagination work for submissions?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Answers are returned in pages. Start with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pageNumber: 1"]},", then increment for each subsequent page. Compare the number of records you have collected against ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["totalCount"]}," in the response to know when you are done. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/tutorials/fetching-submissions"},"children":["Fetching submissions"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"what-is-searchafter-in-the-answer-response","__idx":15},"children":["What is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["searchAfter"]}," in the answer response?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each page includes a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["searchAfter"]}," cursor pointing to the last record on that page. For most integrations, incrementing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pageNumber"]}," is enough. The cursor is available for advanced cursor-based navigation."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"rate-limits","__idx":16},"children":["Rate limits"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"what-happens-when-i-hit-the-rate-limit","__idx":17},"children":["What happens when I hit the rate limit?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The API returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429 Too Many Requests"]},". Wait briefly and retry. Avoid hammering the endpoint in a tight loop."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"is-there-a-health-check-endpoint","__idx":18},"children":["Is there a health check endpoint?"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Yes. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /__health"]}," returns the gateway status and does not require authentication. Use it for uptime monitoring."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"getting-help","__idx":19},"children":["Getting help"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/quickstart"},"children":["Quick start"]},": create a key and make your first call"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/apis"},"children":["API reference"]},": endpoints, schemas, and examples"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://forms.app/en/help-center"},"children":["forms.app support"]},": account and product questions"]}]}]},"headings":[{"value":"Frequently asked questions","id":"frequently-asked-questions","depth":1},{"value":"General","id":"general","depth":2},{"value":"What is the API base URL?","id":"what-is-the-api-base-url","depth":3},{"value":"Which forms are returned when I list my account?","id":"which-forms-are-returned-when-i-list-my-account","depth":3},{"value":"Authentication","id":"authentication","depth":2},{"value":"Should I use an API key or OAuth?","id":"should-i-use-an-api-key-or-oauth","depth":3},{"value":"Can I use both an API key and a bearer token in one request?","id":"can-i-use-both-an-api-key-and-a-bearer-token-in-one-request","depth":3},{"value":"I lost my API key. Can I retrieve it?","id":"i-lost-my-api-key-can-i-retrieve-it","depth":3},{"value":"How many API keys can I create?","id":"how-many-api-keys-can-i-create","depth":3},{"value":"Responses and errors","id":"responses-and-errors","depth":2},{"value":"What does the response envelope look like?","id":"what-does-the-response-envelope-look-like","depth":3},{"value":"How do I handle errors in code?","id":"how-do-i-handle-errors-in-code","depth":3},{"value":"Why am I getting 404 Not Found for a form?","id":"why-am-i-getting-404-not-found-for-a-form","depth":3},{"value":"Submissions","id":"submissions","depth":2},{"value":"How does pagination work for submissions?","id":"how-does-pagination-work-for-submissions","depth":3},{"value":"What is searchAfter in the answer response?","id":"what-is-searchafter-in-the-answer-response","depth":3},{"value":"Rate limits","id":"rate-limits","depth":2},{"value":"What happens when I hit the rate limit?","id":"what-happens-when-i-hit-the-rate-limit","depth":3},{"value":"Is there a health check endpoint?","id":"is-there-a-health-check-endpoint","depth":3},{"value":"Getting help","id":"getting-help","depth":2}],"frontmatter":{"seo":{"title":"Frequently asked questions"}},"lastModified":"2026-06-22T14:59:37.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/faq","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}