> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finsync.ar/llms.txt
> Use this file to discover all available pages before exploring further.

# Client tags workflow

> Create company labels and assign them to clients or cheques the same way Configuración > Catálogo > Etiquetas and the client/cheque forms do.

# 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](/docs/workflows/cost-centers) for that path.

## List tags

```bash theme={null}
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`.

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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}`

## Related endpoints

* `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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.