Customize API Request Tool requests

Now that your coffee-order assistant can submit a basic order, you can add the information your API needs to process the customer’s order. In this guide, you’ll add HTTP headers, fixed application metadata, call-time Liquid values, and authentication while keeping customer-provided values in the model-generated request body. Separating these values makes requests more predictable, prevents the model from inventing trusted application data, and gives your server the context it needs to validate and route each request.

Prerequisites

• An existing API Request Tool
• An HTTPS endpoint that returns JSON
• For cURL requests, a Vapi API key and the tool ID

Choose where each value comes from

Use the request body schema for values the caller provides or the model infers. Use static body fields for values your application or the call already knows.

For the full static-parameter behavior, supported value types, and trust model, see Static variables and aliases.

Configure the request

The configuration below updates createCoffeeOrder with the X-Docs-Example and X-Docs-Call-Type headers and the source and requestTimestamp static body fields. The endpoint continues to receive customerName, productId, and quantity from the model.

Dashboard

cURL

1

Open the tool

Open the Dashboard, select Tools, then select createCoffeeOrder.

2

Configure the endpoint

Under Base Configuration, set Request URL to https://vapi-docs-orders.val.run/ and Request HTTP Method to POST.

Set the HTTP method explicitly. API Request Tools support GET, POST, PUT, PATCH, and DELETE. See the Create Tool API reference for the complete API Request Tool schema.

3

Define the model-generated body

Under Request Body, add these required properties:

Property	Type	Configuration
customerName	String	Description: Customer name for the order.
productId	String	Allowed values: coffee-beans, tea-sampler, ceramic-mug
quantity	Integer	Minimum: 1; description: The confirmed quantity.

Set the productId description to The product the customer confirmed. Then enable Lock schema (no additional properties).

4

Add request headers

Expand Request Headers, then add these string headers:

Header	Value
X-Docs-Example	coffee-order
X-Docs-Call-Type	{{ call.type }}

Use request headers for non-sensitive HTTP metadata. The call.type Liquid value resolves when the tool runs.

5

Add static body fields

Under Static Body Fields, select Add Field and add these fields:

Key	Type	Value
source	String	inbound-phone
requestTimestamp	String	{{ "now" | date: "%Y-%m-%dT%H:%M:%SZ", "UTC" }}

Vapi merges these fields into the request body after the model generates its values. A static body field overrides a model-generated field with the same key.

6

Publish the tool

Select Publish.

Define model-generated request values

The body JSON Schema is the source of truth for the arguments the model can generate. For requests with a JSON body, Vapi uses those arguments to construct the body sent to the endpoint.

Write a specific description for every property. Add required properties to required, and constrain known values with enum, a format, or another supported schema rule.

Use Liquid values at request time

Liquid values resolve when the API Request Tool runs. You can use them in the request URL, request header values, and static body field values.

In the request configuration above, X-Docs-Call-Type uses {{ call.type }} for direct substitution, while requestTimestamp uses the LiquidJS date filter to generate an ISO-8601 UTC timestamp. See Default variables for the complete runtime-variable list and Advanced date and time usage for formatting syntax.

Authenticate requests

An API Request Tool can reference a reusable Custom Credential through its credentialId. This endpoint credential is separate from the Vapi API key used to create or update the tool.

The public coffee-order endpoint does not require authentication. Attach a credential only when configuring a protected endpoint that you control.

Verify the request

Place an inbound test call after publishing the tool. The public endpoint returns a sanitized requestContext object when it detects any advanced configuration field:

1
{
2
  "requestContext": {
3
    "advancedConfigurationDetected": true,
4
    "headers": {
5
      "docsExampleReceived": true,
6
      "docsExampleMatchesExpectedValue": true,
7
      "callTypeResolved": true,
8
      "callTypeSupported": true
9
    },
10
    "staticBodyFields": {
11
      "sourceReceived": true,
12
      "sourceMatchesExpectedValue": true,
13
      "requestTimestampResolved": true,
14
      "requestTimestampValid": true,
15
      "requestTimestampRecent": true
16
    }
17
  }
18
}

Each value should be true. The endpoint validates the call type and request timestamp without returning a call identifier or caller phone number.

If the request fails, compare the saved tool configuration with the endpoint’s expected HTTP method, URL, headers, and JSON body. The endpoint must return JSON for a successful response. For broader tool-call issues, see Custom tools troubleshooting.