Tags API

Scope: ZohoProjects.tags.{Operation}

Operations: READ, CREATE, ALL

Use the ALL operation to gain the scope for all the other operations like READ and CREATE at once.

Get All Tags
GET /api/v3/portal/[PORTALID]/tags

Create Tag
POST /api/v3/portal/[PORTALID]/tags

Update Tag
PATCH /api/v3/portal/[PORTALID]/tags/[TAGID]

Delete Tag
DELETE /api/v3/portal/[PORTALID]/tags/[TAGID]

Associate Tag
POST /api/v3/portal/[PORTALID]/projects/[PROJECTID]/tags/associate

Dissociate Tag
POST /api/v3/portal/[PORTALID]/projects/[PROJECTID]/tags/dissociate

Get Tag Results
GET /api/v3/portal/[PORTALID]/globaltags/search

Get All Tags

Fetches all the tags present in a specific portal.

GET /api/v3/portal/[PORTALID]/tags

Scope: ZohoProjects.tags.READ

Request Parameters

Param name	Data type	Description	Value
index	int	Index number of the tag.	0
range	int	Range of the tags.	100

Sample Response

Status: 200 Success

Content Type: application/json;charset=utf-8

{
    "tags": [
        {
            "id": "170876000008279189",
            "name": "Construction",
            "color_class": "bg-tag3",
            "created_by": {
                "id": 703961433,
                "zpuid": "170876000007981001",
                "name": "Monica",
                "email": "monica.hemsworth@zylker.com",
                "is_client_user": false,
                "zuidString": "703961433"
            }
        },
 {
            "id": "170876000008433005",
            "name": "construction projects",
            "color_class": "bg-tag19",
            "created_by": {
                "id": 703961433,
                "zpuid": "170876000007981001",
                "name": "Monica",
                "email": "monica.hemsworth@zylker.com",
                "is_client_user": false,
                "zuidString": "703961433"
            }
        },

 {
            "id": "170876000008433019",
            "name": "Partner Demo",
            "color_class": "bg-tag14",
            "created_by": {
                "id": 63475760,
                "zpuid": "170876000005155145",
                "name": "Kiruthika V",
                "email": "kiruthika.v@zylker.com",
                "is_client_user": false,
                "zuidString": "63475760"
            }
        }
 }
    ]
}

Create Tag

Creates tags for a specific portal.

POST /api/v3/portal/[PORTALID]/tags

Scope: ZohoProjects.tags.CREATE

Request Parameters

Param name	Data type	Description
tags	JSON Array	"name" and "color_class" must be given in the array to map the tag with a relevant color. [{"name":"priority","color_class":"bg-tag16"}]

Sample Response

Status: 200 Success

Content Type: application/json;charset=utf-8

{

    "tags": [
        {
            "id": "170876000008716005",
            "name": "priority",
            "color_class": "bg-tag16"
        }
    ]
}

Update Tag

Updates a specific tag present in a specific portal.

PATCH /api/v3/portal/[PORTALID]/tags/[TAGID]

Scope: ZohoProjects.tags.READ

Request Body

Content Type: application/json;charset=utf-8

The below keys are passed in a JSONObject.

Key name	Data type	Description
name	String	Name of the tag
color_class	String	Color of the tag

Sample Input

{

"name": "priorityTest”,

"color_class": "bg-tag1"

}

Sample Response

Status: 200 Success

Content Type: application/json;charset=utf-8

{
    "tags": {
        "id": "170876000008716005",
        "name": "priorityTest",
        "color_class": "bg-tag1"
    }
}

Delete Tag

Deletes a specific tag from a specific portal.

DELETE /api/v3/portal/[PORTALID]/tags/[TAGID]

Scope: ZohoProjects.tags.READ

Sample Response

Status: 204

Associate Tag

Associates a tag with a specific entity in a specific project. The following are the list of values mapped against each entity in Zoho Projects.
{"PROJECT":2, "MILESTONE":3, "TASKLIST":4, "TASK":5, "BUG":6, "FORUM":7, "STATUS":8}

POST /api/v3/portal/[PORTALID]/projects/[PROJECTID]/tags/associate

Scope: ZohoProjects.tags.CREATE

Request Parameters

Param name	Data type	Description	Value
tag_id	Long	The unique identifier for a tag.	170876000008433001
entity_id	Long	The unique identifier for an entity.	170876000008548093
entityType	int	The module with which the tag has to be associated.	2

Sample Response

Status: 204

Dissociate Tag

Dissociates a tag from a specific entity in a specific project. The following are the list of values mapped against each entity in Zoho Projects.
{"PROJECT":2, "MILESTONE":3, "TASKLIST":4, "TASK":5, "BUG":6, "FORUM":7, "STATUS":8}

POST /api/v3/portal/[PORTALID]/projects/[PROJECTID]/tags/dissociate

Scope: ZohoProjects.tags.CREATE

Request Parameters

Param name	Data type	Description	Value
tag_id	Long	The unique identifier for a tag.	170876000008433001
entity_id	Long	The unique identifier for an entity.	170876000008548093
entityType	int	The module with which the tag has to be associated.	2

Sample Response

Status: 204

Get Tag Results

Fetches the tag results across the portal. If a tag has to be searched across all the modules, the value of the entity is -1.

GET /api/v3/portal/[PORTALID]/globaltags/search

Scope: ZohoSearch.securesearch.READ, ZohoProjects.tags.READ

Request Parameters

Param name	Data type	Description	Value
tag_id	Long	A unique identifier for a tag	170876000008279189
index	int	The index number of the tags	0
range	int	The range of the tags	50
filter	JSON Object	The filter criteria for the tag. The JSON has the project's name, status, and module.	{"project":"0","projstatus":"active","module":-1}

