Get order status

Extend the configured coffee-order assistant with a second API Request Tool that looks up an order by its five-digit order number. This guide keeps createCoffeeOrder and its request configuration unchanged. You update the existing assistant and keep its connected phone number.

Prerequisites

The coffee-order assistant and createCoffeeOrder tool from the quickstart
The request configuration from Customize API Request tool requests
For cURL, your Vapi API key, the existing tool ID, and the assistant ID from the quickstart

1. Create the status tool

Create one new API Request Tool named getCoffeeOrderStatus. Keep the existing createCoffeeOrder tool and any request configuration you already added to it.

Dashboard

cURL

Create the tool

Open the Dashboard, select Tools, select Create Tool, then choose API Request.

Configure the status request

Enter these values under Base Configuration:

Field	Value
Tool Name	`getCoffeeOrderStatus`
Description	`Gets the status of a mock coffee shop order. Use only after the caller states and confirms a five-digit order number. Never guess an order number or status.`
Request URL	`https://vapi-docs-orders.val.run/lookup`
Request HTTP Method	`POST`

Under Authorization, keep No authentication selected.

Define the request body

Under Request Body, add one required property:

Property	Type	Required	Configuration
`orderId`	Number	Yes	Description: `The five-digit whole-number order ID stated and confirmed by the caller.`

Leave Default value empty. The Dashboard exposes this property as Number; the endpoint still requires a whole number from 10000 through 99999.

Select Apply, enable Lock schema (no additional properties), then select Publish.

Vapi Dashboard Request Body with orderId as the only required property — Require the caller's confirmed order ID

Do not copy the headers, static body fields, or credential from createCoffeeOrder. The status endpoint needs only orderId.

2. Extend the existing assistant

Replace the assistant’s complete System Prompt with the prompt below. It includes the existing product and order instructions plus the new status flow, so do not append it to the old prompt.

System prompt

You are a friendly coffee shop assistant. Help callers place an order or check the status of an existing order.
Available products:
- House coffee beans: productId coffee-beans, $18 each
- Tea sampler: productId tea-sampler, $14 each
- Ceramic mug: productId ceramic-mug, $12 each
Ask one question at a time and keep responses concise. Use tool results to answer naturally. Do not read product IDs, internal field names, the internal requestId, or raw tool responses aloud.
To place an order, collect the caller's name, product, and positive whole-number quantity. If the caller requests an unavailable product, say it is unavailable and offer the listed products. Never substitute another product without confirmation.
Read back the caller's name, product, quantity, and listed unit price, then get explicit confirmation before calling createCoffeeOrder. Never invent a productId, and never call createCoffeeOrder before confirmation.
After a successful createCoffeeOrder response, confirm the product, quantity, and server-calculated total. Read the five-digit order number one digit at a time and tell the caller to save it for a later status check. If createCoffeeOrder fails, do not claim that the order was created or invent an order number or total.
To check order status, collect the five-digit order number. Do not collect the caller's name, product, or quantity, and do not call createCoffeeOrder. Read the order number back one digit at a time and get explicit confirmation before calling getCoffeeOrderStatus. Never guess or complete a partial number.
After a successful getCoffeeOrderStatus response, state the returned order number and communicate the returned statusLabel naturally. If the first lookup finds no order, reconfirm the number and try once more. If no order is found after the second confirmed lookup, apologize, state that the order could not be located, and do not retry again for that request. For any other error, say you could not retrieve the status. Do not guess.
After completing a request, do not reuse its collected name, product, quantity, or order number. If the caller starts another order or status check, collect and confirm the required information again.
After completing the caller's request, ask whether they need anything else. If they do not, say "Thanks for calling. Goodbye." Do not continue speaking after that sentence.

Dashboard

cURL

Update the existing assistant

Open Docs Coffee Order Hello World and update these fields:

Field	Value
First Message	`Thanks for calling the Vapi coffee shop. Would you like to place an order or check an existing order?`
System Prompt	Replace the complete prompt with the system prompt above.

Keep the assistant’s existing end-call settings, other settings, and connected phone number. Do not create another assistant.

Attach the status tool

In Tools, add getCoffeeOrderStatus and keep createCoffeeOrder attached.

Vapi Dashboard assistant Tools section with createCoffeeOrder and getCoffeeOrderStatus attached — Attach both coffee-order tools to the assistant

Publish the assistant

Select Publish, review the changes, then select Quick Publish. The existing phone number remains connected to this assistant.

3. Test two calls

Place an order

Call the connected phone number and follow the quickstart test flow. Save the five-digit order number the assistant reads back.

Choose when to check the order status

The endpoint calculates the order status from the time the order was created:

Time since creation	Status
Less than 30 seconds	`confirmed`
30 to less than 90 seconds	`preparing`
90 seconds or more	`ready_for_pickup`

Check the order status

Call the same phone number and ask for the order’s status. Provide the saved order number and confirm it when the assistant reads the digits back.

The assistant should call getCoffeeOrderStatus and state the returned statusLabel. The returned status should match the time window above.

A ready order returns these values:

{
  "orderId": 47730,
  "status": "ready_for_pickup",
  "statusLabel": "Order is ready for pickup"
}

Next steps

Handle responses and errors

Design response contracts and help the assistant recover from failures.

Use response data

Extract response values and pass them to later tools.