The Calls API from Root Insurance — 4 operation(s) for calls.
openapi: 3.1.0
info:
version: 1.0.1
title: Root Applications Calls API
description: Root is an end-to-end digital insurance platform that enables you to launch new products and digital engagement channels fast.
termsOfService: https://rootplatform.com/about
contact:
name: Root support team
url: https://rootplatform.com/contact
email: support@root.co.za
servers:
- url: https://sandbox.uk.rootplatform.com/v1/insurance
description: United Kingdom multi-tenant - sandbox
- url: https://api.uk.rootplatform.com/v1/insurance
description: United Kingdom multi-tenant - production
- url: https://sandbox.rootplatform.com/v1/insurance
description: South Africa multi-tenant - sandbox
- url: https://api.rootplatform.com/v1/insurance
description: South Africa multi-tenant - production
security:
- basicAuth: []
tags:
- name: Calls
paths:
/calls:
get:
operationId: fetch-calls
summary: List all calls
description: Returns a paginated list of calls for the organization. Use the `include` parameter to include the related policyholder object.
tags:
- Calls
x-additional-tags:
- Endpoints
parameters:
- $ref: '#/components/parameters/page_size'
- $ref: '#/components/parameters/page'
- name: call_status
in: query
description: Filter by call status. Accepts multiple values.
required: false
schema:
type: array
items:
type: string
enum:
- initiated
- ringing
- in-progress
- completed
- busy
- no-answer
style: form
explode: false
example: completed,busy
- name: include
in: query
description: 'A comma-separated list of related objects to include in the response. Valid values: `policyholder`.'
required: false
schema:
type: array
items:
type: string
enum:
- policyholder
style: form
explode: false
example: policyholder
responses:
'200':
description: Success
headers:
X-Total-Count:
description: The total number of calls matching the query.
schema:
type: integer
example: 42
content:
application/json:
schema:
$ref: '#/components/schemas/calls'
example:
- call_id: 0ac6dffb-bd15-4829-b96d-e2c1abe61d3a
policyholder_id: 8349345c-a6c5-4bf9-8ebb-6bbfc1628715
claim_id: null
created_at: '2017-11-26T11:14:59.777Z'
call_status: completed
direction: inbound
from_number: '+27823378000'
to_number: '+27821234567'
topic: general
recording_url: https://recordingurl.com
call_duration: '5'
post:
operationId: create-call
summary: Create a call
description: Creates a new call record with an associated recording. The recording must be provided as a base64-encoded string.
tags:
- Calls
x-additional-tags:
- Endpoints
parameters: []
requestBody:
content:
application/json:
schema:
type: object
required:
- recording_file_name
- recording_file_type
- recording_base64_string
properties:
claim_id:
type: string
description: Must be a UUID. The unique identifier of the [claim](ref:claim) for which the call is being made.
policyholder_id:
type: string
description: Must be a UUID. The unique identifier of the [policyholder](ref:policyholder) for whom the call is being made.
direction:
type: string
description: The direction of the call.
enum:
- inbound
- outbound
from:
type: string
description: The phone number the call was made from.
to:
type: string
description: The phone number the call was made to.
topic:
type: string
description: The topic category of the call.
enum:
- claims
- complaints
- general
call_duration:
type: integer
minimum: 0
description: The duration of the call in seconds.
call_status:
type: string
description: The status of the call.
enum:
- initiated
- ringing
- in-progress
- completed
- busy
- no-answer
recording_file_name:
type: string
description: The filename of the recording (e.g., `Recording0001.mp3`).
recording_file_type:
type: string
description: The MIME type of the recording. Must be `audio/mpeg`.
recording_base64_string:
type: string
description: The base64-encoded string of the call recording.
example:
policyholder_id: 8349345c-a6c5-4bf9-8ebb-6bbfc1628715
claim_id: 673b8081-9668-4136-97cc-6ae0debda083
direction: outbound
from: '0721234567'
to: 0821234567
topic: general
call_duration: 72
call_status: completed
recording_file_name: Recording0001.mp3
recording_file_type: audio/mpeg
recording_base64_string: //uUZAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWGluZwAAAA8AAAAT
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/call'
example:
call_id: d3d13c48-4dc3-4816-8d01-de3215878225
policyholder_id: 8349345c-a6c5-4bf9-8ebb-6bbfc1628715
claim_id: 673b8081-9668-4136-97cc-6ae0debda083
created_at: '2017-10-16T10:12:02.872Z'
call_status: completed
direction: outbound
from_number: '0721234567'
to_number: 0821234567
topic: general
recording_url: https://sandbox.root.co.za/v1/files/download/ccbd249e-a404-11ea-8f4a-47e769474b83/Recording0001.mp3
call_duration: '72'
/calls/{call_id}:
get:
operationId: retrieve-call
summary: Retrieve a call
tags:
- Calls
x-additional-tags:
- Endpoints
parameters:
- name: call_id
in: path
description: Must be a UUID. The unique identifier of the [call](ref:call).
required: true
schema:
type: string
example: d3d13c48-4dc3-4816-8d01-de3215878225
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/call'
example:
call_id: d3d13c48-4dc3-4816-8d01-de3215878225
policyholder_id: 8349345c-a6c5-4bf9-8ebb-6bbfc1628715
claim_id: 673b8081-9668-4136-97cc-6ae0debda083
created_at: '2017-10-16T10:12:02.872Z'
call_status: completed
direction: outbound
from_number: '0721234567'
to_number: 0821234567
topic: general
recording_url: https://sandbox.root.co.za/v1/files/download/ccbd249e-a404-11ea-8f4a-47e769474b83/Recording0001.mp3
call_duration: '72'
/calls/{call_id}/events:
get:
operationId: retrieve-call-events
summary: Retrieve call events
description: Returns a list of events associated with a specific call, sorted by creation time in descending order (most recent first). Events include call status changes, recordings added, and other call-related activities.
tags:
- Calls
x-additional-tags:
- Events
parameters:
- name: call_id
in: path
description: Must be a UUID. The unique identifier of the [call](ref:call).
required: true
schema:
type: string
example: d3d13c48-4dc3-4816-8d01-de3215878225
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
type: object
description: An event object containing details about an action that occurred on the call.
properties:
type:
type: string
description: 'The type of call event. Possible values include: `inbound_call_started`, `outbound_call_started`, `option_entered`, `recording_added`, `call_initiated`, `call_ringing`, `call_answered`, `call_completed`, `call_not_answered`, `called_busy`, `call_flushed`, `call_created`, `call_updated`, `connect_call_initiated`, `connect_call_ringing`, `connect_call_answered`, `connect_call_completed`, `connect_call_not_answered`, `connect_called_busy`.'
call_id:
type: string
description: Must be a UUID. The unique identifier of the call.
created_at:
type: string
format: date-time
description: The timestamp at which the event occurred.
requested_by:
type: object
description: An object indicating the user or API key that triggered the event.
properties:
type:
type: string
description: The type of requester (e.g., `user`, `api_key`).
id:
type: string
description: The unique identifier of the requester.
owner_id:
type: string
description: The owner ID associated with the requester.
to_number:
type: string
description: The destination phone number. Only present for `connect_call_initiated` events.
from:
type: string
description: The originating phone number. Present for `inbound_call_started` and `outbound_call_started` events.
to:
type: string
description: The destination phone number. Present for `outbound_call_started` events.
option:
type: string
description: The option entered by the caller. Only present for `option_entered` events.
recording_url:
type: string
description: The URL of the call recording. Only present for `recording_added` events.
example:
- type: call_completed
call_id: d3d13c48-4dc3-4816-8d01-de3215878225
created_at: '2023-02-03T12:05:00.000Z'
requested_by:
type: system
id: 00000000-0000-0000-0000-000000000000
- type: recording_added
call_id: d3d13c48-4dc3-4816-8d01-de3215878225
created_at: '2023-02-03T12:04:30.000Z'
requested_by:
type: system
id: 00000000-0000-0000-0000-000000000000
recording_url: https://sandbox.root.co.za/v1/files/download/ccbd249e-a404-11ea-8f4a-47e769474b83/Recording0001.mp3
- type: call_answered
call_id: d3d13c48-4dc3-4816-8d01-de3215878225
created_at: '2023-02-03T12:00:15.000Z'
requested_by:
type: system
id: 00000000-0000-0000-0000-000000000000
- type: outbound_call_started
call_id: d3d13c48-4dc3-4816-8d01-de3215878225
created_at: '2023-02-03T12:00:00.000Z'
requested_by:
type: user
id: 00000000-0000-0000-0000-000000000001
from: '0721234567'
to: 0821234567
/calls/{call_id}/playback-url:
get:
operationId: retrieve-call-playback-url
summary: Retrieve call playback URL
description: Returns a signed URL for playing back the recording of a specific call. If the call has an associated attachment, a signed download URL is returned. Otherwise, the legacy recording URL is returned if available. Returns a 404 error if no recording exists for the call.
tags:
- Calls
x-additional-tags:
- Playback
parameters:
- name: call_id
in: path
description: Must be a UUID. The unique identifier of the [call](ref:call).
required: true
schema:
type: string
example: d3d13c48-4dc3-4816-8d01-de3215878225
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
required:
- url
properties:
url:
type: string
description: The URL to play back the call recording. This may be a signed download URL (for newer recordings stored as attachments) or a legacy recording URL.
file_id:
type: string
description: Must be a UUID. The unique identifier of the attachment file. Only present if the recording is stored as an attachment.
file_type:
type: string
description: The MIME type of the recording file (e.g., `audio/mpeg`). Only present if the recording is stored as an attachment.
file_name:
type: string
description: The filename of the recording. Only present if the recording is stored as an attachment.
file_url:
type: string
description: The permanent download URL for the file. Only present if the recording is stored as an attachment.
created_at:
type: integer
description: Unix timestamp (seconds) when the attachment was created. Only present if the recording is stored as an attachment.
examples:
with_attachment:
summary: Recording stored as attachment
value:
url: https://sandbox.root.co.za/v1/files/download/ccbd249e-a404-11ea-8f4a-47e769474b83/Recording0001.mp3?signature=abc123
file_id: ccbd249e-a404-11ea-8f4a-47e769474b83
file_type: audio/mpeg
file_name: Recording0001.mp3
file_url: https://sandbox.root.co.za/v1/files/download/ccbd249e-a404-11ea-8f4a-47e769474b83
created_at: 1697456522
legacy_url:
summary: Legacy recording URL
value:
url: https://recordings.example.com/Recording0001.mp3
'404':
description: Not Found - No recording exists for this call
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Error type identifier.
message:
type: string
description: Human-readable error message.
example:
error: not_found
message: No recording url or attachment found for call with id d3d13c48-4dc3-4816-8d01-de3215878225
components:
parameters:
page_size:
name: page_size
in: query
description: The maximum number of items that will be contained in a single page, between 1 and 100 (inclusive).
required: false
schema:
type: integer
minimum: 1
maximum: 100
example: 30
default: 30
page:
name: page
in: query
description: The page number of the entities to fetch. Must be a minimum of 1.
required: false
schema:
type: integer
minimum: 1
example: 1
default: 1
schemas:
call:
type: object
required:
- call_id
- created_at
- call_status
- direction
- from_number
- topic
properties:
call_id:
type: string
description: Must be a UUID. The unique identifier of the call.
policyholder_id:
type:
- string
- 'null'
description: Must be a UUID. The unique identifier of the [policyholder](ref:policyholder) associated with the call. `null` if no policyholder is linked.
policyholder:
type:
- object
- 'null'
description: The [policyholder](ref:policyholder) object associated with this call. Only included when `include=policyholder` query parameter is specified.
claim_id:
type:
- string
- 'null'
description: Must be a UUID. The unique identifier of the [claim](ref:claim) associated with the call. `null` if no claim is linked.
created_at:
type: string
format: date-time
description: The timestamp at which the call was logged.
call_status:
type: string
description: The current status of the call.
enum:
- initiated
- ringing
- in-progress
- completed
- busy
- no-answer
direction:
type: string
description: The direction of the call.
enum:
- inbound
- outbound
from_number:
type: string
description: The initiating phone number of the call.
to_number:
type:
- string
- 'null'
description: The receiving phone number of the call. `null` if not available.
topic:
type: string
description: The topic category of the call.
enum:
- claims
- complaints
- general
recording_url:
type:
- string
- 'null'
description: The URL of the call recording. This is available if the call successfully connected and only once the call is completed. `null` if no recording exists.
call_duration:
type:
- string
- 'null'
description: The duration of the call in seconds. May be `null` if not recorded.
example:
call_id: d3d13c48-4dc3-4816-8d01-de3215878225
policyholder_id: 8349345c-a6c5-4bf9-8ebb-6bbfc1628715
claim_id: 673b8081-9668-4136-97cc-6ae0debda083
created_at: '2017-10-16T10:12:02.872Z'
call_status: completed
direction: outbound
from_number: '0721234567'
to_number: 0821234567
topic: general
recording_url: https://sandbox.root.co.za/v1/files/download/ccbd249e-a404-11ea-8f4a-47e769474b83/Recording0001.mp3
call_duration: '72'
calls:
type: array
items:
$ref: '#/components/schemas/call'
securitySchemes:
basicAuth:
type: http
scheme: basic
x-readme:
explorer-enabled: true
proxy-enabled: true
samples-enabled: true