Project

Important Notice

30 June 2022 - Cases have recently been renamed Projects across Capsule but the API endpoints have not been changed as it would be a breaking change for existing applications. The endpoints spell cases with a "k", this was to prevent clashes with `case` which is a reserved word in many languages.

Projects provide a handy place to store emails, notes and tasks relating to a specific event or project. For a full description of the model see the Project model definition.

List projects

The collection of Projects 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 request additional data that aren’t included in the response by default. If provided, should be a comma separated list of strings. Supported values for this endpoint are tags ( tags), fields (custom fields and fields in DataTags), party (assigned party), opportunity (the associated opportunity), and missingImportantFields (indicates if a project has any Important custom fields that are missing a value). Read more about embed.

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 Project 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": [
    {
      "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"
      },
      "stage": {
        "name": "Project Brief",
        "id": 149
      },
      "createdAt": "2015-12-07T16:54:27Z",
      "updatedAt": "2015-12-07T16:54:27Z",
      "expectedCloseOn": "2015-12-09",
      "description": "Scope and design web site shopping cart",
      "name": "Consulting",
      "closedOn": null,
      "lastContactedAt": null
    },
    {... another project object ...},
    {... another project object ...},
    {... another project object ...}
  ]
}

Headers:

Name Type Description
Link String

Links to the next and previous pages, encoded as defined in RFC 5988.

List projects by party

The collection of all projects associated with the given party.

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

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 request additional data that aren’t included in the response by default. If provided, should be a comma separated list of strings. Supported values for this endpoint are tags ( tags), fields (custom fields and fields in DataTags), party (assigned party), opportunity (the associated opportunity), and missingImportantFields (indicates if a project has any Important custom fields that are missing a value). Read more about embed.

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 Project objects. In the project 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/parties/581/kases?page=4>; rel="next" 
{
  "kases": [
    {
      "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"
      },
      "stage": {
        "name": "Project Brief",
        "id": 149
      },
      "createdAt": "2015-12-07T16:54:27Z",
      "updatedAt": "2015-12-07T16:54:27Z",
      "expectedCloseOn": "2015-12-09",
      "description": "Scope and design web site shopping cart",
      "name": "Consulting",
      "closedOn": null,
      "lastContactedAt": null
    },
    {... another project object ...},
    {... another project object ...},
    {... another project object ...}
  ]
}

Headers:

Name Type Description
Link String

Links to the next and previous pages, encoded as defined in RFC 5988.

Show project

Show a specific project.

GET
https://api.capsulecrm.com/api/v2/kases/{projectId}

Query Parameters

Name Type Description
embed Array of String

Can be used to request additional data that aren’t included in the response by default. If provided, should be a comma separated list of strings. Supported values for this endpoint are tags ( tags), fields (custom fields and fields in DataTags), party (assigned party), opportunity (the associated opportunity), and missingImportantFields (indicates if a project has any Important custom fields that are missing a value). Read more about embed.

Response

Returns HTTP status code 200. The body of the response will be a Project 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",
    "stage" : {
      "name" : "Project Brief",
      "id" : 149
    },
    "createdAt" : "2015-12-07T16:54:27Z",
    "updatedAt" : "2015-12-07T16:54:27Z",
    "expectedCloseOn" : "2015-12-09",
    "description" : "Scope and design web site shopping cart",
    "name" : "Consulting"
  }
}

Show multiple projects

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

GET
https://api.capsulecrm.com/api/v2/kases/{projectIds}

Query Parameters

Name Type Description
embed Array of String

Can be used to request additional data that aren’t included in the response by default. If provided, should be a comma separated list of strings. Supported values for this endpoint are tags ( tags), fields (custom fields and fields in DataTags), party (assigned party), opportunity (the associated opportunity), and missingImportantFields (indicates if a project has any Important custom fields that are missing a value). Read more about embed.

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 Project objects. The endpoint will return 404 NOT FOUND if any one of the provided ids does not match an existing project. 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": 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"
      },
      "stage": {
        "name": "Project Brief",
        "id": 149
      },
      "createdAt": "2015-12-07T16:54:27Z",
      "updatedAt": "2015-12-07T16:54:27Z",
      "expectedCloseOn": "2015-12-09",
      "description": "Scope and design web site shopping cart",
      "name": "Consulting",
      "closedOn": null,
      "lastContactedAt": null
    },
    {... another project object ...},
    {... another project object ...},
    {... another project object ...}
  ]
}

Create project

Creates a new project. The body must contain an object with a single property kase which must be a Project object.

  • One or more tracks can be applied to the project by including the relevant track ids in a tracks array. This is a convenient shortcut to apply tracks to new projects only, and tracks is not a field of Project objects. Tracks can be specified using a definition object or the ID shorthand, or a mixture of both, as shown below.

  • To add a custom field you'll need to specify a definition id or name and a value. Use the List Field Definitions operation to get a list of the Project fields defined on your Capsule account.

    • If you are identifying the custom field by name and the field belongs to a DataTag, you also need to specify the tag's id or name. For custom fields that don't belong to a DataTag you should explicitly state "tag": null.

POST
https://api.capsulecrm.com/api/v2/kases
          {
  "kase": {
    "party": { "id": 892 },
    "status": "OPEN",
    "description": "Scope and design web site shopping cart",
    "name": "Consulting",
    "stage": 149,
    "expectedCloseOn": "2015-12-09",
    "tracks": [ 
      { "definition": { "id": 1 } },
      { "definition": 2 } 
    ],
    "fields": [
      {
        "definition": {
          "id": 2
        },
        "value": "2015-09-02"
      },
      {
        "definition": 3,
        "value": "Yellow"
      },
      {
        "definition": {
          "name": "Size",
          "tag": null
        },
        "value": "Medium"
      },
      {
        "definition": {
          "name": "Referral",
          "tag": 15
        },
        "value": "Yes"
      }
    ]
  }
}

