> ## Documentation Index
> Fetch the complete documentation index at: https://docs.conversion.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# HTTP Request

> Call any external API from a workflow and write values from the response back onto contact and company fields.

The HTTP request node sends a request to any external API when a contact reaches that step, then writes values from the JSON response onto fields on the contact or their company. Use it to look up data that lives in another system, push a record into a tool that has no native integration, or trigger an action in your own API — and, unlike a one-way webhook, bring the answer back into Conversion.

Add the node from the node picker under **Messages**.

<Info>
  If you only need to send data out and do not care about the response, the [Webhooks](/product-docs/workflows/nodes/webhooks) node is simpler: you configure the endpoint once in Settings and reuse it across workflows. Use the HTTP request node when you need to shape the request yourself or read something back.
</Info>

## Configuration

| Setting     | Description                                                                                           |
| ----------- | ----------------------------------------------------------------------------------------------------- |
| **Method**  | The HTTP method to use: Get, Post, Put, Patch, Delete, or Head.                                       |
| **URL**     | The URL the request is sent to. Must use HTTPS, and supports [Liquid](/product-docs/liquid/overview). |
| **Headers** | Sent with the request. Credentials belong here. Both the name and the value support Liquid.           |
| **Body**    | A JSON payload sent with the request. Supports Liquid. Only available for Post, Put, and Patch.       |
| **Fields**  | Write values from the JSON response onto fields. Each row pairs a data path with the field it fills.  |

### Personalizing the request

The URL, every header name and value, and the body all support Liquid, so each contact can get a different request. Reference contact and company fields the same way you would in an email:

```json theme={null}
{
  "email": "{{ contact.email }}",
  "company": "{{ company.name }}"
}
```

A contact whose email is `ada@example.com` produces `{"email": "ada@example.com", ...}`. The same works in the URL — `https://api.example.com/contacts/{{ contact.email }}` — and in headers.

### Authentication

There is no separate credential store for this node. Add the credential your API expects as a header, most commonly:

| Name            | Value                   |
| --------------- | ----------------------- |
| `Authorization` | `Bearer your-api-token` |

<Warning>
  Credentials you enter here are saved as part of the workflow configuration, so anyone who can edit the workflow can read them. Use a token scoped to only what the request needs, and rotate it if workspace access changes.
</Warning>

### Mapping the response to fields

Each row under **Fields** takes a data path, the field to write, and whether to overwrite.

| Setting                       | Description                                                                                                  |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Data path**                 | A path into the JSON response, such as `$.results[0].email`.                                                 |
| **Field**                     | The contact or company field that receives the value. Read-only fields cannot be selected.                   |
| **Overwrite existing values** | When **off** (default), only empty fields are filled. When **on**, the field is replaced with the new value. |

Paths start at the root of the response body. Use dots for object keys and square brackets for array positions, which are counted from zero:

| Path                   | Reads                                 |
| ---------------------- | ------------------------------------- |
| `$.email`              | A top-level `email` key               |
| `$.data.company.name`  | A nested key                          |
| `$.results[0].email`   | The first item of the `results` array |
| `$.data["first name"]` | A key containing a space              |

For a response like this:

```json theme={null}
{
  "data": {
    "company": { "name": "Acme", "size": 42 },
    "tags": ["enterprise", "priority"]
  }
}
```

`$.data.company.name` returns `Acme` and `$.data.company.size` returns `42`. `$.data.tags` returns nothing, because a field holds a single value rather than a list — map `$.data.tags[0]` instead to take the first tag.

## Behavior

* The node sends one request per contact that reaches it, at the moment the contact arrives.
* Only HTTPS URLs are allowed. If the API redirects the request, the redirect must also be HTTPS.
* A request that takes longer than 15 seconds, or a response larger than 1 MB, is treated as a failure.
* Only single values map onto fields — text, numbers, and true/false. Objects, lists, and `null` are ignored.
* The value must suit the field: a number field only accepts a number, and a date field only accepts a date. Mappings that do not match are skipped and the rest still apply.
* Paths that are not found in the response are skipped. If no path resolves, the step completes without changing anything.
* If the API returns an error status, no fields are written and the step is recorded as failed. The request is not retried.
* The contact continues to the next node whether the request succeeded or failed.

<Info>
  Open the [workflow run](/product-docs/workflows/runs) for a contact to see how the step behaved, including the status code the API returned and how many of your paths resolved.
</Info>

## Best practices

* **Test against the real endpoint first.** Send the request from your own API client and inspect the JSON before you write data paths, so you are mapping against a response you have actually seen rather than one you expect.
* **Start with overwrite off.** Leave **Overwrite existing values** off for anything your own data should own, so the API only fills gaps. Turn it on for fields where the external system is the source of truth.
* **Keep the request small.** Send only the fields the API needs. The body is stored with the workflow and sent on every run, so trimming it limits what leaves Conversion.
* **Branch on what you get back.** Follow the node with an [If/Else Branch](/product-docs/workflows/nodes/if-else-branch) on a field you just filled to handle contacts the lookup could not resolve.
* **Put enrichment first.** If the request personalizes on data you do not always have, run [Magic Enrichment](/product-docs/workflows/nodes/magic-enrichment) or [Apollo Enrichment](/product-docs/workflows/nodes/apollo-enrichment) upstream so the request goes out complete.