With the user tag management-related APIs, you can create, query, modify and delete the Official Account tags, and tag and untag users.

Tag Management

1. Creating Tags

A maximum of 100 tags can be created for an Official Account.

API Request Format

HTTP request method: POST (use HTTPS protocol)
https://api.weixin.qq.com/cgi-bin/tags/create?access_token=ACCESS_TOKEN

POST data format: JSON POST data example:

{   "tag" : {     "name" : "Guangdong"//Tag Name  } } 

Parameters

Parameter Description
access_token Credential for calling API
name Tag name, with a maximum length of 30 characters (bytes).

Response (example of the JSON packet returned for a successful request)

{  "tag":{ "id":134,//Tag ID "name":"Guangdong" } } 

Response Parameters

Parameter Description
id Tag ID assigned by WeChat
name UTF8-encoded tag name

Error Codes

Error Code Description
-1 System is busy.
45157 Invalid tag name. Duplicate names are not allowed.
45158 Tag name length exceeds 30 characters (bytes).
45056 Too many tags created. The number of tags cannot be greater than 100.

2. Obtaining the Official Account's Created Tags

API Request Format

HTTP request method: GET (use the HTTPS protocol)
https://api.weixin.qq.com/cgi-bin/tags/get?access_token=ACCESS_TOKEN 

Response

{   
"tags":[{       
    "id":1,       
    "name":"Coca Cola Stars",      
    "count":0 //Number of followers under this tag
},
{   
    "id":2,   
    "name":"Starred Group",   
    "count":0
},
{   
    "id":127,  
    "name":"Guangdong",  
    "count":5 
 }   
] } 

3. Editing Tags

API Request Format

HTTP request method: POST (use the HTTPS protocol)
https://api.weixin.qq.com/cgi-bin/tags/update?access_token=ACCESS_TOKEN 

POST data format: JSON POST data example:

{   "tag" : {     "id" : 134,     "name" : "Cantonese"   } } 

Response

{   "errcode":0,   "errmsg":"ok" } 

Error Codes

Error Code Description
-1 System is busy.
45157 Invalid tag name. Duplicate names are not allowed.
45158 Tag name length exceeds 30 characters (bytes).
45058 The reserved tags of the systems 0, 1 and 2 are non-editable.

4. Deleting Tags

Note: If the number of followers under a tag exceeds 100,000, the tag cannot be deleted directly. You need to untag followers in the tag's OpenID list to reduce the number of followers to 100,000 or less before you can delete the tag.

API Request Format

HTTP request method: POST (use the HTTPS protocol)
https://api.weixin.qq.com/cgi-bin/tags/delete?access_token=ACCESS_TOKEN 

POST data format: JSON POST data example:

{   "tag":{        "id" : 134   } } 

Response

{   "errcode":0,   "errmsg":"ok" } 

Error Codes

Error Code Description
-1 System is busy.
45058 The reserved tags of the systems 0, 1 and 2 are non-editable.
45057 This tag has more than 100, 000 followers and cannot be directly deleted.

5. Obtaining the Follower List Under a Tag

API Request Format

HTTP request method: GET (use the HTTPS protocol)
https://api.weixin.qq.com/cgi-bin/user/tag/get?access_token=ACCESS_TOKEN 

POST data format: JSON POST data example:

{   "tagid" : 134,   "next_openid":""// The first OpenID to be fetched. If it is left empty, the list is fetched from the beginning. | 

Response (Example of returned JSON packet for a successful request)

{  
    "count":2,//Number of fetched followers   
    "data":{//List of followers
    "openid":[  
    "ocYxcuAEy30bX0NXmGn4ypqx3tI0",    
    "ocYxcuBt0mRugKZ7tGAHPnUaOW7Y"  ]  
},  
    "next_openid":"ocYxcuBt0mRugKZ7tGAHPnUaOW7Y"// The OpenID of the last user in the fetched list. 
}

Error Codes

Error Code Description
-1 System is busy.
40003 Invalid OpenID
45159 Invalid tag_id

User Management

A maximum of 20 tags can be set for a user under an Official Account.

1. Tagging Users in Batch

API Request Format

HTTP request method: POST (use the HTTPS protocol)
https://api.weixin.qq.com/cgi-bin/tags/members/batchtagging?access_token=ACCESS_TOKEN

POST data example:

{   
    "openid_list" : [//List of followers    
    "ocYxcuAEy30bX0NXmGn4ypqx3tI0",    
    "ocYxcuBt0mRugKZ7tGAHPnUaOW7Y"   ],   
    "tagid" : 134
 } 

Response (Example of returned JSON packet for a successful request)

{   
    "errcode":0,   
    "errmsg":"ok"
} 

Error Codes

Error Code Description
-1 System is busy.
40032 The number of OpenIDs in each list cannot exceed 50.
45159 Invalid tag
45059 A number of tags for a follower exceeds the limit. A maximum of 20 tags are allowed for a user.
40003 Invalid OpenID
49003 The OpenID entered does not belong to this AppID.

2. Untagging Users in Batch

API Request Format

HTTP request method: POST (use the HTTPS protocol)
https://api.weixin.qq.com/cgi-bin/tags/members/batchuntagging?access_token=ACCESS_TOKEN

POST data format: JSON POST data example:

{   
    "openid_list" : [//List of followers     
    "ocYxcuAEy30bX0NXmGn4ypqx3tI0",     
    "ocYxcuBt0mRugKZ7tGAHPnUaOW7Y"   ],   
    "tagid" : 134
 } 

Response (Example of returned JSON packet for a successful request)

{  
    "errcode":0,   
    "errmsg":"ok"
} 

Error Codes

Error Code Description
-1 System is busy.
40032 The number of OpenIDs in each list cannot exceed 50.
45159 Invalid tag
40003 Invalid OpenID
49003 The OpenID entered does not belong to this AppID.

3. Obtaining Tag List for a User

API Request Format

HTTP request method: POST (use the HTTPS protocol)
https://api.weixin.qq.com/cgi-bin/tags/getidlist?access_token=ACCESS_TOKEN

POST data format: JSON POST data example:

{   "openid" : "ocYxcuBt0mRugKZ7tGAHPnUaOW7Y" } 

Response (Example of returned JSON packet for a successful request):

{  "tagid_list":[//List of tags for the user 134, 2 ] } 

Error Codes

Error Code Description
-1 System is busy.
40003 Invalid OpenID
49003 The OpenID entered does not belong to this AppID.