Migrating from API v1

We've made significant improvements to API v2 that provide a simpler and intuitive experience for developers. In creating API v2 we've followed a similar RESTful conventions to API v1 and tried to make the migration process as easy as possible.

To help you migrate your existing API v1 application to API v2 here is a high-level overview of the changes we have made. If you have any question, you can contact us using our support email.

Please note that API v1 will be switched off on January 31, 2018. If you are a developer of an existing integration, please consider your migration plan as soon as you can rather than leaving it to the last minute ;-)

JSON only

API v1 supported both XML and JSON. In API v2 we’ve dropped support for XML in favour of first class JSON support. Things have moved on since we launched API v1 and JSON has established itself as the preferred payload for RESTful APIs. The majority of development environments enable JSON natively or via a library making it relatively straight forward to utilise JSON.

Now that we're supporting JSON only, we’ve simplified the structure by removing the redundant wrapping of elements that was required to support XML in API v1. List endpoints and elements that only return a single result no longer get unwrapped into an object — they are now returned as arrays.

Dedicated api.capsulecrm.com domain for API requests

In API v1 it was necessary to make API requests on the address of the customer’s account (e.g. https://exampleco.capsulecrm.com). In API v2 all requests use the api.capsulecrm.com domain to simplify integration. As a result you no longer need to store the customer’s subdomain for making API requests.

Additionally the use of the dedicated api.capsulecrm.com domain for API requests ensures that integrations running in the browser (such as browser extensions) avoid conflict with a user's existing session making it easier to build browser extensions.

If you need to know the subdomain of a Capsule account (for example to build URL links from your application to Capsule) this can retrieved using the /api/v2/site endpoint.

OAuth 2 for an easier on boarding flow

One of the key improvements in API v2 is the introduction of oAuth 2. Users no longer need to copy and paste their API key into your integration. Instead users now approve your application with a single click in a simple and secure way using standards defined by oAuth 2.

But we understand that setting up the OAuth 2 dance in your code can take a little time to build. To make it easier to get started we also support "private" API bearer tokens so you can get something working on your own account quickly or for projects that you don't intend to share.

Read more about Authentication and OAuth 2.

To help you handle the upgrade to oAuth 2:

  • You can exchange your existing user level API keys for oAuth 2 tokens so there is no need to ask users to re-authenticate your integration.
  • oAuth 2 support has been enabled on API v1 endpoints. This gives you a few more options for how you phase your migration. For example, you could convert your integration and customers to oAuth 2 and then later (but before API v1 is discontinued) migrate your code to use the new API v2 endpoints.

Endpoint changes

Beside obviously adding v2 to the path, we changed all endpoints to consistently use the plural version of the entity. For example, the parties endpoint is now /api/v2/parties instead of /api/party

Objects are returned when you POST

POST requests that create or update an entity now return the fully populated entity in the body of the response. This avoids the need to make an additional request to get the resulting object. If you're creating a new entity (i.e. a HTTP 201 response) we continue to include the Location header in the response.

See our writing to the API guide for more detail.

Get nested tags and custom fields in responses

Using API v2, you are able to get a richer response that include custom fields and tags in the response for show or list parties/opportunities/kases operations by including the ?embed=tags,fields query parameter in the request URL.

So for example, if you're getting a list of parties you no longer need to make a separate API call for each party to fetch its tags. If you have 10 parties and you want to include their tags you'll only need to make one API request instead of the previous 11.

You can also include tags and custom fields when we creating or updating your parties, cases or opportunities.


The list endpoints now apply pagination by default. Most endpoints return 50 records at a time. See our Reading from the API article for details.

Searching and Filtering

We've made big changes to improve options for searching and filtering parties, cases and opportunities on the API. We already have API endpoint for performing searches that work just like the search box that appears in Capsule.

If you're looking to filter by other attributes (such as Tag) we don't currently have these endpoints documented but they are on the way — if you would like early access please contact us at support@capsulecrm.com.

Object format changes

API v2 changed the name and format of some of the objects returned by the API. You can check the models definitions for each object to see the new formats. For example, to be consistent:

  • The name of fields that contain a date with time ends with at
  • The name of fields that contain a date without time ends with on