---
title: "List the roles an anagrafica can hold"
method: GET
path: "/api/v1/rest/anagrafiche/roles"
tags: ["Contacts"]
---

# List the roles an anagrafica can hold

`GET /api/v1/rest/anagrafiche/roles`

## Request

- Base URL: `https://api.custodo.ai`
- URL: `https://api.custodo.ai/api/v1/rest/anagrafiche/roles`
- Auth: HTTP bearer

The organisation’s roles catalogue: the nine built-in roles (cliente, potenziale_cliente, ex_cliente, fornitore, agente, dipendente, collaboratore, consulente, firmatario) and the organisation’s own, each with how many records the caller can see holding it. The keys are what `roles` takes on anagrafiche_create_party and anagrafiche_update_party and what `role` filters anagrafiche_search_parties by. `label` is null for a built-in the organisation did not rename — its key IS its Italian name. `uses` says what the OTHER modules pick the role for (crm_customer, firme_signer, raccolta_recipient, documents_party, staff, ordini_customer): their pickers open on the roles carrying the use, and the person filling the form can still widen the list to every record — except staff, which is also a rule: only a person holding a role that carries it can have an employment (login, Responsabile, matricola, dates). `access` says what the CALLER may do with records holding the role (read, write, delete) — an administrator decides that per member; a role with read false is one whose records the caller cannot see. An `archived` role is no longer offered for new records, and existing holders keep it. Changing the catalogue is a settings act and has no tool.

**Examples**

- What kinds of contacts do we keep?
  `GET /api/v1/rest/anagrafiche/roles`
- Including the roles we stopped using
  `GET /api/v1/rest/anagrafiche/roles?include_archived=true`

## Query parameters

- `include_archived` boolean

## Headers

- `X-Tenant-Id` string, uuid

## Response `200`

Done. `data` is the tool’s own answer.

- RestResult
  - `ok` true, required
  - `data` unknown, required

## Other responses

- `400`: The arguments did not validate: `error.message` names the field, what it expects and what arrived.
- `401`: No API key, or one that is malformed, unknown, revoked or expired.
- `403`: The call never ran: the module is off for this organisation, the credential lacks the permission or the module, the tier does not cover it, or the tool is destructive and the key was not minted for that.
- `422`: The tool ran and refused, in a sentence of its own (`TOOL_REFUSED`): the message says what to change. Retrying the same call will not help.
- `429`: The API key has spent its minute, or its day. Every request a key makes counts. See `Retry-After`.

---

[API](https://skmtc.dev/custodo/apis/custodo-integrazioni.md) · [All operations](https://skmtc.dev/custodo/apis/custodo-integrazioni/llms.txt) · [OpenAPI document](https://skmtc.dev/custodo/apis/custodo-integrazioni/revisions/16d336d3ec2a?raw)