Client tags workflow

Company tags are labels with a name + hex color. They are many-to-many on clients (Tag + ClientTag). Authenticate with x-api-key. These are not the special cost-center marker (Centro de resultados / legacy Centro de costos) used to mark budget clients. Use Cost centers for that path.

curl --request GET \
  --url "https://finsync.ar/api/tags" \
  --header "x-api-key: YOUR_API_KEY"

The response is an array of tags (id, name, color, company_id, timestamps).

Create a tag

Same validation as the dashboard modal: name is required (2–50 characters, unique per company) and color must be #RRGGBB.

curl --request POST \
  --url "https://finsync.ar/api/tags" \
  --header "Content-Type: application/json" \
  --header "x-api-key: YOUR_API_KEY" \
  --data '{
    "name": "VIP",
    "color": "#3b82f6"
  }'

A duplicate name returns 409. Optional PATCH /api/tags/{id} renames or recolors. Delete is not exposed.

Assign tags on create

POST /api/clients accepts optional tag_ids (existing company tag IDs, same as dashboard create). Unknown IDs return 404 and the client is not created.

curl --request POST \
  --url "https://finsync.ar/api/clients" \
  --header "Content-Type: application/json" \
  --header "x-api-key: YOUR_API_KEY" \
  --data '{
    "name": "ACME Brokers",
    "tag_ids": [7]
  }'

The 201 body includes client_tags (join rows with a nested tag).

Replace tags on an existing client

PUT /api/clients/{id}/tags replaces the full set — the same add/remove diff the dashboard edit form uses. Send tag_ids: [] to clear labels.

curl --request PUT \
  --url "https://finsync.ar/api/clients/99/tags" \
  --header "Content-Type: application/json" \
  --header "x-api-key: YOUR_API_KEY" \
  --data '{
    "tag_ids": [7, 8]
  }'

Verify after assign

GET /api/clients and GET /api/clients/{id} already embed client_tags.

Cheque tags (same catalog)

Cheques reuse the same company Tag rows via a ChequeTag join (not a second vocabulary). Dashboard list embeds cheque_tags; filter with repeated tagIds (AND). Assign from cheque detail the same way clients add/remove labels. Portal cheques_portfolio scopes store filter + privacy on ExternalAccessScope.config (tag_mode, tag_ids, show_tags). Empty tag_ids = no filter (legacy grants). show_tags defaults to false: tags filter server-side and names are not sent to the third party.

GET /api/dashboard/cheques?tagIds=7&tagIds=8
GET /api/dashboard/cheques/{id}/tags
POST /api/dashboard/cheques/{id}/tags (tag_id)
DELETE /api/dashboard/cheques/{id}/tags/{tagId}

GET /api/tags
POST /api/tags
PATCH /api/tags/{id}
POST /api/clients (tag_ids)
PUT /api/clients/{id}/tags
GET /api/clients / GET /api/clients/{id} (client_tags)
Dashboard cheque tag routes above

​Client tags workflow

​List tags

​Create a tag

​Assign tags on create

​Replace tags on an existing client

​Verify after assign

​Cheque tags (same catalog)

​Related endpoints