Xero Contacts Management
Overview
Contacts are the foundational entity in Xero, representing customers (clients you invoice), suppliers (vendors you pay), or both. Every invoice, payment, credit note, and bank transaction is linked to a contact. For MSPs, contacts typically represent managed services clients, hardware vendors, software suppliers, and subcontractors.
Core Concepts
Contact Types
Xero contacts can be customers, suppliers, or both. The type is determined by usage rather than a fixed field:
| Role | Description | MSP Example | |------|-------------|-------------| | Customer | Contacts you create sales invoices (ACCREC) for | Managed services clients | | Supplier | Contacts you receive bills (ACCPAY) from | Software vendors, ISPs | | Customer & Supplier | Both roles | Partner MSPs, distributors |
Contact Status
| Status | Description | |--------|-------------| | ACTIVE | Active contact (default) | | ARCHIVED | Archived contact (hidden from lists) | | GDPR_REQUEST | GDPR deletion requested |
Contact Groups
Contacts can be organized into groups for reporting and filtering:
| Group | MSP Use Case | |-------|-------------| | Managed Services | Clients on monthly contracts | | Break-Fix | Ad-hoc support clients | | Vendors | Hardware and software suppliers | | Partners | Co-managed or referral partners |
Field Reference
Core Fields
| Field | Type | Required | Description | |-------|------|----------|-------------| | ContactID | string (UUID) | System | Auto-generated unique identifier | | Name | string | Yes | Contact/company name (must be unique) | | ContactNumber | string | No | Your reference number for this contact | | AccountNumber | string | No | Account number in your system | | ContactStatus | string | No | ACTIVE, ARCHIVED, or GDPR_REQUEST | | EmailAddress | string | No | Primary email address | | FirstName | string | No | First name (for individual contacts) | | LastName | string | No | Last name (for individual contacts) | | BankAccountDetails | string | No | Bank account information | | TaxNumber | string | No | Tax identification number | | AccountsReceivableTaxType | string | No | Default tax type for sales | | AccountsPayableTaxType | string | No | Default tax type for purchases | | DefaultCurrency | string | No | Default currency code (e.g., USD, AUD) | | IsSupplier | boolean | Read-only | Has supplier invoices | | IsCustomer | boolean | Read-only | Has customer invoices |
Address Fields
Contacts support two address types: POBOX (mailing) and STREET (physical):
| Field | Type | Description | |-------|------|-------------| | AddressType | string | POBOX or STREET | | AddressLine1 | string | Street address line 1 | | AddressLine2 | string | Street address line 2 | | AddressLine3 | string | Street address line 3 | | AddressLine4 | string | Street address line 4 | | City | string | City | | Region | string | State/province/region | | PostalCode | string | Postal/zip code | | Country | string | Country | | AttentionTo | string | Attention to name |
Phone Fields
Contacts support four phone types: DEFAULT, DDI, MOBILE, FAX:
| Field | Type | Description | |-------|------|-------------| | PhoneType | string | DEFAULT, DDI, MOBILE, or FAX | | PhoneNumber | string | Phone number | | PhoneAreaCode | string | Area code | | PhoneCountryCode | string | Country code |
Financial Summary Fields (Read-Only)
| Field | Type | Description | |-------|------|-------------| | Balances.AccountsReceivable.Outstanding | decimal | Total outstanding AR | | Balances.AccountsReceivable.Overdue | decimal | Total overdue AR | | Balances.AccountsPayable.Outstanding | decimal | Total outstanding AP | | Balances.AccountsPayable.Overdue | decimal | Total overdue AP | | UpdatedDateUTC | datetime | Last modification timestamp |
API Patterns
List Contacts
curl -s -X GET "https://api.xero.com/api.xro/2.0/Contacts" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "xero-tenant-id: ${XERO_TENANT_ID}" \
-H "Accept: application/json"With Filters:
# Search by name (partial match)
curl -s -X GET "https://api.xero.com/api.xro/2.0/Contacts?where=Name.Contains(%22Acme%22)" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "xero-tenant-id: ${XERO_TENANT_ID}" \
-H "Accept: application/json"
# Active customers only
curl -s -X GET "https://api.xero.com/api.xro/2.0/Contacts?where=ContactStatus==%22ACTIVE%22&&IsCustomer==true" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "xero-tenant-id: ${XERO_TENANT_ID}" \
-H "Accept: application/json"
# With pagination
curl -s -X GET "https://api.xero.com/api.xro/2.0/Contacts?page=1" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "xero-tenant-id: ${XERO_TENANT_ID}" \
-H "Accept: application/json"Get Single Contact
curl -s -X GET "https://api.xero.com/api.xro/2.0/Contacts/${CONTACT_ID}" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "xero-tenant-id: ${XERO_TENANT_ID}" \
-H "Accept: application/json"Create Contact
curl -s -X POST "https://api.xero.com/api.xro/2.0/Contacts" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "xero-tenant-id: ${XERO_TENANT_ID}" \
-H "Content-Type: application/json" \
-d '{
"Name": "Acme Corp",
"ContactNumber": "MSP-001",
"AccountNumber": "ACME001",
"EmailAddress": "billing@acme.com",
"Addresses": [
{
"AddressType": "STREET",
"AddressLine1": "123 Main Street",
"City": "Springfield",
"Region": "IL",
"PostalCode": "62704",
"Country": "US"
},
{
"AddressType": "POBOX",
"AddressLine1": "PO Box 456",
"City": "Springfield",
"Region": "IL",
"PostalCode": "62704",
"Country": "US"
}
],
"Phones": [
{
"PhoneType": "DEFAULT",
"PhoneNumber": "555-0123",
"PhoneAreaCode": "217"
}
],
"DefaultCurrency": "USD"
}'Update Contact
curl -s -X POST "https://api.xero.com/api.xro/2.0/Contacts/${CONTACT_ID}" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "xero-tenant-id: ${XERO_TENANT_ID}" \
-H "Content-Type: application/json" \
-d '{
"ContactID": "'${CONTACT_ID}'",
"EmailAddress": "newemail@acme.com",
"Phones": [
{
"PhoneType": "DEFAULT",
"PhoneNumber": "555-9999",
"PhoneAreaCode": "217"
}
]
}'Archive Contact
curl -s -X POST "https://api.xero.com/api.xro/2.0/Contacts/${CONTACT_ID}" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "xero-tenant-id: ${XERO_TENANT_ID}" \
-H "Content-Type: application/json" \
-d '{
"ContactID": "'${CONTACT_ID}'",
"ContactStatus": "ARCHIVED"
}'Search Contacts
# Search by name
curl -s -X GET "https://api.xero.com/api.xro/2.0/Contacts?where=Name.StartsWith(%22Acme%22)" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "xero-tenant-id: ${XERO_TENANT_ID}" \
-H "Accept: application/json"
# Search by email
curl -s -X GET "https://api.xero.com/api.xro/2.0/Contacts?where=EmailAddress==%22billing@acme.com%22" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "xero-tenant-id: ${XERO_TENANT_ID}" \
-H "Accept: application/json"
# Search by account number
curl -s -X GET "https://api.xero.com/api.xro/2.0/Contacts?where=AccountNumber==%22ACME001%22" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "xero-tenant-id: ${XERO_TENANT_ID}" \
-H "Accept: application/json"Common Workflows
MSP Client Onboarding
- Create contact with company details and billing address
- Set account number using your PSA or internal reference
- Add to contact group (e.g., "Managed Services")
- Set default currency if multi-currency
- Create first invoice for onboarding or first month
async