Formcarry API Overview

The Formcarry API lets you manage forms, submissions, email notifications, and account resources programmatically. All requests are JSON over HTTPS and authenticated with a Bearer token.

Base URL

https://api.formcarry.com

Every endpoint is versioned under the /v1 prefix, for example GET https://api.formcarry.com/v1/forms.

Authentication

Formcarry uses Bearer token authentication. Pass your API key in the Authorization header on every request:

curl https://api.formcarry.com/v1/me \
  -H "Authorization: Bearer fc_live_your_api_key"

See Authentication for details on generating keys, scopes, and verifying credentials.

Common resources

Forms

Create, list, update, and delete forms in your workspace.

Submissions

Read, filter, and manage submissions on a form.

Email notifications

Manage self-email recipients and connected email servers.

Webhooks

Subscribe HTTPS endpoints to receive every submission as a signed JSON POST.

Account

Inspect the authenticated key with GET /v1/me.

Pagination

List endpoints (such as GET /v1/forms and GET /v1/forms/{form_id}/submissions) use cursor pagination. Pass limit and cursor as query parameters; responses include a next_cursor field when more results are available.

curl "https://api.formcarry.com/v1/forms?limit=50" \
  -H "Authorization: Bearer fc_live_your_api_key"

To fetch the next page, send the returned next_cursor back as the cursor parameter.

Errors

The API returns a unified error envelope with a machine-readable code and a human-readable message. Every error response carries request_id, and every response carries an X-Request-Id header, which Formcarry support can use to trace the call.

{
  "error": {
    "type": "authentication_error",
    "code": "missing_bearer",
    "message": "Authorization header is required.",
    "request_id": "req_01H..."
  }
}

Common error codes:

Code	Meaning
`missing_bearer`	No `Authorization` header on the request.
`invalid_key`	The API key is malformed or has been revoked.
`wrong_audience`	The key is not valid for this API.
`insufficient_scope`	The key does not have the required scope.
`form_access_restricted`	The key cannot access the requested form.
`team_inactive`	The workspace is suspended.
`owner_unverified`	The account owner has not verified their email.
`plan_restricted`	The action requires a higher plan.
`rate_limited`	Too many requests. Retry after the delay in the `Retry-After` header.
`invalid_parameter`	A request parameter failed validation.
`form_not_found`	The `form_id` does not exist or is not visible to this key.
`invalid_cursor`	The pagination cursor is malformed or expired.
`payload_too_large`	The request body exceeded the size limit (1 MB for JSON, 5 MB for image uploads).
`recipient_not_found`	The email address is not on the notification list.
`webhook_limit_reached`	The form already has its 10 webhooks. Delete one to add another.
`webhook_url_taken`	Another webhook on this form already posts to that URL.
`scan_concurrency`	At most 2 filtered submission requests may run at once per key.

Rate limits

Formcarry enforces per-key rate limits. When you exceed a limit, requests return HTTP 429 with code: "rate_limited". Respect the Retry-After response header before retrying.

Reference

Every endpoint, request schema, and response schema is documented in the Endpoints section, generated directly from the live OpenAPI specification at https://api.formcarry.com/docs-json.

​Base URL

​Authentication

​Common resources