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 ;-)
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.
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
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.
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
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.
Using API v2, you are able to get a richer response that include custom fields and tags in the response for show or list
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.
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 firstname.lastname@example.org.
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: