Canonical contacts API
Manage one identity with cumulative customer, supplier and lead roles. The canonical API now covers bulk creation and archival, direct identifier lookup, AEAT census verification, statistics, activity and imports.
The public API now exposes the complete contacts surface. One contact stores the shared identity and can hold customer, supplier and lead roles at the same time. This avoids duplicated identities while preserving separate sales and purchase defaults.
Public contact operations
| Compatibility workflow | Canonical contacts workflow |
|---|---|
| List clients or suppliers | GET /v1/contacts with the roles filter |
| Search clients or suppliers | GET /v1/contacts/search with the roles filter |
| Find by tax ID or external ID | POST /v1/contacts/find-by-tax-id or POST /v1/contacts/find-by-external-id |
| Client or supplier statistics | GET /v1/contacts/stats, with unique identities and counters per role |
| Client or supplier activity | GET /v1/contacts/{contact}/activities, filterable by direction and category |
| Download an import template | GET /v1/contacts/import/template |
| Create several records | POST /v1/contacts/bulk-create, with optional dry_run |
| Delete several records | POST /v1/contacts/bulk-delete (deletes) or POST /v1/contacts/bulk/archive (archives) |
| Verify a Spanish identity with AEAT | POST /v1/contacts/census-verification |
| Activate or deactivate suppliers | PUT /v1/contacts/{contact}/roles/{role}/status or POST /v1/contacts/bulk/status |
/v1/contacts is the only public resource for customers, suppliers and fiscal leads. The pre-launch /v1/clients and /v1/suppliers surfaces were removed before external integrations depended on them.
POST /v1/contacts/import accepts CSV, TXT, XLSX or XLS files up to 10 MB and at most three distinct target_roles; use the preview endpoint first and expect 202 when a large import is queued. The create operation ships a ready-to-use example of a company with customer and supplier roles.
Scopes
Reads use contacts:read, mutations use contacts:write, and removals — archiving, deletion and role removal — use contacts:delete. The same contact tools are available through MCP for JSON operations; the CSV template remains a REST download.