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

# Custom API Integration

> Create tools that call your own backend, internal services, or any HTTP endpoint.

## Introduction

To call your own API during a conversation, build a **webhook tool**. Use one when:

* You have your own backend API you want to call during calls
* You're integrating with a third-party service that isn't in the built-in list
* You need custom request formatting, headers, or authentication

This tutorial builds a tool that saves a call summary with Bland's [Create Prompt](https://docs.bland.ai/api-v1/post/prompts.md) endpoint. By the end, you'll know how to:

* Store an API key as a secret and reference it
* Write a request with variables the agent fills in
* Capture data from the response
* Tag the tool into an agent's prompt and use what it returns

For the full builder reference, see [Build a webhook tool](https://docs.bland.ai/agents/tools.md#build-a-webhook-tool).

## Prerequisites

* An agent to tag the tool into, from [Agent builder](https://docs.bland.ai/agents/agent-builder.md)
* Your Bland API key

***

## Step 1: Store your API key as a secret

Do not paste an API key into a tool. Set the sidebar selector to **All agents**, open **Tools**, and on the **Secrets** tab click **Add Secret**. Name it something like `bland_api_key` and paste your key as a Static secret.

See [Secrets](https://docs.bland.ai/tutorials/secrets.md) for details.

***

## Step 2: Create the tool

From inside your agent, open **Tools**, click **Create tool**, and choose **Webhook**.

If you already have a working `curl` command, choose **Import from cURL** instead. It opens the builder with the request filled in.

***

## Step 3: Name and describe it

**Name.** The name is what you type after `@` in a prompt. Make it the thing the tool does: "Save call summary" reads better than "POST request".

**Description.** The agent reads this to decide when to call the tool. Write the trigger:

```text theme={null}
Save a summary of the call. Use this once the caller has finished
describing their request and before you wrap up.
```

**Agent speech.** What the agent says while the tool runs, like "One moment while I save that." It keeps the caller from hearing dead air.

***

## Step 4: Configure the request

**Method and URL.** Choose **POST** and enter `https://api.bland.ai/v1/prompts`.

> [!WARNING]
>
> Webhook tools run **GET** and **POST** only. The method list shows other verbs, but a tool using one of them fails to save with `Failed to create tool`.

**Authorization.** On the **Authorization** tab, choose **API Key**. Set **Header name** to `authorization`, which is the header the Bland API expects, and pick your `bland_api_key` secret.

**Body.** Write the request body. Anywhere a value should change per call, write a variable:

```json theme={null}
{
  "name": "{{caller_name}}",
  "prompt": "{{call_summary}}"
}
```

Add any other headers your API needs on the **Headers** tab.

***

## Step 5: Say which variables the agent fills in

The variables you wrote are listed under **Detected variables**. For each one, click **Add input variable** so the agent fills it from the conversation. Then give it instructions, a type, and whether it is required:

| Variable | Instructions |
| - | - |
| `caller_name` | The caller's full name. |
| `call_summary` | A short summary of the key points discussed in this call. |

Write instructions for a person. Be specific about the format when it matters.

A variable you leave alone resolves from [variables already on the call](https://docs.bland.ai/agents/agent-builder.md#extract-variables) instead, and the agent never fills it.

***

## Step 6: Declare what comes back

**Output fields** name the parts of the response the agent can use. They start with `ok`, `message`, and `data`, with `ok` and `message` checked. Keep `ok` checked: a failed call returns only `ok` and `message`.

For a POST tool, the response fields under `data` are named `rest_api_post_*`:

| Field | What it holds |
| - | - |
| `rest_api_post_status` | The HTTP status |
| `rest_api_post_status_text` | The status text |
| `rest_api_post_data` | The response body from your endpoint |

The builder lists these as `rest_api_get_*` until the tool is saved. Save it, reopen it, and check the `rest_api_post_*` rows then.

To pull one value out of the response body, add a row with a name and a JSONPath. For the prompt ID, add a row named `prompt_id` with the path `$.data.rest_api_post_data.prompt.id`.

> [!WARNING]
>
> Checking at least one output field is what makes the tool wait for a response. Check nothing and the tool fires and moves on.

Run the tool with sample values and check the response before you attach it to anything.

***

## Step 7: Tag the tool into a prompt

Building the tool does not give it to the agent. In the agent's **Prompt**, type `@` and pick **Save call summary**. The tool then appears under **Tool references**.

Use the tool's outputs in the same prompt by their bare names:

```text theme={null}
When the caller is done, use @Save call summary. If {{ok}} is true,
tell the caller their reference ID is {{prompt_id}}. If not, apologize
and let them know a teammate will follow up.
```

If the step that needs the tool lives in its own pathway, tag the tool in that pathway's prompt too. Tools do not follow the agent into pathways. See [Tag a tool into a prompt](https://docs.bland.ai/agents/tools.md#tag-a-tool-into-a-prompt).

***

## Additional settings

These sit below the output fields:

* **Timeout:** how long to wait before giving up, from 1,000 to 60,000 milliseconds.
* **Cooldown:** the minimum gap between calls, from 1 to 30 seconds.

***

Docs for agents: [llms.txt](https://docs.bland.ai/llms.txt)


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