API Documentation | RocketPhone Call Insights

Overview

The Call Insights REST API provides programmatic access to call logs, call summaries, and call quality data for use in your applications and tools. This API allows you to search and retrieve call records with advanced filtering capabilities.

Base URL

Call Insights data is available under the following base URL. The REST API is served over HTTPS; unencrypted HTTP is not supported.

https://portalapi.rp4s.app/api/v1/call-logs

Authentication

To authenticate requests to the Call Insights API, use the X-RP-API-Key header with your API key. API keys are mapped to specific tenants in the system configuration.

Example Request

curl -X POST https://portalapi.rp4s.app/api/v1/call-logs/search \
  -H "X-RP-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "from": "2024-01-01T00:00:00Z",
      "to": "2024-01-31T23:59:59Z",
      "limit": 25,
      "offset": 0
    }
  }'

Search Endpoint

The search endpoint provides advanced filtering capabilities for call logs with support for multiple search criteria, date ranges, and pagination.

POST /call-logs/search

Request Body

{
  "keywords": ["string"],
  "agents": ["string"],
  "teams": ["string"],
  "contacts": ["string"],
  "bookmarks": ["string"],
  "call_directions": ["inbound", "outbound"],
  "call_statuses": ["completed", "failed", "busy"],
  "call_outcomes": ["success", "failure"],
  "call_durations": [
    {
      "from": 0,
      "to": 300
    }
  ],
  "activity_type": "string",
  "from": "2024-01-01T00:00:00Z",
  "to": "2024-01-31T23:59:59Z",
  "limit": 25,
  "offset": 0
}

Parameters

Parameter	Type	Required	Description	Example
`keywords`	string[]	No	Search keywords to match against call data, transcriptions, and notes. Supports partial matching and case-insensitive search.	`["support", "issue", "problem"]`
`agents`	string[]	No	Filter by agent names. Exact match required. Can be full names or partial names.	`["John Doe", "Jane Smith"]`
`teams`	string[]	No	Filter by team names. Exact match required. Used for organizational grouping.	`["Sales", "Support", "Billing"]`
`contacts`	string[]	No	Filter by contact phone numbers. Supports various formats: +1234567890, 123-456-7890, (123) 456-7890.	`["+1234567890", "+1987654321"]`
`bookmarks`	string[]	No	Filter by bookmark tags. Used for categorizing and organizing calls.	`["important", "follow-up", "escalated"]`
`call_directions`	string[]	No	Filter by call direction. Valid values: "inbound" (calls received), "outbound" (calls made).	`["inbound", "outbound"]`
`call_statuses`	string[]	No	Filter by call status. Valid values: "completed", "failed", "busy", "no-answer", "cancelled".	`["completed", "failed"]`
`call_outcomes`	string[]	No	Filter by call outcome. Valid values: "success", "failure", "partial", "abandoned".	`["success", "failure"]`
`call_durations`	object[]	No	Filter by call duration range in seconds. Each object contains "from" and "to" properties.	`[{"from": 60, "to": 600}]`
`activity_type`	string	No	Filter by activity type. Valid values: "call", "voicemail", "sms", "email".	`"call"`
`from`	datetime	No	Start date and time for search range. ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.	`"2024-01-01T00:00:00Z"`
`to`	datetime	No	End date and time for search range. ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.	`"2024-01-31T23:59:59Z"`
`limit`	integer	No	Number of results to return per page. Range: 1-100. Default: 25.	`50`
`offset`	integer	No	Number of results to skip for pagination. Used with limit for pagination. Default: 0.	`25`

Response

Each item in data is a call-log object. Contact crmReference and call crmReference use Salesforce Ids when linked. Media URLs under callMedia are signed URLs that expire after 30 minutes. For team calls, team.name is set; otherwise team is null.

