Execute API

Description

The Execute API Activity enables workflows to connect and communicate with any RESTful API by executing configurable HTTP requests such as GET, POST, PUT, PATCH, or DELETE. It allows users to define the request structure including headers, query parameters, body content, file uploads, pagination rules, response parsing, and authentication.

Supported Features

• Multiple HTTP Methods: GET, POST, PUT, PATCH, DELETE, or custom methods
• Authentication: OAuth 2.0, API Keys, Basic Auth, and Bearer tokens via configured connections
• Request Types: JSON payloads, form-encoded data, and multipart file uploads
• Response Parsing: Extract data from nested JSON responses and flatten complex structures
• Pagination: Automatic handling of paginated APIs with cursor-based or token-based pagination
• File Handling: Upload files with form data and export API responses as JSON or CSV
• Dynamic Parameters: Replace placeholders with values from previous activities for batch processing
• Header Control: Add custom headers, include response headers in output, configure content encoding

Use case:
In a logistics automation workflow, use this activity to call a courier tracking API like https://api.courier.com/track to fetch live shipment updates. Pass tracking numbers dynamically using Form Data, handle pagination automatically, and export the results as JSON or CSV for audit purposes.

---

Input

Placeholder Syntax

The Execute API activity supports two placeholder patterns for dynamic value substitution:

• @[ColumnName] - References a column from the current input data row

  • Example: @[customerId], @[email], @[phone]
  • Used when processing input data directly

• @[ActivityName.Data.ColumnName] - References data from a previous activity

  • Example: @[GetCustomers.Data.customerId], @[ValidateEmail.Data.result]
  • Used to reference outputs from activities earlier in the workflow
  • Syntax: @[ActivityDisplayName.Data.ColumnName] or @[ActivityDisplayName.Files.FileName]

Placeholders can be used in: Request URL, Headers, Body, Form Data, URL Params, and File Field Name.

Input Data Flow

The Execute API activity supports three input scenarios:

1. Static Request (No Input Data)

When Input Type is empty or Parameters field is empty:

• The activity executes a single API request using only the configured URL, headers, and body
• No data rows are processed
• Example: Fetch a list of customers without any filtering

2. Single Request with Row Iteration (ReplacerForAllRows = False)

When Input Data is provided and ReplacerForAllRows is disabled:

• One API request is made per input row
• Placeholders in URL, body, headers, and parameters are replaced with values from each row (e.g., @[email], @[customerId])
• Each row’s API response is collected separately
• Output contains one data row per API response (plus metadata fields)
• Useful for lookups, updates, or other operations on individual records
• Example: Look up 100 customer IDs one at a time by calling the API 100 times with each @[customerId]

3. Batch Request (ReplacerForAllRows = True)

When Input Data is provided and ReplacerForAllRows is enabled:

• All input rows are combined into a SINGLE API request
• Placeholders in Body are replaced with combined data from all rows
• The entire batch is submitted in one call (useful for batch import/processing APIs)
• Output contains one data row with the batch response (plus metadata fields)
• Useful for bulk operations where multiple records are processed together
• Example: Submit 100 customer records in a single POST request by combining them in the body as @[allCustomers]

Input Data Mapping

Input data columns are mapped to request components via the Parameters field:

• Column values replace placeholders (e.g., @[customerId]) in URL, headers, body, and URL params
• Previous Activity Data: Reference data from previous activities using @[ActivityName.Data.fieldName]
• File Input: When uploading files, the InputFilePattern field filters files, and FileKey specifies the form field name
• Form Data: Row data can populate form fields dynamically

Type	Required	Description
Data	Optional	Input rows with values to map to request components. Used when Parameters field is populated for dynamic request construction.
Files	Optional	Files to upload with the request (used with multipart/form-data content type).

---

Output

Output Structure

The activity returns structured data with the following fields:

Data Output

• Format: List of dictionaries (key-value pairs) containing flattened data from API response(s)
• Nested JSON: When Root of Response is configured, only that portion is extracted and included
• Multiple Pages: When pagination is enabled (NextPageKeyPath is set), all pages are automatically fetched and combined
• Response Data: Each row contains the actual parsed API response data (or file details when ResponseType is File)

Response Metadata Fields

Every data row includes these fields:

• Response (string): Raw JSON response from the API as a string (serialized form of the data)
• HeaderResponse (object): HTTP response headers from the API request
• API (boolean): true if request succeeded, false if API returned an error status
• APIResponseCode (int): HTTP status code (e.g., 200, 404, 500)
• Request Url (string): The actual URL that was called

Export Fields

When ExportFile is enabled:

• FileName (string): Name of the exported file (JSON or CSV format)
• For JSON Export: Each API response generates a separate file named Response-{i}-{Guid}.json
• For CSV Export: CSV data is extracted from the field specified in JSON Field and exported

