Zapier Integration

1. Overview

The integration exposes a small REST API under https://api.maxforms.com/v1/forms/automations. The flow:

1. The user authorizes Zapier via OAuth 2.0, granting access to a specific workspace.
2. Zapier calls GET /forms to populate a form-picker dropdown.
3. When the user enables a Zap, Zapier calls POST /subscribe with a target URL.
4. On every new form submission, Maxforms POSTs the submission payload to that URL.
5. When the Zap is disabled, Zapier calls DELETE /unsubscribe/{id}.

All resources are scoped to the workspace selected at authorization time. Removing the user from the workspace automatically revokes the token.

2. Authentication (OAuth 2.0)

Maxforms uses the OAuth 2.0 Authorization Code grant. Credentials are issued on request — email [email protected] with your integration name and redirect URI.

Workspace binding

Each access token is bound to the workspace active when the user authorized the connection. Tokens can only read and operate on resources within that workspace. If the user later switches workspaces in the Maxforms UI, the existing token continues to operate on the originally-bound workspace.

Verifying a connection

Use GET /v1/forms/automations/auth/test to confirm a token is valid. Response:

{
  "status": "authenticated",
  "email": "[email protected]",
  "name": "User Name"
}

3. Scopes

Request all four scopes for full Zapier functionality:

4. Endpoints

All endpoints are under https://api.maxforms.com/v1/forms/automations and require Authorization: Bearer <token>.

GET /forms — list forms

Returns every form in the token's workspace. Required scope: forms:read.

GET /v1/forms/automations/forms
Authorization: Bearer <token>

HTTP/1.1 200 OK
[
  { "id": "aZ3kP9mQ7nB4", "name": "Contact form" },
  { "id": "bX4mLp2QrT9c", "name": "Event signup" }
]

POST /subscribe — create a REST Hook

Registers a target URL to receive event payloads. Required scope: webhooks:write.

POST /v1/forms/automations/subscribe
Authorization: Bearer <token>
Content-Type: application/json

{
  "form_id":    "aZ3kP9mQ7nB4",
  "target_url": "https://hooks.zapier.com/hooks/standard/123/abc",
  "event":      "submission.created",
  "platform":   "zapier"
}

HTTP/1.1 201 Created
{
  "id":     "01HV7E…",
  "status": "subscribed"
}

• event defaults to submission.created (currently the only supported event).
• target_url must be a publicly resolvable HTTPS URL. Private/loopback ranges are rejected with 422.
• form_id must belong to the token's workspace. 404 otherwise.
• form_id is the form's public code (the id value returned by /forms), not the internal id.

DELETE /unsubscribe/{id} — remove a REST Hook

Required scope: webhooks:write.

DELETE /v1/forms/automations/unsubscribe/01HV7E…
Authorization: Bearer <token>

HTTP/1.1 200 OK
{ "status": "unsubscribed" }

GET /submissions — sample data

Returns the 10 most recent submissions for a form, in the same flat shape Maxforms posts to subscribed targets. Used by Zapier to populate field options during Zap setup. Required scope: submissions:read.

GET /v1/forms/automations/submissions?form_id=aZ3kP9mQ7nB4
Authorization: Bearer <token>

HTTP/1.1 200 OK
[
  {
    "id":           "01HV7F…",
    "form_id":      "aZ3kP9mQ7nB4",
    "form_name":    "Contact form",
    "submitted_at": "2026-05-20T10:14:32+00:00",
    "field_name":   "Ada Lovelace",
    "field_email":  "[email protected]"
  }
]

GET /fields — output field metadata

Returns the form's input fields as { key, label, type } objects, where key matches the field_* keys in the submission payload. Zapier uses this to label output fields with the form's human field names. The key is stable across field renames; only the label changes. Required scope: forms:read.

GET /v1/forms/automations/fields?form_id=aZ3kP9mQ7nB4
Authorization: Bearer <token>

HTTP/1.1 200 OK
[
  { "key": "field_full_name", "label": "Full Name",     "type": "text" },
  { "key": "field_email",     "label": "Email Address", "type": "email" }
]

GET /auth/test — connection test

Returns the authenticated user's name and email. Used by Zapier to label the connection.

5. Submission payload

When a form is submitted, every active subscription receives an HTTP POST with this body (top-level fields plus one field_* entry per form field):

{
  "id":           "01HV7F…",
  "form_id":      "aZ3kP9mQ7nB4",
  "form_name":    "Contact form",
  "submitted_at": "2026-05-20T10:14:32+00:00",
  "field_name":   "Ada Lovelace",
  "field_email":  "[email protected]",
  "field_message":"Hello!"
}

• Field keys are derived from the form's field identifiers, prefixed with field_.
• Multi-value fields (checkbox groups, multi-selects) are serialized as comma-joined strings.
• The endpoint must respond with a 2xx status within 30 seconds. Non-2xx responses are logged and not retried.

6. Errors & rate limits

Default rate limit: 60 requests/minute per token. Higher limits available on request.

7. Support

For OAuth credentials, raised rate limits, or integration partner inquiries: [email protected]. For account or product questions: [email protected].