> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.vapi.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.vapi.ai/_mcp/server.

# Use API Request tool response data

> Use API Request Tool JSON responses immediately, extract response fields with schemas or aliases, and pass extracted variables to subsequent tools.

A successful API Request Tool response is available to the model as a tool result. The model can use it immediately without additional response configuration. Configure variable extraction only when later tools or assistants need to reference specific response values through Liquid.

## Prerequisites

* An API Request Tool whose endpoint returns JSON
* For cURL requests, a [Vapi API key](/security-and-privacy/api-keys) and the tool ID

## Choose how to use the response

| Goal                                                          | Configuration                                                                             |
| ------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| Let the assistant speak values from the current response      | None. Instruct the assistant to use the tool result.                                      |
| Store selected response fields under explicit variable names  | Add aliases to `variableExtractionPlan`.                                                  |
| Extract a larger response shape with its existing field names | Add a response schema to `variableExtractionPlan`.                                        |
| Send an extracted value in a later request                    | Reference the extracted variable in the later tool's URL, headers, or static body fields. |

The coffee-order quickstart needs only the first option. Its assistant reads `orderId`, `productName`, `quantity`, and `totalDisplay` from the successful tool result, then ends the conversation. Extraction would add configuration without changing that experience.

> **Note**
>
> The tool's **Request Body** defines values the model sends to the API. **Response Body** and **Aliases** extract values returned by the API. They serve different directions of the request.

## Use the immediate tool result

Return concise JSON with descriptive field names and instruct the assistant which fields are authoritative. For the coffee-order assistant, the system prompt includes:

**`Response instructions`**

```txt title="Response instructions" wordWrap
After a successful tool response, confirm the product, quantity, five-digit order number, and server-calculated total. Never read the internal requestId aloud.
```

No response schema or alias is required for that instruction. The model receives the successful JSON result and can use those values in its next response.

See [Handle responses and errors](/tools/api-request/response-handling) for the coffee endpoint's success and failure contracts.

## Extract selected values with aliases

Aliases copy selected values from a JSON response into the call's variable bag. Use names that describe their source and purpose to avoid collisions with variables created by other tools.

The alias configuration below stores `orderId`, `totalDisplay`, and `productName` from a successful coffee-order response under coffee-order-specific variable names:

#### Dashboard

#### Open the tool

