Allo

Common use cases

Examples of how to use the Allo API to answer business questions and automate workflows

Updated on

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.

This counts inbound calls that went to voicemail. Outbound calls that reached the contact's answering machine keep result: "ANSWERED" — identify those with the detected_outbound_voicemail field on each item.

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.