Sample Response

Status: 200 Success

Content Type: application/json;charset=utf-8

{
  "total_count": 7,
  "categories": [
    {
      "values": [
        {
          "name": "Tasks",
          "count": 2,
          "id": "moduleid_5"
        },
        {
          "name": "Issues",
          "count": 2,
          "id": "moduleid_6"
        },
        {
          "name": "Projects",
          "count": 1,
          "id": "moduleid_2"
        },
        {
          "name": "Milestones",
          "count": 1,
          "id": "moduleid_3"
        },
        {
          "name": "Task Lists",
          "count": 1,
          "id": "moduleid_4"
        },
        {
          "name": "Forums",
          "count": 0,
          "id": "moduleid_7"
        },
        {
          "name": "Status",
          "count": 0,
          "id": "moduleid_8"
        },
        {
          "name": "Events",
          "count": 0,
          "id": "moduleid_9"
        }
      ],
      "name": "modules",
      "id": "module_id"
    }
  ],
  "results": [
    {
      "extra_data": {
        "bug_key": "6",
        "status_name": "Open"
      },
      "module": "BUG",
      "project": {
        "name": "Donnelly Apartments Constructions",
        "id": "170876000006151013"
      },
      "entity_id": "170876000006210007",
      "title": "#106 ZPhone cable issue",
      "bug_prefix": "DC1-I",
      "created_by": {},
      "tags": [
        {
          "createdby": "170876000007981001",
          "name": "Construction",
          "id": "170876000008279189",
          "color_class": "bg-tag3"
        }
      ]
    },
    {
      "extra_data": {
        "status_name": "Open",
        "task_key": "108",
        "due_date": "1585157400000"
      },
      "module": "TASK",
      "project": {
        "name": "Donnelly Apartments Constructions",
        "id": "170876000006151013"
      },
      "task_prefix": "DC1",
      "assignee": [
        {
          "name": "Unassigned User",
          "id": "0",
          "email": "Unassigned User"
        }
      ],
      "entity_id": "170876000006154433",
      "title": "Foundation certification",
      "created_by": {
        "name": "Helen",
        "id": "639283127",
        "email": "helenc@zylker.com"
      },
      "tags": [
        {
          "createdby": "170876000007981001",
          "name": "Construction",
          "id": "170876000008279189",
          "color_class": "bg-tag3"
        }
      ]
    },
    {
      "extra_data": {
        "status_name": "Open",
        "task_key": "102",
        "due_date": "1585593000000"
      },
      "module": "TASK",
      "project": {
        "name": "Donnelly Apartments Constructions",
        "id": "170876000006151013"
      },
      "task_prefix": "DC1",
      "assignee": [
        {
          "name": "Amritha Agrawal",
          "id": "2063270",
          "email": "igrawal@zillum.com"
        }
      ],
      "entity_id": "170876000006154409",
      "title": "2nd floor wall framing",
      "created_by": {
        "name": "Helen",
        "id": "639283127",
        "email": "helenc@zylker.com"
      },
      "tags": [
        {
          "createdby": "170876000007981001",
          "name": "Construction",
          "id": "170876000008279189",
          "color_class": "bg-tag3"
        }
      ]
    },
    {
      "extra_data": {
        "bug_key": "7",
        "status_name": "To be tested"
      },
      "module": "BUG",
      "project": {
        "name": "Donnelly Apartments Constructions",
        "id": "170876000006151013"
      },
      "entity_id": "170876000006694023",
      "title": "#107 New ticket from Zoho Desk",
      "bug_prefix": "DC1-I",
      "created_by": {
        "name": "rufus.david92",
        "id": "649332655",
        "email": "rufus.david92@gmail.com"
      },
      "tags": [
        {
          "createdby": "170876000007981001",
          "name": "Construction",
          "id": "170876000008279189",
          "color_class": "bg-tag3"
        }
      ]
    },
    {
      "extra_data": {
        "flag": "external",
        "milestone": {
          "name": "Phase 2",
          "id": "170876000008695025"
        },
        "is_completed": false
      },
      "module": "TASKLIST",
      "project": {
        "name": "Donnelly Apartments Constructions",
        "id": "170876000006151013"
      },
      "entity_id": "170876000008695029",
      "title": "General List",
      "created_by": {},
      "tags": [
        {
          "createdby": "170876000007981001",
          "name": "Construction",
          "id": "170876000008279189",
          "color_class": "bg-tag3"
        }
      ]
    },
    {
      "extra_data": {
        "flag": "external",
        "is_archived": false,
        "due_date": "1585099799000",
        "is_completed": false
      },
      "module": "MILESTONE",
      "project": {
        "name": "Donnelly Apartments Constructions",
        "id": "170876000006151013"
      },
      "assignee": [
        {
          "name": "Anushree Bose",
          "id": "651219802",
          "email": "anushree.b@zohocorp.com"
        }
      ],
      "entity_id": "170876000008695025",
      "title": "Phase 2",
      "created_by": {
        "name": "Anushree Bose",
        "id": "651219802",
        "email": "anushree.b@zohocorp.com"
      },
      "tags": [
        {
          "createdby": "170876000007981001",
          "name": "Construction",
          "id": "170876000008279189",
          "color_class": "bg-tag3"
        }
      ]
    },
    {
      "module": "PROJECT",
      "project": {
        "name": "Donnelly Apartments Constructions",
        "id": "170876000006151013"
      },
      "entity_id": "170876000006151013",
      "title": "Donnelly Apartments Constructions",
      "created_by": {},
      "tags": [
        {
          "createdby": "170876000007981001",
          "name": "Construction",
          "id": "170876000008279189",
          "color_class": "bg-tag3"
        }
      ]
    }
  ]
}