Call an external API
When a service has no node of its own, call its API with the HTTP node. This guide covers sending a request, signing in, using the response, and handling errors.
1. Add the request
- Click Add Step, open Built-in and choose HTTP.
- Choose the method the API expects: GET, POST, PUT, PATCH, DELETE or OPTIONS. Custom Request lets you choose the method in its settings instead.
- Fill in the request:
| Setting | What to enter |
|---|---|
| URL | The endpoint, such as https://api.example.com/v1/orders. You can insert values: https://api.example.com/v1/orders/ followed by a reference to an order ID. |
| Query Parameters | Key–value pairs added after ? in the URL. |
| Headers | Key–value pairs, such as Content-Type: application/json. |
| Body | For POST, PUT and PATCH: the content to send, usually JSON. |
| Timeout | How long to wait for a response, in milliseconds. The default is 10000 (10 seconds). |
For a JSON body, write the JSON and put references in the values:
{
"customer_email": "$trigger.output.email",
"items": "$.01JA9F3K7Q2M8XVBC4RTE5NHWD.output.data.items"
}Each reference is replaced by its value, and lists and objects stay as JSON. Pick references from the $ list rather than typing step IDs.
2. Sign in to the API
Most APIs need a key or token. Rather than pasting it into a header, save it once as a credential and pick it in the step's Credential setting. The HTTP node supports:
| Credential | Use it when the API asks for… |
|---|---|
| API Key | A key in a header or query parameter. |
| Bearer Token | Authorization: Bearer <token>. |
| Basic Auth | A username and password. |
| OAuth2 | Signing in with an OAuth app. |
| Digest Auth, NTLM Auth, WSSE Auth, AWS Signature V4 | These specific schemes. |
A credential keeps the secret out of the step's settings, and you can reuse it in every flow in the workspace.
3. Use the response
The step's output contains the response:
| Field | Contains |
|---|---|
statusCode | The HTTP status, such as 200. |
body | The response body. JSON responses are parsed, so you can go into them. |
headers | The response headers. |
rawBody | The body as plain text. |
So if the API returns {"order": {"status": "shipped"}}, a later step reads the status with:
$.<HTTP step ID>.output.body.order.statusRun the step once and look at its output in Executions to see the exact shape of the response.
If the response is a file, such as a PDF or an image, set Response › Response Format to File to save the body as a file instead of returning it in the output. See Storage for working with files.
4. Handle errors
A response with a status of 400 or higher fails the step, and by default the flow stops. The error in Executions shows the status and the API's message, such as Not Found (404).
To handle an expected error, such as a record that doesn't exist yet:
- In the HTTP step's Nodes Setting, set Error Handling to Continue flow.
- Add a Path after it with a condition on
statusCode, for example Number: Equals404, and add the steps for that case to its branch.