Tag

Create Tag

This is not a public endpoint and requires token access. (how to get access token)

Available after version: Ver5.2023-11-22

• Endpoint: /api/v5/entity/tags/group/create

• HTTP Method: POST

• Request Parameters:

  Parameter	Type	Required	Name	Description
  name	String	Y	Tag name
  variable_name	String	Y	Tag variable name
  description	String	Y	Tag description
  attribute	String	Y	Attribute	Only 3 available types: define/number/string
  category	String	Y	Category
  corp_id	String	Y	Organization ID

• Response Format & Parameters: JSON

  Parameter	Type	Description
  tags_group_id	String	The ID of tag group
  corp_id	String	Organization ID
  name	String	Tag group name

Bash Example with CURL:

curl -X POST 
    -H "Content-Type: application/json; charset=utf-8"
    -H "Authorization: Bearer <TOKEN>"
    -H "X-APP-ID: <APP_ID>"
    -d '{"name": "group_possible", "variable_name": "champion_26004","description": "test","attribute": "define","category": "follow_up","corp_id": <CORP_ID>}'
    <API_SERVICE_HOST>/api/v5/user/create

Example Response

{
  "code": 0, 
  "msg": "success.", 
  "data": {
    "tags_group_id": "7a529dce6d4d41df882a4fcb9ce8277c", 
    "corp_id": <CORP_ID>, 
    "name": "group_possible"
  }
}

Get Tag Group List

This is not a public endpoint and requires token access. (how to get access token)

Available after version: Ver5.2023-11-22

• Endpoint: /api/v5/entity/tags/group/list

• HTTP Method: GET

• Request Parameters:

  Parameter	Type	Required	Name	Description
  corp_id	String	Y	Organization ID
  category	String	Y	Category
  start_index	Integer	Y	Start Index	Page start index number
  step	Integer	Y	Step

• Response Format & Parameters: JSON

  Parameter	Type	Description
  entity_id	String	The ID of tag group
  attribute	String	Attribute
  calculation_rules	String	Calculation rules
  category	String	Tag group name
  corp_id	String	Organization ID
  ctime	String	Tag group create time
  description	String	Tag group decription
  is_active	String	Active
  is_auto	String	Automated
  is_deleted	String	Deleted
  is_locked	String	Locked
  mtime	String	Last modification time
  name	String	Tag group name
  type	String	Tag group type
  variable_name	String	Varialbe name
  version	String	Version

Bash Example with CURL:

curl -X GET 
    -H "Content-Type: application/json; charset=utf-8"
    -H "Authorization: Bearer <TOKEN>"
    -H "X-APP-ID: <APP_ID>"
    <API_SERVICE_HOST>/api/v5/entity/tags/group/list?corp_id=<CORP_ID>&category=<CATEGORY>&start_index=<START_INDEX>&step=<STEP>

Example Response

{
  "code": 0, 
  "msg": "success.", 
  "data": {
    "total": 1, 
    "rows": [
      { "entity_id": "d0f50f5fd5fa48909f4b460cf8dab1ed", 
        "attribute": "define", 
        "calculation_rules": {},
        "category": "b2b", 
        "corp_id": <CORP_ID>, 
        "ctime": "2024-01-03 11:54:58", 
        "description": "originally b2b 60001 to B contacted already", 
        "is_active": true,
        "is_auto": false, 
        "is_deleted": false, 
        "is_locked": false, 
        "mtime": "2024-01-05 13:37:19",
        "name": "toB_contacted_already",
        "type": "system",
        "variable_name": "champion_60001",
        "version": 0
      }
    ]
  }
}

Update Tag Group

This endpoint allows updating an existing tag group.

• Endpoint: /api/v5/entity/tags/group/update

• HTTP Method: POST

• Request Parameters:

  Parameter	Type	Required	Name	Description
  entity_id	String	Y	Entity ID	The ID of the tag group to be updated.
  corp_id	String	Y	Organization ID	The ID of the organization.
  name	String	Y	Tag name	The updated name of the tag group.
  variable_name	String	Y	Tag variable name	The updated variable name of the tag group.
  description	String	Y	Tag description	The updated description of the tag group.
  attribute	String	Y	Attribute	The updated attribute of the tag group.
  category	String	Y	Category	The updated category of the tag group.

• Response Format & Parameters: JSON

  Parameter	Type	Description
  code	Integer	Error code. 0 indicates success.
  msg	String	Error message or success message.
  data	String	The ID of the updated tag group.

Example Request:

curl -X POST \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "Authorization: Bearer <TOKEN>" \
     -H "X-APP-ID: <APP_ID>" \
     -d '{
        "entity_id": "123456789010f5f92e3e458d87b",
        "corp_id": "12345678901487490102f169d934ae4",
        "name": "test_update",
        "variable_name": "update",
        "description": "should update successfully",
        "attribute": "define",
        "category": "follow_up"
     }' \
     <API_SERVICE_HOST>/api/v5/entity/tags/group/update

Example Response:

{
  "code": 0,
  "msg": "success.",
  "data": "d6be5f3fe1844e289f5f92e3e458d87b"
}

Deactivate Tag Group

This endpoint allows deactivating an existing tag group.

