Tag

Tags are keywords that can be used to categorize parties, projects or opportunities. For a full description of the model see the Tag definition model description.

To add or remove tags from parties, opportunities or projects use the update party, update opportunity or update project endpoints instead.

List tag definitions

The collection of all of the tags on this Capsule account. The entity parameter inside the URL must be parties, opportunities or kases and defines which tags to return.

GET
https://api.capsulecrm.com/api/v2/{entity}/tags

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

Response

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

HTTP/1.1 200
Link: <https://api.capsulecrm.com/api/v2/parties/tags?page=2>; rel="next" 
{
  "tags" : [ {
    "id" : 1840253,
    "name" : "Nice Guy",
    "dataTag" : false
  }, {
    "id" : 1199,
    "name" : "Customer",
    "description" : "Contacts that have an active subscription",
    "dataTag" : true
  } ]
}

Headers:

Name Type Description
Link String

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

Show tag definition

Show a specific tag.

GET
https://api.capsulecrm.com/api/v2/{entity}/tags/{tagId}

Response

Returns HTTP status code 200. The body of the response will contain an object with a single property tag which is a Tag Definition object.

HTTP/1.1 200 
{
  "tag" : {
    "id" : 1840253,
    "name" : "Nice Guy",
    "dataTag" : false
  }
}

Create tag definition

Defines a new party, opportunity or project tag. The type of this tag is defined by the entity parameter inside the URL which must be parties, opportunities or kases.

The body must contain an object with a single property tag which must be a Tag Definition object. To create a new data tag set the dataTag field to true and then separately use the add field definition endpoint to add custom fields.

POST
https://api.capsulecrm.com/api/v2/{entity}/tags
          {
  "tag" : {
    "name" : "Nice Guy",
    "dataTag" : false
  }
}

Response

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

HTTP/1.1 201
Location: https://api.capsulecrm.com/api/v2/parties/tags/1840253 
{
  "tag" : {
    "id" : 1840253,
    "name" : "Nice Guy",
    "dataTag" : false
  }
}

Headers:

Name Type Description
Location String

The URL that identifies the new tag.

Update tag definition

Update the details of a party, opportunity or project tag. The body must contain an object with a single property tag which must be a Tag Definition object.

To convert a data tag back to a simple tag you will need to first delete all the custom field definitions linked to it and then set the dataTag field to false.

PUT
https://api.capsulecrm.com/api/v2/{entity}/tags/{tagId}
          {
  "tag" : {
    "name" : "Nice Person"
  }
}

Response

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

HTTP/1.1 200 
{
  "tag" : {
    "id" : 1840253,
    "name" : "Nice Person",
    "dataTag" : false
  }
}

Delete tag definition

Removes a tag from the Capsule account. Note that this will remove the tag from any parties, opportunities and projects it was assigned to.

DELETE
https://api.capsulecrm.com/api/v2/{entity}/tags/{tagId}

Response

Returns HTTP status code 204. However, Capsule might schedule the deletion for later and return HTTP status 202 Accepted as defined in Long Running Operation section.

HTTP/1.1 204