# API Step

The **API** step makes an HTTP request to any external endpoint and optionally extracts data from the response into lead fields for use in downstream steps.

<figure><img src="/files/K8xkOh6YIFKgiw0dxZDt" alt=""><figcaption><p>The API step configuration panel with method, URL, JSON body, and field extraction.</p></figcaption></figure>

## Configuration

### Method and URL

Select the HTTP method (**GET**, **POST**, or **PUT**) and enter the full endpoint URL.

The URL supports variables — you can dynamically construct URLs using lead data. For example:

```
https://api.example.com/enrich?email={{ email }}
```

### Headers

Add request headers as key/value pairs. Common uses:

* `Authorization: Bearer your-api-key`
* `Content-Type: application/json`

Click **Add header** to add rows and the trash icon to remove them.

{% hint style="warning" %}
**Security:** Avoid hardcoding sensitive API keys directly in workflows. Use a secure proxy or environment-specific secrets management where possible.
{% endhint %}

### Body

For **POST** and **PUT** requests, enter the request body as JSON. The editor provides:

* **Syntax highlighting** — JSON keys, strings, and values are color-coded
* **Inline validation** — errors are underlined with a description
* **Format button** — auto-formats and pretty-prints your JSON

The body also supports variables via the **Insert menu** (⚡). For example:

```json
{
  "email": "{{ email }}",
  "company": "{{ company_name }}",
  "source": "spara-workflow"
}
```

### Field Extraction

After the API call completes, Spara can extract values from the response and save them as lead fields. These extracted fields are then available as workflow-scoped variables in downstream steps.

Add one or more **Fields**:

| Field           | Description                                                                  |
| --------------- | ---------------------------------------------------------------------------- |
| **Name**        | The field name (e.g., `intent_score`). Use snake\_case.                      |
| **Description** | Tell the AI what this field represents and where to find it in the response. |

Spara uses the description to intelligently extract the correct value from the API response, even if the response structure is nested or complex.

## Example: Enrich a Lead

```
POST https://api.clearbit.com/v1/people/find
Headers: Authorization: Bearer {{ clearbit_key }}
Body:
{
  "email": "{{ email }}"
}

Field Extraction:
- Name: job_seniority
  Description: The lead's seniority level from the "seniority" field in the response
- Name: linkedin_url
  Description: The lead's LinkedIn profile URL from "linkedin.handle"
```

Downstream steps can then use `{{ job_seniority }}` and `{{ linkedin_url }}` in their content.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.spara.com/agents/workflows/api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.