Overview

Freshcaller is a cloud-based, easy to integrate call center software that allows you to engage, communicate, and collaborate with customers so as to deliver express customer service and handle business systematically and efficiently. These APIs can be easily integrated with various other businesses like sales, marketing, support, and so on.

With Freshcaller APIs, you can access agent and call metrics information, update agent or call details, obtain the status of agents whether busy or available to take calls, and so on.

Status and error messages

Freshcaller uses the following standard HTTP status codes to indicate the success or failure of an API request.

HTTP Status Code Message
200 Success Request
201 Created Record
302 Redirected
401 Unauthenticated Request
403 Forbidden
404 Not Found
422 Unprocessable Entity
423 Locked
429 Too Many Requests
500 Internal Server Error

A successful create request returns 201 Created along with the created object. A successful update request returns 200 OK along with the updated object. A successful request to retrieve a call recording returns 302 Redirected with the corresponding URL mentioned as the value of the location parameter in the response header. An unsuccessful API request returns a relevant HTTP status code along with an error response.


The error response
Example
1
2
3
4
5
6
{ "error_type":"record_not_found", "message":"Couldn't find User with 'id'=102667", "errors":[] }

Attributes
Attribute Name Data Type Description
error_type string Error definition corresponding to the standard HTTP status code.
message string Freshcaller specific message that states the cause of the error.
errors
Displayed only when error_type is model_validation_failed.
array of objects Lists the attributes that cause the error.

Date and time literals

All system generated timestamps in the date-time format follow the Coordinated Universal Time (UTC) standard.
All attributes that accept or return data in the date format, follow the YYYY-MM-DD format.

Header parameters

The common request header parameters that are used in requests to Freshcaller APIs are as follows:

  • Accept
  • X-Api-Auth

Accept

Specifies the accepted format of response. The parameter is used in API requests that are expected to return a response body.

Header parameter format

Accept: application/<format>

