Common use cases

Getting started

Discover what your API key can do

Always start by calling the capabilities endpoint:

GET /v2/api/me

The response lists your scopes, available endpoints, team, and rate limits. Use the endpoints array to know which API calls you can make.

Syncing data

CRM sync (incremental)

Fetch only new activity since your last sync — no need to re-fetch everything.

GET /v2/api/conversations?allo_number=%2B14155550100&last_activity_since=2026-04-20T10:00:00Z

Store the last_activity timestamp from the response and use it as last_activity_since on the next sync.

Export all outbound calls from this quarter

Paginate through all results:

POST /v2/api/conversations/items/search
{
  "date": { "from": "2026-01-01", "to": "2026-03-31" },
  "direction": "OUTBOUND",
  "type": "CALL",
  "page": 1,
  "size": 100
}

Increment page until pagination.has_more is false.

Searching conversations

Find calls where customers mentioned billing issues

Keyword search across all call transcripts and summaries:

POST /v2/api/conversations/items/search
{
  "search": "billing issues",
  "type": "CALL",
  "sort": "RELEVANCE"
}

Search terms are AND’d and use prefix matching — "bill" matches “billing”, “billed”, etc.

Search what we discussed about refunds with a contact

POST /v2/api/conversations/items/search
{
  "contact_number": "+14155551234",
  "search": "refunds",
  "sort": "RELEVANCE"
}

Show all interactions with a contact

POST /v2/api/conversations/items/search
{
  "contact_number": "+14155551234"
}

Returns the full timeline of calls and SMS with a contact, including matched contacts, company, and deals.

Get full context on a specific call

GET /v2/api/conversations/items/cll-abc123?extend=transcript

Returns the call with summary, tags, recording URL, and full transcript. transcript is the only supported extend value.

How many calls were missed last week?

Use the search endpoint with size=1 to get just the count:

POST /v2/api/conversations/items/search
{
  "date": { "from": "2026-04-14", "to": "2026-04-21" },
  "result": "VOICEMAIL",
  "type": "CALL",
  "size": 1
}

Read pagination.total_count from the response — no need to fetch all results.

Show me qualified leads from cold calls this month

First, check what tags exist:

GET /v2/api/tags

Then filter conversations by tag:

POST /v2/api/conversations/items/search
{
  "date": { "from": "2026-04-01", "to": "2026-04-21" },
  "tags": ["qualified"],
  "direction": "OUTBOUND"
}

Find all unread conversations on a line

GET /v2/api/conversations?allo_number=%2B14155550100&unread=true

The allo_number parameter is required. List your numbers with GET /v2/api/numbers to find the right one.

Taking actions

Tag a call and then find all calls with that tag

# 1. Tag the call
POST /v2/api/conversations/items/cll-abc123/tags
{ "tags": ["qualified"] }

# 2. Find all calls with that tag
POST /v2/api/conversations/items/search
{ "tags": ["qualified"] }

Adding a tag that already exists returns 409 TAG_ALREADY_EXISTS — no duplicate is created.

Mark a conversation as read

PUT /v2/api/conversations/%2B14155551234/action
{ "action": "READ" }

To scope to a specific Allo number:

PUT /v2/api/conversations/%2B14155551234/action
{ "action": "READ", "allo_number": "+14155550100" }

All actions are idempotent — calling READ on an already-read conversation is a no-op.

Archive a conversation

PUT /v2/api/conversations/%2B14155551234/action
{ "action": "ARCHIVE" }

This archives the contact and marks all items as read.

Send an SMS follow-up

SMS sending uses the v1 API endpoint:

POST /v1/api/sms
{
  "to": "+14155551234",
  "allo_number": "+14155550100",
  "content": "Thanks for your call! Let me know if you have any other questions."
}

Requires the SMS_SEND scope. See Send SMS for details.

Analytics and reporting

What is my cold calling performance this week compared to last?

# 1. Get the outbound funnel with week-over-week comparison
POST /v2/api/analytics/outbound
{
  "date": { "from": "2026-04-14", "to": "2026-04-21" },
  "compare_date": { "from": "2026-04-07", "to": "2026-04-14" },
  "tags": ["meeting_booked"],
  "granularity": "DAY"
}

The response includes the full funnel (dials, connected, conversations, conversions) with change vs last week, daily time series, heatmap, and leaderboard.

# 2. Drill into the calls that converted (use extend=items)
POST /v2/api/analytics/outbound
{
  "date": { "from": "2026-04-14", "to": "2026-04-21" },
  "tags": ["meeting_booked"],
  "granularity": "DAY",
  "extend": "items",
  "stage": "CONVERSION"
}

# 3. Get full details (summary, transcript, tags)
POST /v2/api/conversations/items/batch
{ "ids": ["cll-abc123", "cll-def456"] }

Get team performance for last month

POST /v2/api/analytics/overview
{
  "date": { "from": "2026-03-01", "to": "2026-03-31" },
  "compare_date": { "from": "2026-02-01", "to": "2026-02-28" }
}

Returns total calls, talk time, answer rate, and per-user breakdown — all with change vs the comparison period.

Compare two reps' performance

POST /v2/api/analytics/overview
{
  "date": { "from": "2026-04-01", "to": "2026-04-21" },
  "compare_date": { "from": "2026-03-01", "to": "2026-03-31" },
  "user_ids": ["usr-abc123", "usr-def456"]
}

The breakdown in the response includes both users with their individual metrics and change vs the comparison period.

Cold calling performance for a specific line

POST /v2/api/analytics/outbound
{
  "date": { "from": "2026-04-01", "to": "2026-04-21" },
  "allo_numbers": ["+14155550100"],
  "tags": ["meeting_booked"],
  "granularity": "WEEK"
}

Team and setup

Resolve a team member name to filter conversations

# 1. Find the user
GET /v2/api/users

# 2. Use their ID to filter
POST /v2/api/conversations/items/search
{ "user_id": "usr-abc123", "type": "CALL" }

Find which Allo number to use for a country

GET /v2/api/numbers

Filter the response by country and check capabilities to find a number that supports the channel you need (VOICE, SMS, MMS).

List all available tags before building a report

GET /v2/api/tags

Use the tag names in conversation search filters or as conversion tags in analytics.

API

Webhooks

Conversations

People

Companies

Deals

Notes

Threads

Phone Numbers

Tags

Summary Templates

Users

SMS

Analytics

Power Dialer

Partner

Getting started

Syncing data

Searching conversations

Taking actions

Analytics and reporting

Team and setup

​Getting started

​Syncing data

​Searching conversations

​Taking actions

​Analytics and reporting

​Team and setup

Getting started

Syncing data

Searching conversations

Taking actions

Analytics and reporting

Team and setup