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

# Connect an API tool: product inventory lookup

> Follow a 2-minute-35-second video to connect an AI assistant to a product API, configure parameters and response fields, and test an inventory lookup.

A customer calls and asks, “Is product number one in stock?” Connect a product API so your AI assistant can pass the product ID to your system, retrieve inventory, and answer from the result.

<video controls playsInline preload="metadata" poster="/images/tutorials/product-api-cover.png" src="https://mintcdn.com/brightalk/w2jEeyGa90l6GD4n/videos/product-api-tutorial.mp4?fit=max&auto=format&n=w2jEeyGa90l6GD4n&q=85&s=2b1ef0ce5ece5f6a71698ee6a6c3ac45" alt="Product inventory API tutorial with Mandarin narration and Traditional Chinese captions" aria-label="Connect an API tool: product inventory lookup, 2 minutes 35 seconds, Mandarin narration">
  Your browser cannot play this video. Follow the complete written steps below.
</video>

The video is **2 minutes 35 seconds**, with Mandarin narration and Traditional Chinese captions. Follow the English instructions below for the same configuration.

## What you will build

1. The customer provides a product ID, such as `1`.
2. The `lookup_product` tool sends `GET /products/1` to the product system.
3. The AI receives the product name, price, and stock quantity, then answers the customer.

This example uses the [DummyJSON sample product API](https://dummyjson.com/docs/products). Its sample inventory is separate from your store. Replace it with your own API to retrieve your products.

Before starting, prepare an AI assistant that will use the tool and an account with integration management permission. Open **Settings → Integrations → [API tools and data](https://www.brightalk.ai/settings/integrations/api-tools)**.

## 1. Create a shared connection

Under **Shared connections**, click **Add connection**, enter these values, and save.

| Field | Example value |
| - | - |
| Name | Product API |
| API base URL | `https://dummyjson.com` |
| Authentication | No authentication |

The connection holds the API address and authentication. If your system requires a credential, select **Bearer token** or **Custom authentication header** according to its documentation and enter the credential.

## 2. Define the lookup tool

Click **Add lookup tool** and complete the **Configuration** tab.

* **Tool name**: `lookup_product`
* **Connection**: the **Product API** connection you just created
* **Available to**: the assistant handling product questions
* **Enable tool**: on

For **When to use this tool**, enter:

```text theme={null}
Use when a customer asks about a product's price or stock. Confirm the product ID first, then look up its name, price, and stock quantity. Ask the customer for the ID if it is missing.
```

## 3. Pass the product ID to the API

Open **Request parameters**, set **Request path** to `/products/{product_id}`, and add a parameter.

| Field | Value |
| - | - |
| Parameter name | `product_id` |
| Data type | `number` |
| Value source | From conversation |
| Location | URL path |
| Required | On |

The name inside the braces must match the parameter name. When the customer provides ID `1`, the request path becomes `/products/1`.

## 4. Choose the fields the AI receives

Under **Response data**, add these three fields and mark each as required.

| Response field path | Variable name for AI | Purpose |
| - | - | - |
| `title` | `product_name` | Product name |
| `price` | `unit_price` | Price |
| `stock` | `stock_qty` | Stock quantity |

The left column must match the API's actual JSON structure. The right column provides names you can reference in the response instructions. If your API nests the title under `data.title`, use `data.title` in the left column.

## 5. Set the response instructions

Enter your service rules in **How the AI should use the result**, then click **Save settings**.

```text theme={null}
Confirm the product using product_name, then answer with stock_qty. If stock_qty is 0, explain that the product is out of stock.
Use the original unit_price value. If the currency is missing, ask for clarification rather than assuming a currency or converting it.
Ask for missing information. Do not promise that an item has been reserved or an order has been placed.
```

## 6. Run a test lookup

Open **Test and preview** and enter this in **Test input (JSON)**:

```json theme={null}
{"product_id": 1}
```

Click **Run query** and compare **Data before field mapping** with **Data actually sent to AI**. The mapped product fields below were returned during filming; use the API's current response when you test.

```json theme={null}
{
  "product_name": "Essence Mascara Lash Princess",
  "unit_price": 9.99,
  "stock_qty": 99
}
```

When all three fields are correct, the connection, parameters, and mapping work for this lookup. With the sample stock value of `99`, the assistant can answer, “There are currently 99 units in stock.” Next, test a conversation with your assistant: it should ask for a missing product ID, call the tool once it has the ID, and answer from the result.

## Use your own product system

Ask your API integrator for the base URL, authentication method, request path, and a sample JSON response. Generic lookup tools currently use **HTTPS GET**. Replace the connection, parameters, and fields above, then test a product from your system.

| Problem during testing | Check first |
| - | - |
| Connection or authentication fails | Base URL, authentication method, and whether the credential is correct or expired |
| Invalid parameter or product not found | The `product_id` name, number type, URL path location, and product ID |
| A required response field is missing | Whether the API's JSON structure matches the `title`, `price`, and `stock` paths |
| The lookup works, but the assistant does not use the tool | Whether the tool is enabled, its scope includes the assistant, and its usage description fits the question |

For first-time setup, see [Create your first outbound AI agent](https://docs.brightalk.ai/en/guides/create-outbound-agent.md). For line and availability requirements, see [AI voice agents](https://docs.brightalk.ai/en/concepts/agents.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.