Allo

Send fax

Sends a PDF as a fax from one of your Allo lines. The line must be a US or Canada local number on which fax is turned on in the number settings ("Send and…

POST/v2/api/faxes

Behavior

Sends a PDF as a fax from one of your Allo lines. The request is multipart/form-data with three parts: from, to and file.

curl -X POST https://api.withallo.com/v2/api/faxes \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -F "from=+14155550100" \
  -F "to=+14155551234" \
  -F "[email protected];type=application/pdf"

The response is 201 with the new conversation item: type SMS, message_type FAX, status PENDING, and the PDF in attachments. The fax goes out in the background. page_count is null in this response and is set once the fax has been sent. Fetch the item later with Get conversation item to follow its status.

Requirements

  • Fax is enabled on your account.
  • from is a US or Canada local number you can use, with Send and receive faxes turned on in its number settings in the Allo app. Toll-free numbers and sender IDs cannot send faxes.
  • file is a PDF sent with content type application/pdf, of at most 12 MB.
  • Your team has enough credits. Each faxed page uses message credits.

See Fax overview for how faxes appear in conversations.

Errors

StatusCodeWhen
400MISSING_PARAMETERfrom, to or file is missing
400FAX_NOT_SUPPORTED_ON_NUMBERThe from line cannot send faxes
400FAX_NOT_ENABLED_ON_LINESend and receive faxes is turned off on the from line
400FAX_FILE_NOT_PDFfile is not sent as application/pdf
400FAX_FILE_EMPTYfile is empty
400MAX_UPLOAD_SIZE_EXCEEDEDfile is larger than 12 MB
402INSUFFICIENT_CREDITSYour team does not have enough credits to send the fax
403FAX_NOT_AVAILABLEFax is not enabled on your account. Contact Allo support.
404FROM_NUMBER_NOT_FOUNDfrom is not a line you can use

Other errors, such as an invalid to number, are the same as for sending an SMS. See Error codes.

Authorization

Authorizationstring · headerrequired

Scope needed: FAX_SEND

Responses

201Fax accepted for sending. Returns the new conversation item.
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.

ANSWEREDVOICEMAILTRANSFERRED_AITRANSFERRED_EXTERNALBLOCKEDFAILEDFAILED_EXTERNALRECEIVEDCLOSED

detected_outbound_voicemailboolean | null

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.

recording_download_expires_atstring<date-time> | null

When recording_download_url stops working.

recording_durationinteger | null

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.

400
401
402Not enough message credits to send the fax
errorobject
6 fields
typestring
codestring
messagestring
retryableboolean
request_idstring
retry_after_secondsinteger | null
403
404
429