Connect to Developer Tools

What "developer tools" means in FormAssembly

FormAssembly groups two connectors under developer tools — connections that talk to an API rather than to a named business application:

• Webhook / HTTP — sends submission data to any web address you choose, and can also read data back from that address to prefill fields or fill a dropdown list. This is the connector to use when the service you need has an API but no dedicated FormAssembly connector.
• Google Maps — powers address autocomplete on a form field, so respondents pick a real address instead of typing it, and the parts of that address (street, city, state, postal code, country) land in separate fields.

Other services — Salesforce, Google Sheets, Stripe, and the rest — are covered by their own articles. This article covers only Webhook / HTTP and Google Maps.

This article assumes you already have the connection you need. If you don't, see Connecting Services for how to add and authorize a connection from the Connections page. The Connections page has no Webhook / HTTP row: to register your own API, click Define a service there.

Webhook / HTTP

The Webhook / HTTP connector is sold as an add-on. If your account does not include it, FormAssembly refuses to save a workflow that uses it and tells you the connector is not available on your account — contact your account owner or FormAssembly to add it.

What can the Webhook / HTTP connector do?

The Webhook / HTTP connector can do three things:

• Send data out. After a respondent submits, FormAssembly sends the answers you map to a web address you specify. This is the classic "post my form data to my system" use case.
• Read data in to prefill. Before a respondent sees a form, FormAssembly can call a read-only endpoint, take values out of the response, and use them to prefill fields.
• Fill a dropdown from live data. A form field can search your endpoint as the respondent types and show matching results in a picklist.

The connector is outbound only. FormAssembly calls your endpoint; it cannot receive events that your system pushes to FormAssembly.

What your endpoint needs to allow

The Webhook / HTTP connector authenticates per endpoint, using whatever the endpoint expects. The settings are split between the service and the connection: when you define the service with Define a service on the Connections page, you set its base web address, its optional OpenAPI description address, and its authentication method. Each connection to that service then holds only the credential — the key, token, or password. The authentication methods you can choose for a service are:

• None — public endpoint — for endpoints that need no authentication. You still define the service, because the service definition stores the base web address (and optionally an API description) in one place you can reuse.
• API key — a key sent either as a header or as a query parameter, whichever your endpoint requires.
• Bearer token
• Username and password
• OAuth 2.0, where you supply your service's own sign-in and token addresses. The form offers the server-to-server style of OAuth 2.0 only, because that style is usable the moment you save it — a flow that would require a browser sign-in at your service is not offered.

Two rules matter when you plan the integration:

• Credentials live only on the connection, never in a step. FormAssembly will not accept a step that carries its own authorization header or an API key written into a web address. This keeps secrets out of workflow configuration and out of error messages.
• Every address used by a step must be on the same site as the service's base address. If your service points at https://api.example.com, the steps that use it can call paths on api.example.com and nowhere else. A Webhook / HTTP step always needs a connection: without one, the step cannot be tested or published. For a public address that needs no credential, define the service with None — public endpoint authentication and use a connection to that service.

Your endpoint must be reachable on the public internet. FormAssembly refuses addresses on private, internal, loopback, or cloud-metadata networks, and there is no setting that overrides this. Both https and http are allowed; https is strongly recommended, because with plain http your submission data travels unencrypted.

Describing your API so FormAssembly can help you configure it

