Create a tag

Create a tag in your account. Pass a session_key to also put it on that conversation in the same call.

Tag names are unique per account, ignoring case. If a tag with that name already exists, nothing new is created: the endpoint returns the existing tag (and puts it on the conversation, if you sent a session_key). This makes it safe to call every time you need a tag, without listing first.

Endpoint

POST https://api.p.2chat.io/open/tags

Authentication

Include your API key in the X-User-API-Key header. Learn more about authentication.

Parameters

These parameters should be sent as JSON payload in the request body.

Field	Type	Required	Description
`name`	string	Yes	Name of the tag, up to 100 characters. Spaces at the start and end are removed.
`session_key`	string	No	A conversation of your account to put the tag on. See where to get it.

New tags are gray (#CCCCCC). To pick a color, update the tag after creating it.

Invocation

cURL
Python
JavaScript
PHP

curl --location --request POST 'https://api.p.2chat.io/open/tags' \
--header 'Content-Type: application/json' \
--header 'X-User-API-Key: your_api_key_here' \
--data '{
    "name": "Hot lead",
    "session_key": "WA-WAN8fd3442f-e111-4fed-9323-1824fd7546c9-14085550176"
}'

import requests

url = "https://api.p.2chat.io/open/tags"
headers = {
    "Content-Type": "application/json",
    "X-User-API-Key": "your_api_key_here"
}
payload = {
    "name": "Hot lead",
    "session_key": "WA-WAN8fd3442f-e111-4fed-9323-1824fd7546c9-14085550176"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

const axios = require('axios');

const response = await axios.post('https://api.p.2chat.io/open/tags', {
    name: 'Hot lead',
    session_key: 'WA-WAN8fd3442f-e111-4fed-9323-1824fd7546c9-14085550176'
}, {
    headers: {
        'Content-Type': 'application/json',
        'X-User-API-Key': 'your_api_key_here'
    }
});

console.log(response.data);

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.p.2chat.io/open/tags',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => json_encode([
      'name' => 'Hot lead',
      'session_key' => 'WA-WAN8fd3442f-e111-4fed-9323-1824fd7546c9-14085550176'
  ]),
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'X-User-API-Key: your_api_key_here'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Response

Success (HTTP 201 Created)

The same response comes back when the tag already existed.

{
    "success": true,
    "data": {
        "uuid": "TAGd37f22fa-fe01-4a90-b57d-7e83ccc6a05a",
        "name": "Hot lead",
        "color": "#CCCCCC",
        "exclude_from_campaigns": false,
        "created_at": "2026-10-28T17:55:04Z",
        "updated_at": "2026-10-28T17:55:04Z",
        "created_by_user_id": 4809
    }
}

Field	Description
`success`	`true` when the request succeeded
`data`	The tag. See the tag object.

Error

{
    "success": false,
    "error": true,
    "error_message": "Payload is invalid. Make sure all required fields are present and with valid values: session_key does not belong to this account"
}

HTTP status	When
`400`	`name` is empty, or `session_key` is not a conversation of your account
`422`	The body has no `name` field

Create a tag

Endpoint​

Authentication​

Parameters​

Invocation​

Response​

Success (HTTP 201 Created)​

Error​