Connect an external API

Build a workflow that validates input, calls a service, and returns a stable response. Start with a read-only operation so you can verify routing and data contracts without changing upstream records.

Prepare the integration#

Obtain the upstream service's actual request contract: hostname, method, path, authentication, required parameters, and an example response. Choose a sandbox or test account when the provider offers one.

Create stored selectors for the environment-specific base URL and credential. For example, use SERVICE_BASE_URL and an appropriately protected SERVICE_TOKEN.

Build the path#

Authorize caller → Validate input → FetchCustomer → CustomerResponse

1. Create an action with a route such as customers/${customerId} and the GET method.
2. Add the required gateway and user authorization.
3. Validate the captured customer ID before using it in a URL.
4. Add an HTTP Request node named FetchCustomer with the provider's method, URL, and headers.
5. Add a Function named CustomerResponse and read ${FetchCustomer} directly in its script.

If the provider's response is the object {"id":"123","name":"Avery"}, the Function can shape it as:

import json

customer = ${FetchCustomer}
return json.dumps({
    "id": customer["id"],
    "name": customer.get("name", "")
})

Adapt this to the response you actually observed. Do not assume a wrapper or field type from a different provider endpoint.

Test the contract#

Run a known customer lookup, an unknown ID, malformed input, invalid upstream credentials, and denied caller access. Inspect the outbound request log and final response.

A provider failure may stop the Request node before your response Function runs. Confirm the observed error behavior and expose a consistent client contract using the workflow's supported configuration.

Release the integration#

Review production selectors, provider limits, timeout/retry settings, and any user-scoped access. Test the public sandbox URL from the intended client, then use release review.

For write operations, add a stable operation identifier and the provider's supported duplicate-prevention behavior before enabling retries.