Skip to main content

Overview

Bolna lets you reject unwanted inbound calls (spam, promotional callers, specific number ranges) before the agent answers and before any AI or telephony usage is incurred. Instead of configuring individual numbers on Bolna, you keep the blocklist on your side and let Bolna consult it on every incoming call. This works by combining two existing inbound features:
  1. Caller identification — Bolna calls your API (or looks up a CSV / Google Sheet) with the caller’s number before the call is answered.
  2. Allow Calls Only from Database — a toggle in the Inbound tab that rejects any caller for whom no record is found.
Your API decides who gets through: return caller data for allowed numbers and an empty result for anything you want to block. Because the check runs in your own code, you can block single numbers, whole prefixes, or number ranges, and update the list at any time without touching Bolna.
This guide uses the Internal API data source because it is the only option that lets you express prefix and range rules. CSV and Google Sheet sources only support exact-match allow lists.

How it works


Step-by-step setup

1

Define your blocklist

Decide which callers to reject. You can mix exact numbers and prefixes. Store the list wherever is convenient for you — a config file, a database table, or an environment variable.In this guide we block the entire +9179470 range (written as +9179470*) plus one specific number:
Always store and compare numbers in E.164 format (+ followed by country code and number, no spaces or dashes). This is the format Bolna sends in contact_number.
2

Build a GET endpoint that checks the caller

Create a GET endpoint that accepts the query parameters Bolna sends:The endpoint must:
  • Return an empty result ({}) when the number is blocked.
  • Return a JSON object with caller details when the number is allowed.
  • Respond within 3 seconds.
If you do not have caller data for allowed numbers, return any non-empty JSON object (for example {"allowed": true}). Only an empty result triggers the rejection.
Your API must respond within 3 seconds. If it times out, Bolna treats the lookup as returning no data — with the restriction toggle enabled this means the call is rejected, so make sure your endpoint is fast and highly available.
3

Connect the endpoint to your agent

In the Bolna dashboard, open your inbound agent and go to the Inbound tab.
  1. Under Database Matching, choose “Use your internal APIs” from the dropdown.
  2. Enter your endpoint URL, for example https://api.your-domain.com/callers.
  3. Optionally add a Bearer token so only Bolna can call your endpoint.
Inbound settings with the internal API option showing API endpoint URL and auth token fields

Connecting an internal API for caller identification

4

Turn on 'Allow Calls Only from Database'

Still in the Inbound tab, under Call Restrictions, toggle on “Allow Calls Only from Database”.This is what converts an empty result into a rejected call. Without it, blocked callers would still reach the agent — just without any injected data.Save the agent.
5

Test the blocklist

Verify your endpoint behaves correctly before routing live traffic:
Then place a test call to your Bolna number from a blocked and an allowed phone. The blocked call should be rejected without the agent answering; the allowed call should connect as usual.

Blocking patterns

All matching happens in your code, so any rule you can express is supported. Common patterns:
Because the blocklist lives on your side, you can update it instantly — add a spammer’s number to your database and the very next call from them is rejected. No changes are needed on Bolna.

Using this alongside an allow list

You can combine both behaviours in the same endpoint:
  • Allow list first: if the number is a known customer, return their data.
  • Blocklist next: if the number matches a blocked prefix, return {}.
  • Everyone else: either return {} (strict, only known callers get through) or a minimal non-empty object like {"known": false} (open, unknown callers are still answered).

Identify Incoming Callers

Full reference for API, CSV and Google Sheet data sources

Inbound Tab

Call restrictions and spam prevention settings

Inbound Call Setup

Configure inbound calling for your agents