Query Parameters

Name Type Description
embed Array of String

Can be used to request additional data that aren’t included in the response by default. If provided, should be a comma separated list of strings. Supported values for this endpoint are tags ( tags), fields (custom fields and fields in DataTags), party (assigned party), opportunity (the associated opportunity), and missingImportantFields (indicates if a project has any Important custom fields that are missing a value). Read more about embed.

Response

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

HTTP/1.1 201
Location: https://api.capsulecrm.com/api/v2/kases/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",
    "stage" : {
      "name" : "Project Brief",
      "id" : 149
    },
    "createdAt" : "2015-12-07T16:54:27Z",
    "updatedAt" : "2015-12-07T16:54:27Z",
    "expectedCloseOn" : "2015-12-09",
    "description" : "Scope and design web site shopping cart",
    "name" : "Consulting"
  }
}

Headers:

Name Type Description
Location String

The URL that identifies the new project.

Update project

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

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

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

  • To add a new entity: create an entity without an id.
  • 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 .

PUT
https://api.capsulecrm.com/api/v2/kases/{projectId}
          {
  "kase": {
    "name": "new project name",
    "tags": [
      {
        "id": 2
      },
      {
        "id": 3,
        "_delete": true
      }
    ],
    "fields": [
      {
        "id": 1,
        "value": "follow-up"
      }
    ]
  }
}

Query Parameters

Name Type Description
embed Array of String

Can be used to request additional data that aren’t included in the response by default. If provided, should be a comma separated list of strings. Supported values for this endpoint are tags ( tags), fields (custom fields and fields in DataTags), party (assigned party), opportunity (the associated opportunity), and missingImportantFields (indicates if a project has any Important custom fields that are missing a value). Read more about embed.

Response

Returns HTTP status code 200. All good

HTTP/1.1 200 
{
  "kase": {
    "id": 10,
    "owner": {
      "id": 6,
      "username": "scottspacey",
      "name": "Scott Spacey"
    },
    "team": null,
    "party": {
      "id": 581,
      "pictureURL": "https://capsulecrm.com/theme/default/images/person_avatar_70.png",
      "type": "organisation",
      "name": "Capsule"
    },
    "status": "OPEN",
    "tags": [
      {
        "id": 2,
        "name": "Urgent",
        "dataTag": false
      }
    ],
    "opportunity": {
      "id": 1,
      "name": "new opp"
    },
    "createdAt": "2020-08-07T15:02:40Z",
    "updatedAt": "2020-12-18T12:45:32Z",
    "expectedCloseOn": "2015-12-09",
    "description": null,
    "name": "new project name",
    "closedOn": null,
    "lastContactedAt": null,
    "fields": [
      {
        "id": 1,
        "definition": {
          "id": 4,
          "name": "type"
        },
        "value": "follow-up",
        "tagId": null
      }
    ]
  }
}

Delete project

Fully delete the specific project from Capsule.

DELETE
https://api.capsulecrm.com/api/v2/kases/{projectId}

Response

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

HTTP/1.1 204

List deleted projects

A collection of projects that have been deleted from Capsule since the date specified in the since parameter. Also contains projects 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 Project objects.

The body of the response object will also contain a property restrictedKases which is an array of Restricted Project objects. This is only present if any projects 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 projects

Search for projects 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
embed Array of String

Can be used to request additional data that aren’t included in the response by default. If provided, should be a comma separated list of strings. Supported values for this endpoint are tags ( tags), fields (custom fields and fields in DataTags), party (assigned party), opportunity (the associated opportunity), and missingImportantFields (indicates if a project has any Important custom fields that are missing a value). Read more about embed.

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 Project 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/search?q=zestia&page=4>; rel="next" 
{
  "kases": [
    {
      "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"
      },
      "stage": {
        "name": "Project Brief",
        "id": 149
      },
      "createdAt": "2015-12-07T16:54:27Z",
      "updatedAt": "2015-12-07T16:54:27Z",
      "expectedCloseOn": "2015-12-09",
      "description": "Scope and design web site shopping cart",
      "name": "Consulting",
      "closedOn": null,
      "lastContactedAt": null
    },
    {... another project object ...},
    {... another project object ...},
    {... another project 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 project.

GET
https://api.capsulecrm.com/api/v2/kases/{projectId}/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 request additional data that aren’t included in the response by default. If provided, should be a comma separated list of strings. Supported values for this endpoint are tags (tags), fields (custom fields and fields in DataTags), organisation (extended organisation details for people), and missingImportantFields (indicates if a party has any Important custom fields that are missing a value). Read more about embed.

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": "Mr",
      "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": [
        {
          "id": 106,
          "type": "Home",
          "address": "https://capsulecrm.com",
          "service": "URL",
          "url": "https://capsulecrm.com"
        },
        {
          "id": 109,
          "type": "Work",
          "address": "capsulecrm",
          "service": "TWITTER",
          "url": "https://twitter.com/capsulecrm"
        }
      ],
      "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 project.

POST
https://api.capsulecrm.com/api/v2/kases/{projectId}/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 project.

DELETE
https://api.capsulecrm.com/api/v2/kases/{projectId}/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