> For the complete documentation index, see [llms.txt](https://learn.doubletick.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://learn.doubletick.io/ai-agent/how-to-create-a-new-ai-agent/tools-how-to-give-your-ai-agent-the-ability-to-take-action/api-tools-how-to-connect-your-ai-agent-to-external-systems.md).

# API Tools — How to Connect Your AI Agent to External Systems

#### <mark style="color:$primary;">**What is an API Tool?**</mark>

An API Tool connects your AI Agent to an external system — like your CRM, booking platform, property database, or any third-party service that provides an API. When a customer asks a question that requires live data, the agent collects the required information and calls the API to fetch or send data in real time.

Unlike Bot Tools that trigger a journey inside Bot Studio, API Tools call an external URL directly and return the result to the agent, which then uses it to respond to the customer.

***

#### <mark style="color:$primary;">When Should You Use an API Tool?</mark>

Use an API Tool when the agent needs to pull live data or push data to an external system. Here are some common scenarios:

| Scenario                                                       | What the API Tool Does                                    |
| -------------------------------------------------------------- | --------------------------------------------------------- |
| **Customer asks "What is the status of my order?"**            | Fetches order details from your system using the order ID |
| **Customer shares their phone number**                         | Looks up their record in your CRM                         |
| **Customer asks "What properties are available in Mumbai?"**   | Fetches a list of properties filtered by city             |
| **Customer wants to book a site visit**                        | Sends the booking details to your scheduling system       |
| **Customer says "Register me as a lead"**                      | Creates a new lead record in your CRM                     |
| **Customer asks "What time slots are available on Saturday?"** | Fetches available slots from your booking system          |

**If the answer depends on live data from another system, an API Tool is the right choice.**

***

#### <mark style="color:$primary;">**How API Tools Work**</mark>

1. A customer sends a message on WhatsApp.
2. The AI Agent reads the message and matches it to an API Tool based on the tool's description.
3. If the tool has parameters, the agent collects each piece of information from the customer.
4. Once all required information is collected, the agent calls the external API.
5. The API returns data to the agent.
6. The agent uses the returned data to respond to the customer.

The entire process happens automatically — the customer simply chats, and the agent handles the API call behind the scenes.

***

#### <mark style="color:$primary;">**Key Fields in an API Tool**</mark>

Every API Tool has the same basic fields as a Bot Tool — Name, Description, Type, and Parameters. But because it connects to an external system, it has additional fields:

<table><thead><tr><th width="158.00006103515625">Field</th><th>What It Means</th></tr></thead><tbody><tr><td><strong>Name</strong></td><td>A clear name describing what the tool does — for example, Get Lead By Phone or Book Site Visit</td></tr><tr><td><strong>Description</strong></td><td>Tells the agent when to use this tool. Write it clearly — the agent reads this to decide when to trigger it</td></tr><tr><td><strong>Type</strong></td><td>Set to API</td></tr><tr><td><strong>Parameters</strong></td><td>Information the agent collects from the customer before calling the API</td></tr><tr><td><strong>Import from cURL</strong></td><td>Paste a cURL command to auto-fill the Method, URL, Headers, and a basic skeleton of the request body including parameters. Useful if your developer shares a cURL command with you</td></tr><tr><td><strong>Method</strong></td><td>The type of API request — GET, POST, PUT, PATCH, or DELETE</td></tr><tr><td><strong>URL</strong></td><td>The external API endpoint the tool will call</td></tr><tr><td><strong>Headers</strong></td><td>Authentication details — click Add Header to add key-value pairs like an API key</td></tr><tr><td><strong>Request Body</strong></td><td>For POST and PUT requests, enter the JSON body here. Use {{parameter_name}} to insert collected values</td></tr><tr><td><strong>Test API</strong></td><td>Sends a test request using your sample values to verify the connection before saving</td></tr></tbody></table>

***

Got it. The current article has the order wrong — it adds parameters before importing the cURL, but the correct workflow is the other way around. You import the cURL first, understand what parameters are needed from the skeleton it gives you, then create and map them. Let me rewrite just the step-by-step guide section with the correct flow.

***

#### <mark style="color:$primary;">**How to Set Up an API Tool**</mark>

Open the AI Agent you want to configure and navigate to the Tools section. Click the AI Tool panel to open it. This is where all your API Tools are created and managed.

#### <mark style="color:$primary;">**Step 1 — Create the Tool**</mark>

<figure><img src="/files/yIfZKW2rkxWUQp3dSqen" alt=""><figcaption></figcaption></figure>

Click the **Add Tool** button.

Fill in the following fields:

* **Name** — Give the tool a clear name that describes what it does. For example: Book Site Visit or Get Lead By Phone.
* **Description** — Describe when the agent should use this tool. The agent reads this to decide when to trigger it, so be specific.
* **Type** — Select API.

#### <mark style="color:$primary;">**Step 2 — Import from cURL**</mark>

<figure><img src="/files/mzpPbpo4x02uIRSpkEZe" alt=""><figcaption></figcaption></figure>

Click the Import from cURL dropdown and paste the cURL command. The Method, URL, Headers, and a basic skeleton of the request body will be auto-filled automatically.

Once imported, review the skeleton carefully. The request body will show you what fields the API expects — this tells you exactly which parameters you need to create in the next step and whether they are mandatory or optional.

If you do not have a cURL command, you can fill in the Method, URL, and Headers manually.

#### <mark style="color:$primary;">**Step 3 — Create Parameters**</mark>

Based on what the imported cURL skeleton shows, add the required parameters one by one.

For each parameter, fill in:

* **Name** — Match this exactly to the field name in the API request body.
* **Type** — Select String for text values or Number for numeric values.
* **Description** — Describe what this parameter is, where it is used, and any restrictions or accepted formats. For example: "Visit date in YYYY-MM-DD format" or "Must be a valid property ID from the system."
* **Required** — Mark as required if the API cannot function without this value. Mark as optional only if the API can still return a meaningful response without it.

#### <mark style="color:$primary;">**Step 4 — Map Parameters in the Request Body**</mark>

Go to the Request Body field and update the JSON skeleton to reference the parameters you just created. Use {{parameter\_name}} wherever the API expects a dynamic value.

For example:

```
{
  "customer_id": {{customer_id}},
  "property_id": {{property_id}},
  "visit_date": "{{visit_date}}",
  "visit_time": "{{visit_time}}"
}
```

Make sure the names inside {{ }} exactly match the parameter names you created in Step 3. A mismatch will cause the API call to fail.

Remember: String values must be wrapped in quotes — "{{visit\_date}}". Number values must not be wrapped in quotes — {{customer\_id}}.

#### <mark style="color:$primary;">**Step 5 — Add Sample Values**</mark>

Go back to each parameter and enter a sample value. This is a realistic test value that represents what a customer would provide — for example, 2026-06-15 for a date or 1234 for a customer ID.

These sample values are what the Test API button will use in the next step, so make sure they are accurate and match the correct data type.

#### <mark style="color:$primary;">**Step 6 — Test the API**</mark>

Click the Test API button. The test runs using the sample values you entered and the {{parameter\_name}} notations in the request body. Review the response to confirm the API is returning the expected data.

If the test fails, check for the most common issues — wrong API key in Headers, parameter name mismatch in the Request Body, or incorrect data types in sample values.

Do not save the tool until the test passes successfully.

#### <mark style="color:$primary;">**Step 7 — Save the Tool**</mark>

Once the test is successful, click Create to save the tool.

After saving, make sure the toggle next to the tool is turned on (green). The agent will not use a tool that is disabled.

In live conversations, the static sample values are automatically replaced by the actual values the agent collects from the customer in real time.

***

#### <mark style="color:$primary;">**Summary**</mark>

In this article, you learned how to open the AI Tool panel, what API Tools are and when to use them, how to import a cURL command to auto-fill the connection details, how to add parameters with clear descriptions and limitations, how to use sample values for testing, how to configure the Request Body using {{parameter\_name}}, and how to test the API connection before saving. You also saw real examples and common mistakes to avoid.

In the next article, we will cover Unresolved Intents — how to review questions your agent could not answer and improve its knowledge over time.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://learn.doubletick.io/ai-agent/how-to-create-a-new-ai-agent/tools-how-to-give-your-ai-agent-the-ability-to-take-action/api-tools-how-to-connect-your-ai-agent-to-external-systems.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.