Managing Tags

Tags help you organize and categorize your calls. Use them to mark important calls, track topics, or integrate with your workflow.

Required Scopes

Operation	Scope
List tags	tags.read
Create/update/delete tags	tags.write
View tags on calls	calls.read
Add/remove tags from calls	calls.tags.write

Tag Basics

List All Tags

cURL

curl "https://app.sipsim.com/api/v2/tags" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Python

import requests

access_token = "YOUR_ACCESS_TOKEN"

response = requests.get(
    "https://app.sipsim.com/api/v2/tags",
    headers={"Authorization": f"Bearer {access_token}"}
)

tags = response.json()["data"]
for tag in tags:
    print(f"{tag['name']} (#{tag['color']})")

Tag Response

{
  "status": 200,
  "request_id": "...",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": [
    {
      "id": 1,
      "name": "Important",
      "color": "#FF0000",
      "description": "High priority calls"
    },
    {
      "id": 2,
      "name": "Follow-up",
      "color": "#FFA500",
      "description": "Requires callback"
    }
  ],
  "pagination": {
    "count": 2,
    "limit": 1000,
    "has_more": false
  }
}

Tag Fields

Field	Type	Description
id	integer	Unique tag identifier
name	string	Tag name
color	string	Hex color code (e.g., #FF0000)
description	string	Optional description of the tag

Create a Tag

cURL

curl -X POST "https://app.sipsim.com/api/v2/tags" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Lead",
    "color": "#22C55E",
    "description": "Potential sales opportunity"
  }'

Python

import requests

access_token = "YOUR_ACCESS_TOKEN"

response = requests.post(
    "https://app.sipsim.com/api/v2/tags",
    headers={
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Sales Lead",
        "color": "#22C55E",
        "description": "Potential sales opportunity"
    }
)

if response.status_code == 201:
    tag = response.json()["data"]
    print(f"Created tag: {tag['name']} (ID: {tag['id']})")

Create Tag Parameters

Parameter	Type	Required	Description
name	string	Yes	Tag name (must be unique)
color	string	No	Hex color (default: #6B7280)
description	string	No	Optional description of the tag

Handling Duplicate Names

If you try to create a tag with a name that already exists, you'll get a 409 Conflict:

{
  "status": 409,
  "errors": ["Tag with this name already exists"],
  "request_id": "...",
  "path": "/api/v2/tags"
}

Update a Tag

cURL

curl -X PATCH "https://app.sipsim.com/api/v2/tags/1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "VIP Customer",
    "color": "#8B5CF6"
  }'

Python

import requests

access_token = "YOUR_ACCESS_TOKEN"
tag_id = 1

response = requests.patch(
    f"https://app.sipsim.com/api/v2/tags/{tag_id}",
    headers={
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json"
    },
    json={
        "name": "VIP Customer",
        "color": "#8B5CF6"
    }
)

if response.status_code == 200:
    tag = response.json()["data"]
    print(f"Updated tag: {tag['name']}")

Delete a Tag

cURL

curl -X DELETE "https://app.sipsim.com/api/v2/tags/1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Python

import requests

access_token = "YOUR_ACCESS_TOKEN"
tag_id = 1

response = requests.delete(
    f"https://app.sipsim.com/api/v2/tags/{tag_id}",
    headers={"Authorization": f"Bearer {access_token}"}
)

if response.status_code == 204:
    print("Tag deleted successfully")

warning

Deleting a tag removes it from all associated calls. This action cannot be undone.

Tagging Calls

View Tags on a Call

Tags are included in the call response:

curl "https://app.sipsim.com/api/v2/calls/12345" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response includes:

{
  "data": {
    "id": 12345,
    "tags": [
      {"id": 1, "name": "Important", "color": "#FF0000"},
      {"id": 2, "name": "Follow-up", "color": "#FFA500"}
    ]
  }
}

List Tags on a Call

Get just the tags for a specific call:

curl "https://app.sipsim.com/api/v2/calls/12345/tags" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Add a Tag to a Call

cURL

curl -X PUT "https://app.sipsim.com/api/v2/calls/12345/tags/1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Python

import requests

access_token = "YOUR_ACCESS_TOKEN"
call_id = "12345"
tag_id = 1

response = requests.put(
    f"https://app.sipsim.com/api/v2/calls/{call_id}/tags/{tag_id}",
    headers={"Authorization": f"Bearer {access_token}"}
)

