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

Xero Contacts

Como adicionar

Cole no README do seu repo

Skills relacionadas

pdf

pptx

docx

canvas-design

Receba novas skills de Documentos toda segunda