Search and filter items across all conversations. Supports keyword search across transcripts, summaries, and message content.
POST/v2/api/conversations/items/search
This endpoint is paginated. Use page and size in the request body to control results. See Pagination.
Outbound calls that reached a voicemail
When an outbound call is answered by the contact's answering machine, result stays ANSWERED, because the carrier treats a machine pickup as an answer. Two fields carry the voicemail signal instead:
Field
Meaning
detected_outbound_voicemail
A machine picked up (answering machine detection, or the transcript)
voicemail_left
A message was actually left after the beep
Both are independent: detected_outbound_voicemail: true with voicemail_left: false means the call reached a voicemail and the caller hung up without leaving a message. Either can be null when that particular signal was never determined. null is not the same as false.
Search behavior
The search field is a keyword search, not a natural language query. Extract keywords from the user's question before passing them.
User asks
search value
"Find calls where customers complained about billing"
"billing complaint"
"What did we discuss about the refund policy?"
"refund policy"
"Show me conversations mentioning enterprise pricing"
"enterprise pricing"
How matching works:
Terms are AND'd: "billing refund" matches items containing both words
Prefix matching is used: "bill" matches "billing", "billed", etc.
Searches across: call transcripts, call summaries, and SMS message content
Use sort=RELEVANCE to rank results by match quality instead of date
Filter by type
type
Returns
ALL (default)
Calls and messages
CALL
Calls only
SMS
Messages, faxes included
FAX
Faxes only
A fax is returned as an item of typeSMS with message_typeFAX. See Faxes.
Field notes
Field
Null when
summary
SMS items, or calls where AI summary is not yet available
duration
SMS items (only applies to calls)
result
SMS items (only applies to calls)
detected_outbound_voicemail
Inbound calls, SMS items, or outbound calls where no detection ran
voicemail_left
Inbound calls, SMS items, or outbound calls where it was not determined
recording_url
Recording disabled, call not answered, SMS items, or accounts sold under a white-label partner's brand
recording_download_url
Accounts not created by a partner, calls on a HIPAA-enabled team, calls without a recording, a key user who cannot play the recording, or SMS items
recording_download_expires_at
Same as recording_download_url
recording_duration
Recording disabled, call not answered, or SMS items
transcript
Not requested via extend=transcript, or SMS items
content
Call items (only applies to SMS)
status
Call items (only applies to SMS)
attachments
Call items. An SMS with no photo or file returns an empty array.
page_count
Calls, messages that are not faxes, or a fax whose page count is not known yet
tags
SMS items (tags only apply to calls)
duration is the total call length in seconds, ringing included. recording_duration is the talk time, which is what the Allo app displays for recorded calls. For calls without a recording, the app falls back to duration.
recording_download_url downloads the recording file with no Allo login, for 48 hours. It is returned only on lines of accounts created by a partner, never for a HIPAA call. See Recording links.
attachments lists the photos and other files of an MMS, each with a download_url valid for 30 minutes. See MMS attachments.
Extend parameter
Value
Effect
transcript
Include full call transcripts on each item
Passing an unsupported value returns a 400 error with code UNSUPPORTED_EXTEND_VALUE.
Authorization
Authorizationstring · headerrequired
Api-Key ak_live_…
Body
allo_numberstring
contact_numberstring
user_idstring
directionenum<string>
INBOUNDOUTBOUND
typeenum<string>
SMS returns all messages, faxes included. FAX returns only faxes.
CALLSMSFAXALL
resultenum<string>
ANSWEREDVOICEMAILTRANSFERRED
tagsstring[]
unreadboolean
unrespondedboolean
searchstring
Keyword search (not natural language). Extract keywords from the user's question. Terms are AND'd with prefix matching — 'billing refund' matches items containing both words, 'bill' matches 'billing'. Searches across call transcripts, summaries, and SMS content.
sortenum<string>
DATE_DESCDATE_ASCRELEVANCE
extendstring
pageinteger
sizeinteger
dateobject
2 fields
fromstring<date>required
Start date
tostring<date>required
End date
Responses
200Search results
dataobject[]
26 fields
idstring
typeenum<string>
CALL for a call, SMS for a message. Faxes are SMS items with message_type set to FAX.
CALLSMS
directionenum<string>
INBOUNDOUTBOUND
allo_numberstring
contact_numberstring
contactsobject[]
4 fields
idstring
namestring
companyobject | null
2 fields
idstring
namestring
dealsobject[]
3 fields
idstring
namestring
statusenum<string>
OPENWONLOST
userobject
3 fields
idstring
namestring
emailstring
datestring<date-time>
durationinteger | null
Total call length in seconds, from when the call starts (ringing included) to when it ends. For the talk time shown in the Allo app, use recording_duration.
resultenum<string>
Call outcome. Null for SMS items. An outbound call that reached voicemail reports VOICEMAIL. FAILED_EXTERNAL only appears on older calls. New values may be added: handle unknown values gracefully.
Outbound calls only. true when the call was answered by an answering machine, false when a human answered, null when no detection ran for this call (never set on inbound calls or SMS). Note that result stays ANSWERED for these calls — the carrier considers a machine pickup an answer.
voicemail_leftboolean | null
Outbound calls only. true when a message was actually left on the voicemail, false when the caller hung up without leaving one, null when not determined. Independent of detected_outbound_voicemail: either can be set without the other.
recording_urlstring | null
Link to the call recording. Absent when the call was not recorded, and for accounts sold under a white-label partner's brand: use recording_download_url there.
recording_download_urlstring | null
Signed link that downloads the recording with no login, valid for 48 hours. Returned only for lines of accounts created by a partner, never for a call on a HIPAA-enabled team, and only when the key's user can play the recording. For a fresh link, call GET /v2/api/conversations/items/{id}/recording.
Length of the call recording in seconds: the talk time, excluding ringing. This is the duration shown in the Allo app for recorded calls. null when the call was not recorded.
summarystring | null
tagsstring[]
extracted_dataobject | null
Contact details Allo's AI picked up from the call transcript, under a contact object: name, company, job_title, website, address (strings, empty when not mentioned) and emails (array). Null for SMS items and for calls Allo has not analyzed.
1 fields
contactobject
6 fields
namestring
companystring
job_titlestring
websitestring
addressstring
emailsstring[]
data_collectedobject | null
Legacy field kept for compatibility. An empty object on current calls. Null for SMS items.
transcriptobject[]
3 fields
sourceenum<string>
USEREXTERNAL
timestring<date-time>
textstring
contentstring | null
statusenum<string>
PENDINGSENTDELIVEREDFAILED
message_typeenum<string>
SMSMMSWHATSAPPFAX
attachmentsobject[]
Photos and other files sent with the message, in the order they were sent. For a fax, the faxed PDF. An empty array for a message with no files, and null for a call.
5 fields
file_namestring
content_typestring
MIME type of the file.
file_sizeinteger<int64> | null
Size of the file in bytes.
download_urlstring | null
Signed link that downloads the file with no login, valid for 30 minutes. null for a message on a HIPAA-enabled team. For a fresh link, fetch the item again.
download_expires_atstring<date-time> | null
When download_url stops working.
page_countinteger | null
Number of pages of a fax. null for calls, for messages that are not faxes, and for a fax whose page count is not known yet.