# 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](/guides/quickstart#step-1-create-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:

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

### Response

```json
{
  "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:

```bash
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](/guides/tutorials/fetching-submissions).

```json
{
  "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](/guides/the-essentials#response-envelope).

## Typical integration pattern

1. Call `GET /v1/form` periodically to discover forms and their IDs.
2. Call `GET /v1/form/{id}` for each form you need to sync.
3. Store the form structure in your system.
4. Use the question IDs when processing submissions in [Fetching submissions](/guides/tutorials/fetching-submissions).


## What's next?

- [Fetching submissions](/guides/tutorials/fetching-submissions)
- [API reference](/apis)
- [Frequently asked questions](/guides/faq)