---
title: "Find anagrafiche — customers, suppliers, people"
method: GET
path: "/api/v1/rest/anagrafiche/parties"
tags: ["Contacts"]
---

# Find anagrafiche — customers, suppliers, people

`GET /api/v1/rest/anagrafiche/parties`

## Request

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

Full-text search over the register of everybody the organisation deals with — customers, prospects, suppliers, agents, employees, consultants: company and person names, partita IVA, codice fiscale, email and PEC. Narrow by `kind` (a company or an individual), by `role` (one role key, e.g. `fornitore`), by the company a person works for (`parent_id`) or by owner. Each row carries the fiscal identifiers an Italian invoice needs and the roles the record holds. Newest first, paged with `cursor`; ask for a name, not for an id.

**Examples**

- Do we have Rossi in the register?
  `GET /api/v1/rest/anagrafiche/parties?query=rossi`
- List our suppliers
  `GET /api/v1/rest/anagrafiche/parties?role=fornitore&kind=company&limit=50`
- Find the company with VAT 12345678903
  `GET /api/v1/rest/anagrafiche/parties?query=12345678903`
- Who do we know at Rossi S.r.l.?
  `GET /api/v1/rest/anagrafiche/parties?parent_id=11111111-2222-4333-8444-555555555555`

## Query parameters

- `query` string
- `kind` 'company' | 'person'
- `role` string
- `lifecycle` 'lead' | 'prospect' | 'customer' | 'former'
- `parent_id` string, uuid
- `owner_user_id` string, uuid
- `limit` integer
- `cursor` string

## 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)