Skip to main content
POST
/
api
/
v1
/
tags
Create Tag
curl --request POST \
  --url https://api.example.com/api/v1/tags \
  --header 'Content-Type: application/json' \
  --data '
{
  "workspace_id": "<string>",
  "name": "<string>",
  "type": "<string>",
  "color": "<string>",
  "description": "<string>"
}
'
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELD",
    "message": "The 'name' field is required",
    "field": "name"
  }
}

​
Authentication

This endpoint requires authentication via Bearer token. 
Authorization: Bearer YOUR_API_KEY

​
Request Body

​
workspace_id
string
required
The workspace ID to create the tag in
​
name
string
required
Tag name (e.g., “Customer Payment”, “Vendor Expense”)
  • Min length: 1 character
  • Max length: 50 characters
  • Must be unique within workspace
​
type
string
required
Tag type for categorization
  • income - For revenue/income transactions
  • expense - For costs/expense transactions
  • neutral - For transfers or other transactions
​
color
string
Hex color code for visual identification (default: auto-assigned)
  • Format: #RRGGBB
  • Example: #10B981
​
description
string
Optional description explaining the tag’s purpose
  • Max length: 200 characters

​
Response

​
success
boolean
Indicates if the tag was created successfully
​
data
object

​
Example Request

curl -X POST "https://api.cryptotally.xyz/v1/tags" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "ws_123",
    "name": "Customer Payment",
    "type": "income",
    "color": "#10B981",
    "description": "Payments received from clients for services"
  }'

​
Example Response

{
  "success": true,
  "data": {
    "id": "tag_abc123",
    "name": "Customer Payment",
    "type": "income",
    "color": "#10B981",
    "description": "Payments received from clients for services",
    "workspace_id": "ws_123",
    "created_by": "usr_xyz789",
    "created_at": "2024-03-20T10:30:00Z",
    "usage_count": 0
  }
}

​
Error Responses

{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELD",
    "message": "The 'name' field is required",
    "field": "name"
  }
}

​
Common Tag Examples

​
Income Tags

{
  "name": "Customer Payment",
  "type": "income",
  "color": "#10B981"
}

{
  "name": "Grant Funding",
  "type": "income",
  "color": "#3B82F6"
}

{
  "name": "Investment",
  "type": "income",
  "color": "#8B5CF6"
}

​
Expense Tags

{
  "name": "Vendor Payment",
  "type": "expense",
  "color": "#EF4444"
}

{
  "name": "Salary",
  "type": "expense",
  "color": "#F59E0B"
}

{
  "name": "Gas Fees",
  "type": "expense",
  "color": "#6B7280"
}

​
Neutral Tags

{
  "name": "Transfer",
  "type": "neutral",
  "color": "#64748B"
}

{
  "name": "Asset Purchase",
  "type": "neutral",
  "color": "#0EA5E9"
}

​
Bulk Tag Creation

To create multiple tags at once, send multiple requests in parallel: 
const tags = [
  { name: 'Customer Payment', type: 'income', color: '#10B981' },
  { name: 'Vendor Payment', type: 'expense', color: '#EF4444' },
  { name: 'Salary', type: 'expense', color: '#F59E0B' }
];

const results = await Promise.all(
  tags.map(tag =>
    fetch('https://api.cryptotally.xyz/v1/tags', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ ...tag, workspace_id: 'ws_123' })
    }).then(res => res.json())
  )
);

console.log(results);

​
Tag Management Operations

​
Get All Tags

GET /api/v1/tags?workspace_id=ws_123

​
Update Tag

PATCH /api/v1/tags/:tag_id

​
Delete Tag

DELETE /api/v1/tags/:tag_id

​
Apply Tag to Transaction

POST /api/v1/transactions/:transaction_id/tags

​
Tag Naming Best Practices

✅ “Customer Payment” ❌ “CP” ✅ “Vendor Expense” ❌ “Expense1”
Choose one style and stick with it:
  • Title Case: “Customer Payment”
  • Sentence case: “Customer payment”
  • lowercase: “customer payment”
❌ “Client Payment” and “Customer Payment” ✅ Choose one term and use it consistently
For project-specific tracking:
  • “Grant - Phase 1”
  • “Client A - Q1 2024”
  • “Marketing - Social Media”

​
Color Palette Suggestions

​
Income (Green Shades)

  • #10B981 - Emerald (Default income color)
  • #22C55E - Green
  • #84CC16 - Lime

​
Expense (Red/Orange Shades)

  • #EF4444 - Red (Default expense color)
  • #F59E0B - Amber
  • #F97316 - Orange

​
Neutral (Blue/Gray Shades)

  • #64748B - Slate (Default neutral color)
  • #3B82F6 - Blue
  • #0EA5E9 - Sky

​
Category-Specific

  • #8B5CF6 - Purple (Investments, Assets)
  • #EC4899 - Pink (Subscriptions, Recurring)
  • #14B8A6 - Teal (Payroll, HR)

​
Rate Limits

  • Free Tier: 100 tags per workspace, 100 API requests/hour
  • Pro Tier: 500 tags per workspace, 1,000 API requests/hour
  • Enterprise Tier: Unlimited tags, custom rate limits

​
Webhooks

Subscribe to tag events:
  • tag.created - New tag created
  • tag.updated - Tag name or details changed
  • tag.deleted - Tag removed
See Webhooks for setup instructions.

Get Tags

Fetch all workspace tags

Update Tag

Modify tag details

Delete Tag

Remove a tag

Apply Tag to Transaction

Tag a transaction