{
  "tenant_name": "Acme Corp",
  "data": [
    {
      "callId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "agent": {
        "name": "Jane Smith"
      },
      "contact": {
        "name": "John Doe",
        "crmReference": "003XX000001FGHIJ",
        "phoneNumber": "+15551234567",
        "type": "Contact"
      },
      "startTime": "2025-08-25T07:02:39.287Z",
      "calledVia": "+15559876543",
      "endTime": "2025-08-25T07:05:44.287Z",
      "duration": 185,
      "direction": "Inbound",
      "outcome": "Completed",
      "status": "Completed",
      "crmReference": "00TXX000007KLMNO",
      "team": {
        "name": "Sales Team"
      },
      "callMedium": "phone",
      "callWasForwarded": false,
      "callWasDiverted": false,
      "callTargetType": "User",
      "wrapUpStatus": "completed",
      "bookmarks": [
        {
          "name": "Pricing discussion",
          "startTime": "2025-08-25T07:03:10.000Z",
          "relativeStartTime": 31,
          "description": "Customer asked about enterprise pricing",
          "reference": "a0BXX000001BOOK1",
          "actionReference": "a0CXX000001ACT01",
          "transcriptionSegments": [
            {
              "description": "What does the enterprise plan include?",
              "startTime": "00:00:31",
              "endTime": "00:00:35",
              "speaker": "Contact"
            }
          ],
          "type": "Automated"
        }
      ],
      "callEvents": [
        {
          "startTime": "2025-08-25T07:02:39.287Z",
          "type": "CallStarted"
        },
        {
          "startTime": "2025-08-25T07:05:44.287Z",
          "type": "CallEnded"
        }
      ],
      "aiinsights": {
        "sentiment": "positive",
        "summary": "Customer inquired about enterprise pricing and next steps.",
        "topics": ["pricing", "enterprise"],
        "coachingTips": [
          {
            "selectedText": "Let me check with my manager",
            "tipsNote": ["Offer a clear next step and timeline"],
            "startTime": "2025-08-25T07:04:00.000Z",
            "type": "Default"
          }
        ]
      },
      "callMedia": {
        "agent-recording_url": "https://storage.googleapis.com/bucket/mic.wav?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Expires=1800&X-Goog-Signature=...",
        "contact-recording_url": "https://storage.googleapis.com/bucket/phone.wav?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Expires=1800&X-Goog-Signature=...",
        "call-transcription_url": "https://storage.googleapis.com/bucket/transcript.json?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Expires=1800&X-Goog-Signature=..."
      }
    }
  ],
  "pagination": {
    "count": 1,
    "offset": 0,
    "limit": 25,
    "total": 142
  },
  "error": null
}

Response Parameters

Parameter	Type	Description	Example
`callId`	string	Unique identifier for the call record	`"a1b2c3d4-e5f6-7890-abcd-ef1234567890"`
`agent`	object	Agent who handled the call (name only).	`{"name":"Jane Smith"}`
`contact`	object	Contact / customer. Name is resolved from the contacts table via callee_id. If callee_type is Account, name/crmReference are resolved from the accounts table instead. phoneNumber comes from the call record customer phone. type comes from callee_type.	`{"name":"John Doe","crmReference":"003XX000001FGHIJ","phoneNumber":"+15551234567","type":"Contact"}`
`startTime`	datetime	Timestamp when the call started (ISO 8601 format)	`"2025-08-25T07:02:39.287Z"`
`calledVia`	string	Tenant-side number that was called (user, team, or org line). Use with callTargetType to know which kind of number it is.	`"+15559876543"`
`endTime`	datetime	Timestamp when the call ended (ISO 8601 format)	`"2025-08-25T07:05:44.287Z"`
`duration`	integer	Call duration in seconds	`185`
`direction`	string	Call direction (e.g. Inbound / Outbound)	`"Inbound"`
`outcome`	string	Call outcome	`"Completed"`
`status`	string	Call status	`"Completed"`
`crmReference`	string	Salesforce Task Id (00T…) linked to the call	`"00TXX000007KLMNO"`
`team`	object \| null	Present only for team calls, with the team name. Otherwise null.	`{"name":"Sales Team"}` or `null`
`callMedium`	string	Medium used for the call	`"phone"`
`callWasForwarded`	boolean	Whether the call was forwarded	`false`
`callWasDiverted`	boolean	Whether the call was diverted	`false`
`callTargetType`	string	What calledVia belongs to: "User", "Team", "Org", "Account", "Contact", etc.	`"User"`
`wrapUpStatus`	string	Wrap-up status of the call record	`"completed"`
`bookmarks`	object[]	Bookmarks detected on the call. reference / actionReference use Salesforce Ids when available.	—
`callEvents`	object[]	Timeline events for the call	—
`aiinsights`	object	AI insights: sentiment, summary, topics, and coaching tips	—
`callMedia`	object	Signed media URLs (agent recording, contact recording, transcription). Valid for 30 minutes.	—