if response.status_code == 201:
    print("Tag added to call")
elif response.status_code == 204:
    print("Tag was already on the call")

The PUT operation is idempotent:

• Returns 201 Created if the tag was added
• Returns 204 No Content if the tag was already present

Remove a Tag from a Call

cURL

curl -X DELETE "https://app.sipsim.com/api/v2/calls/12345/tags/1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Python

import requests

access_token = "YOUR_ACCESS_TOKEN"
call_id = "12345"
tag_id = 1

response = requests.delete(
    f"https://app.sipsim.com/api/v2/calls/{call_id}/tags/{tag_id}",
    headers={"Authorization": f"Bearer {access_token}"}
)

if response.status_code == 204:
    print("Tag removed from call")

The DELETE operation is also idempotent — it always returns 204 regardless of whether the tag was present.

Filtering Calls by Tags

Use the tags parameter when listing calls:

# Get calls with tag ID 1 or 2
curl "https://app.sipsim.com/api/v2/calls?start_time=2024-01-01T00:00:00Z&tags=1,2" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Practical Examples

Auto-Tag Based on Call Duration

Tag long calls automatically:

import requests

access_token = "YOUR_ACCESS_TOKEN"
base_url = "https://app.sipsim.com/api/v2"
headers = {"Authorization": f"Bearer {access_token}"}

# Ensure "Long Call" tag exists
tags_response = requests.get(f"{base_url}/tags", headers=headers)
tags = tags_response.json()["data"]
long_call_tag = next((t for t in tags if t["name"] == "Long Call"), None)

if not long_call_tag:
    # Create the tag
    create_response = requests.post(
        f"{base_url}/tags",
        headers={**headers, "Content-Type": "application/json"},
        json={"name": "Long Call", "color": "#EF4444", "description": "Calls over 30 minutes"}
    )
    long_call_tag = create_response.json()["data"]

# Get recent calls
calls_response = requests.get(
    f"{base_url}/calls",
    headers=headers,
    params={"start_time": "2024-01-01T00:00:00Z", "limit": 100}
)
calls = calls_response.json()["data"]

# Tag calls over 30 minutes
for call in calls:
    if (call["duration_sec"] or 0) > 1800:  # 30 minutes
        requests.put(
            f"{base_url}/calls/{call['id']}/tags/{long_call_tag['id']}",
            headers=headers
        )
        print(f"Tagged call {call['id']} as Long Call")

Sync Tags with CRM

import requests

access_token = "YOUR_ACCESS_TOKEN"
base_url = "https://app.sipsim.com/api/v2"
headers = {"Authorization": f"Bearer {access_token}"}

def sync_crm_tags_to_sipsim(crm_tags):
    """
    Ensure SIPSIM has all the tags from your CRM.
    Returns a mapping of CRM tag names to SIPSIM tag IDs.
    """
    # Get existing SIPSIM tags
    response = requests.get(f"{base_url}/tags", headers=headers)
    existing = {t["name"]: t["id"] for t in response.json()["data"]}
    
    tag_mapping = {}
    
    for crm_tag in crm_tags:
        name = crm_tag["name"]
        
        if name in existing:
            tag_mapping[name] = existing[name]
        else:
            # Create in SIPSIM
            response = requests.post(
                f"{base_url}/tags",
                headers={**headers, "Content-Type": "application/json"},
                json={
                    "name": name,
                    "color": crm_tag.get("color", "#6B7280"),
                    "description": f"Synced from CRM"
                }
            )
            tag_mapping[name] = response.json()["data"]["id"]
    
    return tag_mapping

# Example: Sync from your CRM
crm_tags = [
    {"name": "Hot Lead", "color": "#EF4444"},
    {"name": "Qualified", "color": "#22C55E"},
    {"name": "Nurture", "color": "#3B82F6"}
]

mapping = sync_crm_tags_to_sipsim(crm_tags)
print("Tag mapping:", mapping)

Best Practices

1. Use descriptive names — Make tag purposes clear
2. Establish a color convention — e.g., red for urgent, green for resolved
3. Keep tags organized — Delete unused tags to avoid clutter
4. Document your tagging system — Help your team use tags consistently
5. Automate when possible — Use the API to auto-tag based on rules

Next Steps

• Working with Calls — Filter calls by tags
• AI Features — Use AI to help categorize calls
• API Reference — Complete Tags API reference