Create Tag

Define a new tag in a recording project.

POSThttps://api.identitycall.ai/api/v1/public/tags

Creates a tag in the project. Idempotent: an existing name is returned unchanged.

Requires write permission

This call is idempotent on name. If the project already has a tag with that name — compared case-insensitively, so VIP matches vip — the existing tag is returned with status 200 instead of 201, and nothing is created. You can call it on every sync without accumulating duplicates.

Scope

API key scope	Behavior
Account-wide	Creates the tag in the project named by `project_id`. The parameter is required.
Project-scoped	Creates the tag in the bound project. `project_id` may be omitted.

Request Body

Body Parameters (application/json)

Name	Type	Required	Default	Description
`name`	string	Yes	-	The tag name. Leading and trailing whitespace is stripped. Must be unique within the project, case-insensitively.
`project_id`	integer	No	-	The project to create the tag in. Required for account-wide keys; optional for project-scoped keys, which may only pass their own project id.

Colours cannot be set — they are assigned automatically from a fixed ten-colour palette, per project.

Request

cURL


curl -X POST "https://api.identitycall.ai/api/v1/public/tags" \
  -H "Authorization: Bearer $IDENTITYCALL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "vip",
    "project_id": 12
  }'

Python


import requests
import os
 
API_KEY = os.environ.get("IDENTITYCALL_API_KEY")
 
response = requests.post(
    "https://api.identitycall.ai/api/v1/public/tags",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    },
    json={"name": "vip", "project_id": 12}
)
 
tag = response.json()["data"]
created = response.status_code == 201
print(f"{'Created' if created else 'Reused'} tag {tag['id']}: {tag['name']}")

Node.js


const API_KEY = process.env.IDENTITYCALL_API_KEY;
 
const response = await fetch(
  'https://api.identitycall.ai/api/v1/public/tags',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ name: 'vip', project_id: 12 })
  }
);
 
const { data: tag } = await response.json();
console.log(`${response.status === 201 ? 'Created' : 'Reused'} tag ${tag.id}: ${tag.name}`);

Response

Response201 Created

{
"data": {
  "id": 4,
  "name": "vip",
  "color": "#EF4444",
  "project_id": 12,
  "recordings_count": 0
}
}

A repeat call with the same name returns 200 and the existing row, recordings_count included.

Response Fields

Field	Type	Description
`id`	integer	Unique tag ID. Only meaningful within its project.
`name`	string	The tag name as stored
`color`	string	Hex colour assigned automatically
`project_id`	integer	The recording project this tag belongs to
`recordings_count`	integer	How many recordings currently carry this tag

Errors

Status	Error	Description
401	“Invalid API key”	Missing or unrecognized bearer token
403	“Write permission required”	API key lacks write permission
403	“project_id does not match this API key’s project”	A project-scoped key passed a different project’s id
404	“Project not found”	The project does not exist, or belongs to another account
422	“name is required”	`name` was missing, empty, or only whitespace
422	“project_id is required for account-wide API keys”	An account-wide key omitted `project_id`