The Capsule API is implemented in a RESTful style using XML or JSON over HTTP. As per REST principles, four HTTP methods are used: GET, POST, PUT and DELETE.
All API requests are made via HTTPS using your own unique Capsule URL just like you would using your web browser application (e.g. https://sample.capsulecrm.com). All requests on the API are authenticated using HTTP Basic Authentication with a user's API authentication token.
An authentication token for each user is available from the users settings screen. To access users setting select My Settings from the More menu. The API will be authorised to only view, update and delete the records that can be accessed by the owner of the authentication token.
When using the authentication token you do not require any additional password. However most HTTP Basic Authentication tools and libraries require a password be supplied. Where this is the case simply provide a dummy password, such as ‘x’. Also remember to keep your authentication token secure and if you believe that your authentication token has been compromised you can generate a new token from your user settings page in Capsule.
Here’s an example using curl:
curl -u d4a581cceff06c03a47015643661ee75:x https://sample.capsulecrm.com/api/party/1
Every request to the Capsule API is assumed to be in XML format unless overridden. Here's an example using curl:
curl -u token:x https://sample.capsulecrm.com/api/party/1
JSON can also be used by setting the "Content-Type" and "Accept" headers to "application/json".
curl -u token:x -H ‘Accept: application/json’ -H ‘Content-Type: application/json’
https://sample.capsulecrm.com/api/party/1
Finally we appreciate developers providing the name of their product in the user agent header.
curl -u token:x -H ‘User-Agent: sample-application/v1.0’
https://sample.capsulecrm.com/api/party/1
If an API request fails, the error will be returned as a HTTP status code in the range 400 - 599. When a request has been successful the API will return a status of 200 or 201.
| Response | Reason |
|---|---|
| HTTP/1.1 200 OK | A successful request |
|
HTTP/1.1 201 Created
Location: https://sample.capsulecrm.com/api/opportunity/53 |
The request has created a new record in Capsule (i.e. created a new person or opportunity etc), included in the response header will be the Location where you can request the newly created record. |
| HTTP/1.1 401 Not authorized | Incorrect authentication taken details were supplied, you’ll get a 401 Not authorized response |
| HTTP/1.1 404 Not Found | You have requested a record the authenticated user does not have access to, or the record does not exist. |
| HTTP/1.1 400 Bad Request | If you PUT or POST a resource with invalid XML. |
| HTTP/1.1 500 Internal Server Error | Occurs when the supplied XML does not match the expected document type. If you get this error and your confident the request XML is in the correct format please contact .capsulecrm.com including a copy of the XML request subdomain name and the time & date the request took place. |