---
title: "Check an Excel file before importing it"
method: GET
path: "/api/v1/rest/anagrafiche/imports/{document_id}/analysis"
tags: ["Contacts"]
---

# Check an Excel file before importing it

`GET /api/v1/rest/anagrafiche/imports/{document_id}/analysis`

## Request

- Base URL: `https://api.custodo.ai`
- URL: `https://api.custodo.ai/api/v1/rest/anagrafiche/imports/{document_id}/analysis`
- Auth: HTTP bearer

Reads an Excel workbook (.xlsx) in the Archivio — a file attached to the chat is one — and reports what importing it into Anagrafiche WOULD do, writing nothing: the tab and header row found, how each column was read (`read_as`, null = not read), how many anagrafiche would be created, updated or left alone, and every row with a problem (Excel row, column, why). ANY list works: map the file’s own headers with `columns` and give every row a role with `roles`. Existing anagrafiche are matched by codice fiscale, else partita IVA, else name, and updated, never duplicated. Employee lists work too (Nome/Cognome, matricola, Responsabile, dates; the Custodo login is bound by e-mail). Repeat with a better mapping until the report is clean, then call anagrafiche_import_spreadsheet with EXACTLY the same arguments. It reads the file itself — no documents_get_content first. At most 2000 rows and 8 MB.

**Examples**

- Update the contacts with the customer list I attached
  `GET /api/v1/rest/anagrafiche/imports/66666666-7777-4888-8999-aaaaaaaaaaaa/analysis?columns=%7B%22Cliente%22%3A%22name%22%2C%22Nazionalit%C3%A0%22%3A%22ignore%22%2C%22Classificazioni%22%3A%22tags%22%7D&roles=cliente`
- Add only the new suppliers from this list and leave the ones I have alone
  `GET /api/v1/rest/anagrafiche/imports/66666666-7777-4888-8999-aaaaaaaaaaaa/analysis?roles=fornitore&existing=skip`
- Load our employees from this HR list, with their managers
  `GET /api/v1/rest/anagrafiche/imports/66666666-7777-4888-8999-aaaaaaaaaaaa/analysis?columns=%7B%22Matr%22%3A%22employee_code%22%2C%22Resp.+diretto%22%3A%22manager%22%2C%22Assunto+il%22%3A%22hired_on%22%2C%22Reparto%22%3A%22custom.reparto%22%7D&roles=dipendente`

## Path parameters

- `document_id` string, uuid, required

## Query parameters

- `roles` string[]
- `existing` 'update' | 'skip'
- `skip_invalid_rows` boolean
- `sheet` 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.
- `404`: Nothing with that id in this organisation.
- `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)