Open the [Dashboard](https://dashboard.vapi.ai), select **Tools**, then select `createCoffeeOrder`.

#### Add aliases

Expand **Aliases**, then add:

| Original field name | Alias name           |
| ------------------- | -------------------- |
| `orderId`           | `coffeeOrderId`      |
| `totalDisplay`      | `coffeeOrderTotal`   |
| `productName`       | `coffeeOrderProduct` |

![Vapi Dashboard Aliases mapping orderId, totalDisplay, and productName to coffee-order variable names](/_fern-files/_img/3dbde65e4cfed6d0628da8b86164268ef2896bfeca109ac615b8e14e7d239f60.webp)

#### Publish the tool

Select **Publish**.

#### cURL

Set your API key and coffee-order tool ID:

```bash
export VAPI_API_KEY="YOUR_VAPI_API_KEY"
export VAPI_TOOL_ID="YOUR_TOOL_ID"
```

Add the aliases with the [Update Tool endpoint](/api-reference/tools/update):

```bash
curl --request PATCH \
  --url "https://api.vapi.ai/tool/$VAPI_TOOL_ID" \
  --header "Authorization: Bearer $VAPI_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "variableExtractionPlan": {
      "aliases": [
        {
          "key": "coffeeOrderId",
          "value": "{{ $.orderId }}"
        },
        {
          "key": "coffeeOrderTotal",
          "value": "{{ $.totalDisplay }}"
        },
        {
          "key": "coffeeOrderProduct",
          "value": "{{ $.productName }}"
        }
      ]
    }
  }'
```

After a successful tool call, the values are available as `{{ coffeeOrderId }}`, `{{ coffeeOrderTotal }}`, and `{{ coffeeOrderProduct }}` for the remainder of the call.

## Extract a response shape

Use a response schema when you want to extract several fields under their existing names. For an object response, each property listed in the schema becomes a call-level variable.

#### Dashboard

Under **Response Body**, add these properties:

| Property       | Type   | Required |
| -------------- | ------ | -------- |
| `orderId`      | Number | Yes      |
| `productName`  | String | Yes      |
| `totalDisplay` | String | Yes      |

Publish the tool. After a successful request, the values are available as `{{ orderId }}`, `{{ productName }}`, and `{{ totalDisplay }}`.

![Vapi Dashboard Response Body extracting orderId, productName, and totalDisplay](/_fern-files/_img/5c7f58fab3069564221ee3099b9af3789e7e17cf9980c80ec5039e08b513dcca.webp)

#### cURL

Add the response schema with the [Update Tool endpoint](/api-reference/tools/update):

```bash
curl --request PATCH \
  --url "https://api.vapi.ai/tool/$VAPI_TOOL_ID" \
  --header "Authorization: Bearer $VAPI_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "variableExtractionPlan": {
      "schema": {
        "type": "object",
        "properties": {
          "orderId": {
            "type": "integer"
          },
          "productName": {
            "type": "string"
          },
          "totalDisplay": {
            "type": "string"
          }
        },
        "required": ["orderId", "productName", "totalDisplay"]
      }
    }
  }'
```

Prefer aliases when you want unique names, a nested response path, or a Liquid transformation. Prefer a schema when the response already has clear field names and you want to extract several fields together. Do not configure both approaches for the same values unless you intentionally need both variable names.

## Pass a value to a later tool

Reference an extracted value with Liquid in a subsequent tool. Use a static body field when the model should not choose or rewrite the value.

#### Dashboard

Open the later tool. Under **Static Body Fields**, add this field:

| Key       | Type   | Value                 |
| --------- | ------ | --------------------- |
| `orderId` | String | `{{ coffeeOrderId }}` |

The field is merged into the later request when that tool runs. The model does not supply it as an argument.

#### cURL

Replace `YOUR_FOLLOWUP_TOOL_ID` with the later tool's ID, then update it with the [Update Tool endpoint](/api-reference/tools/update):

```bash
export VAPI_FOLLOWUP_TOOL_ID="YOUR_FOLLOWUP_TOOL_ID"

curl --request PATCH \
  --url "https://api.vapi.ai/tool/$VAPI_FOLLOWUP_TOOL_ID" \
  --header "Authorization: Bearer $VAPI_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "parameters": [
      {
        "key": "orderId",
        "value": "{{ coffeeOrderId }}"
      }
    ]
  }'
```

This passes the extracted value deterministically, without relying on the model to copy the order ID from one tool result into another tool call.

## Verify extracted values

Place a test call that completes the source tool before any tool that consumes its variables.

#### Dashboard

Open [Logs](https://dashboard.vapi.ai/logs), select the call, and confirm that the source tool succeeded before the later tool ran. Inspect the call's messages to confirm the expected response fields were present.

#### cURL

Retrieve the completed call:

```bash
export VAPI_CALL_ID="YOUR_CALL_ID"

curl --request GET \
  --url "https://api.vapi.ai/call/$VAPI_CALL_ID" \
  --header "Authorization: Bearer $VAPI_API_KEY"
```

Confirm that `artifact.variableValues` contains the alias keys and expected values. See the [Get Call API reference](/api-reference/calls/get) for the full Call schema.

## Apply extraction safely

* Extraction requires a JSON response. Plain text, HTML, and malformed JSON cannot provide response variables.
* Extracted values are available only after the source tool succeeds. Do not run a dependent tool first.
* Variable names are global for the call. Use unique, descriptive names to prevent collisions.
* Aliases improve deterministic forwarding; they do not hide data from the model. The complete tool response remains in the model's conversation history.
* Never return a secret in the response body expecting extraction to conceal it. Keep secrets out of model-visible responses.
* An extracted value is only as trustworthy as its source. Validate caller-controlled values on your server before using them for sensitive actions.

For nested objects, arrays, Liquid transformations, and the full trust model, see [Variable extraction plan (aliases)](/tools/static-variables-and-aliases#variable-extraction-plan-aliases). For static-field behavior, see [Static variables and aliases](/tools/static-variables-and-aliases).