The Calls API provides a simple interface to manage calls.

The API allows you to create, read and delete your calls. You can retrieve individual calls, as well as list of all calls.

JSON format

Name Type Read only Description
id number true Unique identifier of the call.
user_id number false Unique identifier of the user who performed the call.
summary string false Content of the note about this call.
recording_url string false URL pointing to call recording.
outcome_id number false Unique identifier of Call Outcome assigned to the call. See more at Call Outcomes.
duration number false Duration of the call in seconds.
phone_number number false Phone number of the person with which the call was made.
incoming boolean false Indicator of whether the call was incoming or not.
missed boolean false Indicator of whether the call was missed (not answered) by the user or not.
resource_type string false Name of the resource type the call is attached to. If provided, then resource_id also has to be provided. Possible values: lead, contact
resource_id number false Unique identifier of the resource the call is attached to. If provided, then resource_type also has to be provided.
associated_deal_ids array false An array of ids of deals associated to the call.
made_at string false Date and time of when the call was made (started) in UTC (ISO8601 format).
updated_at string true Date and time of the last update in UTC (ISO8601 format).
external_id string false Unique identifier of a call from an external system.

Retrieve All Calls

GET /v2/calls

Returns all calls available to the user, according to the parameters provided. Calls are always sorted by made_at in descending order.

Parameters

Name Type In Required Description
page number Query false Page number to start from. Page numbering starts at 1, and omitting the page parameter will return the first page. e.g. ?page=2
per_page number Query false Number of records to return per page. Default limit is 25 and the maximum number that can be returned is 100. e.g. ?per_page=20
ids number Query false Comma-separated list of call IDs to be returned in request. e.g. ?ids=1,2,3
resource_type number Query false Name of the type of resource calls are attached to. Possible valies: lead, contact. e.g. ?resource_type=lead
resource_id number Query false Unique identifier of the resource calls are attached to. e.g. ?associated_deal_id=12

Allowed for

  • Agents

Using curl

curl -v -X GET https://api.getbase.com/v2/calls \-H "Accept: application/json" \-H "Authorization: Bearer $ACCESS_TOKEN"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8Content-Language: en
{  "items": [    {      "data": {        "id": 1,        "user_id": 1,        "summary": "Schedule another call.",        "recording_url": "https://{subdomain}.zendesk.com/sales/apis/voice/api/v1/recordings/15934235/recording.mp3",        "outcome_id": 8,        "duration": 115,        "phone_number": "+44-208-1234567",        "incoming": true,        "missed": false,        "resource_type": "contact",        "resource_id": 7,        "associated_deal_ids": [          12        ],        "made_at": "2016-10-02T11:08:56Z",        "updated_at": "2016-10-03T16:32:56Z",        "external_id": "a897658e-5e44-4477-9102-d576a2601284"      },      "meta": {        "type": "call"      }    }  ],  "meta": {    "type": "collection",    "count": 1,    "links": {      "self": "http://api.getbase.com/v2/calls.json"    }  }}

Create a Call

POST /v2/calls

Creates a new call.

Parameters

Name Type Required Description
user_id number false Unique identifier of the user who performed the call.
summary string false Content of the note about this call.
recording_url string false URL pointing to call recording.
outcome_id number false Unique identifier of Call Outcome assigned to the call. See more at Call Outcomes.
duration number false Duration of the call in seconds.
phone_number number true Phone number of the person with which the call was made.
incoming boolean false Indicator of whether the call was incoming or not.
missed boolean false Indicator of whether the call was missed (not answered) by the user or not.
resource_type string false Name of the resource type the call is attached to. If provided, then resource_id also has to be provided. Possible values: lead, contact
resource_id number false Unique identifier of the resource the call is attached to. If provided, then resource_type also has to be provided.
associated_deal_ids array false An array of ids of deals associated to the call.
made_at string false Date and time of when the call was made (started) in UTC (ISO8601 format).
updated_at string false Date and time of the last update in UTC (ISO8601 format).
external_id string false Unique identifier of a call from an external system. Defaults to null

Allowed for

  • Agents

Using cURL

curl -v -X POST https://api.getbase.com/v2/calls \-H "Accept: application/json" \-H "Content-Type: application/json" \-H "Authorization: Bearer $ACCESS_TOKEN" \-d '{  "data": {    "user_id": 1,    "summary": "Schedule another call.",    "recording_url": "https://{subdomain}.zendesk.com/sales/apis/voice/api/v1/recordings/15934235/recording.mp3",    "outcome_id": 8,    "duration": 115,    "phone_number": "+44-208-1234567",    "incoming": true,    "missed": false,    "resource_type": "contact",    "resource_id": 7,    "associated_deal_ids": [      12    ],    "made_at": "2016-10-02T11:08:56Z",    "external_id": "a897658e-5e44-4477-9102-d576a2601284"  }}'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8Content-Language: en
{  "data": {    "id": 1,    "user_id": 1,    "summary": "Schedule another call.",    "recording_url": "https://{subdomain}.zendesk.com/sales/apis/voice/api/v1/recordings/15934235/recording.mp3",    "outcome_id": 8,    "duration": 115,    "phone_number": "+44-208-1234567",    "incoming": true,    "missed": false,    "resource_type": "contact",    "resource_id": 7,    "associated_deal_ids": [      12    ],    "made_at": "2016-10-02T11:08:56Z",    "updated_at": "2016-10-03T16:32:56Z",    "external_id": "a897658e-5e44-4477-9102-d576a2601284"  },  "meta": {    "type": "call"  }}

