Skip to content
Last updated

General

What is the API base URL?

https://api.forms.app

Which forms are returned when I list my account?

The list includes all forms that belong to your authenticated account, regardless of visibility (public, unlisted, or private), as long as they are not in the trash or archived.

Authentication

Should I use an API key or OAuth?

  • API key: best for server-side scripts, cron jobs, and backend integrations you control.
  • OAuth bearer token: best when a third-party app needs access on behalf of a user.

For most getting-started scenarios, an API key is enough.

Can I use both an API key and a bearer token in one request?

No. The API requires exactly one authentication method per request. Sending both returns 401 Unauthorized.

I lost my API key. Can I retrieve it?

No. Keys are shown only once at creation. Revoke the old key in Account Settings → API Keys and create a new one.

How many API keys can I create?

You can create multiple keys (for example, one per environment or integration) and revoke any of them individually.

Responses and errors

What does the response envelope look like?

Every response wraps the payload in a consistent structure. On success, success is true and the payload is in data. On failure, success is false, data is null, and details are in errors. See The essentials.

How do I handle errors in code?

  1. Check the HTTP status code.
  2. Parse the JSON body.
  3. If success is false, read the errors array for errorCode and errorMessage.

Why am I getting 404 Not Found for a form?

The form may not exist, or it may belong to a different account. Confirm you are using the correct _id from GET /v1/form and the same credentials that own the form.

Submissions

How does pagination work for submissions?

Answers are returned in pages. Start with pageNumber: 1, then increment for each subsequent page. Compare the number of records you have collected against totalCount in the response to know when you are done. See Fetching submissions.

What is searchAfter in the answer response?

Each page includes a searchAfter cursor pointing to the last record on that page. For most integrations, incrementing pageNumber is enough. The cursor is available for advanced cursor-based navigation.

Rate limits

What happens when I hit the rate limit?

The API returns 429 Too Many Requests. Wait briefly and retry. Avoid hammering the endpoint in a tight loop.

Is there a health check endpoint?

Yes. GET /__health returns the gateway status and does not require authentication. Use it for uptime monitoring.

Getting help

The essentials

Fetching forms