# REST API (forms & submissions)

> Read and manage forms, submissions and webhooks with an OAuth access token. Powers the Formclick app on Make.

Source: https://docs.formclick.io/api-reference/rest-api

The REST API gives OAuth apps account-level access: list and manage forms, search submissions and subscribe to new submissions. It is the API behind the [Formclick app on Make](https://docs.formclick.io/html-forms/make).

## Base URL

```
https://app.formclick.io/api/v1
```

## Authentication

Send an OAuth 2.1 access token as `Authorization: Bearer <token>`. Tokens come from Formclick’s authorization server (authorization code + PKCE, discovery at `/.well-known/oauth-authorization-server`), the same one the [MCP server](https://docs.formclick.io/mcp/mcp-authentication) uses. Access tokens last 1 hour; refresh tokens rotate on every use.

| Scope | Allows |
| --- | --- |
| `forms:read` | List forms and read their settings |
| `forms:write` | Create forms and change their settings |
| `submissions:read` | List, search and read submissions |
| `webhooks:write` | Subscribe and unsubscribe webhooks |
| `usage:read` | Read plan usage |

## Endpoints

| Method & path | Scope | Description |
| --- | --- | --- |
| `GET /me` | — | The account behind the token |
| `GET /forms` | `forms:read` | List your HTML Forms |
| `POST /forms` | `forms:write` | Create a form: `name`, `description`, `notification_emails`, `redirect_url` |
| `GET /forms/:id` | `forms:read` | Form settings, endpoint, access key and webhooks |
| `PATCH /forms/:id` | `forms:write` | Change `name`, `notification_emails`, `redirect_url` (empty removes it), `success_message`, `is_active` |
| `GET /forms/:id/submissions` | `submissions:read` | Newest first. Query: `page`, `limit` (max 50), `search`, `from`, `to`, `filter` (`all`, `unread`, `read`, `starred`, `spam`, `archived`) |
| `GET /forms/:id/submissions/:submissionId` | `submissions:read` | One submission |
| `POST /forms/:id/hooks` | `webhooks:write` | Subscribe an `https://` `url` to new submissions |
| `DELETE /forms/:id/hooks/:hookId` | `webhooks:write` | Unsubscribe (idempotent) |
| `GET /usage` | `usage:read` | Plan, usage this period and form count |

## Example

```bash
curl https://app.formclick.io/api/v1/forms/FORM_ID/submissions?limit=10 \
  -H "Authorization: Bearer $FORMCLICK_TOKEN"
```

```json
{
  "total": 42, "page": 1, "limit": 10, "has_more": true,
  "submissions": [{
    "submission_id": "7f6c2b8e-…",
    "submitted_at": "2026-11-09T10:24:31.000Z",
    "from_name": "Jane Smith",
    "from_email": "jane@example.com",
    "is_spam": false,
    "fields": { "name": "Jane Smith", "message": "Hi!" }
  }]
}
```

Field values that look like passwords, tokens or card numbers are returned as `[redacted]`. Webhooks you subscribe receive the [webhook event](https://docs.formclick.io/api-reference/webhook-events) payload.

## Errors & limits

Errors are JSON `{ "error": "<code>", "message": "…" }` with `401` (missing or invalid token), `403` (missing scope or no access), `404`, `400` (invalid input) or `429` (rate limited, with `Retry-After`). Limits: 60 requests and 20 writes per minute for each user and app.