Calls

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-8
Content-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": "[phone]",
        "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": "[phone]",
    "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-8
Content-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": "[phone]",
    "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-8
Content-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": "[phone]",
    "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": "[phone]",
    "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-8
Content-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": "[phone]",
    "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 200
content-type: audio/mpeg