API Getting Started

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.

Authentication & Authorisation

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 r.equests on the API are authenticated with a user's API token using HTTP Basic Authentication. Users can find their API token by visiting My Preferences via their username menu in the Capsule navigation bar.

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

Requests

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

Responses

If a request fails, the error will be returned as a HTTP status code in the range 400 - 599. Successful requests will return a status code 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 (i.e. created a new person or opportunity etc). The Location parameter in the response header identifies the URL (and therefore ID) of the new record.
HTTP/1.1 401 Not authorized	An authentication token wasn't supplied or was incorrect, or the authenticated user didn't have the appropriate rights to perform the request.
HTTP/1.1 404 Not Found	The requested record doesn't exist, or the authenticated user doesn't have access to the record.
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 .(JavaScript must be enabled to view this email address) including a copy of the XML request subdomain name and the time & date the request took place.