API Request block

Call any HTTP API from a workflow step, with the method, headers and body you configure, and use the response in later steps.

The API Request block calls one HTTP endpoint and parses the response so later steps can use it. Use it for a system that has an API but no Loopfour integration. In a workflow definition it is a step with type: "action" and action: "api.request".

When to use it

Pull a report or a list of records from an internal or third-party API.
Post data to a system Loopfour has no block for.
Download a CSV or PDF over HTTP and hand it to a Data Table, PDF or Workspace Files step.

If the system has an integration block, prefer it: it uses the saved connection and maps the system's errors.

Configuration

Field (`config` key)	Editor label	Type	Required	Meaning
`url`	URL	string	Yes	Absolute `https` URL. Plain `http` is refused (see Errors and limits). Accepts template references such as `{{input.reportId}}`.
`method`	Method	string	Yes	`GET`, `POST`, `PUT`, `PATCH` or `DELETE`. Default `GET`.
`params`	Query Params	object or `[{Key, Value}]` table	No	Added to the URL query string.
`headers`	Headers	object or `[{Key, Value}]` table	No	Request headers. Put credentials in a secret: `Authorization: Bearer {{secrets.MY_API_KEY}}`.
`body`	Body	object or string	No	An object is sent as JSON with `Content-Type: application/json`. A string is sent as is; a string that parses as JSON gets the JSON content type when you set none.
`responseFormat`	Response Format	string	No	`auto` (default), `json`, `csv`, `text`, `pdf` or `binary`. `auto` picks a format from the response content type.
`csvDelimiter`	CSV Delimiter	string	No	Delimiter for `csv`. Default `,`.
`timeout`	Timeout (ms)	number	No	Request timeout. Default 300000, capped at 600000.
`retries`	Retries	number	No	Extra attempts after a timeout, network error, 408, 429 or 5xx response. Default 0.
`retryDelayMs`	Retry Delay (ms)	number	No	First retry delay. Doubles each attempt. Default 500. A `Retry-After` header takes precedence.
`retryMaxDelayMs`	Max Retry Delay (ms)	number	No	Upper bound on a retry delay. Default 30000.
`retryNonIdempotent`	Retry POST/PATCH	boolean	No	Allow retries for `POST` and `PATCH`. Off by default, because a retry can repeat a side effect such as creating a payment twice.
`maxResponseBytes`	Max Response (bytes)	number	No	Fail rather than load a larger response. Default 20971520 (20 MB).
`failOnError`	Fail On Error Status	boolean	No	Default `true`: a non-2xx response fails the step. Set `false` to keep going and branch on `status` or `ok`.

Output

Field	Type	When present	Meaning
`ok`	boolean	Always	`true` for a 2xx response.
`status`	number	Always	HTTP status code.
`statusText`	string	Always	HTTP status text.
`headers`	object	Always	Response headers, lower-case names.
`contentType`	string	Always	Response content type.
`sizeBytes`	number	Always	Response size in bytes.
`responseFormat`	string	Always	The format used to parse the body.
`data`	any	Always	Parsed body: the JSON value, the CSV rows, the text, or the base64 content for `binary`.
`text`	string	`json`, `csv`, `text`, `pdf`	The body as text. For `pdf`, the extracted text.
`rows`	array	`csv`	One object per data row, keyed by header.
`columns`	array	`csv`	Header names.
`rowCount`	number	`csv`	Number of data rows.
`pageCount`	number	`pdf`	Pages in the PDF.
`content`	string	`pdf`, `binary`	The body as base64.
`contentEncoding`	string	`pdf`, `binary`	`base64`.

Read a JSON field as {{steps.<step id>.data.<path>}}. Pass a downloaded file to a Workspace Files saveFile step with content set to {{steps.<step id>.content}}.

Example

This workflow fetches an aging report as CSV and upserts the rows into a table. The token is stored as a company secret named AR_REPORT_TOKEN.

{
  "name": "Import AR aging report",
  "trigger": { "type": "schedule", "cron": "0 7 * * 1-5", "timezone": "America/New_York" },
  "steps": [
    {
      "id": "fetch_aging",
      "type": "action",
      "name": "Fetch AR aging CSV",
      "action": "api.request",
      "config": {
        "url": "https://reports.example.com/v1/ar-aging",
        "method": "GET",
        "params": { "asOf": "today", "format": "csv" },
        "headers": { "Authorization": "Bearer {{secrets.AR_REPORT_TOKEN}}" },
        "responseFormat": "csv",
        "retries": 2
      }
    },
    {
      "id": "save_rows",
      "type": "data_table",
      "name": "Upsert aging rows",
      "config": {
        "operation": "upsertMany",
        "tableId": "8c1f0f5e-2a4b-4c55-9a64-0d2f3e6b7a10",
        "matchKey": "invoiceNumber",
        "rows": "{{steps.fetch_aging.rows}}"
      }
    }
  ]
}

Errors and limits

A non-2xx response fails the step with the status and up to 500 characters of the body, unless failOnError is false.
A response marked or forced as json that does not parse fails the step with Response was not valid JSON.
A response larger than maxResponseBytes fails the step and is not retried.
The request goes through Loopfour's outbound network policy. The policy refuses plain http, loopback and private or internal addresses. A refused destination fails the step and is not retried.
With retries exhausted, the step fails with API request to <origin><path> failed after N attempt(s).
Secrets in headers are substituted at run time and removed from the stored step output. See Variable references.