> 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. # API Request tool quickstart > Build a coffee-order assistant that sends confirmed orders to a public endpoint and reads the server-calculated total and order number back to the caller. In this quickstart, you'll create a coffee-order assistant and place a test order in about 10 minutes. The assistant collects order details, calls a public endpoint, and reads the server-calculated result to the caller. ## What you'll build * An API Request Tool that sends a confirmed coffee order to an HTTP endpoint * An assistant that collects and confirms the order before calling the tool * An inbound phone experience that reads back the server-calculated total and order number ## Prerequisites * [A Vapi account](https://dashboard.vapi.ai) * [A Vapi phone number](/free-telephony) * For the cURL method, a [Vapi API key](/security-and-privacy/api-keys) ## 1. Test the order endpoint Send a coffee order directly to the public test endpoint. ```bash curl --request POST \ --url https://vapi-docs-orders.val.run/ \ --header "Content-Type: application/json" \ --data '{ "customerName": "Alex", "productId": "coffee-beans", "quantity": 2 }' ``` The endpoint returns an HTTP `201` response with a new `requestId` and a randomly generated five-digit `orderId`. ```json { "success": true, "requestId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "orderId": 47730, "mock": true, "customerName": "Alex", "productId": "coffee-beans", "productName": "House coffee beans", "quantity": 2, "totalCents": 3600, "totalDisplay": "$36.00", "message": "Your mock order for 2 House coffee beans was accepted for $36.00." } ``` ## 2. Create the API Request Tool #### Dashboard #### Create an API Request Tool Open the [Dashboard](https://dashboard.vapi.ai), select **Tools**, select **Create Tool**, then choose **API Request**. #### Configure the request Enter the following values under **Base Configuration**: | Field | Value | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Tool Name** | `createCoffeeOrder` | | **Description** | `Creates a mock coffee shop order. Use only after the caller confirms their name, product, and quantity. If the request is rejected, explain the error and help the caller correct the order.` | | **Request URL** | `https://vapi-docs-orders.val.run/` | | **Request HTTP Method** | `POST` | Under **Authorization**, keep **No authentication** selected. This public endpoint is for testing only. #### Define the request body Under **Request Body**, select **Add Property** and add these properties: | Property | Type | Required | Configuration | | -------------- | ------- | -------- | ------------------------------------------------------------ | | `customerName` | String | Yes | Description: `Customer name for the order.` | | `productId` | String | Yes | Allowed values: `coffee-beans`, `tea-sampler`, `ceramic-mug` | | `quantity` | Integer | Yes | Minimum: `1` | Set the `productId` description to `The product the customer confirmed.` and the `quantity` description to `The confirmed quantity.` Then enable **Lock schema (no additional properties)**. ![Vapi Dashboard Request Body with customerName, productId, and quantity as required properties](/_fern-files/_img/a6eb90cd91606e9204ce87841ff1118a2c185cf168637e8fc1aaa77617d1fe1b.webp) #### Publish the tool Select **Publish**. #### cURL #### Set your API key Export your Vapi API key as an environment variable. ```bash export VAPI_API_KEY="YOUR_VAPI_API_KEY" ``` #### Create the tool Send the request to the [Create Tool endpoint](/api-reference/tools/create). ```bash curl --request POST \ --url https://api.vapi.ai/tool \ --header "Authorization: Bearer $VAPI_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "type": "apiRequest", "name": "createCoffeeOrder", "description": "Creates a mock coffee shop order. Use only after the caller confirms their name, product, and quantity. If the request is rejected, explain the error and help the caller correct the order.", "method": "POST", "url": "https://vapi-docs-orders.val.run/", "timeoutSeconds": 20, "body": { "type": "object", "properties": { "customerName": { "type": "string", "description": "Customer name for the order." }, "productId": { "type": "string", "enum": ["coffee-beans", "tea-sampler", "ceramic-mug"], "description": "The product the customer confirmed." }, "quantity": { "type": "integer", "minimum": 1, "description": "The confirmed quantity." } }, "required": ["customerName", "productId", "quantity"], "additionalProperties": false } }' ``` Copy the `id` from the response. You will use it as `YOUR_TOOL_ID` when you create the assistant. ## 3. Create the assistant Use this system prompt in either method: **`System prompt`** ```txt title="System prompt" wordWrap You are a friendly coffee shop order assistant. Available products: - House coffee beans: productId coffee-beans, $18 each - Tea sampler: productId tea-sampler, $14 each - Ceramic mug: productId ceramic-mug, $12 each Help the caller place one order. Collect their name, product, and positive whole-number quantity. Read the complete order back and get explicit confirmation before calling createCoffeeOrder. Never invent a productId and never call the tool before confirmation. After a successful tool response, confirm the product, quantity, five-digit order number, and server-calculated total. Never read the internal requestId aloud. After confirming a successful order, ask whether the caller needs anything else. If they do not, say "Thanks for calling. Goodbye." Do not continue speaking after that closing sentence. ``` #### Dashboard #### Create a blank assistant Select **Assistants**, then select **Create Assistant**. #### Configure the assistant Set **Name** to `Docs Coffee Order Hello World` and **First Message** to: **`First message`** ```txt title="First message" wordWrap Thanks for calling the Vapi coffee shop. What would you like to order? ``` Select OpenAI **GPT 6 Luna** as the model and Vapi **Clara v2** as the voice. Replace **System Prompt** with the prompt above. #### Attach the tool In the assistant's **Tools** section, add `createCoffeeOrder`. #### Configure how the call ends In the assistant editor, set **End Call Message** to `Thanks for calling. Goodbye.` Then add `Thanks for calling. Goodbye.` to **End Call Phrases**. Only the assistant's speech triggers an end call phrase. Using the complete closing sentence keeps the phrase from matching the assistant's opening. #### Publish the assistant Select **Publish**, review the changes, then select **Next**. Review the version and traffic settings, then select **Publish**. #### cURL #### Save the assistant configuration Replace `YOUR_TOOL_ID` with the tool ID returned in the previous section, then save the following as `coffee-order-assistant.json`: **`coffee-order-assistant.json`** ```json title="coffee-order-assistant.json" wordWrap { "name": "Docs Coffee Order Hello World", "firstMessage": "Thanks for calling the Vapi coffee shop. What would you like to order?", "model": { "provider": "openai", "model": "gpt-6-luna", "reasoningEffort": "none", "toolIds": ["YOUR_TOOL_ID"], "messages": [ { "role": "system", "content": "You are a friendly coffee shop order assistant.\n\nAvailable products:\n- House coffee beans: productId coffee-beans, $18 each\n- Tea sampler: productId tea-sampler, $14 each\n- Ceramic mug: productId ceramic-mug, $12 each\n\nHelp the caller place one order. Collect their name, product, and positive whole-number quantity. Read the complete order back and get explicit confirmation before calling createCoffeeOrder. Never invent a productId and never call the tool before confirmation.\n\nAfter a successful tool response, confirm the product, quantity, five-digit order number, and server-calculated total. Never read the internal requestId aloud.\n\nAfter confirming a successful order, ask whether the caller needs anything else. If they do not, say \"Thanks for calling. Goodbye.\" Do not continue speaking after that closing sentence." } ] }, "voice": { "provider": "vapi", "voiceId": "Clara", "version": "latest" }, "endCallMessage": "Thanks for calling. Goodbye.", "endCallPhrases": ["Thanks for calling. Goodbye."] } ``` #### Create the assistant Set `VAPI_API_KEY` to your Vapi API key, then send the file to the [Create Assistant endpoint](/api-reference/assistants/create): ```bash curl --fail-with-body https://api.vapi.ai/assistant \ --header "Authorization: Bearer $VAPI_API_KEY" \ --header "Content-Type: application/json" \ --data-binary @coffee-order-assistant.json ``` Copy the `id` from the response. You will use it as `YOUR_ASSISTANT_ID` when you extend the assistant in [Get order status](/tools/api-request/order-status). ## 4. Connect the phone number Open **Phone Numbers** in the [Dashboard](https://dashboard.vapi.ai), then select your existing phone number. Find **Inbound Settings**, choose `Docs Coffee Order Hello World` from the **Assistant** menu, then select **Save**. If you do not have a number, [request a free Vapi phone number](/free-telephony) before continuing. ## 5. Place a coffee order Call the phone number and order two bags of house coffee beans. Give the assistant your name, then confirm the complete order when it reads the details back. The assistant should call the API only after confirmation. It should then read a five-digit order number and the server-calculated total of `$36.00`. When it asks whether you need anything else, say no. The assistant should say its closing sentence and end the call. ## Next steps #### [Configure requests](/tools/api-request/configuration) Add headers, static fields, Liquid values, and authentication. #### [Handle latency and retries](/tools/api-request/reliability) Configure timeouts, caller messages, and safe handling for failed requests. #### [Handle responses and errors](/tools/api-request/response-handling) Design response contracts and help the assistant recover from failures. #### [Use response data](/tools/api-request/response-data) Extract response values and pass them to later tools. #### [End call phrases](/documentation/assistants/conversation-behavior/end-call-phrases) Learn how spoken phrases end an assistant's call.