# Agents Library
Source: https://www.bolna.ai/docs/agents-library
Browse Bolna's Voice AI agent templates for quick and efficient setup. Customize pre-built agents to create powerful, AI-driven voice agents seamlessly.
## What is the Agents Library?
The Bolna Agents Library provides ready-to-use Voice AI agent templates that you can import and customize for your specific use case. Each template comes pre-configured with optimized prompts, workflows, and settings, allowing you to deploy production-ready agents in minutes rather than hours.
## How to use agent templates?
1. Click the "Import this agent →" link for any template below
2. The agent will be imported into your [Playground](/playground/agent-setup)
3. Customize the prompts, [context variables](/using-context), and settings to match your needs
4. Test using the Playground chat or by [making test calls](/making-outgoing-calls)
5. Deploy for [inbound](/receiving-incoming-calls) or [outbound](/making-outgoing-calls) calling
## Featured agents
AI agents that screen, interview, and onboard candidates at scale
Languages: `English`
Import this agent →
Provides 24/7 inbound call answering for FAQs and customer triage
Languages: `English`
Import this agent →
Calls customers with abandoned items in carts, recovering sales
Languages: `English + Hindi`
Import this agent →
Calls every lead to ask qualifying questions, answer FAQs, and warmly introduce the business
Languages: `Hindi`
Import this agent →
Conducts personalized guidance calls to warmly onboard users
Languages: `English`
Import this agent →
Answers every call to handle clinic, hotel, and office scheduling
Languages: `English`
Import this agent →
## Additional agent templates
| Agent name | Learn More | Import Agent | Description |
| -------------------------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| [COD Confirmation Agent](/voice-agents/cod-confirmation-agent) | [Details →](/voice-agents/cod-confirmation-agent) | [Import →](https://bolna.ai/a/ae8026a4-76a2-42d1-a2da-b6893b7cc131) | Handles a variety of last mile logistics tasks, saving human effort |
| [Announcements Agent](/voice-agents/announcements-agent) | [Details →](/voice-agents/announcements-agent) | [Import →](https://bolna.ai/a/b2fb2c68-602f-4d00-98f7-2feb0653f065) | Keeps users engaged with all feature upgrades and product launches |
| [Reminders Agent](/voice-agents/reminders-agent) | [Details →](/voice-agents/reminders-agent) | [Import →](https://bolna.ai/a/e33e9f48-5db3-4a0c-90e1-0d50a967971a) | Automates all reminders, from EMIs and collections to form filling deadlines |
| [Surveys Agent](/voice-agents/surveys-agent) | [Details →](/voice-agents/surveys-agent) | [Import →](https://bolna.ai/a/e3f31313-c28c-452e-9026-70edd7042691) | Automated NPS, feedback & product surveys with detailed personalised questioning |
| [Property Tech Agent](/voice-agents/property-tech-agent) | [Details →](/voice-agents/property-tech-agent) | [Import →](https://bolna.ai/a/d3dbc421-b964-4c12-8afa-e087e440cb3e) | Lead Qualification of Owner or Broker and asks further details about property |
| [Dentist Appointment Agent](/voice-agents/dentist-appointment-agent) | [Details →](/voice-agents/dentist-appointment-agent) | [Import →](https://bolna.ai/a/49077539-c821-42d4-84cb-f3522bea3187) | Front Desk for Dentist ; Schedules Appointments and collects information |
| [Salon Booking Agent](/voice-agents/salon-booking-agent) | [Details →](/voice-agents/salon-booking-agent) | [Import →](https://bolna.ai/a/547e8f2d-d231-4fc6-a9f1-b90801d672b8) | Front Desk for Salon ; Schedules appointment and collects information |
| [Weekend Planner Agent](/voice-agents/weekend-planner-agent) | [Details →](/voice-agents/weekend-planner-agent) | [Import →](https://bolna.ai/a/00b05a0f-d451-4afe-b55f-7e2a3fa4896d) | Plan your weekend with Samantha ; Helps users make weekend and vacation plans |
| [Sales - Credit Card Agent](/voice-agents/sales-credit-card-agent) | [Details →](/voice-agents/sales-credit-card-agent) | [Import →](https://bolna.ai/a/68762ade-7e39-4b06-96e6-0d98863fbd0b) | Sales agent for credit cards (Hindi) ; Helps fintech companies sell credit cards |
| [Sales - Loans Agent](/voice-agents/sales-loans-agent) | [Details →](/voice-agents/sales-loans-agent) | [Import →](https://bolna.ai/a/29780b7b-876e-40a6-96bd-069b8409dedb) | Sales agent for Loans (Hindi) ; Helps fintech companies sell loans |
# Create Voice AI Agent API (deprecated)
Source: https://www.bolna.ai/docs/api-reference/agent/create
POST /agent
Learn how to create new agents with Bolna APIs, enabling customized tasks, prompts, and configurations for Bolna voice AI agents.
These APIs have now been deprecated.
Please use the latest [**v2 APIs**](/api-reference/agent/v2/overview).
# Retrieve Voice AI Agent Details API (deprecated)
Source: https://www.bolna.ai/docs/api-reference/agent/get
GET /agent/{agent_id}
Retrieve detailed Voice AI agent information, including configuration, status, and tasks, using Bolna APIs.
These APIs have now been deprecated.
Please use the latest [**v2 APIs**](/api-reference/agent/v2/overview).
# List all Voice AI Agents API (deprecated)
Source: https://www.bolna.ai/docs/api-reference/agent/get_all
GET /agent/all
List all Voice AI agents under your account, along with their names, statuses, and creation dates, using Bolna APIs.
These APIs have now been deprecated.
Please use the latest [**v2 APIs**](/api-reference/agent/v2/overview).
# Get All Voice AI Agent Executions API
Source: https://www.bolna.ai/docs/api-reference/agent/get_all_agent_executions
GET /agent/{agent_id}/executions
Access all execution records for a specific agent, providing insights into performance and past interactions with Bolna APIs.
# Bolna Voice AI Agent APIs Overview (deprecated)
Source: https://www.bolna.ai/docs/api-reference/agent/overview
Explore Bolna Voice AI Agent APIs overview, featuring endpoints for creating, managing, and executing autonomous voice agents.
These APIs have now been deprecated.
Please use the latest [**v2 APIs**](/api-reference/agent/v2/overview).
## Endpoints
```
POST /agent
GET /agent
PUT /agent/:agent_id
PATCH /agent/:agent_id
GET /agent/all
```
## Agent Object Attributes
### `agent_config`
* `agent_name` *string* **(required)**
Name of the agent
* `agent_welcome_message` *string* **(required)**
Initial agent welcome message. you can pass dynamic values here using variables encloed within `{}`
* `webhook_url` *string* **(required)**
Get real-time details of the call progress and call data on a webhook. All supported events are listed in [Poll call data using webhooks](/polling-call-status-webhooks)
* `tasks` *array* **(required)**
Definitions and configuration for the agentic tasks
### `agent_prompts`
Prompts to be provided to the agent.
# Patch Update to Voice AI Agent API (deprecated)
Source: https://www.bolna.ai/docs/api-reference/agent/patch_update
PATCH /agent/{agent_id}
Learn how to partially update properties. Update Bolna Voice AI agent name, welcome message, webhook URL, voice settings, and prompts, using this endpoint.
These APIs have now been deprecated.
Please use the latest [**v2 APIs**](/api-reference/agent/v2/overview).
# Update Voice AI Agent API (deprecated)
Source: https://www.bolna.ai/docs/api-reference/agent/update
PUT /agent/{agent_id}
Update agent configurations, tasks, and prompts to refine behavior and capabilities using Bolna Voice AI agent APIs.
These APIs have now been deprecated.
Please use the latest [**v2 APIs**](/api-reference/agent/v2/overview).
# Create Voice AI Agent API
Source: https://www.bolna.ai/docs/api-reference/agent/v2/create
POST /v2/agent
Learn how to create new agents with Bolna APIs, enabling customized tasks, prompts, and configurations for Bolna voice AI agents.
# Delete Voice AI Agent API
Source: https://www.bolna.ai/docs/api-reference/agent/v2/delete
DELETE /v2/agent/{agent_id}
Use Bolna APIs to delete agents and their related data, ensuring proper cleanup of batches, executions, and configurations.
This deletes **ALL** agent data including all batches, all executions, etc.
# Retrieve Voice AI Agent Details API
Source: https://www.bolna.ai/docs/api-reference/agent/v2/get
GET /v2/agent/{agent_id}
Retrieve detailed Voice AI agent information, including configuration, status, and tasks, using Bolna APIs.
# Retrieve Voice AI Agent Execution API
Source: https://www.bolna.ai/docs/api-reference/agent/v2/get_agent_execution
GET /agent/{agent_id}/execution/{execution_id}
Fetch specific execution details of a Voice AI agent, including conversation times, statuses, and metrics, via Bolna APIs.
# List all Voice AI Agents API
Source: https://www.bolna.ai/docs/api-reference/agent/v2/get_all
GET /v2/agent/all
List all Voice AI agents under your account, along with their names, statuses, and creation dates, using Bolna APIs.
# Get All Voice AI Agent Executions API
Source: https://www.bolna.ai/docs/api-reference/agent/v2/get_all_agent_executions
GET /v2/agent/{agent_id}/executions
Access all execution records for a specific agent, providing insights into performance and past interactions with Bolna APIs.
## Pagination
This API supports pagination using the `page_number` and `page_size` query parameters. You can utilize `has_more` in the API response to determine if you should fetch the next page. You can learn more about it from the [pagination documentation](/api-reference/pagination).
# Bolna Voice AI Agent APIs Overview
Source: https://www.bolna.ai/docs/api-reference/agent/v2/overview
Explore Bolna Voice AI Agent APIs overview, featuring endpoints for creating, managing, and executing autonomous voice agents.
## Endpoints
```
POST /v2/agent
GET /v2/agent
PUT /v2/agent/:agent_id
GET /v2/agent/all
```
## Agent Object Attributes
### `agent_config`
* `agent_name` *string* **(required)**
Name of the agent
* `agent_welcome_message` *string* **(required)**
Initial agent welcome message. you can pass dynamic values here using variables encloed within `{}`
* `webhook_url` *string* **(required)**
Get real-time details of the call progress and call data on a webhook. All supported events are listed in [Poll call data using webhooks](/polling-call-status-webhooks)
* `tasks` *array* **(required)**
Definitions and configuration for the agentic tasks
### `agent_prompts`
Prompts to be provided to the agent.
# Patch Update to Voice AI Agent API
Source: https://www.bolna.ai/docs/api-reference/agent/v2/patch_update
PATCH /v2/agent/{agent_id}
Learn how to partially update properties. Update Bolna Voice AI agent name, welcome message, webhook URL, voice settings, and prompts, using this endpoint.
Currently, only the following agent attributes can be updated for the `PATCH` update.
* `agent_name`
* `agent_welcome_message`
* `webhook_url`
* `synthesizer`
* `agent_prompts`
* `ingest_source_config`
# Stop Agent Queued Calls API
Source: https://www.bolna.ai/docs/api-reference/agent/v2/stop
POST /v2/agent/{agent_id}/stop
Use Bolna APIs to stop all queued calls for a specific agent, preventing any pending calls from being executed.
This stops **ALL** the queued calls for a given agent.
This endpoint stops all queued calls for the specified agent. Any calls that are currently in the queue waiting to be executed will be cancelled and will not be processed.
# Update Voice AI Agent API
Source: https://www.bolna.ai/docs/api-reference/agent/v2/update
PUT /v2/agent/{agent_id}
Update agent configurations, tasks, and prompts to refine behavior and capabilities using Bolna Voice AI agent APIs.
# Create Batch API
Source: https://www.bolna.ai/docs/api-reference/batches/create
POST /batches
Discover how to create a batch for Bolna Voice AI agent by uploading a CSV file containing user contact numbers and prompt variable details for users.
# Delete Batch API
Source: https://www.bolna.ai/docs/api-reference/batches/delete
DELETE /batches/{batch_id}
Understand how to delete a specific batch using its ID, effectively removing it from your scheduled or active batches.
# List Batch Executions API
Source: https://www.bolna.ai/docs/api-reference/batches/executions
GET /batches/{batch_id}/executions
Learn how to retrieve all executions from a batch, providing detailed information on each call's outcome and metrics.
# Get Batch API
Source: https://www.bolna.ai/docs/api-reference/batches/get_batch
GET /batches/{batch_id}
Find out how to retrieve details of a specific batch, including its creation time, status, call status and scheduled execution time.
# List All Batches API
Source: https://www.bolna.ai/docs/api-reference/batches/get_batches
GET /batches/{agent_id}/all
Explore how to list all batches associated with a particular Bolna Voice AI agent, providing an overview of their statuses, schedules and other relevant details
# Batch APIs Overview
Source: https://www.bolna.ai/docs/api-reference/batches/overview
Understand how to create and schedule multiple Bolna Voice AI calls together using Bolna Batch APIs for efficient call management.
## Endpoints
```
POST /batches
POST /batches/schedule
POST /batches/:batch_id/stop
GET /batches/:batch_id
GET /batches/:batch_id/executions
GET /batches/:agent_id
DELETE /batches/:batch_id
```
# Schedule Batch API
Source: https://www.bolna.ai/docs/api-reference/batches/schedule
POST /batches/{batch_id}/schedule
Learn how to schedule a batch for calling via Bolna Voice AI agent by specifying the batch ID and the desired execution time.
# Stop Batch API
Source: https://www.bolna.ai/docs/api-reference/batches/stop
POST /batches/{batch_id}/stop
Understand how to stop a running batch using its ID, allowing you to halt ongoing calls in the batch.
# Make Voice AI Call API
Source: https://www.bolna.ai/docs/api-reference/calls/make
POST /call
Learn how to initiate outbound phone calls using Bolna Voice AI agents. Start making phone calls using the agent ID and recipient's phone number.
# Calling APIs overview
Source: https://www.bolna.ai/docs/api-reference/calls/overview
Explore Bolna Calling APIs to invoke outbound Voice AI phone calls from your agents. This overview provides the available endpoints and their functionalities.
## Endpoints
```
POST /call
```
# Stop a Previously Initiated Voice AI Call API
Source: https://www.bolna.ai/docs/api-reference/calls/stop_call
POST /call/{execution_id}/stop
Learn how to stop a call when its status is `queued` or `scheduled` This API allows you to cancel pending calls before they are executed.
# Get Batch Executions API
Source: https://www.bolna.ai/docs/api-reference/executions/get_batch_executions
GET /batches/{batch_id}/executions
Retrieve all executions for specific batches using Bolna APIs. This endpoint provides detailed information on each call's outcome and metrics within the batch.
# Retrieve Voice AI Execution API
Source: https://www.bolna.ai/docs/api-reference/executions/get_execution
GET /executions/{execution_id}
Fetch details of a specific phone call execution by its ID using Bolna APIs. This includes information such as conversation time, status, and telephony data.
# Retrieve Voice AI Execution Raw Logs API
Source: https://www.bolna.ai/docs/api-reference/executions/get_execution_raw_logs
GET /executions/{execution_id}/log
Fetch raw logs of a specific phone call execution by its ID using Bolna APIs. This includes information such as prompts, requests & responses by the models
# Get All Voice AI Agent Executions API
Source: https://www.bolna.ai/docs/api-reference/executions/get_executions
GET /v2/agent/{agent_id}/executions
Retrieve all executions performed by a specific agent using Bolna APIs. This endpoint provides a comprehensive history of the agent's calls and conversations.
## Pagination
This API supports pagination using the `page_number` and `page_size` query parameters. You can utilize `has_more` in the API response to determine if you should fetch the next page. You can learn more about it from the [pagination documentation](/api-reference/pagination).
# Executions APIs overview
Source: https://www.bolna.ai/docs/api-reference/executions/overview
Access your Voice AI agents call and conversation history using Bolna Executions APIs. This page details the available endpoints for managing call executions.
## Endpoints
```
GET /executions/:execution_id
GET /batch/:batch_id/executions
GET /v2/agent/:agent_id/executions
GET /executions/:execution_id/log
```
# Set Inbound Agent API
Source: https://www.bolna.ai/docs/api-reference/inbound/agent
POST /inbound/setup
Configure Bolna Voice AI agent to handle inbound calls automatically by associating it with a specific phone number using Bolna APIs.
# Inbound Bolna Voice AI Agent APIs Overview
Source: https://www.bolna.ai/docs/api-reference/inbound/overview
Discover how to set up Bolna Voice AI agents to answer inbound calls, enabling responsive communication channels.
## Endpoints
```
POST /inbound/setup
```
# Remove Inbound Agent API
Source: https://www.bolna.ai/docs/api-reference/inbound/unlink
POST /inbound/unlink
Remove and unlink a Bolna Voice AI agent from a specific phone number to disable automated inbound voice call answering by AI agents.
# Bolna API Documentation
Source: https://www.bolna.ai/docs/api-reference/introduction
Use and leverage Bolna Voice AI using APIs through HTTP requests from any language in your applications and workflows.
## What is the Bolna API?
The Bolna API enables you to programmatically create, configure, and manage Voice AI agents from your applications. Build voice AI capabilities into your products using simple HTTP requests from any programming language.
Bolna API features consistent, resource-oriented URLs, handles application/json request bodies, returns responses in JSON format, and utilizes standard HTTP response codes, authentication methods, and HTTP verbs.
You must have a valid Bolna account to generate and use APIs
## How do I authenticate with the Bolna API?
* Login to the dashboard at [https://platform.bolna.ai](https://platform.bolna.ai)
* Navigate to [Developers](https://platform.bolna.ai/developers) tab from the left menu bar after login
* Click the button `Generate a new API Key` to generate a key
* Save your API Key
The API Key will be shown only once. Hence, please save it somewhere secure.
## Using the API Key
To authenticate your API requests, you must include your `API Key` in the Authorization header of HTTP requests made as a `Bearer` token
```
Authorization: Bearer
```
## Example of an Authenticated API Request
Following is an example of making a GET request to Bolna API using the API key:
```http theme={"system"}
GET https://api.bolna.ai/agent/all
Headers:
Authorization: Bearer
```
## Next steps
Ready to integrate Bolna into your application? Explore the API endpoints:
* [Create an agent](/api-reference/agent/create) programmatically
* [Make outbound calls](/api-reference/calls/make) from your application
* [Get execution details](/api-reference/executions/get_execution) to retrieve call results
* Review [agent configuration options](/playground/agent-setup) to understand available parameters
For advanced integrations, explore [custom function calls](/tool-calling/custom-function-calls) and [webhook configuration](/playground/tasks-tab).
# Create Knowledgebase API
Source: https://www.bolna.ai/docs/api-reference/knowledgebase/create
POST /knowledgebase
Upload a PDF document to create a knowledgebase, enhancing your Bolna Voice AI agent's information base and response accuracy.
# Delete Knowledgebase API
Source: https://www.bolna.ai/docs/api-reference/knowledgebase/delete
DELETE /knowledgebase/{rag_id}
Remove and delete an existing knowledgebase from your Bolna account maintaining your Bolna Voice AI agents upto date.
# Get Knowledgebase API
Source: https://www.bolna.ai/docs/api-reference/knowledgebase/get_knowledgebase
GET /knowledgebase/{rag_id}
Retrieve details of a specific knowledgebase, including its ID, file name, creation time, and status, using Bolna APIs.
# List All Knowledgebases API
Source: https://www.bolna.ai/docs/api-reference/knowledgebase/get_knowledgebases
GET /knowledgebase/all
Retrieve all knowledgebases associated with your account, including their status and creation dates.
# Knowledgebases Overview
Source: https://www.bolna.ai/docs/api-reference/knowledgebase/overview
Learn how to ingest and add knowledgebases to Bolna Voice AI agents, enhancing their information base and response accuracy.
## Endpoints
```
POST /knowledgebase
GET /knowledgebase/:rag_id
GET /knowledgebase/all
DELETE /knowledgebase/:rag_id
```
# Pagination in Bolna API
Source: https://www.bolna.ai/docs/api-reference/pagination
Learn how to use pagination in Bolna Voice AI APIs using `page_number` and `page_size` to fetch results efficiently and build scalable workflows.
The endpoints also support pagination using the `page_number` and `page_size` query parameters. This allows you to fetch large sets of results in smaller, manageable chunks.
## Query Parameters
* `page_number` (integer, optional): The page of results to retrieve. Defaults to `1`. The first page starts at `1`.
* `page_size` (integer, optional): The number of results per page. Defaults to `20`. You can request up to `50` results per page.
## How it works
The API uses offset-based pagination under the hood. For example:
| page\_number | page\_size | Returned records |
| ------------ | ---------- | ---------------- |
| 1 | 10 | Records 1–10 |
| 2 | 10 | Records 11–20 |
| 3 | 5 | Records 11–15 |
## Example Request
```curl example-request theme={"system"}
GET /v2/agent/1234/executions?page_number=2&page_size=5
```
```json example-response theme={"system"}
{
"total": 38,
"page": 2,
"page_size": 5,
"has_more": true,
"data": [
{ "id": "ex_101", "status": "success", "created_at": "..." },
{ "id": "ex_102", "status": "failed", "created_at": "..." },
...
]
}
```
## Tips
* Use `has_more` to determine if you should fetch the next page.
* Combine pagination with filters supported in the API to narrow results efficiently.
# Buy Phone Numbers API
Source: https://www.bolna.ai/docs/api-reference/phone-numbers/buy
POST /phone-numbers/buy
Buy virtual phone numbers with full purchase, pricing, and provider details to use with Bolna Voice agents for outbound and inbound calls.
# Delete Phone Numbers API
Source: https://www.bolna.ai/docs/api-reference/phone-numbers/delete
DELETE /phone-numbers/{phone_number_id}
Delete a purchased phone number to stop billing and remove it permanently from your active inventory.
# List Phone Numbers API
Source: https://www.bolna.ai/docs/api-reference/phone-numbers/get_all
GET /phone-numbers/all
Retrieve all phone numbers associated with your account, including details like creation date and telephony provider like Twilio, Plivo, etc.
# Phone Numbers APIs Overview
Source: https://www.bolna.ai/docs/api-reference/phone-numbers/overview
Manage your phone numbers effectively using Bolna APIs, including buying, listing, deleting and associating numbers with Bolna Voice AI agents.
## Endpoints
```
POST /phone-numbers/all
GET /phone-numbers/search
POST /phone-numbers/buy
DELETE /phone-numbers/delete
```
# Search Phone Numbers API
Source: https://www.bolna.ai/docs/api-reference/phone-numbers/search
GET /phone-numbers/search
Search available phone numbers by region, locality, or pattern, with price to use them with Bolna Voice agents.
# Add a New Provider API
Source: https://www.bolna.ai/docs/api-reference/providers/add
POST /providers
Learn how to securely add a new provider to your Bolna account by specifying the provider's name and associated credentials.
You can add your own providers securely in Bolna. Please [read this page](/providers) for more information about all current supported providers.
# List Providers API
Source: https://www.bolna.ai/docs/api-reference/providers/get
GET /providers
Retrieve all providers associated with your Bolna account, including their IDs, names, and creation timestamps.
# Providers APIs overview
Source: https://www.bolna.ai/docs/api-reference/providers/overview
Add and manage your own providers securely in Bolna, supporting various telephony and voice services.
You can add your own providers securely in Bolna.
Please [read this page](/providers) for more information about all current supported providers.
## Endpoints
```
POST /providers
GET /providers
DELETE /providers/:provider_key_name
```
# Remove a Provider API
Source: https://www.bolna.ai/docs/api-reference/providers/remove
DELETE /providers/{provider_key_name}
Delete a previously added provider from your Bolna account, ensuring your integrations remain current.
# Get All Sub-Accounts Usage API
Source: https://www.bolna.ai/docs/api-reference/sub-accounts/all_usage
GET /sub-accounts/all/usage
Retrieve usage, consumption, and billing details for all sub-accounts under the authenticated organization.
This is an `enterprise` feature.
You can read more about our enterprise offering here [Bolna enterprise](/enterprise/plan).
## Summary
This endpoint returns aggregated usage data for **all sub-accounts** associated with the authenticated user's organization.\
It provides fine-grained insight into usage, consumption, and cost breakdowns for each sub-account.
## Endpoint
```yaml theme={"system"}
GET /sub-accounts/all/usage
```
# Create a new Sub-Account API
Source: https://www.bolna.ai/docs/api-reference/sub-accounts/create
POST /sub-accounts/create
Create a new sub-account using the Bolna API to define separate workspaces with custom configurations for enterprise-level management.
This is an `enterprise` feature.
You can read more about our enterprise offering here [Bolna enterprise](/enterprise/plan).
# Deleting a Sub-account
Source: https://www.bolna.ai/docs/api-reference/sub-accounts/delete
DELETE /sub-accounts/{sub_account_id}
Use Bolna APIs to delete a sub-account and their related data, ensuring proper cleanup of agents, batches, executions, and configurations.
This deletes **ALL** the data for that sub-account's batches, executions and agents.
# List all Sub-Accounts API
Source: https://www.bolna.ai/docs/api-reference/sub-accounts/get_all
GET /sub-accounts/all
Retrieve all sub-accounts linked to your main account enabling centralized visibility and management.
This is an `enterprise` feature.
You can read more about our enterprise offering here [Bolna enterprise](/enterprise/plan).
# Sub accounts APIs overview
Source: https://www.bolna.ai/docs/api-reference/sub-accounts/overview
Manage multiple customers or business units with Bolna Sub-Accounts API. Create, list, and track usage with clear data separation and control.
This is an `enterprise` feature.
You can read more about our enterprise offering here [Bolna enterprise](/enterprise/plan).
## Endpoints
```
POST /sub-accounts/create
GET /sub-accounts/all
GET /sub-accounts/:sub_account_id/usage
```
# Patch Update a Sub-account
Source: https://www.bolna.ai/docs/api-reference/sub-accounts/patch_update
PATCH /sub-accounts/{sub_account_id}
Use this Bolna API endpoint to partially modify and update sub-account properties, including its name, concurrency limits, and call capacity settings.
Currently, only the following agent attributes can be updated for the `PATCH` update.
* `allow_concurrent_calls`
* `name`
# Track Sub-Account Usage API
Source: https://www.bolna.ai/docs/api-reference/sub-accounts/usage
GET /sub-accounts/{sub_account_id}/usage
Track usage for a specific sub-account giving you fine-grained insights into usage, consumption and billing.
This is an `enterprise` feature.
You can read more about our enterprise offering here [Bolna enterprise](/enterprise/plan).
# Add a New Custom LLM Model
Source: https://www.bolna.ai/docs/api-reference/user/add_model
POST /user/model/custom
Learn how to integrate your custom Large Language Model (LLM) with Bolna Voice AI agents using Bolna APIs.
This request specifies how to add your own Custom LLM Models and use it with Bolna Voice AI agents. Please read about it more from [using-custom-llm](/customizations/using-custom-llm)
# User information
Source: https://www.bolna.ai/docs/api-reference/user/info
GET /user/me
Get details like name, email, current wallet balance, concurrency limits using this API
# User APIs Overview
Source: https://www.bolna.ai/docs/api-reference/user/overview
Explore APIs related to user and account information for Bolna Voice AI agents, including endpoints for adding custom LLM models.
## Endpoints
```
GET /user/me
POST /user/model/custom
```
# List All Voices API
Source: https://www.bolna.ai/docs/api-reference/voice/get_all
GET /me/voices
Retrieve a list of all available voices for your account, including details like provider, language, and accent.
# Voice APIs Overview
Source: https://www.bolna.ai/docs/api-reference/voice/overview
APIs for accessing voices and generating test transcripts which can be utilized for Bolna Voice AI agents.
## Endpoints
```
GET /me/voices
```
# Automate and schedule calls using Batches
Source: https://www.bolna.ai/docs/batch-calling
Learn how to schedule and manage batch calls using Bolna's Voice AI agents. Upload CSV files, set call parameters, and monitor execution for efficient outreach.
## What is batch calling in Bolna?
Batch calling allows you to automate outbound calls to hundreds or thousands of contacts by uploading a CSV file with phone numbers and custom data. This feature is perfect for lead qualification, customer outreach, appointment reminders, and other high-volume calling campaigns.
## How should I structure my batch CSV file?
1. All phone numbers should include the country prefix in [E.164](https://en.wikipedia.org/wiki/E.164) format
2. All phone numbers should have `contact_number` as the header
3. All other variables can be included in the CSV file in separate coloumns
###
```csv example_batch_file.csv theme={"system"}
contact_number,first_name,last_name
+11231237890,Bruce,Wayne
+91012345678,Bruce,Lee
+00021000000,Satoshi,Nakamoto
+44999999007,James,Bond
```
## How to export a CSV file from Excel or Google Sheets?
In Excel, when you type a `+` at the beginning of a cell, Excel interprets it as a formula.
To ensure the plus sign `+` is retained when entering phone numbers with country codes,
**please add an apostrophe (`'`) before the plus sign.**
[Download an example CSV file](https://bolna-public.s3.amazonaws.com/Bolna+batch+calling+example+csv.csv)
***
## How to use Batch APIs step by step?
### i. Create a batch for agent
Once the CSV file is ready, upload it using the [Create Batch API](/api-reference/batches/create)
```bash request theme={"system"}
curl --location 'https://api.bolna.ai/batches' \
--header 'Authorization: Bearer ' \
--form 'agent_id="aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"' \
--form 'file=@"/my-first-batch.csv"'
```
```bash response theme={"system"}
{
"batch_id": "abcdefghijklmnopqrstuvwxyz012345",
"state": "created"
}
```
### ii. Scheduling the batch
After receiving your `batch_id`, you can schedule a batch using [Schedule Batch API](/api-reference/batches/schedule)
The scheduled date and time should be in **ISO 8601** format with time zone.
```bash request theme={"system"}
curl --location 'https://api.bolna.ai/batches/abcdefghijklmnopqrstuvwxyz012345/schedule' \
--header 'Authorization: Bearer ' \
--form 'scheduled_at="2024-03-20T04:05:00+00:00"'
```
```bash response theme={"system"}
{
"message": "success",
"state": "scheduled at 2024-03-20T04:10:00+00:00"
}
```
### iii. Retrieving batch status
Check the status of the batch using [Get Batch API](/api-reference/batches/get_batch)
```bash request theme={"system"}
curl --location 'https://api.bolna.ai/batches/abcdefghijklmnopqrstuvwxyz012345' \
--header 'Authorization: Bearer '
```
```bash response theme={"system"}
{
"batch_id": "abcdefghijklmnopqrstuvwxyz012345",
"humanized_created_at": "19 minutes ago",
"created_at": "2024-03-13T14:12:50.596315",
"updated_at": "2024-03-13T14:19:13.115411",
"status": "scheduled",
"scheduled_at": "2024-03-20T04:10:00+05:30"
}
```
### iv. Retrieving all batch executions
Once the batch has run, you can check all executions by the agent using [List Batch Executions API](/api-reference/batches/executions)
```bash request theme={"system"}
curl --location 'https://api.bolna.ai/batches/abcdefghijklmnopqrstuvwxyz012345/executions' \
--header 'Authorization: Bearer '
```
```bash response theme={"system"}
[
{
"id": 7432382142914,
"conversation_time": 123,
"total_cost": 123,
"transcript": "",
"createdAt": "2024-01-23T01:14:37Z",
"updatedAt": "2024-01-29T18:31:22Z",
"usage_breakdown": {
"synthesizerCharacters": 123,
"synthesizerModel": "polly",
"transcriberDuration": 123,
"transcriberModel": "deepgram",
"llmTokens": 123,
"llmModel": {
"gpt-3.5-turbo-16k": {
"output": 28,
"input": 1826
},
"gpt-3.5-standard-8k": {
"output": 20,
"input": 1234
}
}
}
},
{...},
{...},
{...},
{...}
]
```
## Complete example: Building a batch calling application
```python batch_script.py theme={"system"}
import asyncio
import os
from dotenv import load_dotenv
import aiohttp
# Load environment variables from .env file
load_dotenv()
# Load from .env
host = "https://api.bolna.ai"
api_key = os.getenv("api_key", None)
agent_id = 'ee153a6c-19f8-3a61-989a-9146a31c7834' #agent_id in which we want to create the batch
file_path = '/path/of/csv/file'
schedule_time = '2024-06-01T04:10:00+05:30'
async def schedule_batch(api_key, batch_id, scheduled_at):
print("now scheduling batch for batch id : {}".format(batch_id))
url = f"{host}/batches/{batch_id}/schedule"
headers = {'Authorization': f'Bearer {api_key}'}
data = {
'scheduled_at': scheduled_at
}
try:
async with aiohttp.ClientSession() as session:
async with session.post(url, headers=headers, data=data) as response:
response_data = await response.json()
if response.status == 200:
return response_data
else:
raise Exception(f"Error scheduling batch: {response_data}")
except aiohttp.ClientError as e:
print(f"HTTP Client Error: {str(e)}")
except Exception as e:
print(f"Unexpected error: {str(e)}")
async def get_batch_status(api_key, batch_id):
print("now getting batch status for batch id : {}".format(batch_id))
url = f"{host}/batches/{batch_id}"
headers = {'Authorization': f'Bearer {api_key}'}
try:
async with aiohttp.ClientSession() as session:
async with session.get(url, headers=headers) as response:
response_data = await response.json()
if response.status == 200:
return response_data
else:
raise Exception(f"Error getting batch status: {response_data}")
except aiohttp.ClientError as e:
print(f"HTTP Client Error: {str(e)}")
except Exception as e:
print(f"Unexpected error: {str(e)}")
async def get_batch_executions(api_key, batch_id):
print("now getting batch executions for batch id : {}".format(batch_id))
url = f"{host}/batches/{batch_id}/executions"
headers = {'Authorization': f'Bearer {api_key}'}
try:
async with aiohttp.ClientSession() as session:
async with session.get(url, headers=headers) as response:
response_data = await response.json()
if response.status == 200:
return response_data
else:
raise Exception(f"Error getting batch executions: {response_data}")
except aiohttp.ClientError as e:
print(f"HTTP Client Error: {str(e)}")
except Exception as e:
print(f"Unexpected error: {str(e)}")
async def create_batch():
url = f"{host}/batches"
headers = {'Authorization': f'Bearer {api_key}'}
with open(file_path, 'rb') as f:
form_data = aiohttp.FormData()
form_data.add_field('agent_id', agent_id)
form_data.add_field('file', f, filename=os.path.basename(file_path))
async with aiohttp.ClientSession() as session:
async with session.post(url, headers=headers, data=form_data) as response:
response_data = await response.json()
if response_data.get('state') == 'created':
batch_id = response_data.get('batch_id')
res = await schedule_batch(api_key, batch_id, scheduled_at=schedule_time)
if res.get('state') == 'scheduled':
check = True
while check:
# Checking the current status every 1 minute
await asyncio.sleep(60)
res = await get_batch_status(api_key, batch_id)
if res.get('status') == 'completed':
check = False
break
if not check:
res = await get_batch_executions(api_key, batch_id)
print(res)
return res
if __name__ == "__main__":
asyncio.run(create_batch())
```
## Next steps
Ready to implement batch calling? Start by [creating your first batch](/api-reference/batches/create) via the API or explore related features:
* Learn about [outbound calling concurrency](/outbound-calling-concurrency) limits
* Set up [dedicated phone numbers](/buying-phone-numbers) for your campaigns
* Configure [context variables](/using-context) to personalize each call
* Monitor [call details](/call-details) and execution results
For high-volume needs, consider the [Enterprise Plan](/enterprise/plan) with elevated concurrency limits and priority processing.
# Acquire Dedicated Phone Numbers through Bolna
Source: https://www.bolna.ai/docs/buying-phone-numbers
Purchase and manage phone numbers directly from Bolna's dashboard. Follow step-by-step instructions to secure numbers for your Voice AI agents.
Buy and view your Phone numbers on [https://platform.bolna.ai/phone-numbers](https://platform.bolna.ai/phone-numbers).
## Detailed steps to purchase phone numbers
All phone numbers are purchased for a monthly recurring cost and the amounts are deducted from the Bolna wallet balance. View [call pricing](/pricing/call-pricing) for more details on costs.
## What can I do with my purchased phone numbers?
Once you've purchased phone numbers, you can:
* [Make outbound calls](/making-outgoing-calls) from your dedicated numbers
* [Receive inbound calls](/receiving-incoming-calls) to your Voice AI agents
* [Configure telephony providers](/supported-telephony-providers) like Twilio or Plivo
* [Run batch calling campaigns](/batch-calling) at scale
# Extract Structured Data from Conversations in Bolna Voice AI
Source: https://www.bolna.ai/docs/call-details
Access detailed insights into call logs and data with Bolna Voice AI. Learn how to analyze and utilize call details for better decision-making.
## What is data extraction in Bolna?
Data extraction allows you to automatically capture specific information from voice conversations in a structured JSON format. This is essential for CRM integration, lead qualification, appointment booking, and post-call analysis.
## How to extract call details in structured JSON format?
By defining any relevant information you wish to extract from the conversation, you can use `Extraction prompt`.
Post every call, you'll get this data in the [Execution](/api-reference/executions/get_execution) payload in `extracted_data` key.
### Example
```text extraction prompt theme={"system"}
user_name : Yield the name of the user.
payment_mode : If user is paying by cash, yield cash. If they are paying by card yield card. Else yield NA
payment_date: yield payment date by the user in YYYY-MM-DD format
```
```json response theme={"system"}
...
...
"extracted_data": {
"user_name": "Bruce",
"payment_mode": "paypal,
"payment_date": "2024-12-30"
},
...
...
```
## What can I extract from calls?
You can extract any information discussed during the conversation:
* **Customer information**: Names, email addresses, phone numbers
* **Appointment details**: Dates, times, preferences
* **Lead qualification data**: Budget, timeline, decision-maker status
* **Payment information**: Payment method, amount, date
* **Product preferences**: Sizes, colors, quantities
* **Feedback and sentiment**: Satisfaction scores, complaints, compliments
## Next steps
Ready to implement data extraction? Configure extraction prompts in your agent or explore related features:
* Use [context variables](/using-context) to pre-fill known information
* Access extraction data via the [Executions API](/api-reference/executions/get_execution)
* Integrate with [custom functions](/tool-calling/custom-function-calls) for real-time actions
* Set up [batch calling](/batch-calling) with personalized context per call
For advanced use cases, combine extraction with [multi-agent workflows](/multi-agent-prompt) for complex conversations.
# Understanding Latency Metrics in Voice AI Executions
Source: https://www.bolna.ai/docs/call-latencies
Comprehensive guide to analyzing latency in Bolna Voice AI. Explore performance insights across transcription, LLM processing, and speech synthesis.
## Introduction
Bolna provides detailed latency metrics for every Voice AI execution, allowing you to monitor and optimize the performance of your conversational AI agents. These metrics help you understand where time is being spent in the conversation pipeline and identify potential bottlenecks that may affect user experience.
The latency data is included in the execution payload when you fetch execution details via the [Get Execution API](/api-reference/executions/get_execution). This data provides granular timing information across all major components of the voice AI pipeline.
This is a `beta` feature and slowly being rolled out to every user.
## Latency Data Structure
The `latency_data` object in the execution payload contains timing information organized by component. Here's the complete structure:
### Top-Level Metrics
```json theme={"system"}
{
"latency_data": {
"stream_id": 129.56982,
"time_to_first_audio": 130.84888,
"region": "in",
"transcriber": {
"time_to_connect": 226,
"turns": [...]
},
"llm": {
"time_to_connect": null,
"turns": [...]
},
"synthesizer": {
"time_to_connect": 271,
"turns": [...]
}
}
}
```
| Field | Type | Description |
| --------------------- | ------ | -------------------------------------------------------------------------------------------------------- |
| `stream_id` | float | Time in milliseconds to establish the audio stream connection |
| `time_to_first_audio` | float | Total time in milliseconds from call start until the first audio is played to the user |
| `region` | string | Geographic region code where the execution occurred (e.g., `in` for India, `us` for United States) |
## Transcriber Metrics
The transcriber component converts spoken audio into text. This section tracks how quickly speech is being transcribed.
```json theme={"system"}
{
"transcriber": {
"time_to_connect": 226,
"turns": [
{
"turn": 1,
"turn_latency": [
{
"sequence_id": 1,
"audio_to_text_latency": 20.12128,
"text": "hello who is there"
},
{
"sequence_id": 2,
"audio_to_text_latency": 19.96126,
"text": "hello who is this"
}
]
}
]
}
}
```
### Field Definition
| Field | Type | Description |
| ------------------------------- | --------------- | ------------------------------------------------------------------------ |
| `time_to_connect` | `integer` | Time (ms) to establish connection with the transcriber provider. |
| `turns` | `array