Case

Cases provide a handy place to store emails, notes and tasks relating a specific event or project. For a full description of the model see the Case model definition. The endpoints spell cases with a "k", this is to prevent clashes with case which is a reserved word in many languages.

List cases

The collection of Cases on the Capsule account.

GET

https://api.capsulecrm.com/api/v2/kases

Query Parameters

Name	Type	Description
since	Date	If set then includes only entities that have been changed after this date. Must in be ISO8601 format.
page	Integer	The page of results to return. Default: `1`
perPage	Integer	The number of entities to return per page. Value must be between `1` and `100`. Default: `50`
embed	Array of String	Can be used to specify extra entities to fully include in the result. If provided, should be a comma separated list of strings. Accepted values are `tags`, `fields`, `party` and `opportunity`.

Response

Returns HTTP status code 200. The body of the response will contain an object with a single property kases which is an array of Case objects. In the case of an invalid request, an error message will be returned, as described in the errors section.

HTTP/1.1 200
          
Link: <https://api.capsulecrm.com/api/v2/kases?page=4>; rel="next"

{
  "kases": [
    {
      "kase": {
        "id": 12,
        "party": {
          "id": 892,
          "type": "organisation",
          "name": "Zestia",
          "pictureURL": "https://capsulecrm.com/theme/default/images/org_avatar_70.png"
        },
        "owner": {
          "id": 61,
          "username": "ted",
          "name": "Ted Danson"
        },
        "status": "OPEN",
        "opportunity": {
          "id": 83948362,
          "name": "Scope and design web site shopping cart"
        },
        "createdAt": "2015-12-07T16:54:27Z",
        "updatedAt": "2015-12-07T16:54:27Z",
        "description": "Scope and design web site shopping cart",
        "name": "Consulting",
        "closedOn": null,
        "lastContactedAt": null
      }
    },
    {... another kase object ...},
    {... another kase object ...},
    {... another kase object ...}
  ]
}

Headers:

Name	Type	Description
Link	String	Links to the next and previous pages, encoded as defined in RFC 5988.

Show case

Show a specified case.

GET

https://api.capsulecrm.com/api/v2/kases/{caseId}

Query Parameters

Name	Type	Description
embed	Array of String	Can be used to specify extra entities to fully include in the result. If provided, should be a comma separated list of strings. Accepted values are `tags`, `fields`, `party` and `opportunity`.

Response

Returns HTTP status code 200. The body of the response will be a Case object.

HTTP/1.1 200

{
  "kase" : {
    "id" : 12,
    "party" : {
      "id" : 892,
      "type" : "organisation",
      "name" : "Zestia",
      "pictureURL" : "https://capsulecrm.com/theme/default/images/org_avatar_70.png"
    },
    "owner" : {
      "id" : 61,
      "username" : "ted",
      "name" : "Ted Danson"
    },
    "status" : "OPEN",
    "createdAt" : "2015-12-07T16:54:27Z",
    "updatedAt" : "2015-12-07T16:54:27Z",
    "description" : "Scope and design web site shopping cart",
    "name" : "Consulting"
  }
}

Show multiple cases

Allows to load a list of cases by providing their unique ids. caseIds must be a comma separated list of integers and can contain at most 10 values.

GET

https://api.capsulecrm.com/api/v2/kases/{caseIds}

Query Parameters

Name	Type	Description
embed	Array of String	Can be used to specify extra entities to fully include in the result. If provided, should be a comma separated list of strings. Accepted values are `tags`, `fields`, `party` and `opportunity`.

Response

Returns HTTP status code 200. The body of the response will contain an object with a single property kases which is an array of Case objects. The endpoint will return 404 NOT FOUND if any one of the provided ids does not match and existing case. In the case of an invalid request, an error message will be returned, as described in the errors section.

HTTP/1.1 200