If your service publishes an OpenAPI description (a standard, machine-readable document that lists an API's operations and fields), you can add its address when you define the service. FormAssembly reads that description and uses it while the step is being set up, so operations and field names come from your API's own list instead of being typed from memory — which also means Fai, FormAssembly's built-in AI assistant, can configure the step from your API's real operations rather than from what you remember of them.

Important characteristics of the OpenAPI description:

• The description is used only while you configure, never when the workflow runs. Steps store the finished request details. If the description later moves or breaks, your live workflows keep working — you just lose the assisted configuration until you fix it.
• FormAssembly supports OpenAPI 3.0 and 3.1, in either JSON or YAML format, supplied as a web address. Pasting or uploading a file is not supported, and older Swagger 2.0 documents are not supported.
• The document must be under 1 MB and must not reference other external documents.
• If no description is configured, or it can't be read, configuration still works — you supply the address, method, and field names yourself.

Problems in a description are reported while you configure, so they never turn into a surprise failure on a live submission.

How do I send form data to my endpoint?

1. Open the workflow in the builder and ask Fai to add a Webhook / HTTP step where the delivery should happen — usually after the Collect step. The Add step menu has no Webhook / HTTP item, so asking Fai is the only way to add one, and asking works from either Overview or Focus view.
2. Tell Fai which connection the step should use.
3. Ask Fai to configure the delivery. A Webhook / HTTP step shows a read-only summary of its configuration ending "Connector configuration is managed by the AI agent." — there are no fields to edit on the step itself, so you describe what you want in the Fai panel and Fai writes the configuration.
4. Tell Fai the details that make up the request: the address to call, the request method (such as POST, PUT, or PATCH), the body format (a JSON object, a form-encoded body, or a body you write yourself as a template), and which answers to send and under what names. Each value you send is a form field, a workflow variable, or a fixed value you give.
5. Tell Fai if you want part of the endpoint's response stored in a workflow variable, so later steps can use it. A common use is capturing the ID of the record your endpoint just created. FormAssembly can also record a link to the created record when your endpoint supplies one, either in its response headers or in a response field you name; when the endpoint supplies neither, the ID and the link are simply left empty rather than guessed.
6. Use Test to run the workflow, then Publish when it behaves as expected.

Two details specific to Webhook / HTTP deliveries:

• A value sent with no prefix is placed in the request body. If you need a value in the web address instead, say that it is a query parameter. GET and DELETE requests send no body at all, so FormAssembly rejects a configuration that pairs one of them with body values — those values must be query parameters instead. This is checked while you configure, so sent data is never silently dropped behind a successful response.
• The custom body option uses one template. When you write the body yourself, it is a single template using the same tokens you already use in email bodies and confirmation messages, written as {{ step_1.fieldId }}, including repeated blocks for repeating sections. There is nothing new to learn, and no second template language. FormAssembly labels a custom body as JSON unless you set a content type of your own, which is the right default for the most common uses — a nested structure a flat list of values can't express, or a query for a GraphQL API.

How do I pull data in to prefill a form?

To prefill, ask Fai to add a Webhook / HTTP step before the first Collect step and to configure an operation that reads from your endpoint. FormAssembly calls a read-only endpoint, takes the values you asked for, and writes them into workflow variables. You then reference those variables as default values on the form fields you want prefilled.

Three things control the behaviour, and it is worth naming all three when you ask Fai:

• The query values you send — each one is either a fixed value or a reference to something already known, such as a parameter in the link that launched the workflow. If a reference has no value, FormAssembly sends the parameter as empty rather than leaving it out, so a lookup for one record can never quietly widen into a request for every record.
• Where the records are in the response. You tell FormAssembly which part of the response holds the list of records. If the response is a plain list, or a single record on its own, leave that setting empty to use the whole response. FormAssembly cannot guess this reliably, so it asks.
• What to do on no match or several matches. For no match you can skip the action, stop the submission, or continue with nothing filled in. For several matches you can skip, stop, take the first record, or run the following actions once per record. "First record" means first in the order your endpoint returned them — only use it against an endpoint whose ordering you trust.

Only workflow variables are written by the connector. Getting those values onto the form is the job of a field's default value.

How do I fill a dropdown from my endpoint?

Ask Fai to set up a dynamic lookup on the form field, using your Webhook / HTTP connection. You specify:

• The address to search and the name of the search parameter that receives what the respondent types.
• Where the results are in the response, plus which result field supplies the visible label and which supplies the underlying identifier.
• Extra fields to carry along, so selecting a result can also fill other fields on the form (for example, choosing a customer name also fills their email and account number).
• Any linked parameters, so one field's selection narrows another field's list.
• A minimum number of characters before FormAssembly searches. The default is 1, which means an empty box triggers no request. Set it to 0 if you want a default list to appear before the respondent types anything.

Limits worth knowing before you design the field:

• You can carry at most 25 extra fields alongside the label. This is a limit of the dynamic-lookup feature, not of your endpoint.
• A search returns at most 100 results. Design the search so the right answer appears near the top, and raise the minimum character count if lists come back too broad.
• Only the parameters you configure are ever sent. Respondents cannot add parameters, change the address, or alter the headers, because FormAssembly builds each search request from your stored configuration alone.

What if my endpoint's search parameter expects an expression?

Some endpoints don't accept a bare search term. An Airtable filter formula or a Jira JQL query expects a snippet of that service's own query language, and sending the typed term on its own makes the term be the whole expression — Airtable reads a bare ada as a field name and rejects the request.

For those endpoints, ask Fai to configure a search expression for the lookup instead of sending the term verbatim. Write the expression in the endpoint's own language and place the %%query%% token where the respondent's term belongs — for example, an Airtable search formula that tests whether the name contains the query token. FormAssembly substitutes the typed term into that position when it builds the request.

Rules that apply to a search expression:

• Do not put quotes around the token. FormAssembly adds the quoting and escaping itself, so a respondent who types an apostrophe or a quotation mark cannot break the expression.
• Write "contains" behaviour in the endpoint's own spelling. Asterisk wildcards have no meaning here, because FormAssembly cannot know what your endpoint treats as a wildcard.
• FormAssembly quotes values with double quotes and backslash escaping. A query language that uses single quotes and doubles them to escape — such as an OData filter — is not a safe target for a search expression; use a plain search parameter against such a service instead.
• Every field you reference in the expression must be declared as a linked parameter, and an undeclared reference is reported when you publish rather than being sent.

Leave the search expression empty for an ordinary endpoint that takes a plain term, such as one with a q parameter. A query value is data, not an expression, so there is nothing for a template to add.

Google Maps address autocomplete

The Google Maps connector adds address autocomplete to a form field. As the respondent types, FormAssembly shows up to five suggested addresses from Google Places; selecting one writes the full formatted address into the field. Ask Fai to set the lookup up on the field you want to autocomplete.

Google Maps is different from every other connector in one respect: it needs no connection of your own. FormAssembly uses a platform-level Google key, so there is nothing to authorize on the Connections page and nothing to reconnect.

The lookup field itself holds the whole formatted address, not just the street line — for example 5780 West Delap Road, Ellettsville, IN 47429, USA. If you are sending the address to a CRM that expects a street on its own, do not map the lookup field into that street field. Map the separate street number and street name parts described below, and combine them into one value when the address is sent to the CRM.

Filling separate address fields

Ask Fai to turn on address details for the lookup field so it receives the structured parts of the selected address, then map each part to a field on your form. The parts available are:

• Street number
• Street name
• City
• State or province
• Postal code
• Country code (the two-letter ISO code, such as US or FR)
• Google place ID (a stable identifier Google assigns to the selected place)

You map the parts you want by name and can ignore the rest — nothing has to be mapped in order or without gaps. The place ID and all six address parts are always returned when details are enabled. Parts that don't exist for a given address come back empty rather than being left out, so your field mapping stays stable from one country to the next.

International behaviour

• United Kingdom and Sweden: the city comes from the postal town, and FormAssembly handles that automatically.
• Some Asian cities, including Hong Kong and parts of Japan, report the city at a sub-locality level; this is also handled automatically.
• Countries without postal codes return an empty postal code.
• Countries without a state or province level return an empty state.

Suggestions are returned in English. Language and region biasing are not configurable, and address parts beyond the six listed above (such as neighbourhood or sub-premise) are not available.

Address validation

Google Maps also powers address validation, which answers a different question from autocomplete: instead of "which known places match this text?", validation asks "is this address real and complete, and what is its canonical form?" It returns one of three verdicts — verified, needs confirmation, or not verified — along with Google's canonical version of the address and the parts it could not confirm.

Address validation is used today by FormAssembly's AI intake agents, which check an address a respondent gives in conversation and ask about the doubtful part before accepting it. Validation does not run on the autocomplete path, so turning autocomplete on or off does not change it, and there is nothing to configure on the form field. A verified verdict means Google raised nothing to confirm or fix; it is not a guarantee that mail will arrive.

Limits that apply to Webhook / HTTP requests

• Timeouts and size caps. A delivery has 30 seconds and accepts up to 10 MB of response. A prefill read or a dropdown search has 8 seconds and 1 MB. Slow endpoints are the most common cause of failed deliveries.
• No automatic retries. If your endpoint fails, FormAssembly records the failure and moves on. Build your own retry or reconciliation on your side if delivery must be guaranteed.
• Request volume caps. FormAssembly allows up to 1,000 outbound requests per account per minute across deliveries, prefills, and searches, and up to 60 dropdown searches per form session per minute. Normal use stays far below both.
• Redirects are followed at most three times, and an authorization or cookie header is removed if a redirect sends the request to a different site. Only standard redirect responses are followed; an unusual redirect status is treated as an ordinary response, so FormAssembly records what that response returned rather than calling the address it points at. A credential sent as an API key in a header of your own naming does continue across such a hop. Configure the final address directly wherever you can.
• Test mode calls the same endpoint as a live run. The Webhook / HTTP connector has no separate sandbox address, so if you need a rehearsal target, point a test copy of the workflow at a different address.

FormAssembly's own API

FormAssembly publishes a public REST API, so your own systems can work with FormAssembly rather than only the other way round. The API reference is published at /api/openapi/ui on your FormAssembly address, and the machine-readable OpenAPI document at /api/openapi.

To call the API, an account admin registers an application on the API clients page and uses the credentials it issues. See Team & Account for how API clients are created and managed.

Tips & Troubleshooting

• A submission succeeded but no data arrived. Check the request method. GET and DELETE send no body, so values meant for the body must be sent as query parameters. FormAssembly blocks that combination while you configure, so this usually means the values went out as query parameters and your endpoint expects them elsewhere.
• The service or connection can't be saved. The base address must be reachable on the public internet and must not be a private, internal, or loopback address. If you also supplied an OpenAPI description address, FormAssembly checks that it can be read and understood before saving, and reports what's wrong.
• The step can't be tested or published. A Webhook / HTTP step must use a connection to a service you defined. If the endpoint needs no credential, define the service on the Connections page with None — public endpoint authentication and point the step at a connection to it.
• Fai declines to add a Webhook / HTTP step. The connector is an add-on, and Fai will not add the step when your account does not have it. Ask your account owner to add the add-on, then ask Fai again.
• The step won't accept your configuration because of an authorization header. Credentials belong on the connection, not in the step. Remove the header (or the key from the address) and select the connection that carries the credential instead.
• The step fails with an authorization error only when the endpoint redirects. An authorization or cookie header is dropped when a redirect crosses to a different site, so your endpoint receives the request without the credential. Point the step at the final address instead of the redirecting one; a connection that authenticates with an API-key header is not affected.
• Fai has to ask you for every address and field name. That means no usable OpenAPI description is attached to the service, or it couldn't be read. Configuration still works — supply the address, method, and field names yourself — and adding a working description address restores the assisted configuration.
• Prefill filled nothing. Confirm which part of the response holds the records; if the response is a plain list or a single record, leave that setting empty. Also check your no-match setting: "skip" and "continue" both leave fields blank without stopping the submission.
• The dropdown returns nothing until several characters are typed. That is the minimum character setting. Lower it to 0 to show a list before typing, but expect broader, less useful results at one or two characters.
• Your endpoint rejects the search as an invalid formula or query. The endpoint's search parameter expects an expression rather than a plain term. Ask Fai to configure a search expression in the endpoint's own language with the %%query%% token where the term belongs, and leave the token unquoted.
• Some mapped fields don't populate after a dropdown selection. You are likely past the 25 extra-field limit. Reduce the number of carried fields.
• The respondent picked an address and the field cleared itself. When the address parts have to be fetched at the moment of selection, a failure there undoes the selection rather than completing it with empty parts, and a validation message appears on the field. The respondent can retry or pick another address; asking Fai to turn on address details avoids the extra fetch, because the parts arrive with the suggestions.
• A CRM's street field received the whole address. The lookup field holds the complete formatted address. Map the street number and street name parts and combine them for the street field instead.
• Failures mention the endpoint's response. FormAssembly stores what your endpoint returned so the failure is diagnosable later in the Execution log. Respondents see only your configured error message unless you choose to show them the original.
• An address value breaks the request. Values substituted into a web address are encoded as a single path segment, so they cannot rewrite the path or retarget the request. A value that is exactly a dot or a double dot is refused outright rather than sent, because it would move the request up a level and turn a single-record read into a whole-collection read. If your endpoint expects a value containing slashes, send it as a query parameter instead.