Integrations & API

Each form connects to other tools from its settings: open the form's settings and go to Settings → Integrations. There you can add webhooks, post new responses to Slack and copy uploads into Geiger Assets. Choose Save changes when you're done.

Forms has no built-in Zapier, Make or Google Sheets connectors. Connect them with a webhook instead: in Zapier or Make, add a "Catch hook" trigger and add its address as a webhook. You can also pull responses on a schedule from the REST API, whose address for this form's responses is shown at the bottom of Integrations.

For the whole project, Integrations → Webhooks and Integrations → REST / API in the Forms sidebar open the developer screens, covered at the end of this guide.

A webhook sends each response to an address you choose, as soon as it happens. To add one, open the form's settings, go to Settings → Integrations and choose Add webhook.

• Endpoint URL: the address that receives the data, starting with https:// or http://. Forms won't save a webhook without a valid one, and it never sends to private or local network addresses.
• Signing secret: a secret is generated for you, starting whsec_. Generate makes a new one. Use it to check that deliveries come from Forms.
• Events: Response created (selected to start with), Response updated and Response approved.
• The switch at the top pauses the webhook (Paused) or turns it back on (Active).

Send test sends a test delivery straight away and tells you the HTTP status your endpoint returned. The trash icon removes the webhook. Add as many webhooks as you need, then choose Save changes.

Forms sends three events:

• response.created: a new response, after it's been checked and scored and its automations have run.
• response.updated: a respondent edits their response, a payment is confirmed or the approval chain rejects the response.
• response.approved: the last approval step approves the response.

Each delivery is a POST with a JSON body: event, createdAt and data. data.form holds the form's ID, slug and title. data.response holds the response's ID, status, priority, score, outcome, tags, respondent name and email, approval and payment, when it was submitted and edited, and answers, keyed by field ID. Answers to sensitive fields are sent as [protected].

A field's ID is shown at the bottom of its Advanced tab in the builder.

Every delivery carries three headers:

• X-Geiger-Event: the event name, such as response.created.
• X-Geiger-Delivery: the delivery's ID. It stays the same on every retry and replay, so store it and skip IDs you've already handled.
• X-Geiger-Signature: sha256= followed by the hex HMAC-SHA256 of the raw request body, made with the webhook's signing secret.

To check a delivery, compute the same HMAC over the raw body with your secret and compare it with the header. Each attempt is signed again with a fresh createdAt, so you can also reject old timestamps. Your endpoint should answer with a 2xx status within 8 seconds.

Developer → Hooks & Events shows an example payload and a Node.js example of the check.

When a delivery times out, can't connect or gets a 408, 425, 429 or 5xx status, Forms tries again twice within seconds, then backs off from 5 minutes up to a day between tries, for up to 8 attempts. A Retry-After header is honored. Any other status fails at once. Delayed retries run the next time Forms sweeps for them, within minutes while deliveries are flowing and at least once a day, or as soon as the endpoint accepts a new delivery.

When a delivery fails for good, the form's creator gets a notification in the bell and an email headed "Webhook failing", at most once a day per endpoint.

The form's Integrations settings list its 20 most recent deliveries. The Deliveries tab of the developer screens lists every delivery for the form you pick, with when it was sent, its event, endpoint, status (Delivered, Retrying or Failed, with the HTTP code), each attempt and any error. Search it, or choose Refresh.

Replay sends a delivery's original data again with a fresh signature, for up to 30 days. Test deliveries, and deliveries for a webhook that's been removed or paused, can't be replayed. Seeing deliveries needs a role that can edit forms, and replaying also needs access to responses.

Under Settings → Integrations in a form's settings:

• Slack: paste a Slack Incoming webhook URL (in Slack, under Apps → Incoming Webhooks → Add to channel). Each new response then posts a message to that channel with who responded, up to 12 answers, a High priority flag when it applies and a link to open the response in Forms. Sensitive answers show as [protected].
• Geiger Assets: turn on Sync uploads to Assets to add the files respondents upload to the project's library in Geiger Assets, tagged forms.

Choose Save changes to keep them.

API keys let your own code reach a project's forms through the REST API. Each key belongs to one project and only sees that project's forms. Manage them on the API keys tab of Integrations → REST / API, or in the API keys card of Workspace Settings. Only the Owner and Admin roles can create or revoke keys.

1. Choose Create key and give the key a name, so you know where it's used.
2. Pick its scopes: Read lists forms and fetches responses, and Write submits responses (and includes read).
3. Copy the key from Copy your API key. It's shown only this once, so store it somewhere safe.

The list shows each key's name, the start of the key, its scopes, and when it was created and last used. To revoke a key, choose the trash icon and confirm. Anything using it stops working at once, and it can't be undone.

Send your key as Authorization: Bearer gf_…. The REST API tab of the developer screens shows each endpoint with full example addresses for your deployment.

• GET /api/v1/forms: the project's forms, up to 500, the most recently edited first.
• GET /api/v1/forms/{id}: one form, with its fields and public settings.
• GET /api/v1/forms/{id}/responses: the form's responses, oldest first. limit sets the page size (50 to start with, up to 200), since takes an ISO date and cursor takes the nextCursor from the previous page. Sensitive answers come back empty and are listed in encryptedFields.
• POST /api/v1/forms/{id}/responses: submits a response, with a body like {"answers": {"FIELD_ID": "value"}}. It needs the Write scope and goes through the same checks, scoring, automations and webhooks as the public form. It skips access rules and spam checks, but the response limit still applies. It returns 201 with the new response.

Every reply is JSON. A failed request returns an error status and message: 401 means the key is missing, wrong or revoked, and 403 means it lacks the scope.

To show a form in your own design, or show response data in your own dashboard, use these endpoints. They need no key, and work only for published forms:

• GET /api/public/forms/{slug}: the form's fields and public settings, for drawing the form yourself.
• POST /api/public/forms/{slug}/submit: submits answers from your page. The form's honeypot, captcha and rate limit apply.
• GET /api/public/forms/{slug}/results: poll results, when the form shows them to respondents.

To read responses, call the REST API from your server with a Read key. Never put an API key in code that runs in the browser. The Data Front-end and Headless / API-first screens open this reference.

Five sidebar entries open the same developer screens on different tabs: Integrations → Webhooks and Developer → Hooks & Events open Webhooks, Integrations → REST / API opens API keys, and Developer → Headless / API-first and Developer → Data Front-end open REST API.

• API keys: create and revoke keys.
• REST API: the endpoints, with example requests.
• Webhooks: the events, headers, an example payload, a signature check example and the project's forms that have webhooks. Configure opens a form's Integrations settings.
• Deliveries: the delivery log for one form.
• Embed: embed code examples and every embed option. Its script also has a small JavaScript API: GeigerForms.open() opens a form in a popup, slider, popover or full screen, a geiger-form:submitted event fires on your page when someone submits, and GeigerForms.mount() sets up embeds added after the page loads.

The Publishing and sharing guide covers embedding a form step by step.