{
  "kases": [
    {
      "kase": {
        "id": 12,
        "party": {
          "id": 892,
          "type": "organisation",
          "name": "Zestia",
          "pictureURL": "https://capsulecrm.com/theme/default/images/org_avatar_70.png"
        },
        "owner": {
          "id": 61,
          "username": "ted",
          "name": "Ted Danson"
        },
        "status": "OPEN",
        "opportunity": {
          "id": 83948362,
          "name": "Scope and design web site shopping cart"
        },
        "createdAt": "2015-12-07T16:54:27Z",
        "updatedAt": "2015-12-07T16:54:27Z",
        "description": "Scope and design web site shopping cart",
        "name": "Consulting",
        "closedOn": null,
        "lastContactedAt": null
      }
    },
    {... another kase object ...},
    {... another kase object ...},
    {... another kase object ...}
  ]
}

Create case

Creates a new case. The body must contain an object with a single property kase which must be a Case object. Note that one or more tracks can be applied to the case by including the relevant track ids in a tracks array. This is a convenient shortcut to apply tracks to new cases only, and tracks is not a field of Case objects. Tracks can be specified using a definition object or the ID shorthand, or a mixture of both, as shown below.

POST

https://api.capsulecrm.com/api/v2/kases

          {
  "kase" : {
    "party" : {
      "id" : 892
    },
    "status" : "OPEN",
    "description" : "Scope and design web site shopping cart",
    "name" : "Consulting",
    "tracks" : [ {
      "definition" : {
        "id" : 1
      }
    }, {
      "definition" : 2
    } ]
  }
}

Query Parameters

Name	Type	Description
embed	Array of String	Can be used to specify extra entities to fully include in the result. If provided, should be a comma separated list of strings. Accepted values are `tags`, `fields`, `party` and `opportunity`.

Response

Returns HTTP status code 201. The body of the response will contain the case as it was stored in Capsule.

HTTP/1.1 201
          
Location: https://api.capsulecrm.com/api/v2/kase/12

{
  "kase" : {
    "id" : 12,
    "party" : {
      "id" : 892,
      "type" : "organisation",
      "name" : "Zestia",
      "pictureURL" : "https://capsulecrm.com/theme/default/images/org_avatar_70.png"
    },
    "owner" : {
      "id" : 61,
      "username" : "ted",
      "name" : "Ted Danson"
    },
    "status" : "OPEN",
    "createdAt" : "2015-12-07T16:54:27Z",
    "updatedAt" : "2015-12-07T16:54:27Z",
    "description" : "Scope and design web site shopping cart",
    "name" : "Consulting"
  }
}

Headers:

Name	Type	Description
Location	String	The URL that identifies the new case

Update case

Updates an existing case. The body must contain an object with a single property kase which must be an Case object. Fields that are not included in the request will remain unchanged.

An owner and/or team are required on a case.

To apply changes to entities in the tags or fields collections you can do the following:

To update an existing entity: include the id and any attributes that are being updated.
To delete an existing entity: include the id and the following JSON attribute "_delete": true .
To add a new entity: create entity without an id.

PUT

https://api.capsulecrm.com/api/v2/kases/{caseId}

Query Parameters

Name	Type	Description
embed	Array of String	Can be used to specify extra entities to fully include in the result. If provided, should be a comma separated list of strings. Accepted values are `tags`, `fields`, `party` and `opportunity`.

Response

Returns HTTP status code 200. All good

HTTP/1.1 200

{
  "kase" : {
    "id" : 12,
    "party" : {
      "id" : 892,
      "type" : "organisation",
      "name" : "Zestia",
      "pictureURL" : "https://capsulecrm.com/theme/default/images/org_avatar_70.png"
    },
    "owner" : {
      "id" : 61,
      "username" : "ted",
      "name" : "Ted Danson"
    },
    "status" : "OPEN",
    "createdAt" : "2015-12-07T16:54:27Z",
    "updatedAt" : "2015-12-07T16:54:27Z",
    "description" : "Scope and design web site shopping cart",
    "name" : "Consulting"
  }
}

Delete case

Fully delete the specific case from Capsule.

DELETE

https://api.capsulecrm.com/api/v2/kases/{caseId}

Response

Returns HTTP status code 204. Returns status code 204 with an empty body if the case was successfully deleted

HTTP/1.1 204

List deleted cases