Pagination Object

Parameter	Type	Description
`count`	integer	Number of records returned in current response
`offset`	integer	Number of records skipped for pagination
`limit`	integer	Maximum number of records requested
`total`	integer	Total number of records matching the search criteria

Complex Objects

agent

Parameter	Type	Description
`name`	string	Agent display name

contact

Parameter	Type	Description
`name`	string	Resolved from contacts via call record callee_id → contacts id (first_name + last_name)
`crmReference`	string	Salesforce Id for the contact CRM record (Contact 003…, Account 001…, Lead 00Q…, etc.)
`phoneNumber`	string	Customer phone from the call record (customer_phone)
`type`	string	From call record callee_type: Account, Contact, Lead, etc.

team

If the call is a team call, team contains the team name. If it is not a team call, team is null.

Parameter	Type	Description
`name`	string	Team name (only when this is a team call)

Bookmark Object

Parameter	Type	Description
`name`	string	Bookmark name
`startTime`	datetime	Absolute start time of the bookmark
`relativeStartTime`	integer	Seconds from call start when the bookmark occurs
`description`	string	Bookmark description
`reference`	string	Salesforce reference Id for the bookmark
`actionReference`	string	Salesforce reference Id for the bookmark action
`transcriptionSegments`	object[]	Related transcript segments (description, startTime, endTime, speaker)
`type`	string	Bookmark type (e.g. Automated)

callEvents

Parameter	Type	Description
`startTime`	string	Event timestamp
`type`	string	Event type (e.g. CallStarted, CallEnded)

aiinsights

Parameter	Type	Description
`sentiment`	string	Overall sentiment (positive / negative / neutral)
`summary`	string	AI call summary from open_ai_call_summary.ConversationSummary
`topics`	string[]	Topics detected on the call
`coachingTips`	object[]	Coaching tips (selectedText, tipsNote, startTime, type)

callMedia

All URLs are time-limited signed URLs and are valid for 30 minutes from the time of the response. Re-request the search (or sign-media) endpoint if a URL has expired.

Parameter	Type	Description
`agent-recording_url`	string	Signed URL for the agent (mic) recording
`contact-recording_url`	string	Signed URL for the contact (phone) recording
`call-transcription_url`	string	Signed URL for the call transcription

Examples

Basic Search

Search for calls within a date range:

curl -X POST https://portalapi.rp4s.app/api/v1/call-logs/search \
  -H "X-RP-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "2024-01-01T00:00:00Z",
    "to": "2024-01-31T23:59:59Z",
    "limit": 10
  }'

Advanced Search

Search with multiple filters:

curl -X POST https://portalapi.rp4s.app/api/v1/call-logs/search \
  -H "X-RP-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agents": ["John Doe", "Jane Smith"],
    "call_directions": ["inbound"],
    "call_statuses": ["completed"],
    "call_durations": [
      {
        "from": 60,
        "to": 600
      }
    ],
    "from": "2024-01-01T00:00:00Z",
    "to": "2024-01-31T23:59:59Z",
    "limit": 25
  }'

Keyword Search

Search for calls containing specific keywords:

curl -X POST https://portalapi.rp4s.app/api/v1/call-logs/search \
  -H "X-RP-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "keywords": ["support", "issue", "problem"],
    "from": "2024-01-01T00:00:00Z",
    "to": "2024-01-31T23:59:59Z",
    "limit": 50
  }'

Error Codes

HTTP Status	Error Code	Description
400	`INVALID_INPUT`	Invalid request parameters or malformed JSON
401	`UNAUTHORIZED`	Missing or invalid API key
404	`NOT_FOUND`	Resource not found
429	`RATE_LIMIT_EXCEEDED`	Rate limit exceeded
500	`INTERNAL_ERROR`	Internal server error

Error Response Example

{
  "error": {
    "title": "Invalid Input",
    "details": "Invalid date format for 'from' parameter",
    "error_code": "INVALID_INPUT"
  }
}