The essentials

This page covers the core concepts you need before building an integration: authentication, response format, and rate limits.

All API requests use this base URL:

https://api.forms.app

Every request must be authenticated with exactly one of the two methods below. Sending both in the same request returns 401 Unauthorized.

Pass your API key in the X-Api-Key header:

X-Api-Key: <your_api_key>

This is the simplest option for server-to-server integrations. See Quick start for how to create a key.

Obtain a JWT through the forms.app OAuth 2.0 flow and pass it in the Authorization header:

Authorization: Bearer <your_token>

Use OAuth when your integration acts on behalf of a user through a third-party app.

All endpoints return a consistent JSON envelope.

{
  "success": true,
  "data": { },
  "errors": []
}

The data field holds the endpoint payload, an array, object, or paginated result depending on the route.

{
  "success": false,
  "data": null,
  "errors": [
    {
      "errorCode": 1001,
      "errorMessage": "Unauthorized"
    }
  ]
}

Each entry in errors includes:

Always check success before reading data. When success is false, inspect errors for details.

Requests are rate-limited per API key or token. When you exceed the limit, the API returns 429 Too Many Requests.

If you receive a 429:

1. Wait briefly before retrying.
2. Avoid tight retry loops, space out requests or use exponential backoff.
3. Cache form structure when possible instead of re-fetching on every sync.

The API provides read-only access to your forms and submissions. You can:

• List forms in your account
• Fetch a form's full structure (questions, design, settings)
• Page through submitted answers

You cannot create, update, or delete forms or submissions through the API.

• Fetching forms: list forms and retrieve full structure
• Fetching submissions: page through answers
• Frequently asked questions: common integration questions
• API reference: full endpoint and schema documentation