Reading from the API

Use the GET HTTP method to retrieve details about the records on your account. For example, the API method for retrieving all the people and organisations on your Capsule account:


All endpoints on the API will return JSON, however, in the future we plan to make additional content types available on selected endpoints so it’s good practice to specify the Accept: application/json in the header of your request.

Use the following curl command to retrieve the party records listed in your Capsule account (remember to replace the bearer token):

curl -H "Authorization: Bearer {token}" -H "Accept: application/json"


In the documentation responses from the API have been pretty printed to make them easier to read. Actual responses from the API remove any unnecessary new lines and white space.

HTTP/1.1 200
  "parties": [
      "id": 11587,
      "type": "person",
      "about": null,
      "title": null,
      "firstName": "Scott",
      "lastName": "Spacey",
      "jobTitle": "Creative Director",
      "createdAt": "2015-09-15T10:43:23Z",
      "updatedAt": "2015-09-15T10:43:23Z",
      "organisation": null,
      "lastContactedAt": null,
      "addresses": [
          "id": 12135,
          "type": null,
          "city": "Chicago",
          "country": "United States",
          "street": "847 North Rush Street",
          "state": "IL",
          "zip": "65629"
      "phoneNumbers": [
          "id": 12133,
          "type": null,
          "number": "773-338-7786"
      "websites": [],
      "emailAddresses": [
          "id": 12134,
          "type": "Work",
          "address": ""
      "pictureURL": ""


Requests that return multiple items will be paginated to 50 items by default. You can specify further pages with the ?page parameter. You can also set a custom page size up to 100 with the ?perPage parameter.

curl -H "Authorization: Bearer {token}" -H "Accept: application/json"

Note that page numbering is 1-based and that omitting the ?page parameter will return the first page.

Link Header

The pagination info is included in the Link header. It is recommended to follow these Link header values instead of constructing your own URLs.

Link: <>; rel="next",
<>; rel="prev"

Linebreak is included for readability.

The possible rel values are:

  • next: The link relation for the immediate next page of results.
  • prev: The link relation for the immediate previous page of results.

Next Step: Writing to the API