Tag

Tags are keywords that can be used to categorize parties, cases or opportunities. These endpoints allow managing the tags in a Capsule account. For a full description of the model see the Tag model definition.

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

Create tag definition

Defines a new party, opportunity or case 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. To create a new datatag set the datatag field to true and then separately use the add field definition endpoint to add the custom fields.

POST
https://api.capsulecrm.com/api/v2/{entity}/tags
          {
  "tag" : {
    "name" : "Nice Guy",
    "description" : null,
    "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",
    "description" : null,
    "dataTag" : false
  }
}

Headers:

Name Type Description
Location String

The URL that identifies the new tag

Delete tag definition

Removes a tag from the capsule account. Note that this will remove the tag from any parties, opportunities and cases 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

List tag definitions

The collection of all of 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

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.

HTTP/1.1 200
Link: <https://api.capsulecrm.com/api/v2/parties/tags?page=2>; rel="next"
{
  "tags" : [ {
    "id" : 1840253,
    "name" : "Nice Guy",
    "description" : null,
    "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

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.

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

Update tag definition

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

To convert a datatag 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.

POST
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",
    "description" : null,
    "dataTag" : false
  }
}