Retrieve a Single Call

GET /v2/calls/:id

Returns a single call available to the user, according to the unique call ID provided. If the specified call does not exist, this query returns an error.

Parameters

Name Type In Required Description
id number Query true Unique identifier of the call.

Allowed for

  • Agents

Using cURL

curl -v -X GET https://api.getbase.com/v2/calls/1 \-H "Accept: application/json" \-H "Authorization: Bearer $ACCESS_TOKEN"

Example Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8Content-Language: en
{  "data": {    "id": 1,    "user_id": 1,    "summary": "Schedule another call.",    "recording_url": "https://{subdomain}.zendesk.com/sales/apis/voice/api/v1/recordings/15934235/recording.mp3",    "outcome_id": 8,    "duration": 115,    "phone_number": "+44-208-1234567",    "incoming": true,    "missed": false,    "resource_type": "contact",    "resource_id": 7,    "associated_deal_ids": [      12    ],    "made_at": "2016-10-02T11:08:56Z",    "updated_at": "2016-10-03T16:32:56Z",    "external_id": "a897658e-5e44-4477-9102-d576a2601284"  },  "meta": {    "type": "call"  }}

Update a Call

PUT /v2/calls/:id

Updates an existing call. For calls created using Sell Voice, you can only update the following properties:

  • summary
  • outcome_id
  • duration
  • phone_number
  • incoming
  • missed
  • made_at
  • external_id

Parameters

Name Type Mandatory Description
resource_type string false Name of the resource type attached to the call. If provided, resource_id is required. Possible values are "lead" and "contact"
resource_id number false Unique identifier of the resource attached to the call. If provided, resource_type is required
recording_url string false URL for the call recording
summary string false Notes associated with the call
outcome_id number false Unique identifier for the call's outcome. See Call Outcomes
duration number false Duration of the call in seconds
phone_number number false Phone number for the call
incoming boolean false Indicates whether the call was incoming or not
missed boolean false Indicates whether the call was answered by the contact or lead
made_at string false Timestamp when the call started
external_id string false Unique identifier of the call in an external system

Allowed for

  • Agents

Using curl

curl -v -X PUT https://api.getbase.com/v2/calls/1 \-H Accept: application/json \-H Content-Type: application/json \-H Authorization: Bearer $ACCESS_TOKEN \-d '{  "data": {    "resource_type": "contact",    "resource_id": 12345,    "summary": "Schedule another call.",    "outcome_id": 8,    "duration": 115,    "phone_number": "+44-208-1234567",    "incoming": true,    "missed": false,    "made_at": "2016-10-02T11:08:56Z",    "external_id": "a897658e-5e44-4477-9102-d576a2601284"  }}'

Example Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8Content-Language: en
{  "data": {    "id": 1,    "user_id": 1,    "summary": "Schedule another call.",    "recording_url": "https://{subdomain}.zendesk.com/sales/apis/voice/api/v1/recordings/15934235/recording.mp3",    "outcome_id": 8,    "duration": 115,    "phone_number": "+44-208-1234567",    "incoming": true,    "missed": false,    "resource_type": "contact",    "resource_id": 12345,    "associated_deal_ids": [      12    ],    "made_at": "2016-10-02T11:08:56Z",    "updated_at": "2016-10-03T16:32:56Z"  },  "meta": {    "type": "call"  }}

Delete a Call

DELETE /v2/calls/:id

Delete an existing call. If the specified call does not exist, this query returns an error. This operation cannot be undone.

Parameters

Name Type In Required Description
id number Query true Unique identifier of the call.

Allowed for

  • Agents

Using curl

curl -v -X DELETE https://api.getbase.com/v2/calls/1 \-H "Authorization: Bearer $ACCESS_TOKEN"

Example Response

HTTP/1.1 204 No Content

Retrieve a Call Recording

GET /v2/calls/:id/recording.mp3

Returns a call recording based on the call id.

Parameters

Name Type In Required Description
id number Query true Unique identifier of the call

Allowed for

  • Agents

Using curl

curl -v -X GET https://api.getbase.com/v2/calls/140173744/recording.mp3 \-H "Authorization: Bearer ACCESS_TOKEN" \-o "myrecording.mp3"

Example Response

HTTP/2 200content-type: audio/mpeg