REST API

Authentication

Create a secret key in Integrations & API keys and send it with every request. Keep it on your server; never put it in browser code.

Keys can be limited to one site. Plugins and the API are on Starter, Pro and Agency.

Authorization: Bearer sk_live_ab12…

Check a key

Which workspace and site(s) the key belongs to. The plugins call this when you paste a key. `script_seen_recently` lets a plugin warn about double alerts when the script is also installed.

curl -X GET https://api-staging.formcrier.com/api/v1/me \
  -H "Authorization: Bearer sk_live_ab12…"

List forms

Every form on the site, from any source, with whether alerts are on.

curl -X GET https://api-staging.formcrier.com/api/v1/forms \
  -H "Authorization: Bearer sk_live_ab12…"

Sync forms

Plugins send the full list of forms on the site so they appear in the dashboard with switches. New forms start switched off (unless the site listens to all forms). The response says which are switched on, so the plugin only sends those.

curl -X PUT https://api-staging.formcrier.com/api/v1/forms/sync \
  -H "Authorization: Bearer sk_live_ab12…" \
  -H "Content-Type: application/json" \
  -d '{ "source": "wordpress", "forms": [{ "external_ref": "gf-3", "name": "Quote request" }] }'

Send a submission

Goes through the same spam checks, routing and alerts as the script. We reply 202 straight away and send alerts in the background. Send an `Idempotency-Key` header so a retried request never creates a second alert.

curl -X POST https://api-staging.formcrier.com/api/v1/submissions \
  -H "Authorization: Bearer sk_live_ab12…" \
  -H "Idempotency-Key: 5f1c…" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "api",
    "form": { "external_ref": "quote", "name": "Quote request" },
    "fields": [
      { "key": "name", "label": "Name", "type": "text", "value": "Sarah Jones" },
      { "key": "phone", "label": "Phone", "type": "tel", "value": "07700 900123" }
    ],
    "page_url": "https://acmeplumbing.co.uk/quotes"
  }'

Errors and rate limits

Errors are JSON with a machine-readable error and a message you can show: {"error": "unknown_site", "message": "…"}.

401 means the key is missing, wrong or revoked. 403 plan_upgrade_required means the plan doesn't include the API. 422 means the request didn't validate (see errors). 429 means slow down: each key can make 120 requests a minute.