How to Call an External API Mid-Workflow

Summary

The steps

1. 1

   Open the workflow in the editor

   Navigate to your workflow from the Workflows list and click to open it in the Workflow Editor. The editor uses a three-panel layout: the Node Palette on the left, the canvas in the center, and the Properties Panel on the right. You need the Admin or Curate role to open the editor and edit nodes.

   If the workflow has no saved versions yet, the canvas will be blank. Build your surrounding workflow structure first (at minimum a Start node and an End node) so you know where the API Call node fits in the execution sequence.

   Do this

   • Go to the Workflows list and open the target workflow.
   • Confirm you have the Admin or Curate role. Other roles cannot open the editor.
   • Ensure the workflow has at least a Start node and an End node before adding the API Call node.

   Example

   You have a workflow that collects a customer ID from a User Interaction node. Before the next Agent Interaction node processes the customer record, you want to fetch the customer's current status from your CRM. The API Call node sits between the User Interaction node and the Agent Interaction node in the graph.

   Best practice

   • Name your nodes descriptively before saving. Change the default label "API Call" to something specific like "Fetch Customer Status" using the Properties Panel. This makes the graph self-documenting.
   • Save a version of the workflow before adding the API Call node so you have a clean restore point if the configuration becomes complex.
2. 2

   Drag the API Call node onto the canvas

   In the Node Palette on the left sidebar, locate the API Call node. It is marked with a cyan lightning bolt icon. Click and drag it from the palette onto the canvas and release it at the position where you want it to appear in the workflow sequence.

   Once dropped, the node appears on the canvas with its default label. Click the node to select it and open the Properties Panel on the right.

   Do this

   • Locate the API Call node (cyan lightning bolt icon) in the Node Palette.
   • Drag it onto the canvas and drop it between the nodes it should connect.
   • Click the node to open the Properties Panel.
   • Change the label in the Properties Panel to describe what this API call does.

   Example

   You drop the API Call node between the User Interaction node ("Collect Customer ID") and the Agent Interaction node ("Analyze Customer Record"). You rename it "Fetch Customer Status from CRM" in the Properties Panel.

   Best practice

   • Position the node visually between its upstream and downstream neighbors before connecting edges. The canvas is free-form, so placement is for readability, not execution order. Execution order is determined by edges.
   • Use the mini-map in the bottom-right corner to navigate if your workflow is large and the drop position is off-screen.
3. 3

   Connect the node with edges

   Edges define execution order. To connect the API Call node into the workflow sequence, you need two edges: one incoming (from the upstream node to the API Call node) and one outgoing (from the API Call node to the downstream node).

   To create an edge, hover over the source handle (the small circle at the bottom of the upstream node) until it highlights, then click and drag to the target handle (the small circle at the top of the API Call node) and release. Repeat to create the outgoing edge from the API Call node to the downstream node.

   Connections must go from a source handle (bottom) to a target handle (top). You cannot connect source-to-source or target-to-target.

   Do this

   • Hover over the bottom handle of the upstream node. Click and drag to the top handle of the API Call node. Release to create the incoming edge.
   • Hover over the bottom handle of the API Call node. Click and drag to the top handle of the downstream node. Release to create the outgoing edge.
   • Verify the edges appear as animated lines connecting the nodes in the correct direction.

   Example

   You drag from the bottom handle of "Collect Customer ID" to the top handle of "Fetch Customer Status from CRM". Then you drag from the bottom handle of "Fetch Customer Status from CRM" to the top handle of "Analyze Customer Record". The graph now shows a connected sequence.

   Best practice

   • Ensure all paths in your workflow lead to an End node. Dangling paths (nodes with no outgoing edge and no End node) can cause instances to hang at runtime.
   • If you need to branch after the API Call node based on the response, add a Routing node downstream and configure its port criteria against the mapped response fields.
