Use an API action to send a request to an external web service and use its response in the service journey. It can retrieve information, create or update a record, or support a controlled integration with another system.

An API action should be designed with the receiving system’s owner. Agree the endpoint, authentication approach, request and response formats, timeout, error handling, data protection and test environment before adding it to a live service.

Design a safe request and response

Be able to describe the contract in plain language: what information is sent, why, what comes back, and what the person sees if the call cannot be completed.

flowchart LR
  A[Validated service values] --> B[Build request]
  B --> C[External API]
  C --> D{Response received?}
  D -- Expected response --> E[Use result in the journey]
  D -- Timeout or error --> F[Follow designed failure path]

Do not let an external failure leave a person unsure whether their request was recorded. For an essential integration, design a clear retry, review or alternative route. For a non-essential lookup, allow the service to continue only when that is a genuine, safe business outcome.

Configure the action

1. In Page actions, add an API action and give it a stable ID and clear name.
2. Choose a trigger after the source values are available and valid.
3. Set a fixed HTTP method, unless a dynamic method is an explicit integration requirement.
4. Enter the full URL, including https:// where the endpoint supports it.
5. Add a request body for methods that send data, then choose its content type.
6. Add only the headers that the receiving service requires.
7. Choose the response content type that matches the endpoint.
8. Set an appropriate timeout, configure client certificates only when required, then test in QA.

Use a fixed method for most integrations. A dynamic method is harder to review and should be used only where the API contract specifically requires it.

Match request and response formats

The request body and Request body content type must agree. A JSON payload should use the JSON content type; a plain-text or form-encoded API needs its corresponding type. A mismatch can make an otherwise valid request unreadable to the receiving system.

Likewise, set Response content type to the format the API actually returns. This tells Builder how to interpret the result for a later template, condition or Assign action. Test a normal success response and each documented error response; APIs do not always return an error in the same format as a success.

Use Liquid only for values that genuinely vary by journey. Escape or format values according to the API contract, especially when placing user-entered text in a JSON body or URL.

Add headers and credentials safely

Enter required Request header names and their paired values in matching order. Keep the number of headers minimal and document why each is needed. Do not place credentials, tokens, private keys or certificate material in action names, descriptions, screenshots or other documentation.

Some organisations require mutual TLS. Turn on the certificate option and supply the required certificate chain, private key and authority chain only through approved secure configuration. Treat certificate rotation as a planned operational activity with a named owner; do not rely on a service author remembering an expiry date informally.

Choose a realistic timeout and prototype response

The request timeout controls how long the service waits before treating the call as unavailable. Start from the integration’s agreed service level. A shorter timeout may provide a faster failure path; a longer timeout may be justified for an operation that the user expects to wait for. Test the user experience around a slow call, not just the successful result.

Use Mock response only for the prototype environment. It lets you exercise templates and routing without contacting the real external system. Keep the mock response representative of the agreed response format, including important optional or error cases. It must not be used as evidence that the production integration works.

Test the integration end to end

Test the request with ordinary, blank, long and unexpected values; review the received request with the API owner; and check how the service uses every expected response. Test each supported HTTP method and content type only where the integration needs it—not as a substitute for a focused acceptance test.

Record the action’s owner, endpoint purpose and failure route in its description or service runbook. An integration that works only because one person remembers how it was set up is difficult to maintain safely.

Related guidance

• Shared action settings
• Assign actions
• Use conditions and branching
• Write Liquid templates

Bulk Data evidence and integrations

The validated CSV includes respondent corrections; the untouched upload is retained separately. Use Upload files to send a selected Bulk Data evidence version to a configured file store. API actions can send up to 25 MiB of combined raw files as Base64; larger files can be streamed through the Bulk Data download API. Submitted revision selection requires retained Response history.

Bulk Data files, submitted revisions and integration examples