Status and error messages

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

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

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

Attributes

Date and time literals

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

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.

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

Pagination

List APIs, such as APIs to retrieve all users, return bulk data. The meta object in the response specifies information on the bulk data returned.

Response parameters

Request parameters

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

Account

Organizations that use Freshworks’ products have accounts configured within the Freshworks ecosystem. Account information identifies an account and contains miscellaneous configuration details pertaining to the account.

You can use the Export data API to export (as JSON or CSV reports) all calls, call recordings, users, and agent teams related information stored in the Freshcaller system.

Endpoints

POST /account/export

Export data

Account admins and users with admin permissions can export calls, call metrics, users, and teams related data that exist in their account. The data can be exported as JSON or CSV reports.
The export data API creates a job for exporting the data asynchronously. You can use the Retrieve job status API to retrieve the status of the job and the report.

1
curl -X POST "https://<account-name>.freshcaller.com/api/v1/account/export" -H "Content-Type: application/json" -H "X-Api-Auth: bdda5exxxx" -H "accept: application/json" -d '{ "date_range": {"start_date": "2020-04-21T13:03:00Z", "end_date": "2021-04-21T13:03:00Z" }, "resources": [{"name": "calls", "include": [ "participants","recording","life_cycle","recording_to_redact","integrated_resources"]}], "output_format": "json", "delivery_type": "email"}'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "date_range": {
    "start_date": "2020-04-21T13:03:00Z",
    "end_date": "2021-04-21T13:03:00Z"
  },
  "resources": [
    {
      "name": "calls",
      "include": [
        "participants",
        "recording",
        "life_cycle", 
        "recording_to_redact", 
        "integrated_resources"
      ]
    }
  ],
  "output_format": "json",
  "delivery_type": "email"
}

Attributes

Attributes of the resources object

Sample response

A successful request returns 202 Accepted along with the following response object.

1
2
3
4
5
{
    "id": 14078,
    "status": "started",
    "message": "Export job created. Please check the status of the job at /api/v1/jobs/14078"
  }

Attributes

Retrieve a job

Identifies a job by the job_id passed in the request and returns the corresponding information as a job object.

Endpoint: GET /jobs/{job_id}

Path parameters

1
curl -X GET "https://<account-name>.freshcaller.com/api/v1/jobs/14078" -H "Content-Type: application/json" -H "accept: application/json" -H "X-Api-Auth: 9049c82adc39ded92615738c4xxxxxx"

Sample response

A successful request returns 200 OK along with the following response object.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "bulk_job": {
    "id": 14078,
    "created_time": "2023-03-20T08:20:44.022-04:00",
    "updated_time": "2023-03-20T08:21:02.461-04:00",
    "status": "completed",
    "links": [
        {
            "href": "/api/v1/jobs/14078",
            "method": "GET",
            "rel": "status"
        }
      ],
    "job_data": {
        "path": "https://freshcaller-us-exports.s3.amazonaws.com/production/29845/export/14078.zip?jVGXFdNrOytNybHYB8HSZTZLu%2FfLQOIv7u&X-Amz-SignedHeaders=host&X-Amz-Signature=de72cb4bcd530e8b85c48"
    }
  }
}

Attributes

• Calls report: Details of the outbound and inbound calls associated with the account. For information about the call report parameters, see the call object.
• Call metrics report: Details of the call metrics associated with the account. For information about the call metrics report parameters, see the call metrics object.
• Users report: Details of the users associated with the account. For information about the user report parameters, see the user object.
• Teams report: Details of the teams associated with the account. For information about the team report parameters, see the team object.

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

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
    }
  ]
}

Attributes

The create user object

1
2
3
4
{
  "email": "abc@example.com",
  "role": "Account Admin"
  }

Attributes

The update user object

1
2
3
4
5
6
7
{
  "email": "abc@example.com",
  "role":  "Account Admin",
  "preference": 3,
  "mobile_app_preference": 1,
  "deleted": false
  }

Attributes

The user status object

1
2
3
4
5
6
7
8
{
  "id": 170587,
  "name": "Meeting",
  "status_type": "offline",
  "status_sub_type": "offline",
  "emoji": "💻",
  "enabled": 1
  }

Attributes

List all users

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

1
curl -X GET "https://<account-name>.freshcaller.com/api/v1/users?per_page=1000&page=1" -H "accept: application/json" -H "X-Api-Auth: 9049c82adc39ded92615738c44380914"

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.

Create a user

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

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"}"

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.

Path parameters

1
curl -X GET "https://<account-name>.freshcaller.com/api/v1/users/100328" -H "accept: application/json" -H "X-Api-Auth: 9049c82adc39ded92615738c44380914"

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.

Path parameters

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"}"

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.

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"

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

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
}

Attributes