• Endpoint: /api/v5/entity/tags/group/deactivate

• HTTP Method: POST

• Request Parameters:

  Parameter	Type	Required	Name	Description
  entity_id	String	Y	Entity ID	The ID of the tag group to be deactivated.
  corp_id	String	Y	Organization ID	The ID of the organization.

• Response Format & Parameters: JSON

  Parameter	Type	Description
  code	Integer	Error code. 0 indicates success.
  msg	String	Error message or success message.
  data	String	The ID of the deactivated tag group.

Example Request:

curl -X POST \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "Authorization: Bearer <TOKEN>" \
     -H "X-APP-ID: <APP_ID>" \
     -d '{
        "entity_id": <TAGS_GROUP_ID>,
        "corp_id": <CORP_ID>
     }' \
     <API_SERVICE_HOST>/api/v5/entity/tags/group/deactivate

Example Response:

{
  "code": 0,
  "msg": "success.",
  "data": "12345f3fe18ab123455f92123458d87b"
}

Activate Tag Group

This endpoint allows activating an existing tag group.

• Endpoint: /api/v5/entity/tags/group/activate

• HTTP Method: POST

• Request Parameters:

  Parameter	Type	Required	Name	Description
  entity_id	String	Y	Entity ID	The ID of the tag group to be activated.
  corp_id	String	Y	Organization ID	The ID of the organization.

• Response Format & Parameters: JSON

  Parameter	Type	Description
  code	Integer	Error code. 0 indicates success.
  msg	String	Error message or success message.
  data	String	The ID of the activated tag group.

Example Request:

curl -X POST \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "Authorization: Bearer <TOKEN>" \
     -H "X-APP-ID: <APP_ID>" \
     -d '{
        "entity_id": <TAGS_GROUP_ID>,
        "corp_id": <CORP_ID>
     }' \
     <API_SERVICE_HOST>/api/v5/entity/tags/group/activate

Example Response:

{
  "code": 0,
  "msg": "success.",
  "data": "12345f3fe18ab123455f92123458d87b"
}

Assign Tag to User

This endpoint allows assigning a tag to a user.

• Endpoint: /api/v5/entity/user/tags/assign

• HTTP Method: POST

• Request Parameters:

  Parameter	Type	Required	Name	Description
  corp_id	String	Y	Organization ID	The ID of the organization.
  tags_group_id	String	Y	Tag Group ID	The ID of the tag group to assign.
  user_id	String	Y	User ID	The ID of the user to assign the tag to.
  value	String	Y	Value	The value of the tag assigned to the user.

• Response Format & Parameters: JSON

  Parameter	Type	Description
  code	Integer	Error code. 0 indicates success.
  msg	String	Error message or success message.
  data	String	The ID of the assigned tag.

Example Request:

curl -X POST \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "Authorization: Bearer <TOKEN>" \
     -H "X-APP-ID: <APP_ID>" \
     -d '{
        "corp_id": <CORP_ID>,
        "tags_group_id": <TAGS_GROUP_ID>,
        "user_id": <USER_ID>,
        "value": "True"
     }' \
     <API_SERVICE_HOST>/api/v5/entity/user/tags/assign

Example Response:

{
  "code": 0,
  "msg": "success.",
  "data": "54fcaa8fc145403fbf09a6c7b42cc8a6"
}

List User Tags

This endpoint retrieves a list of tags assigned to a user.

• Endpoint: /api/v5/entity/user/tags/list

• HTTP Method: GET

• Query Parameters:

  Parameter	Type	Required	Description
  corp_id	String	Y	Organization ID
  user_id	String	Y	User ID

• Response Format & Parameters: JSON

  Parameter	Type	Description
  entity_id	String	The ID of the tag entity.
  attribute	String	The attribute of the tag.
  corp_id	String	The ID of the organization.
  ctime	String	Creation time of the tag assignment.
  define_value	Boolean	The value of the tag assignment.
  executor_id	String	The ID of the user who assigned the tag.
  is_deleted	Boolean	Indicates whether the tag is deleted.
  mtime	String	Last modification time of the tag assignment.
  source	String	The source of the tag assignment.
  tags_group_id	String	The ID of the tag group.
  user_id	String	The ID of the user.
  version	Integer	The version of the tag assignment.

Example Request:

curl -X GET \
     -H "Authorization: Bearer <TOKEN>" \
     -H "X-APP-ID: <APP_ID>" \
     "<API_SERVICE_HOST>/api/v5/entity/user/tags/list?corp_id=<CORP_ID>&user_id=<USER_ID>"

Example Response:

{
  "code": 0,
  "msg": "success.",
  "data": {
    "total": 1,
    "rows": [
      {
        "entity_id": "1234566145403fbf09a6c7b42cc8a6",
        "attribute": "define",
        "corp_id": <CORP_ID>,
        "ctime": "2024-04-21 16:34:58",
        "define_value": true,
        "executor_id": <EXECUTOR_ID>,
        "is_deleted": false,
        "mtime": "2024-04-25 14:27:51",
        "source": "open_api",
        "tags_group_id": <TAGS_GROUP_ID>,
        "user_id": <USER_ID>,
        "version": 0
      }
    ]
  }
}