POST /api.xro/2.0/Contacts with a JSON or XML body containing at least 'Name'; for a supplier or customer set 'IsSupplier' or 'IsCustomer' to true
Include 'EmailAddress', 'Phones', and 'Addresses' arrays for full contact records; validate that phone and address types match Xero's enumerated values
GET /api.xro/2.0/Contacts?where=Name.StartsWith("Acme") to search by name, or use ?IDs=guid1,guid2 to fetch specific contacts
To update a contact, POST to /api.xro/2.0/Contacts/{ContactID} with the modified fields; Xero uses POST for both create and update on this endpoint
Attach a ContactGroup to categorise contacts: POST /api.xro/2.0/ContactGroups/{ContactGroupID}/Contacts with a Contacts array
Use If-Modified-Since header on GET to retrieve only contacts changed since a given datetime for incremental sync
Known gotchas
Xero does not enforce unique contact names by default; duplicate names are allowed and can cause confusion — consider adding an external reference via 'ExternalLink' or a custom field
Archived contacts are returned in GET results unless you filter with ?includeArchived=false; failing to filter can cause stale data to appear in dropdowns
Batch contact creation (multiple contacts in one POST body) is supported but errors for individual contacts in the batch are reported inline rather than as an HTTP error — always check per-item validation errors
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp