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:

GET
https://api.capsulecrm.com/api/v2/parties

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" https://api.capsulecrm.com/api/v2/parties

Response

Throughout this 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": "scott@homestyleshop.co"
        }
      ],
      "pictureURL": "https://capsulecrm.com/theme/default/images/person_avatar_70.png"
    }
  ]
}

Pagination

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" https://api.capsulecrm.com/api/v2/parties?page=2&perPage=100

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: <https://api.capsulecrm.com/api/v2/parties?page=3&perPage=100>; rel="next",
<https://api.capsulecrm.com/api/v2/parties?page=1&perPage=100>; 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.

Embedding data in responses

Many of our endpoints provide only some of the data by default. This reduces overhead and improves response readability. However, sometimes you might be interested in including additional information in the response. This can be achieved by using the embed query parameter.

Endpoints that support the embed parameter include the show party endpoint, list projects endpoint and create opportunity endpoint, as well as many more. These endpoints list embed in their Query Parameters section, and specify the fields that can be embedded for each endpoint.

For example, in order to obtain the tags and fields on parties in your Capsule account, you can make the following request to the list parties endpoint:

GET
https://api.capsulecrm.com/api/v2/parties?embed=tags,fields

The response will look as follows:

HTTP/1.1 200 
{
  "party": {
    "id": 9,
    "team": null,
    "type": "person",
    "tags": [
      {
        "id": 18,
        "name": "premium client",
        "dataTag": false
      }
    ],
    "about": null,
    "firstName": "Scott",
    "lastName": "Spacey",
    "jobTitle": "Creative Director",
    "createdAt": "2019-10-21T11:37:55Z",
    "updatedAt": "2020-10-08T09:32:25Z",
    "organisation": null,
    "lastContactedAt": null,
    "title": "Sir",
    "fields": [
      {
        "id": 21,
        "definition": {
          "id": 9,
          "name": "favorite color"
        },
        "value": "purple",
        "tagId": null
      }
    ],
    "phoneNumbers": [],
    "addresses": [],
    "websites": []
  }
}

Next Step: Writing to the API