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://your-domain.com/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://your-domain.com/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

{
   "data": [
     {
       "agentName": "string",
       "agentReference": "string",
       "agentPhoneNumber": "string",
       "contactName": "string",
       "contactReference": "string",
       "contactPhoneNumber": "string",
       "startTime": "2025-08-25T07:02:39.287Z",
       "duration": 0,
       "direction": "string",
       "outcome": "string",
       "status": "string",
       "sentiment": "string",
       "summary": "string",
       "topics": ["string"],
       "callTaskRemoteId": "string",
       "remoteId": "string",
       "teamName": "string",
       "accountName": "string",
       "accountReference": "string",
       "accountPhoneNumber": "string",
       "note": {
         "title": "string",
         "text": "string"
       },
       "callMedium": "string",
       "callWasForwarded": true,
       "callWasDiverted": true,
       "callInitiatorUserName": "string",
       "campaignName": "string",
       "callTargetType": "User",
       "conferenceCallStatus": "None",
       "isConferenceCall": true,
       "callRecordWrapUpStatus": "string",
       "activityType": "string",
       "smsContent": {
         "message": "string",
         "templateTitle": "string"
       },
       "emailContent": {
         "subject": "string",
         "recipients": ["string"],
         "recipientsCc": ["string"],
         "recipientsBcc": ["string"]
       },
       "bookmarks": [
         {
           "name": "string",
           "startTime": "2025-08-25T07:02:39.287Z",
           "relativeStartTime": 0,
           "description": "string",
           "bookmarkReference": "string",
           "bookmarkActionReference": "string",
           "transcriptionSegments": [
             {
               "description": "string",
               "relativeStartTime": "string",
               "relativeEndTime": "string",
               "speaker": "string",
               "role": "NotSet"
             }
           ],
           "type": "Automated"
         }
       ],
       "conferenceCallEvents": [
         {
           "statusCallbackEvent": "string",
           "timestamp": "string"
         }
       ],
       "callEvents": [
         {
           "startTime": "string",
           "type": "string"
         }
       ],
       "coachingTips": [
         {
           "selectedText": "string",
           "tipsNote": ["string"],
           "startTime": "2025-08-25T07:02:39.287Z",
           "type": "Default"
         }
       ],
       "calleeDetails": {
         "calleeType": "Account",
         "reference": "string",
         "name": "string",
         "phoneNumber": "string"
       },
       "callRecordID": "string"
     }
   ],
   "pagination": {
     "total": 0,
     "count": 0,
     "offset": 0,
     "limit": 0
   }
 }

Response Parameters

Parameter	Type	Description	Example
`agentName`	string	Name of the agent who handled the call	`"John Doe"`
`agentReference`	string	Unique reference identifier for the agent	`"agent_123"`
`agentPhoneNumber`	string	Phone number of the agent	`"+1234567890"`
`contactName`	string	Name of the contact/customer	`"Jane Smith"`
`contactReference`	string	Unique reference identifier for the contact	`"contact_456"`
`contactPhoneNumber`	string	Phone number of the contact/customer	`"+1987654321"`
`startTime`	datetime	Timestamp when the call started (ISO 8601 format)	`"2025-08-25T07:02:39.287Z"`
`duration`	integer	Call duration in seconds	`180`
`direction`	string	Call direction: "inbound" or "outbound"	`"inbound"`
`outcome`	string	Call outcome: "success", "failure", "partial", "abandoned"	`"success"`
`status`	string	Call status: "completed", "failed", "busy", "no-answer", "cancelled"	`"completed"`
`sentiment`	string	Sentiment analysis of the call: "positive", "negative", "neutral"	`"positive"`
`summary`	string	AI-generated summary of the call content	`"Customer called about billing issue..."`
`topics`	string[]	Array of topics discussed during the call	`["billing", "support"]`
`callTaskRemoteId`	string	Remote task ID associated with the call	`"task_789"`
`remoteId`	string	Remote system identifier for the call	`"remote_123"`
`teamName`	string	Name of the team the agent belongs to	`"Sales Team"`
`accountName`	string	Name of the account associated with the call	`"Acme Corp"`
`accountReference`	string	Unique reference identifier for the account	`"account_101"`
`accountPhoneNumber`	string	Phone number of the account	`"+1555123456"`
`note`	object	Note object with title and text fields	`{"title": "Follow-up", "text": "Call customer back"}`
`callMedium`	string	Medium used for the call: "phone", "web", "mobile"	`"phone"`
`callWasForwarded`	boolean	Whether the call was forwarded to another agent	`true`
`callWasDiverted`	boolean	Whether the call was diverted to another number	`false`
`callInitiatorUserName`	string	Username of the person who initiated the call	`"john.doe"`
`campaignName`	string	Name of the campaign associated with the call	`"Q4 Sales Campaign"`
`callTargetType`	string	Type of call target: "User", "Account", "Contact"	`"User"`
`conferenceCallStatus`	string	Status of conference call: "None", "Active", "Ended"	`"None"`
`isConferenceCall`	boolean	Whether this is a conference call	`false`
`callRecordWrapUpStatus`	string	Wrap-up status of the call record	`"completed"`
`activityType`	string	Type of activity: "call", "voicemail", "sms", "email"	`"call"`
`callRecordID`	string	Unique identifier for the call record	`"call_123456789"`

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

Note Object

Parameter	Type	Description
`title`	string	Title of the note
`text`	string	Content of the note

Bookmark Object

Parameter	Type	Description
`name`	string	Name of the bookmark
`startTime`	datetime	Timestamp when bookmark was created
`relativeStartTime`	integer	Start time relative to call beginning (seconds)
`description`	string	Description of the bookmark
`bookmarkReference`	string	Unique reference for the bookmark
`type`	string	Type of bookmark: "Automated", "Manual"

Coaching Tip Object

Parameter	Type	Description
`selectedText`	string	Text that was selected for coaching
`tipsNote`	string[]	Array of coaching tips
`startTime`	datetime	Timestamp when tip was generated
`type`	string	Type of coaching tip: "Default", "Custom"

Callee Details Object

Parameter	Type	Description
`calleeType`	string	Type of callee: "Account", "Contact", "User"
`reference`	string	Reference identifier for the callee
`name`	string	Name of the callee
`phoneNumber`	string	Phone number of the callee

Examples

Basic Search

Search for calls within a date range:

curl -X POST https://your-domain.com/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://your-domain.com/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://your-domain.com/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"
  }
}