Fetching forms

This tutorial shows how to list the forms in your account and retrieve the complete structure of a single form.

Prerequisites

An API key
A tool to send HTTP requests (curl, Postman, or your preferred HTTP client)

All examples use the base URL https://api.forms.app and the X-Api-Key header.

List all forms

Call GET /v1/form to get every form in your account:

curl -s https://api.forms.app/v1/form \
  -H "X-Api-Key: YOUR_API_KEY"

Response

{
  "success": true,
  "data": [
    {
      "_id": "64f1a2b3c4d5e6f7a8b9c0d1",
      "title": "Customer feedback"
    },
    {
      "_id": "64f1a2b3c4d5e6f7a8b9c0d2",
      "title": "Event registration"
    }
  ],
  "errors": []
}

Each item contains:

Field	Description
`_id`	Unique form identifier (use this in other endpoints)
`title`	Display name of the form

The list includes forms of any visibility state (public, unlisted, or private) that belong to your account and are not trashed or archived.

Get a form by ID

Use the _id from the list to fetch the full form structure:

curl -s https://api.forms.app/v1/form/64f1a2b3c4d5e6f7a8b9c0d1 \
  -H "X-Api-Key: YOUR_API_KEY"

What the response includes

A single form object with everything needed to understand or reproduce the form:

Section	Description
`questions`	Ordered list of questions with type, label, settings, and choices
`baseSettings`	Behaviour: captcha, drafts, multi-step navigation, duplicate prevention
`designSettings`	Visual theme: colours, fonts, border radius, background image
`logo`	Logo image URL, alignment, and display options
`thankYouPages`	Post-submission screens, redirects, and sharing options
`submitButton`	Submit button label and alignment
`state`	Visibility: `public`, `unlisted`, or `private`
`supportedLanguages`	Language codes the form supports
`calculators` / `conditions`	Scoring rules and conditional logic
`createDate` / `updateDate`	ISO 8601 timestamps

Example: reading questions

Each question in the questions array includes a questionType (for example, ShortText, MultipleSelection, Email) along with type-specific settings. Use the _id on each question when matching answers in Fetching submissions.

{
  "success": true,
  "data": {
    "_id": "64f1a2b3c4d5e6f7a8b9c0d1",
    "title": "Customer feedback",
    "state": "public",
    "questions": [
      {
        "_id": "q1",
        "questionType": "ShortText",
        "label": "What is your name?",
        "required": true
      }
    ]
  },
  "errors": []
}

The actual response contains the full question object with all settings for each type.

Error handling

Status	Cause
`401`	Invalid or missing API key
`404`	Form does not exist or belongs to another account
`429`	Rate limit exceeded, wait and retry

When the API returns an error, success is false and details appear in the errors array. See The essentials.

Typical integration pattern

Call GET /v1/form periodically to discover forms and their IDs.
Call GET /v1/form/{id} for each form you need to sync.
Store the form structure in your system.
Use the question IDs when processing submissions in Fetching submissions.