The create team object

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
    }
  ]
}

Attributes

List all teams

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

1
curl -X GET "https://<account-name>.freshcaller.com/api/v1/teams?per_page=1000&page=1" -H "accept: application/json" -H "X-Api-Auth: 9049c82adc39ded92615738c44380914"

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.

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 }]}"

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.

Path parameters

1
curl -X GET "https://<account-name>.freshcaller.com/api/v1/teams/23265" -H "accept: application/json" -H "X-Api-Auth: 9049c82adc39ded92615738c44380914 "

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 create team object.

Path parameters

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 }]}"

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

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
{
	"id": 25847696,
	"direction": "incoming",
	"parent_call_id": null,
	"root_call_id": null,
	"phone_number_id": 43486,
	"phone_number": "+18582810798",
	"assigned_agent_id": null,
	"assigned_agent_name": "Andrew Parker",
	"assigned_team_id": 18525,
	"assigned_team_name": "Travel and Booking",
	"assigned_call_queue_id": 78997,
	"assigned_call_queue_name": "travel_queue_agents",
	"assigned_ivr_id": null,
	"assigned_ivr_name": 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",
		"transcription_url": null,
		"duration": 7,
		"duration_unit": "seconds"
	},
	"recording_to_redact": null,
	"integrated_resources": [],
	"participants": [
		{
			"id": 25847687,
			"call_id": 25847696,
			"caller_id": 8584012,
			"caller_number": "+12132142148",
			"caller_name": "vodafone",
			"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": 243207781,
			"created_time": "2019-12-18T21:38:03.000+00:00",
			"updated_time": "2019-12-18T21:39:03.000+00:00",
			"call_id": 195313556,
			"caller_id": null,
			"caller_number": null,
			"caller_name": null,
			"participant_id": 67030,
				"participant_type": "Agent",
				"connection_type": 1,
				"call_status": 1,
				"duration": 83,
				"duration_unit": "seconds",
				"cost": 0.01,
				"cost_unit": "usd",
				"enqueued_time": null
		}		
	],
	"parallel_call_groups": []
}

Attributes

The call participant object

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "id": 25847687,
  "call_id": 25847696,
  "caller_id": 8584012,
  "caller_number": "+12132142148",
  "caller_name": "vodafone",
  "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"
}

Attributes

List all calls

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

1
curl -X GET "https://<account-name>.freshcaller.com/api/v1/calls?per_page=1000&page=1" -H "accept: application/json" -H "X-Api-Auth: 9049c82adc39ded92615738c44380914"

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.

Retrieve call information

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

Path parameters

1
curl -X GET "https://<account-name>.freshcaller.com/api/v1/calls/25847696" -H "accept: application/json" -H "X-Api-Auth: 9049c82adc39ded92615738c44380914"

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

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
{
	"id": 17993533,
	"created_time": "2019-08-30T10:57:22.000+01:00",
	"updated_time": "2019-08-30T10:57:23.000+01:00",
	"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",
	"csat": {
		"transfer_made": false,
		"outcome": null,
		"time": 0,
		"time_unit": "seconds"
	},
	"tags": [],
	"life_cycle": [
		{
			"type": "call_queue_started",
			"queue_id": 47971,
			"time_stamp": "2019-02-17T21:47:53.105Z"
		},
		{
			"type": "voicemail_initiated",
			"time_stamp": "2019-02-17T21:48:03.428Z"
		},
		{
			"type": "hangup",
			"time_stamp": "2019-02-17T21:48:34.095Z"
		}
	]
}

Attributes

The call metric life cycle object

1
2
3
4
5
{
	"type": "call_queue_started",
	"queue_id": 47975,
	"time_stamp": "2019-02-20T12:47:56.361Z"
}

Attributes

List all call metrics

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

Query parameters

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

1
curl -X GET "https://<account-name>.freshcaller.com/api/v1/call_metrics?per_page=1000&page=1&include=life_cycle"" -H "accept: application/json" -H "X-Api-Auth: 9049c82adc39ded92615738c44380914"

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.

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.

Path parameters

1
curl -X GET "https://<account-name>.freshcaller.com/api/v1/calls/17995187/call_metrics" -H "accept: application/json" -H "X-Api-Auth: 9049c82adc39ded92615738c44380914"

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.

Path parameters

1
curl -X GET "https://<account-name>.freshcaller.com/api/v1/calls/26882213/recording/13769318" -H "accept: application/json" -H "X-Api-Auth: 9049c82adc39ded92615738c44380914"

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.

Path parameters

1
curl -X DELETE "https://<account-name>.freshcaller.com/api/v1/calls/26882213/recording/13769318" -H "accept: application/json" -H "X-Api-Auth: 9049c82adc39ded92615738c44380914"

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.