Headers Output

When IncludeHeadersInResponse is enabled, all HTTP response headers are included as individual fields in the data row (e.g., content-type, x-ratelimit-remaining, etc.)

Field	Type	Description
Data	Array	List of dictionaries, each representing a record from the API response. Includes metadata fields: Response (raw response JSON), HeaderResponse (headers), API (success flag), APIResponseCode (HTTP status), Request Url (called URL).
Files	Array	List of exported files (when ExportFile is enabled). Contains file paths and metadata. For JSON exports, each response becomes a separate file. For CSV exports, data is extracted from the JSON Field and formatted as CSV.
AdditionalResponse	String	JSON-serialized array of raw API responses from all API calls in this activity. Useful for debugging or audit purposes.

---

Configuration Fields

Core Request Configuration

Field Name	Type	Required	Description
Connection	Selector	Yes	Authentication configuration for the API. Supports OAuth 2.0, Basic Auth, API Keys, and Bearer token authentication. Select a pre-configured connection that matches your API’s auth requirements.
Request Type	Dropdown	Yes	HTTP method for the API call. Options: GET, POST, PUT, PATCH, DELETE, Custom.
Request URL	Text	Yes	Full endpoint URL for the API call (e.g., https://api.example.com/customers). Supports placeholder replacement using @[ColumnName] or @[ActivityName.Data.ColumnName] syntax for dynamic values from input or previous activities.
Response Type	Dropdown	Yes	Format of the API response. Options: JSON (structured data), File (binary response saved directly). Default: JSON.
Content Type	Dropdown	Yes	MIME type of the request body. Options: JSON, form-url-encoded, multipart/form-data. Default: JSON. Determines how request body is formatted.

Request Headers & Encoding

Field Name	Type	Required	Description
Headers	Key-Value Array	No	Custom HTTP headers as key-value pairs (e.g., Authorization, X-API-KEY, Accept). Each header is sent with the request. Supports placeholder replacement using @[ColumnName] or @[ActivityName.Data.ColumnName] syntax for dynamic values.
Accept Encoding	Multi-Select	No	Expected content encoding in the response. Options: Gzip, Deflate, Brotli. Improves performance for large responses when server supports compression.

Request Body & Data

Field Name	Type	Required	Description
Body	Text (Large)	Conditional	Request body content in raw JSON or XML format. Required for POST, PUT, PATCH methods. Supports placeholder replacement using @[ColumnName] or @[ActivityName.Data.ColumnName] syntax for dynamic values (e.g., @[email], @[PreviousActivity.Data.userId]).
Form Data	Key-Value Array	No	Form-encoded data fields (key-value pairs). Used when Content Type is form-url-encoded or multipart/form-data. Each pair becomes a form field in the request.
File Field Name (FileKey)	Text	Conditional	Form field name for file upload. Required when uploading files with multipart/form-data. Specifies where the file content is placed in the request.
Input File Pattern	Text	No	Regex pattern to filter input files for upload. Only files matching this pattern are included in the request.

URL & Query Parameters

Field Name	Type	Required	Description
URL Params	Key-Value Array	No	Query parameters appended to the URL (e.g., status=active&limit=100). Each pair becomes a query parameter: ?key1=value1&key2=value2. Supports placeholder replacement using @[ColumnName] or @[ActivityName.Data.ColumnName] syntax.
Parameters	Column Selector	No	Select columns from input data to map to request components. When set, enables dynamic request construction. Used in conjunction with placeholders like @[paramName] or @[ActivityName.Data.paramName] in URL, Body, Headers, and URL Params.
Use All Rows as Part of Request (ReplacerForAllRows)	Boolean	No	Controls how input data is processed. Default: false. When false, each row creates a separate API request. When true, all rows are combined into a single request (useful for batch APIs).

Response Parsing & Extraction

Field Name	Type	Required	Description
Root of Response	Text	No	JSON path to the array/object containing the main response data (e.g., data.customers, results, payload). If specified, only this portion of the response is extracted. Leave empty to use the entire response.
Search Key to Replace	Text	No	Field key in the response whose value should be replaced dynamically. Advanced option for response transformation.
Include Headers in Response	Boolean	No	When enabled, all HTTP response headers are included in the output under a _headers field. Useful for capturing metadata headers (e.g., rate limits, request IDs).

Pagination Configuration

Field Name	Type	Required	Description
Next Page Key Path	Text	Conditional	JSON path to locate the next page token in the API response (e.g., pagination.nextPageToken, data.paging.next). Required when paginating. The value at this path is extracted and used for the next request.
Next Page Key	Text	No	Initial pagination token value (if pagination requires a starting point). Leave empty if the API returns the first page without a token.
Next Page Key Behaviour	Dropdown	Conditional	Where the pagination token is placed in the next request. Options: Key As Params (query parameter), Key As Url (appended to URL), Key as Header (added to headers). Required when using pagination.
Replace Next Page Key With	Text	Conditional	Placeholder to replace with the pagination token in URL or body (e.g., {{nextPageToken}}). Used to inject the token into the correct location for the next paginated request.
Read Next Page Key from Header	Boolean	No	Enable to extract the pagination token from a response header instead of the response body. Useful for APIs using header-based pagination.
Delay	Number	No	Delay in milliseconds between paginated requests. Use to respect API rate limits. Default: 0 (no delay).

File Export Configuration

Field Name	Type	Required	Description
Export File	Boolean	No	When enabled, the API response is exported to a file. Default: false. Enabling this reveals Export File Type field.
Export File Type	Dropdown	Conditional	Format for exported files. Options: JSON, CSV. Only shown when Export File is true. When JSON, each API response is saved as a separate file. When CSV, the data is extracted from the field specified in JSON Field and must be in CSV string format.
JSON Field	Text	Conditional	For CSV export only: Specifies which field in the API response contains the CSV string data (e.g., data.csvContent, exportData). The value at this field path should be a string containing the raw CSV data (with headers and rows). When found, this CSV data is parsed and exported to a file.

Error Handling

Field Name	Type	Required	Description
Continue Execution on Failure	Boolean	No	When enabled, the workflow continues even if the API request fails or returns an error status. Useful for optional API calls or retry logic. When disabled, workflow stops on API errors.

Conditional Field Rendering Rules

The following fields appear/become required based on other field values:

• Body: Becomes required when Request Type is POST, PUT, or PATCH
• Export File Type: Shown when Export File is enabled
• JSON Field: Shown and becomes required when Export File Type is set to CSV
• Pagination Fields (Next Page Key Path, Replace Next Page Key With, Next Page Key Behaviour): All shown together; enable when your API uses pagination
• FileKey & Input File Pattern: Shown when Content Type is multipart/form-data (for file uploads)

---

Sample Input

Not applicable for static requests. See Sample Configurations for examples with input data.

---

Sample Configurations

Scenario 1: Simple GET Request with Pagination

Fetch paginated customer list from an API with cursor-based pagination.

Field	Value
Connection	api-oauth
Request Type	GET
Request URL	https://api.example.com/v1/customers
Response Type	JSON
Content Type	JSON
URL Params	limit = 50
Root of Response	data.customers
Next Page Key Path	data.pagination.cursor
Next Page Key Behaviour	Key As Params
Replace Next Page Key With	cursor={{cursor}}
Include Headers in Response	false

Data Flow:

• Executes GET request to fetch first 50 customers
• Extracts data.pagination.cursor from response
• Automatically makes next request with cursor parameter
• Combines all pages into single output list

---

Scenario 2: POST Request with Form Data and Dynamic Parameters

Submit customer data row-by-row to create customer records using form data.

Field	Value
Connection	api-basic-auth
Request Type	POST
Request URL	https://api.example.com/customers
Response Type	JSON
Content Type	form-url-encoded
Form Data	email = @[email], name = @[name], phone = @[phone]
Parameters	Select: email, name, phone
Use All Rows as Part of Request	false
Include Headers in Response	false
Continue Execution on Failure	true

Data Flow:

• Input has 100 customer rows
• Each row creates separate POST request with form data
• Placeholders (@[email], @[name], @[phone]) replaced with each row’s values
• Results combined into output list
• If one request fails, workflow continues (due to Continue on Failure)

---

Scenario 3: POST with Batch Processing and CSV Export

Submit all input records in batch to create records, then export results as CSV.

Field	Value
Connection	api-api-key
Request Type	POST
Request URL	https://api.example.com/batch/import
Response Type	JSON
Content Type	JSON
Body	{ "records": @[allData], "format": "json" }
Parameters	Select: allData
Use All Rows as Part of Request	true
Export File	true
Export File Type	CSV
JSON Field	importResults
Root of Response	data

Data Flow:

• Input has 100 customer records
• All 100 rows combined into single POST request body as JSON array
• API processes batch and returns results
• Response data extracted (from data path)
• Exported to CSV file with data from importResults field
• Output includes file references and data

---

Scenario 4: Multipart File Upload with Form Data

Upload files with metadata using multipart/form-data.

Field	Value
Connection	api-bearer-token
Request Type	POST
Request URL	https://api.example.com/files/upload
Response Type	JSON
Content Type	multipart/form-data
Form Data	uploadedBy = @[username], department = @[dept]
File Field Name (FileKey)	document
Input File Pattern	.*\.pdf$ (matches PDF files only)
Parameters	Select: username, dept
Include Headers in Response	true

Data Flow:

• Input includes files matching PDF pattern and metadata rows
• Each file uploaded with accompanying form data
• Form field uploadedBy and department populated from input data using @[username] and @[dept]
• Files filtered by regex pattern (*.pdf)
• Response headers included in output (useful for tracking rate limits, request IDs)

---

Sample Output

Output from Scenario 1 (Paginated GET)

{
  "Data": [
    {
      "id": "cust_001",
      "name": "John Smith",
      "email": "[email protected]",
      "status": "active",
      "createdAt": "2024-01-15T10:30:00Z",
      "Request Url": "https://api.example.com/v1/customers?limit=50&cursor=abc123",
      "Response": "{\"id\":\"cust_001\",\"name\":\"John Smith\",...}",
      "HeaderResponse": {
        "content-type": ["application/json"],
        "x-ratelimit-remaining": ["4999"],
        "x-ratelimit-reset": ["1705334400"]
      },
      "APIResponseCode": 200,
      "API": true
    },
    {
      "id": "cust_002",
      "name": "Jane Doe",
      "email": "[email protected]",
      "status": "active",
      "createdAt": "2024-01-16T14:22:00Z",
      "Request Url": "https://api.example.com/v1/customers?limit=50&cursor=def456",
      "Response": "{\"id\":\"cust_002\",\"name\":\"Jane Doe\",...}",
      "HeaderResponse": {...},
      "APIResponseCode": 200,
      "API": true
    }
  ],
  "Files": [],
  "AdditionalResponse": "[{\"id\":\"cust_001\",...}, {\"id\":\"cust_002\",...}]"
}

Output from Scenario 2 (Form Data POST - Row Iteration)

{
  "Data": [
    {
      "id": "cust_101",
      "email": "[email protected]",
      "name": "Alice Brown",
      "phone": "555-1234",
      "created": true,
      "Request Url": "https://api.example.com/customers",
      "Response": "{\"id\":\"cust_101\",\"created\":true}",
      "HeaderResponse": {...},
      "APIResponseCode": 201,
      "API": true
    },
    {
      "id": "cust_102",
      "email": "[email protected]",
      "name": "Bob Johnson",
      "phone": "555-5678",
      "created": true,
      "Request Url": "https://api.example.com/customers",
      "Response": "{\"id\":\"cust_102\",\"created\":true}",
      "HeaderResponse": {...},
      "APIResponseCode": 201,
      "API": true
    }
  ],
  "Files": [],
  "AdditionalResponse": "[{\"id\":\"cust_101\",...}, {\"id\":\"cust_102\",...}]"
}

Note: Two separate POST requests were made (one for each input row). Each output row contains the response from its corresponding API call.

Output from Scenario 3 (Batch POST with CSV Export)

{
  "Data": [
    {
      "recordId": "rec_001",
      "status": "imported",
      "rowsProcessed": 100,
      "FileName": "Response-0-a1b2c3d4.json",
      "Request Url": "https://api.example.com/batch/import",
      "Response": "{\"recordId\":\"rec_001\",\"status\":\"imported\",\"rowsProcessed\":100}",
      "HeaderResponse": {...},
      "APIResponseCode": 200,
      "API": true
    }
  ],
  "Files": [
    {
      "FileName": "Data-a1b2c3d4.csv",
      "FullPath": "/workflows/temp/Data-a1b2c3d4.csv",
      "Size": 5242
    }
  ],
  "AdditionalResponse": "[{\"recordId\":\"rec_001\",...}]"
}

Note: Only ONE data row because all 100 input rows were combined into a single batch request. The FileName field references the exported CSV file (exported from the importResults field in the API response).

Output with Nested JSON Flattening

When API returns nested response with Root of Response = data.customers and IncludeHeadersInResponse = true:

Original API Response:

{
  "data": {
    "customers": [
      {
        "id": 1,
        "name": "John",
        "address": {
          "street": "123 Main",
          "city": "Boston",
          "zip": "02101"
        }
      }
    ]
  }
}

Flattened Output (with headers included):

{
  "Data": [
    {
      "id": 1,
      "name": "John",
      "address.street": "123 Main",
      "address.city": "Boston",
      "address.zip": "02101",
      "Request Url": "https://api.example.com/v1/customers",
      "Response": "{\"id\":1,\"name\":\"John\",...}",
      "HeaderResponse": {...},
      "APIResponseCode": 200,
      "API": true,
      "content-type": "application/json",
      "x-ratelimit-remaining": "4999",
      "cache-control": "max-age=3600"
    }
  ],
  "Files": [],
  "AdditionalResponse": "[{\"id\":1,...}]"
}

Key Points:

• Nested fields are flattened with dot notation (address.street, address.city)
• Root of Response extracts only the data.customers portion
• When IncludeHeadersInResponse is true, response headers appear as individual fields
• Metadata fields (Response, HeaderResponse, API, APIResponseCode, Request Url) are always included

---