Skip to main content

Documentation Index

Fetch the complete documentation index at: https://help.withallo.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Getting started

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

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.
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

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.
POST /v2/api/conversations/items/search
{
  "contact_number": "+14155551234",
  "search": "refunds",
  "sort": "RELEVANCE"
}

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 /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.
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.
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"
}

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

# 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.
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.
PUT /v2/api/conversations/%2B14155551234/action
{ "action": "ARCHIVE" }
This archives the contact and marks all items as read.
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

# 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"] }

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.
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.
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

# 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" }

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).
GET /v2/api/tags
Use the tag names in conversation search filters or as conversion tags in analytics.