4. 4

   Configure the API Call in the Properties Panel

   With the API Call node selected, find the API Configuration section in the Properties Panel. This section contains all the fields that define what request is sent and how the response is handled.

   Configure the following fields:

   • Method: The HTTP method for the request (GET, POST, PUT, PATCH, DELETE, or similar standard methods).
   • URL: The full endpoint URL for the external API, for example https://api.yourcrm.com/v2/customers/{{customerId}}. You can use template variables to inject workflow field values into the URL.
   • Headers: Key-value pairs sent with the request. Use this for authentication headers (such as Authorization: Bearer {{apiKey}}), content type declarations, and any other headers the API requires.
   • Body Template: The request body, used for POST, PUT, and PATCH requests. Supports template variables to inject workflow field values into the payload. Leave empty for GET and DELETE requests that do not send a body.
   • Retries: The number of times DAVE will retry the request if it fails. Configurable from 1 to 10. A retry is triggered on a network error or a non-2xx response code.
   • Timeout: Each attempt has a 30-second timeout. If the external API does not respond within 30 seconds, the attempt is treated as a failure and the retry logic applies.

   Do this

   • Set the Method to match the API endpoint you are calling.
   • Enter the full URL. Use {{fieldName}} syntax to inject workflow field values where the API requires dynamic values.
   • Add any required headers. For authenticated APIs, add the Authorization header with the appropriate scheme and value.
   • For POST, PUT, or PATCH requests, write the body template using {{fieldName}} syntax to inject field values.
   • Set the retry count (1 to 10) based on how critical the call is and how reliable the external API is. For critical integrations, set retries higher. For idempotent GET requests, 3 is a reasonable starting point.

   Example

   For a CRM lookup: Method is GET. URL is https://api.yourcrm.com/v2/customers/{{customerId}}. Headers include Authorization: Bearer {{crmApiKey}} and Accept: application/json. Body is empty. Retries is set to 3. If the CRM does not respond within 30 seconds on any attempt, DAVE retries up to 3 times before marking the node as failed.

   Best practice

   • Store API keys and secrets in workflow fields that are populated securely, rather than hardcoding them in the URL or body template. This keeps credentials out of the workflow graph definition.
   • For idempotent requests (GET, DELETE), higher retry counts are safe. For non-idempotent requests (POST, PUT, PATCH), consider whether retrying on failure could cause duplicate operations on the external system before setting a high retry count.
   • Keep JSON config valid. The Properties Panel silently ignores invalid JSON while you type, but saving with invalid JSON retains the last valid state. Double-check your body template before saving.
5. 5

   Map the API response back into workflow fields

   After the API Call node receives a response, it can extract values from the response body and write them into workflow fields. This is configured in the Response Mapping part of the API Configuration section in the Properties Panel.

   Each mapping entry defines two things: the JSON path to the value in the response body (for example data.status or customer.tier), and the name of the workflow field where the extracted value should be written.

   Once mapped, the extracted values are available as workflow fields for all downstream nodes. An Agent Interaction node that runs after the API Call node can reference these fields in its context. A Routing node can branch based on their values.

   Do this

   • In the API Configuration section, locate the Response Mapping configuration.
   • Add a mapping entry for each value you want to extract from the response.
   • For each entry, specify the JSON path to the value in the response body and the workflow field name to write it to.
   • Use consistent field naming conventions so downstream nodes can reference the mapped values reliably.

   Example

   The CRM API returns: {"data": {"status": "active", "tier": "enterprise", "accountManager": "Jane Smith"}}. You add three response mappings: data.status to customerStatus, data.tier to customerTier, and data.accountManager to accountManager. The downstream Agent Interaction node receives all three values in its context.

   Best practice

   • Map only the fields you actually need downstream. Mapping every field in a large response adds noise to the workflow context without benefit.
   • Use the same field names consistently across your workflow. If a field is called customerStatus here, reference it as customerStatus in downstream agent prompts and routing rules.
   • Test the response structure against a real API call before finalizing the mappings. API response shapes can differ from documentation, especially for error responses.
6. 6

   Save a new version and test the workflow

   When your API Call node is configured and connected, click Save Version in the top-right corner of the editor. This serializes the entire graph into a new immutable version. Previous versions are preserved and can be loaded at any time.

   After saving, run a test instance of the workflow. When the instance reaches the API Call node, DAVE sends the configured HTTP request to the external API. Check the instance log to verify the request was sent, the response was received, and the mapped fields were populated with the expected values.

   If the API call fails after all retries are exhausted, the instance will reflect a failure at that node. Review the instance log for the error detail, check the URL, headers, and authentication configuration, and verify the external API is reachable.

   Do this

   • Click Save Version in the top-right corner. Confirm the version is saved.
   • Start a test instance of the workflow.
   • Progress the instance through any upstream nodes (for example, submit the User Interaction form if there is one).
   • When the instance reaches the API Call node, it executes automatically. Check the instance log to confirm the request was sent and the response was received.
   • Verify that the mapped workflow fields contain the expected values from the API response.
   • If the call fails, review the error in the instance log, adjust the configuration, save a new version, and retest.

   Example

   You save the version and start a test instance. You submit a customer ID of CUST-001 in the User Interaction step. The instance reaches "Fetch Customer Status from CRM", sends a GET request to https://api.yourcrm.com/v2/customers/CUST-001, receives a 200 response, and maps customerStatus: active, customerTier: enterprise, and accountManager: Jane Smith into the workflow context. The downstream Agent Interaction node receives all three values.

   Best practice

   • Test with a representative real input, not just a happy-path example. Verify the behavior when the external API returns a 404, a 500, or a timeout. Confirm the retry logic behaves as expected and the instance fails gracefully when retries are exhausted.
   • Save frequently during configuration. Each save creates a new version with no risk of overwriting previous work. If a configuration change breaks the workflow, the previous version is always available.

What the API Call node does

Retry and timeout behavior

Response mapping and downstream use

Who can configure the API Call node

Frequently asked questions