Organization API

Log a call from a phone system

Requires conversations and phoneSystem enabled. Use E.164 phone numbers (US ten-digit numbers are also accepted). A known customer matches the newest open Case, or their General Conversation when no Case is open. Unknown or ambiguous callers wait in Unmatched for staff selection. A Case hint must belong to the matched customer. Processing is asynchronous; 202 returns id (the Call ID), eventId and status in the data envelope. Repeating an identical request returns the same receipt; reusing a key or provider call ID with different details returns 409. Recording links remain at the provider. Maximum request body: 300,000 bytes.

/api/v1/communications/calls

Log a call from a phone system. Use an organization API key with communications:write. Check the response envelope and meta.requestId before triggering dependent workflow steps.

Required scopes

communications:writeIdempotency-Key required

Parameters

No path or query parameters.

Request body

objectrequired

Field	Type	Description
providerCallId	string	Stable provider ID, unique within the company. Prefix with the phone system name when using multiple systems. Omit to derive an ID from this API key and Idempotency-Key.
directionrequired	INBOUND \| OUTBOUND	Optional unless marked required.
fromrequired	string	Optional unless marked required.
torequired	string	Optional unless marked required.
startedAtrequired	string	Optional unless marked required.
endedAt	string	Optional unless marked required.
durationSeconds	integer	Optional unless marked required.
resultrequired	ANSWERED \| MISSED \| VOICEMAIL \| BUSY \| FAILED	Optional unless marked required.
user	object	Optional unless marked required.
user.emailrequired	string	Active company team member who handled the call.
personEmail	string	Alias of user.email; when both are supplied they must match.
recordingUrl	string	HTTPS provider recording link. Recording audio is never copied into solarOS.
recordingExpiresAt	string	Optional unless marked required.
transcript	string	Optional unless marked required.
summary	string	Optional unless marked required.
hint	object	Optional unless marked required.
hint.caseNumber	string \| integer	Optional unless marked required.
hint.customerEmail	string	Optional unless marked required.

logcommunicationcallRequest

{
  "providerCallId": "phone-system:call-2417",
  "direction": "INBOUND",
  "from": "+17075550101",
  "to": "+17075550102",
  "startedAt": "2026-09-12T17:00:00Z",
  "endedAt": "2026-09-12T17:02:00Z",
  "durationSeconds": 120,
  "result": "ANSWERED",
  "user": {
    "email": "service@example.com"
  },
  "recordingUrl": "https://phone.example.com/recordings/call-2417",
  "transcript": "Customer: The inverter lights are red and green.",
  "summary": "Customer reports red and green inverter lights.",
  "hint": {
    "caseNumber": "2417"
  }
}

Responses

202

Call retained for matching; receipt contains id (the Call ID), eventId and status

#/components/schemas/OrgApiResourceEnvelope

401

Missing or invalid organization API key