> ## Documentation Index
> Fetch the complete documentation index at: https://www.integrate.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# ETL: API Call Transformation
> How to configure the API Call transformation to enrich pipeline rows with data from an HTTP API in your Integrate.io ETL pipeline.
The API Call transformation calls an HTTP API once per input row and enriches that row with fields parsed from the JSON response. Rows flow in, the component makes a request (using values from each row), and rows flow out with the response fields you selected appended. It is the first-class way to do mid-pipeline API lookups, replacing hand-written `Curl()` expressions and manual JSON parsing.
## Overview
* Operates per record: one API call for each input row.
* Enriches 1:1: every input row passes through unchanged and gains the response fields you select, so the output row count equals the input row count.
* Builds the request from row values using `#{field}` placeholders in the URL, headers, and body.
* Parses the response with a JSON Path and projects the fields you choose.
* Supports None, Basic, and saved Connection authentication, so you can reuse a connection's access token instead of hardcoding credentials.
A common pattern is "list and get": a [REST API Source](/etl/using-components-rest-api-source) lists items (each carrying a detail URL), then the API Call transformation calls `#{url}` for each row to fetch and attach the details.
## Configuration
Drop the API Call component into the pipeline designer, connect an input to it, and open it to configure the request and the response.
### Request
| Field | Description |
| :------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- |
| Method | HTTP method: GET, POST, PUT, PATCH, or DELETE. |
| URL | The endpoint to call. Supports `#{field}` placeholders that are replaced with each row's value (for example, `https://api.example.com/users/#{id}`). |
| Authentication | How to authenticate the request: None, Basic, or Connection (see [Authentication](#authentication)). |
| Headers | Request headers as name and value pairs. Values support `#{field}` placeholders (for example, `Authorization: Bearer #{token}`). |
| Body | The request body (JSON) for methods that send one. Supports `#{field}` placeholders. |
### Authentication
| Option | Description |
| :--------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| None | No authentication is added to the request. |
| Basic | Adds HTTP Basic auth from the Username and Password you enter. |
| Connection | Uses a saved connection's credentials or access token, the same way the [REST API Source](/etl/using-components-rest-api-source) does. Choose an existing connection or create a new one. This avoids putting tokens directly in the component. |
### Response and Fields
| Field | Description |
| :--------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| JSON Path | The path applied to the response to locate the data to extract. Use `$` for the whole response object, or a path such as `$.result` to drill into a wrapper. The first match is used. |
| Detect fields from API | Makes a single sample request and uses the real response to suggest a JSON Path and list the fields it found, so you can pick them without typing them by hand. See [Detecting fields](#detecting-fields). |
| Response fields | The fields extracted from the matched JSON and appended to each row. |
| Fail on error | When on, a failed call (non-2xx or network error) or a JSON Path that matches nothing fails the job. When off, the row passes through with null values for the response fields and the job continues. Default: on. |
| Request sleep interval | Milliseconds to wait between calls, used to stay within an API's rate limits. |
Two reserved response fields are available under the **Meta Data** tab of the field picker, populated from the HTTP response itself rather than its body:
| Field | Type | Description |
| :----------------- | :------ | :--------------------------------------- |
| `http_status_code` | integer | The response status code. |
| `http_headers` | string | The response headers serialized as JSON. |
These stay populated even when a call returns an error and Fail on error is off, so a downstream component can branch on the real status while the body fields are null.
## Detecting fields
Because `#{field}` placeholders are only resolved at run time, the component can sample a real response so you do not have to define fields manually.
Set the method, URL, authentication, and any headers or body.
The component makes a single sample request through the upstream data, then displays the response and suggests a JSON Path.
Accept the suggested JSON Path (or enter your own) and choose the fields to add to your rows.
## Example
Enrich a list of records with details fetched per row.
1. A [REST API Source](/etl/using-components-rest-api-source) reads a list endpoint, producing one row per item with fields such as `url` and `title`.
2. An API Call transformation is connected after it:
* Method: `GET`
* URL: `#{url}`
* JSON Path: `$`
* Response fields: `director`, `release_date`
3. For each input row, the component calls that row's `url`, parses the response, and appends `director` and `release_date`.
The output has the same number of rows as the input. Each row keeps its original fields (`url`, `title`) and gains the selected response fields (`director`, `release_date`), which are then available to downstream components.
## Best Practices
* **Use Connection authentication** for any API that needs a token, so credentials live in a managed connection instead of in the component.
* **Set a request sleep interval** when the target API enforces rate limits. Each row is a separate call, so high-volume inputs can hit limits quickly.
* **Decide on Fail on error deliberately.** Leave it on to stop the job on bad responses, or turn it off to let rows pass through with null enrichment (and inspect `http_status_code` downstream).
* **Use `#{field}` placeholders** to drive per-row URLs, headers, and bodies from upstream data.
* **Remember that Preview makes real API calls** to the configured endpoint, just like a job run.
## FAQ
**How many API calls does this component make?**
One call per input row during a job run. **Detect fields from API** makes a single call, regardless of how many rows are upstream, because it only needs one sample response to infer the fields.
**Does the API Call transformation change the number of rows?**
No. It enriches each input row 1:1, so the output row count equals the input row count.
**Can I reuse a saved connection's token instead of entering credentials?**
Yes. Set Authentication to Connection and choose a saved connection. The component uses that connection's credentials or access token for every request.
**What happens when a request fails?**
It depends on Fail on error. When on, a non-2xx response, a network error, or a JSON Path with no match fails the job. When off, the row passes through with null response fields and the job continues, while `http_status_code` and `http_headers` still reflect the real response.
## Related