<format> is typically JSON and a parameter value of application/JSON specifies that the response must be a JSON object.
A parameter value of */* specifies that data of any type is acceptable as the response.

X-Api-Auth

Specifies the credentials required to authenticate and authorize an API request.

Header parameter format

X-Api-Auth: <access-token>

Authorization

To make valid API requests, obtain an API key and pass it as the access-token in the X-Api-Auth header parameter. To obtain the API key:

  1. Navigate to your Freshcaller domain and log in to your account.
  2. Click the profile icon on the right side of the page. A menu is displayed.
  3. Click Profile Settings. The Profile Settings window is displayed. The API key (access-token) is displayed under YOUR API KEY.

Rate Limits

The permissible number of API calls per minute is based on the Freshcaller plan opted for an organization. The rate limit for each plan is applied to an account irrespective of the number of users in the organization and the IP address used to make calls.

Plan Rate Limit (per minute)
Blossom 100
Garden 200
Estate 400

The following parameters in the response header help track the rate limits.

Parameter Name Description
X-RateLimit-Total Specifies the total number of API requests allowed per minute.
X-RateLimit-Remaining Specifies the number of API requests remaining in the current rate limit window.
X-RateLimit-Used-CurrentRequest Specifies the number of API requests consumed by the current call.

Users

Users are agents of a business or organization that uses Freshcaller to handle conversations with customers.

Endpoints

GET /api/v1/users
POST /api/v1/users
GET /api/v1/users/{user_id}
PUT /api/v1/users/{user_id}
GET /api/v1/user_statuses

The user object

Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{ "id": 100328, "name": "John Doe", "email": "john.doe@abc.com", "phone": "+917777774444", "status": 0, "preference": 483697, "mobile_app_preference": 483697, "last_call_time": "2019-09-03T06:08:18.000+01:00", "last_seen_time": "2019-09-13T09:00:13.000+01:00", "confirmed": true, "language": null, "time_zone": "Casablanca", "deleted": false, "role": "Account Admin", "teams": [ { "id": 5 }, { "id": 25 } ] }
EXPAND ↓
Attributes
Attribute Name Data Type Description
id integer ID of the user object, auto-generated when a user’s information is saved. A successful create user request, returns this attribute as part of the response object. Further API requests can use the returned value to identify a user and update the user’s information.
name string Name of the user.
email string Email address of the user.
phone string Phone number of the user.
status integer Status of the user, automatically set according to the status preference selected by the user.
Possible values (enum):
0: offline
1: online
2: busy; the status value is 2, irrespective of the selected preference, when the user is on a call.
3: after call work (acw); the status value is 3, irrespective of the selected preference, when the user is involved in after call work such as documenting notes regarding the call and so on.
preference integer Identifier of the browser status selected by the user. This is a valid user_statuses.id value.
mobile_app_preference integer Identifier of the user’s status on the mobile Freshcaller app and indicates if the user is available to take calls on the mobile.
last_call_time string Time when the last call was handled, in date-time format.
last_seen_time string Time when the user was last active, in date-time format.
confirmed boolean Specifies whether the user account is activated by accessing the activation email.
Possible values: true, false
language string Preferred conversational language selected by the user when setting up the user profile.
time_zone string Time zone selected by the user when setting up the user profile.
deleted boolean Specifies whether the user’s information is deleted from the Freshcaller system.
Possible values: true, false
role string Role assigned to the user.
Possible values: Account Admin, Admin, Supervisor, Agent
teams array of ID object Team identifiers of the different teams to which the user belongs, specified as an array. Each array entry is a team.id object
Attribute of the id object:
id (string): Identifier of a team.

The create user object

Example
1
2
3
4
{ "email": "abc@example.com", "role": "Account Admin" }
EXPAND ↓
Attributes
Attribute Name Data Type Description
email Mandatory string Email address of the user.
role Mandatory string Role assigned to the user.
Valid values: Account Admin, Admin, Supervisor, Agent.

The update user object

Example
1
2
3
4
5
6
7
{ "email": "abc@example.com", "role": "Account Admin", "preference": 3, "mobile_app_preference": 1, "deleted": false }
EXPAND ↓
Attributes
Attribute Name Data Type Description
email string Email address of the user.
role string Role assigned to the user.
preference integer Identifier of the user’s browser status. Must be a valid user_statuses.id value that does not correspond to the busy or acw statuses.
mobile_app_preference integer Identifier of the user’s status on the mobile Freshcaller app and indicates if the user is available to take calls on the mobile. Must be a valid user_statuses.id value.
deleted boolean Specifies whether the user information is to be deleted from the Freshcaller system. A user can leave the organization/business, in which case the user information is deleted.
Possible values: true, false

The user status object

Example
1
2
3
4
5
6
7
8
{ "id": 170587, "name": "Meeting", "status_type": "offline", "status_sub_type": "offline", "emoji": "💻", "enabled": 1 }
EXPAND ↓
Attributes
Attribute Name Data Type Description
id integer ID of the status, auto-generated when a status is created in the Freshcaller system.
name string Descriptive identifier of the status.
status_type string Real-time user availability status.
Possible values (enum): offline, online, busy, acw
status_sub_type string Sub-type of the status. A combination of status_type and status_sub_type indicates the availability status of the user on the browser and mobile app. For example, the status_type value of online and the status_sub_type value of online_phone indicate that the user is available to take calls through the mobile.
Possible values (enum): offline, online, online_phone, busy, acw
emoji string Emoji associated with the status.
enabled integer Specifies if the status is enabled for all users (agents).
Possible values: 0, 1

List all users

Retrieves a list of users and their information from the Freshcaller system.

get
/api/v1/users
Sample request | Curl
Copied Copy
1
curl -X GET "https://<account-name>.freshcaller.com/api/v1/users?per_page=10&page=1" -H "accept: application/json" -H "X-Api-Auth: 9049c82adc39ded92615738c44380914"
EXPAND ↓
Sample response

A successful request returns 200 OK along with all the users’ information, as an array. Each array entry is a user object with the corresponding attribute values. The response data is limited by the query parameters passed in the request.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
[ { "id": 100328, "name": "John Doe", "email": "john.doe@abc.com", "phone": "+917777774444", "status": 0, "preference": 483697, "mobile_app_preference": 483697, "last_call_time": "2019-09-03T06:08:18.000+01:00", "last_seen_time": "2019-09-13T09:00:13.000+01:00", "confirmed": true, "language": null, "time_zone": "Casablanca", "deleted": false, "role": "Account Admin", "teams": [ { "id": 5 }, { "id": 25 } ] }, { "id": 102668, "name": "Jane Doe", "email": "jane.doe@abc.com", "phone": "+917773334444", "status": 0, "preference": 483697, "mobile_app_preference": 483697, "last_call_time": "2019-09-03T06:08:18.000+01:00", "last_seen_time": "2019-09-13T09:00:13.000+01:00", "confirmed": true, "language": null, "time_zone": "Casablanca", "deleted": false, "role": "Account Admin", "teams": [ { "id": 5 }, { "id": 25 } ] } ]
EXPAND ↓

Create a user

Creates a user object based on the request body parameter. The request body parameter is a create user object.

post
/api/v1/users
Sample request | Curl
Copied Copy
1
curl -X POST "https://<account-name>.freshcaller.com/api/v1/users" -H "accept: application/json" -H "X-Api-Auth: 9049c82adc39ded92615738c44380914" -H "Content-Type: application/json" -d "{ "email": "testmail@gmail.com", "role": "Admin"}"
EXPAND ↓
Sample response

A successful request returns 201 Created along with the user object.

Retrieve user information

Identifies a user by the user_id passed in the request and returns the corresponding information as a user object.

get
/api/v1/users/{user_id}
Path parameters
Parameter Name Data Type Description
user_idMandatory number The user.id value that is auto-generated when a user's details are configured in the Freshcaller system.
Sample request | Curl
Copied Copy
1
curl -X GET "https://<account-name>.freshcaller.com/api/v1/users/100328" -H "accept: application/json" -H "X-Api-Auth: 9049c82adc39ded92615738c44380914"
EXPAND ↓
Sample response

A successful request returns 200 OK along with the retrieved user object.

Update user information

Identifies a user object by the user_id passed in the request and updates the object with the information specified in the request body. The request body parameter is an update user object.

put
/api/v1/users/{user_id}
Path parameters
Parameter Name Data Type Description
user_idMandatory number The user.id value that is auto-generated when a user's details are configured in the Freshcaller system.
Sample request | Curl
Copied Copy
1
curl -X PUT "https://<account-name>.freshcaller.com/api/v1/users/104246" -H "accept: application/json" -H "X-Api-Auth: 9049c82adc39ded92615738c44380914" -H "Content-Type: application/json" -d "{ "email": "testmail2@gmail.com"}"
EXPAND ↓
Sample response

A successful request returns 200 OK along with the updated user object.

Retrieve user statuses

Retrieves a list of the default and custom user statuses configured for an organization in the Freshcaller system.

get
/api/v1/user-statuses
Sample request | Curl
Copied Copy
1
curl -X GET "https://<account-name>.freshcaller.com/api/v1/user-statuses?per_page=10&page=1" -H "accept: application/json" -H "X-Api-Auth: 9049c82adc39ded92615738c44380914"
EXPAND ↓
Sample response

A successful request returns 200 OK along with all the user status details, as an array. Each array entry is a user status object with the corresponding attributes. The response data is limited by the query parameters passed in the request.

Teams

Teams are the various groups of agents in the business. An agent can be a member of more than one team.

Endpoints

GET /api/v1/teams
POST /api/v1/teams
GET /api/v1/teams/{team_id}
PUT /api/v1/teams/{team_id}

The team object

Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{ "id": 23360, "name": "Team1", "description": "Team members", "users": [ { "id": 102668 }, { "id": 104245 }, { "id": 112938 } ], "omni_channel": false }
EXPAND ↓
Attributes
Attribute Name Data Type Description
id integer Identifier of the team object, auto-generated when a team is created in the Freshcaller system.
name string Name of the team.
description string Description of the team.
users array of id objects ID of all users who belong to the team, specified as an array.
Attribute of the id object: id (integer): Identifier of a user. This is a valid user.id value.
omni_channel boolean Specifies whether omni-channel routing is enabled for the team.
Possible values: true, false

The create team object

Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{ "name": "MS Team", "description": "MS team members", "users": [ { "id": 102668 }, { "id": 104245 }, { "id": 112938 } ] }
EXPAND ↓
Attributes
Attribute Name Data Type Description
name string Name of the team.
description string Description of the team.
users array of id object Identifiers of users assigned to the team, specified as an array.
Attribute of the id object: id (string): Identifier of a user. Must be a valid user.id value.

List all teams

Retrieves a list of all teams configured in the Freshcaller system.

get
/api/v1/teams
Sample request | Curl
Copied Copy
1
curl -X GET "https://<account-name>.freshcaller.com/api/v1/teams?per_page=10&page=1" -H "accept: application/json" -H "X-Api-Auth: 9049c82adc39ded92615738c44380914"
EXPAND ↓
Sample response

A successful request returns 200 OK along with all the teams’ information, as an array. Each array entry is a team object with the corresponding attributes. The response data is limited by the query parameters passed in the request.

Create a team

Creates a new team in Freshcaller based on the request body parameter. The request body parameter is a create team object.

post
/api/v1/teams
Sample request | Curl
Copied Copy
1
curl -X POST "https://<account-name>.freshcaller.com/api/v1/teams" -H "accept: application/json" -H "X-Api-Auth: 9049c82adc39ded92615738c44380914 " -H "Content-Type: application/json" -d "{ "name": "MS Team", "description": "MS team members", "users": [ { "id": 12321 }, { "id": 423536 }, { "id": 12313 }]}"
EXPAND ↓
Sample response

A successful request returns 201 Created along with the team object. The object contains the id attribute. In further API calls, the id that is returned can be used to update the corresponding team information or retrieve information.

Retrieve team information

Identifies a team by the team_id passed in the request and returns the corresponding information as a team object.

get
/api/v1/teams/{team_id}
Path parameters
Parameter Name Data Type Description
team_idMandatory number The team.id value that is auto-generated when a team's details are configured in the Freshcaller system.
Sample request | Curl
Copied Copy
1
curl -X GET "https://<account-name>.freshcaller.com/api/v1/teams/23265" -H "accept: application/json" -H "X-Api-Auth: 9049c82adc39ded92615738c44380914 "
EXPAND ↓
Sample response

A successful request returns 200 OK along with the retrieved team object.

Update team information

Identifies a team object by the team_id passed in the request and updates the object with the information specified in the request body. The request body parameter is a team create object.

put
/api/v1/teams/{team_id}
Path parameters
Parameter Name Data Type Description
team_idMandatory number The team.id value that is auto-generated when a team's details are configured in the Freshcaller system.
Sample request | Curl
Copied Copy
1
curl -X PUT "https://<account-name>.freshcaller.com/api/v1/teams/1" -H "accept: application/json" -H "X-Api-Auth: 9049c82adc39ded92615738c44380914 " -H "Content-Type: application/json" -d "{ "name": "CS Team", "description": "CS team members", "users": [ { "id": 12321 }, { "id": 423536 }, { "id": 12313 }]}"
EXPAND ↓
Sample response

A successful request returns 200 OK along with the updated team object.

Calls

A call is a connection between a customer’s telephone and a Freshcaller number. Agents of various teams can manage and collaborate on calls in an organized manner, understand customer business requirements, and engage as required.

Endpoints

GET /api/v1/calls
GET /api/v1/calls/{call_id}

The call object

Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
{ "id": 25847696, "direction": "incoming", "parent_call_id": null, "root_call_id": null, "phone_number_id": 43486, "phone_number": "+18582810798", "assigned_agent_id": null, "assigned_team_id": null, "assigned_call_queue_id": 78997, "assigned_ivr_id": null, "call_notes": "John needs details", "bill_duration": 26, "bill_duration_unit": "seconds", "created_time": "2019-12-18T21:36:03.000+00:00", "updated_time": "2019-12-18T21:37:03.000+00:00", "recording": { "id": 13258090, "url": "https://riyazdeenphone.freshcaller.com/api/v1/calls/25847696/recording/13258090", "duration": 7, "duration_unit": "seconds" }, "participants": [ { "id": 25847687, "call_id": 25847696, "caller_id": 8584012, "caller_number": "+12132142148", "participant_id": 25847687, "participant_type": "Customer", "connection_type": 0, "call_status": 10, "duration": 26, "duration_unit": "seconds", "cost": 0.0085, "cost_unit": "usd", "enqueued_time": null, "created_time": "2019-12-18T21:36:03.000+00:00", "updated_time": "2019-12-18T21:37:03.000+00:00" } ] }
EXPAND ↓
Attributes
Attribute Name Data Type Description
id integer Identifier of the call object, auto-generated when the object is created in the Freshcaller system, at the start of a call.
direction integer Specifies the direction of the call.
Possible values (enum): Incoming, Outgoing
parent_call_id integer For transferred calls, parent_call_id is the identifier of the parent call that is transferred to an agent or a team.
For non-transferred calls, the value is null.
root_call_id integer For child calls created because of events such as agent monitoring, root_call_id is the identifier of the source call.
For source calls, the value is null.
phone_number_id integer Identifier of the Freshcaller number from which the call is made or to which the call is received.
phone_number string Freshcaller number from which the call is made or to which the call is received.
assigned_agent_id integer Identifier of the primary agent who interacts with the customer.
assigned_team_id integer For inbound calls, assigned_team_id is the identifier of the team to which the call is assigned.
For outbound calls, the value is null.
assigned_call_queue_id integer For inbound calls, assigned_call_queue_id is the identifier of the call queue associated with the number in which the call is received. The call queue to which a call must be routed is specified when call actions are defined for a Freshcaller number.
For outbound calls, the value is null.
assigned_ivr_id integer For inbound calls, assigned_ivr_id is the identifier of the Interactive Voice Response (ivr) menu associated with the number in which the call is received . The ivr menu is associated with a number when call actions are defined for the number.
For outbound calls and for numbers that don’t have an ivr menu, the value is null.
call_notes string Notes entered by an agent during or after the call.
bill_duration integer Duration for which the cost associated with a call is calculated, specified in the unit defined by bill_duration_unit.
bill_duration_unit string Unit of time used to express bill_duration.
Possible value: seconds.
created_time string Timestamp of when a call is initiated, specified in the date-time format.
updated_time string Timestamp of when the attributes of a call are last updated, specified in the date-time format.
recording recording object Information pertaining to the recording of the call.
Attributes of the recording object:
id (integer): Identifier of the recording, auto-generated when a recording is saved in the Freshcaller system.
url (string): Hyperlink to access the recording.
duration (integer): Duration for which the call is recorded, specified in a unit defined by duration_unit.
duration_unit (string): Unit of time used to express duration. Possible value: seconds
participants array of callparticipant object Information about the agents and customer who participate in the call, specified as an array.

The call participant object

Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{ "id": 25847687, "call_id": 25847696, "caller_id": 8584012, "caller_number": "+12132142148", "participant_id": 25847687, "participant_type": "Customer", "connection_type": 0, "call_status": 10, "duration": 26, "duration_unit": "seconds", "cost": 0.0085, "cost_unit": "usd", "enqueued_time": null, "created_time": "2019-12-18T21:36:03.000+00:00", "updated_time": "2019-12-18T21:37:03.000+00:00" }
EXPAND ↓
Attributes
Attribute Name Data Type Description
id integer Identifier of the callparticipant object, auto-generated when the callparticipant object is created (when a participant joins a call) in the Freshcaller system.
call_id integer Identifier of the call object, auto-generated when a call is initiated in the Freshcaller system.
caller_id integer Identifier of the customer number.
For the agent participant_type, the value is null.
caller_number string Customer's phone number from which the call is made or received.
participant_id integer Identifier of the participant, maybe an agent or a customer.
participant_type string Type of call participant.
Possible values (enum): Agent, Customer
connection_type integer Type of call connection the participant is involved in.
Possible values:
0: Indicates that the participant is involved in the call as a customer.
1: Indicates that the participant is involved in the call as a primary agent.
2: Indicates that the participant is involved in the call as an agent monitoring the call.
3: Indicates that the participant is involved in the call as an agent who has barged into the primary agent’s call.
4: Indicates that the participant is involved in the call as an agent to whom the call was transferred (cold transfer).
5: Indicates that the participant is involved in the call as an agent to whom the call was transferred after the primary agent provided relevant information (warm transfer).
6: Indicates that the participant is involved in the call as an agent in a conference call.
7: Indicates that the participant involved in the call is an agent who received the call in a number external to Freshcaller.
call_status integer Indicator of the state of the call that the participant is involved in.
Default value: 0
Possible values:
1: Answered/Completed
2: The call connection couldn’t be established as the number was busy.
3: The call fell under the category of a missed call.
4: The call connection failed.
5: The call connection was disconnected.
6: The call was routed to a queue.
8: The call is in progress
9: The call was blocked.
10: The call was redirected to a voicemail.
11: The call originated from a restricted number.
12: The call was put on hold.
13: Establishing a call connection was in progress.
15: The call interaction was completed recently.
16: The voicemail recording was in progress.
duration integer Duration of the call, specified in a unit defined by duration_unit.
duration_unit string Unit used to express duration.
Possible value: seconds
enqueued_time string Time when the call reaches the queue, specified in date-time format.
cost integer Cost associated with the call, calculated based on bill_duration and the default pricing mechanism in Freshcaller.
cost_unit string Currency in which cost is expressed, specified as a valid three character ISO currency code.
created_time string Timestamp of when the callparticipant object is created, specified in the date-time format.
updated_time string Timestamp of when the attributes of the callparticipant object are updated, specified in the date-time format.

List all calls

Retrieves a list of calls and their information from the Freshcaller system.

get
/api/v1/calls
Sample request | Curl
Copied Copy
1
curl -X GET "https:/<account-name>.freshcaller.com/api/v1/calls?per_page=10&page=1" -H "accept: application/json" -H "X-Api-Auth: 9049c82adc39ded92615738c44380914"
EXPAND ↓
Sample response

A successful request returns 200 OK along with all calls’ information, as an array. Each array entry is a call object with the corresponding attributes. The response data is limited by the query parameters passed in the request.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
"calls": [ { "id": 25847696, "direction": "incoming", "parent_call_id": null, "root_call_id": null, "phone_number_id": 43486, "phone_number": "+18582810798", "assigned_agent_id": null, "assigned_team_id": null, "assigned_call_queue_id": 78997, "assigned_ivr_id": null, "call_notes": "John needs details", "bill_duration": 26, "bill_duration_unit": "seconds", "created_time": "2019-12-18T21:36:03.000+00:00", "updated_time": "2019-12-18T21:37:03.000+00:00", "recording": { "id": 13258090, "url": "https://riyazdeenphone.freshcaller.com/api/v1/calls/25847696/recording/13258090", "duration": 7, "duration_unit": "seconds" }, "participants": [ { "id": 25847687, "call_id": 25847696, "caller_id": 8584012, "caller_number": "+12132142148", "participant_id": 25847687, "participant_type": "Customer", "connection_type": 0, "call_status": 10, "duration": 26, "duration_unit": "seconds", "cost": 0.0085, "cost_unit": "usd", "enqueued_time": null, "created_time": "2019-12-18T21:36:03.000+00:00", "updated_time": "2019-12-18T21:37:03.000+00:00" } ] }, { "id": 25769170, "direction": "outgoing", "parent_call_id": null, "root_call_id": null, "phone_number_id": 43486, "phone_number": "+18582810778", "assigned_agent_id": 33493318, "assigned_team_id": null, "assigned_call_queue_id": null, "assigned_ivr_id": null, "call_notes": "John Doe needs details", "bill_duration": 12, "bill_duration_unit": "seconds", "created_time": "2019-12-18T06:39:32.000+00:00", "updated_time": "2019-12-18T06:40:17.000+00:00", "recording": { "id": 13216754, "url": "https://riyazdeenphone.freshcaller.com/api/v1/calls/25769170/recording/13216754", "duration": 11, "duration_unit": "seconds" }, "participants": [ { "id": 25769161, "call_id": 25769170, "caller_id": 8365505, "caller_number": "+12135142148", "participant_id": 25769161, "participant_type": "Customer", "connection_type": 0, "call_status": 1, "duration": 11, "duration_unit": "seconds", "cost": 0.013, "cost_unit": "usd", "enqueued_time": null, "created_time": "2019-12-18T06:39:32.000+00:00", "updated_time": "2019-12-18T06:40:17.000+00:00" }, { "id": 33493318, "call_id": 25769170, "caller_id": null, "caller_number": "+12132172148", "participant_id": 33493318, "participant_type": "Agent", "connection_type": 1, "call_status": 1, "duration": 13, "duration_unit": "seconds", "cost": null, "cost_unit": "usd", "enqueued_time": null, "created_time": "2019-12-18T06:39:32.000+00:00", "updated_time": "2019-12-18T06:39:45.000+00:00" } ] } ], "meta": { "total_pages": 10, "total_count": 93, "current": 1 } }
EXPAND ↓

Retrieve call information

Identifies a call by the call_id passed in the request and returns the corresponding information as a call object.

get
/api/v1/calls/{call_id}
Path parameters
Parameter Name Data Type Description
call_idMandatory number The call.id value that is auto-generated when a call's details are configured in the Freshcaller system.
Sample request | Curl
Copied Copy
1
curl -X GET "https://<account-name>.freshcaller.com/api/v1/calls/25847696" -H "accept: application/json" -H "X-Api-Auth: 9049c82adc39ded92615738c44380914"
EXPAND ↓
Sample response

A successful request returns 200 OK along with the retrieved call object.

Call Metrics

Call metrics are all call related measurements that can be tied to the performance of a business that uses Freshcaller.

Endpoints

GET /api/v1/call_metrics
GET /api/v1/calls/{call_id}/call_metrics

The call metric object

Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{ "id": 17993533, "call_id": 17993533, "ivr_time": 0, "ivr_time_unit": "seconds", "hold_duration": 0, "hold_duration_unit": "seconds", "call_work_time": 0, "call_work_time_unit": "seconds" "total_ringing_time": 0, "total_ringing_time_unit": "seconds", "talk_time": 0, "talk_time_unit": "seconds", "answering_speed": null, "answering_speed_unit": "seconds", "recording_duration": 9, "recording_duration_unit": "seconds", "bill_duration": null, "bill_duration_unit": "seconds", "cost": null, "cost_unit": "usd", "created_time": "2019-08-30T10:57:22.000+01:00", "updated_time": "2019-08-30T10:57:23.000+01:00" }
EXPAND ↓
Attributes
Attribute Name Data Type Description
id integer Identifier of the call metric object, auto-generated when a call object is created.
call_id integer Identifier of the call object, auto-generated when call-related information is stored in the Freshcaller system.
created_time string Timestamp of when the call metric object is created, specified in the date-time format. It is the time when the call object is created at the start of a call.
updated_time string Timestamp of when the call metric object is last updated, specified in the date-time format. The call metric object is auto-updated after a call ends.
ivr_time integer Total time a customer is handled through interactive voice response (ivr), during the course of a call, specified in a unit defined by ivr_time_unit.
ivr_time_unit string Unit of time used to express the ivr duration.
Possible value: seconds
hold_duration integer Total time a customer spends being on hold, in the entire call duration, specified in a unit defined by hold_duration_unit.
hold_duration_unit string Unit of time used to express the hold_duration.
Possible value: seconds
call_work_time integer Time agents spend on completely handling an interaction, specified in a unit defined by call_work_time_unit. The call_work_time value includes hold_duration and after call work duration.
call_work_time_unit string Unit of time used to express call_work_time.
Possible value: seconds
total_ringing_time integer For outbound calls, total_ringng_time is the time an agent has to wait before the call is answered, specified in a unit defined by total_ringing_time_unit.
If the call is unanswered, the value is null. For inbound calls, the value is zero.
total_ringing_time_unit string Unit of time used to express total_ringing_time.
Possible value: seconds
talk_time integer Total time agents and customers spend on talking in the entire call duration, specified in a unit defined by talk_time_unit. The talk_time value is devoid of after call work time that is spent on activities such as taking notes or hold_duration.
talk_time_unit string Unit of time used to express talk_time. Possible value: seconds
answering_speed integer For inbound calls, answering_speed is the time the customer has to wait before the call is answered, specified in the unit defined by answering_speed_unit.
If the call is unanswered and directed to a voicemail, the value is null. For outbound calls, the value is null.
answering_speed_unit string Unit of time used to express answering_speed.
Possible value: seconds
recording_duration integer Duration for which the call is recorded, specified in a unit defined by recording_duration_unit.
The recording option (Do not record calls, Record all calls, Record incoming calls, Record outgoing calls, Record manually) is configured when a number is configured for a Freshcaller account.
recording_duration_unit string Unit of time used to express recording_duration.
Possible value: seconds
bill_duration integer Duration for which the cost associated with a call is calculated, specified in the unit defined by bill_duration_unit.
Typically, the bill_duration is a sum of the hold_duration, talk_time, and total_ringing_time.
bill_duration_unit string Unit of time used to express bill_duration.
Possible value: seconds
cost integer Cost associated with the call, calculated based on bill_duration and the default pricing mechanism in Freshcaller.
cost_unit string Currency in which cost is expressed, specified as a valid three character ISO currency code.

List all call metrics

Retrieves a list of the call metrics associated with all calls whose information is stored in the Freshcaller system.

get
/api/v1/call_metrics
Query parameters

You can use a combination of the following query parameters to limit or filter the bulk response data.

Parameter Name Description Example
by_time[from]
Mandatory if the by_time[to] filter is used.
Should be a date-time value in the UTC standard.
Must be a value earlier than the by_time[to] value.
Limits the response to call metric objects whose created_time value is a time after the parameter value and before the by_time[to] value.

GET /api/v1/call_metrics?per_page=10&page=1&by_time%5Bfrom%5D=2019-08-30T12%3A24%3A02&by_time%5Bto%5D=2019-08-30T12%3A24%3A02

by_time[to]
Mandatory if the by_time[from] filter is used.
Should be a date-time value in the UTC standard.
Must be a value later than the by_time[from] value.
Limits the response to call metric objects whose created_time value is a time after the by_time[from] value before the parameter value.
Sample request | Curl
Copied Copy
1
curl -X GET "https://<account-name>.freshcaller.com/api/v1/call_metrics?per_page=100&page=1" -H "accept: application/json" -H "X-Api-Auth: 9049c82adc39ded92615738c44380914"
EXPAND ↓
Sample response

A successful request returns 200 OK along with call metrics of all calls, as an array. Each array entry is a call metric object with the corresponding attributes. The response data is limited by the query and pagination parameters passed in the request.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
{ "call_metrics": [ { "id": 17993533, "call_id": 17993533, "ivr_time": 0, "ivr_time_unit": "seconds", "hold_duration": 0, "hold_duration_unit": "seconds", "call_work_time": 0, "call_work_time_unit": "seconds", "total_ringing_time": 0, "total_ringing_time_unit": "seconds", "talk_time": 0, "talk_time_unit": "seconds", "answering_speed": null, "answering_speed_unit": "seconds", "recording_duration": 9, "recording_duration_unit": "seconds", "bill_duration": null, "bill_duration_unit": "seconds", "cost": null, "cost_unit": "usd", "created_time": "2019-08-30T10:57:22.000+01:00", "updated_time": "2019-08-30T10:57:23.000+01:00" }, { "id": 17995010, "call_id": 17995010, "ivr_time": 0, "ivr_time_unit": "seconds", "hold_duration": 0, "hold_duration_unit": "seconds", "call_work_time": 0, "call_work_time_unit": "seconds", "total_ringing_time": 1, "total_ringing_time_unit": "seconds", "talk_time": 45, "talk_time_unit": "seconds", "answering_speed": null, "answering_speed_unit": "seconds", "recording_duration": 45, "recording_duration_unit": "seconds", "bill_duration": 46, "bill_duration_unit": "seconds", "cost": 0.025, "cost_unit": "usd", "created_time": "2019-08-30T11:25:33.000+01:00", "updated_time": "2019-08-30T11:26:21.000+01:00" }, { "id": 17995187, "call_id": 17995187, "ivr_time": 0, "ivr_time_unit": "seconds", "hold_duration": 0, "hold_duration_unit": "seconds", "call_work_time": 31, "call_work_time_unit": "seconds", "total_ringing_time": 1, "total_ringing_time_unit": "seconds", "talk_time": 19, "talk_time_unit": "seconds", "answering_speed": null, "answering_speed_unit": "seconds", "recording_duration": 20, "recording_duration_unit": "seconds", "bill_duration": 20, "bill_duration_unit": "seconds", "cost": 0.025, "cost_unit": "usd", "created_time": "2019-08-30T11:29:36.000+01:00", "updated_time": "2019-08-30T11:30:29.000+01:00" } ] }
EXPAND ↓

Retrieve call metric information

Identifies a call by the call_id passed in the request and returns the corresponding call metric information as a call metric object.

get
/api/v1/calls/{call_id}/call_metrics
Path parameters
Parameter Name Data Type Description
call_idMandatory integer The call.id value that is auto-generated when call related information is stored in the freshcaller system.
Sample request | Curl
Copied Copy
1
curl -X GET "https://<account-name>.freshcaller.com/api/v1/calls/17995187/call_metrics" -H "accept: application/json" -H "X-Api-Auth: 9049c82adc39ded92615738c44380914"
EXPAND ↓
Sample response

A successful request returns 200 OK along with the retrieved call metric object.

Call Recordings

Recordings of the interactions that take place between agents and customers.

Endpoints

GET /api/v1/calls/{call_id}/recording/{recording_id}
DELETE /api/v1/calls/{call_id}/recording/{recording_id}

Download a recording

Identifies a recording by the call_id and recording_id passed in the request and directs the agent to a url from where the recording can be downloaded.

get
/api/v1/calls/{call_id}/recording/{recording_id}
Path parameters
Parameter Name Data Type Description
call_idMandatory number The call.id value that is auto-generated when a call's details are configured in the Freshcaller system.
recording_idMandatory number The recording.id value that is auto-generated when a recording's details are configured in the Freshcaller system.
Sample request | Curl
Copied Copy
1
curl -X GET "https://<account-name>.freshcaller.com/api/v1/calls/26882213/recording/13769318" -H "accept: application/json" -H "X-Api-Auth: 9049c82adc39ded92615738c44380914"
EXPAND ↓
Sample response

A successful request returns 302 Redirected. The location parameter value in the response header provides the URL from where the recording can be downloaded.

Delete a recording

Identifies a recording by the call_id and recording_id passed in the request and deletes the recording from the Freshcaller system.

delete
/api/v1/calls/{call_id}/recording/{recording_id}
Path parameters
Parameter Name Data Type Description
call_idMandatory number The call.id value that is auto-generated when a call's details are configured in the Freshcaller system.
recording_idMandatory number The recording.id value that is auto-generated when a recording's details are configured in the Freshcaller system.
Sample request | Curl
Copied Copy
1
curl -X DELETE "https://<account-name>.freshcaller.com/api/v1/calls/26882213/recording/13769318" -H "accept: application/json" -H "X-Api-Auth: 9049c82adc39ded92615738c44380914"
EXPAND ↓
Sample response

A successful request returns 200 OK along with a response object. The response object contains the status (boolean) attribute. If the recording is successfully deleted, the attribute value is true.

1
2
3
{ "status": true }
EXPAND ↓