A collection of cases that have been deleted from Capsule since the date specified in the since parameter. Also contains cases that have been made restricted for the user calling the API endpoint.

GET

https://api.capsulecrm.com/api/v2/kases/deleted

Query Parameters

Name	Type	Description
since	Date	If set then includes only entities that have been changed after this date. Must in be ISO8601 format.

Response

Returns HTTP status code 200. The body of the response will contain an object with a property kases which is an array of Deleted Case objects.

The body of the response object will also contain a property restrictedKases which is an array of Restricted Case objects. This is only present if any cases were made restricted.

In the case of an invalid request, an error message will be returned, as described in the errors section.

HTTP/1.1 200

{
  "kases" : [ {
    "id" : 11,
    "deletedAt" : "2015-12-04T11:51:32Z"
  } ],
  "restrictedKases" : [ {
    "id" : 2,
    "name" : "Private",
    "isRestricted" : true
  } ]
}

Search cases

Search for cases on the Capsule account. This will return the same results as the global search inside Capsule.

If you're looking for a more structured search endpoint you can use Filters to search by a specific field or tag.

GET

https://api.capsulecrm.com/api/v2/kases/search

Query Parameters

Name	Type	Description
q	String	The value to search for e.g. a name, a postcode or a phone number.
page	Integer	The page of results to return. Default: `1`
perPage	Integer	The number of entities to return per page. Value must be between `1` and `100`. Default: `50`

Response

HTTP/1.1 200
          
Link: <https://api.capsulecrm.com/api/v2/kases/search?q=zestia&page=4>; rel="next"

{
  "kases": [
    {
      "kase": {
        "id": 12,
        "party": {
          "id": 892,
          "type": "organisation",
          "name": "Zestia",
          "pictureURL": "https://capsulecrm.com/theme/default/images/org_avatar_70.png"
        },
        "owner": {
          "id": 61,
          "username": "ted",
          "name": "Ted Danson"
        },
        "status": "OPEN",
        "opportunity": {
          "id": 83948362,
          "name": "Scope and design web site shopping cart"
        },
        "createdAt": "2015-12-07T16:54:27Z",
        "updatedAt": "2015-12-07T16:54:27Z",
        "description": "Scope and design web site shopping cart",
        "name": "Consulting",
        "closedOn": null,
        "lastContactedAt": null
      }
    },
    {... another kase object ...},
    {... another kase object ...},
    {... another kase object ...}
  ]
}

Headers:

Name	Type	Description
Link	String	Links to the next and previous pages, encoded as defined in RFC 5988.

List additional parties

The collection of additional parties related to this case.

GET

https://api.capsulecrm.com/api/v2/kases/{caseId}/parties

Query Parameters

Name	Type	Description
page	Integer	The page of results to return. Default: `1`
perPage	Integer	The number of entities to return per page. Value must be between `1` and `100`. Default: `50`
embed	Array of String	Can be used to specify extra entities to fully include in the result. If provided, should be a comma separated list of strings. Accepted values are `tags`, `fields` and `organisation`.

Response

Returns HTTP status code 200. The body of the response will contain an object with a single property parties which is an array of Party objects.

HTTP/1.1 200
          
Link: <https://api.capsulecrm.com/api/v2/kases/1/parties?page=4>; rel="next"

{
  "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,
      "owner": null,
      "team": 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"
    }
  ]
}

Headers:

Name	Type	Description
Link	String	Links to the next and previous pages, encoded as defined in RFC 5988.

Add additional party

Add a person or organisation as an additional contact to the case.

POST

https://api.capsulecrm.com/api/v2/kases/{caseId}/parties/{partyId}

Response

Returns HTTP status code 204. Returns status code 204 with an empty body if the related contact was successfully added.

HTTP/1.1 204

Remove additional party

Remove a specific person or organisation as an additional contact of the case.

DELETE

https://api.capsulecrm.com/api/v2/kases/{caseId}/parties/{partyId}

Response

Returns HTTP status code 204. Returns status code 204 with an empty body if the related contact was successfully deleted.

HTTP/1.1 204