caret

Contacts

Overview

URL https://api.xero.com/api.xro/2.0/Contacts
Methods Supported POST, PUT, GET
Description Allows you to retrieve, add and update contacts in a Xero organisation
Allows you to attach files to a contact
Allows you to retrieve history
Allows you to add notes

Important Update

The business rules around contacts in Xero may be changing in the future and 'Contact Name' may no longer be a unique field.

We recommend all developers use ContactID to uniquely reference contacts in Xero and do not rely on ContactName as a way to reference contact data uniquely in Xero.

GET Contacts

The following elements are returned in the Contacts response

ContactID Xero identifier
ContactNumber This field is read only in the Xero UI, used to identify contacts in external systems. It is displayed as Contact Code in the Contacts UI in Xero.
AccountNumber A user defined account number. This can be updated via the API and the Xero UI
ContactStatus Current status of a contact - see contact status types
Name Full name of contact/organisation
FirstName First name of contact person
LastName Last name of contact person
EmailAddress Email address of contact person
SkypeUserName Skype user name of contact
BankAccountDetails Bank account number of contact
TaxNumber Tax number of contact - this is also known as the ABN (Australia), GST Number (New Zealand), VAT Number (UK) or Tax ID Number (US and global) in the Xero UI depending on which regionalized version of Xero you are using
AccountsReceivableTaxType Default tax type used for contact on AR invoices
AccountsPayableTaxType Default tax type used for contact on AP invoices
Addresses Store certain address types for a contact - see address types
Phones Store certain phone types for a contact - see phone types
IsSupplier true or false – Boolean that describes if a contact that has any AP invoices entered against them
IsCustomer true or false – Boolean that describes if a contact has any AR invoices entered against them
DefaultCurrency Default currency for raising invoices against contact
UpdatedDateUTC UTC timestamp of last update to contact
The following are only retrieved on GET requests for a single contact or when pagination is used
ContactPersons See contact persons. A contact can have a maximum of 5 ContactPersons
XeroNetworkKey Store XeroNetworkKey for contacts.
SalesDefaultAccountCode The default sales account code for contacts
PurchasesDefaultAccountCode The default purchases account code for contacts
SalesTrackingCategories The default sales tracking categories for contacts
PurchasesTrackingCategories The default purchases tracking categories for contacts
TrackingCategoryName The name of the Tracking Category assigned to the contact under SalesTrackingCategories and PurchasesTrackingCategories
TrackingOptionName The name of the Tracking Option assigned to the contact under SalesTrackingCategories and PurchasesTrackingCategories
PaymentTerms The default payment terms for the contact - see Payment Terms
ContactGroups Displays which contact groups a contact is included in
Website Website address for contact
BrandingTheme Default branding theme for contact - see Branding Themes
BatchPayments batch payment details for contact
Discount The default discount rate for the contact
Balances The raw AccountsReceivable(sales invoices) and AccountsPayable(bills) outstanding and overdue amounts, converted to base currency
HasAttachments A boolean to indicate if a contact has an attachment
Elements for ContactPerson
FirstName First name of person
LastName Last name of person
EmailAddress Email address of person
IncludeInEmails boolean to indicate whether contact should be included on emails with invoices etc.

Optional parameters for GET Contacts

Record filter You can specify an individual record by appending the value to the endpoint, i.e. GET https://.../Contacts/{identifier}
ContactID - The Xero identifier for a contact e.g. 297c2dc5-cc47-4afd-8ec8-74990b8761e9
ContactNumber - A custom identifier specified from another system e.g. a CRM system has a contact number of CUST100
Modified After The ModifiedAfter filter is actually an HTTP header: ' If-Modified-Since'. A UTC timestamp (yyyy-mm-ddThh:mm:ss) . Only contacts created or modified since this timestamp will be returned e.g. 2009-11-12T00:00:00 Note: changes to the Balances, IsCustomer or IsSupplier values will not trigger a contact to be returned with the Modified-After filter
IDs Filter by a comma-separated list of ContactIDs. Allows you to retrieve a specific set of contacts in a single call. See details.
Where Filter using the where parameter. We recommend you limit filtering to the optimised elements only.
order Order by any element returned ( see Order By )
page Up to 100 contacts will be returned per call when the page parameter is used e.g. page=1
includeArchived e.g. includeArchived=true - Contacts with a status of ARCHIVED will be included in the response

Paging contacts (recommended)

To utilise paging, append a page parameter to the URL e.g. ?page=1. If there are 100 records in the response you will need to check if there is any more data by fetching the next page e.g ?page=2 and continuing this process until no more results are returned.

By using paging all the elements in each individual contact are returned in the response which avoids the need to retrieve each individual contact to get all the details (GET Contacts without paging only returns a subset of elements)

Optimised use of the where filter

The most common filters have been optimised to ensure performance across organisations of all sizes. We recommend you restrict your filtering to the following optimised parameters.

When using individually or combined with the AND operator:
Name equals where=Name="ABC limited"
EmailAddress equals where=EmailAddress="email@example.com"
AccountNumber equals where=AccountNumber="ABC-100"

Retrieving multiple contacts by Id

The IDs query parameter allows you to filter based on a list of ContactIDs:

IDs ?IDs=220ddca8-3144-4085-9a88-2d72c5133734,88192a99-cbc5-4a66-bf1a-2f9fea2d36d0

Optimised ordering:

The following parameters are optimised for ordering:

  • ContactID
  • UpdatedDateUTC

The default order is UpdatedDateUTC ASC, ContactID ASC. Secondary ordering is applied by default using the ContactID. This ensures consistency across pages.

Example response for GET Contacts

GET https://api.xero.com/api.xro/2.0/Contacts
$contacts = $xero->load('Accounting\\Contact')->execute();
    
List<Contact> ContactList = client.getContacts();
    
πŸ“‡ = .πŸ€™

Example response for an individual contact

GET https://api.xero.com/api.xro/2.0/Contacts/bd2270c3-8706-4c11-9cfb-000b551c3f51
$contact = $xero->loadByGUID('Accounting\\Contact', "bd2270c3-8706-4c11-9cfb-000b551c3f51");
    
Contact contact = client.getContact("bd2270c3-8706-4c11-9cfb-000b551c3f51");
    
πŸ“‡ = .🀷("bd2270c3-8706-4c11-9cfb-000b551c3f51")

CIS Settings (UK)

If you are a UK organisation or contractor registered under Construction Industry Scheme, you can retrieve CIS settings for your contacts to identify if it is a CIS subcontractor and also get the CIS deduction rate.

If the contact has never been enabled as a CIS subcontractor then this endpoint will return a 404.

The following is returned for the CIS settings of a contact
CISEnabled true or false - Boolean that describes if the contact is a CIS Subcontractor
Rate CIS Deduction rate for the contact if he is a subcontractor. If the contact is not CISEnabled, then the rate is not returned

Example of retrieving CIS settings for a contact

GET https://api.xero.com/api.xro/2.0/Contacts/bd2270c3-8706-4c11-9cfb-000b551c3f51/CISSettings
/* not implemented Β―\_(ツ)_/Β― */
    
/* not implemented Β―\_(ツ)_/Β― */
    
/* not implemented Β―\_(ツ)_/Β― */

POST Contacts

Use this method to create or update one or more contact records

When you are updating a contact you don’t need to specify every element. If you exclude an element then the existing value will be preserved.

The following is required to create a contact
Name Full name of contact/organisation (max length = 255)
The following are optional when creating/updating contacts
ContactID Xero identifier
ContactNumber This can be updated via the API only i.e. This field is read only on the Xero contact screen, used to identify contacts in external systems (max length = 50). If the Contact Number is used, this is displayed as Contact Code in the Contacts UI in Xero.
AccountNumber A user defined account number. This can be updated via the API and the Xero UI (max length = 50)
ContactStatus Current status of a contact - see contact status types
FirstName First name of contact person (max length = 255)
LastName Last name of contact person (max length = 255)
EmailAddress Email address of contact person (umlauts not supported) (max length = 255)
SkypeUserName Skype user name of contact
ContactPersons See contact persons
BankAccountDetails Bank account number of contact
TaxNumber Tax number of contact - this is also known as the ABN (Australia), GST Number (New Zealand), VAT Number (UK) or Tax ID Number (US and global) in the Xero UI depending on which regionalized version of Xero you are using (max length = 50)
AccountsReceivableTaxType Default tax type used for contact on AR invoices
AccountsPayableTaxType Default tax type used for contact on AP invoices
Addresses Store certain address types for a contact - see address types
Phones Store certain phone types for a contact - see phone types
IsSupplier true or false – Boolean that describes if a contact that has any AP invoices entered against them. Cannot be set via PUT or POST - it is automatically set when an accounts payable invoice is generated against this contact.
IsCustomer true or false – Boolean that describes if a contact has any AR invoices entered against them. Cannot be set via PUT or POST - it is automatically set when an accounts receivable invoice is generated against this contact.
DefaultCurrency Default currency for raising invoices against contact
XeroNetworkKey Store XeroNetworkKey for contacts.
SalesDefaultAccountCode The default sales account code for contacts
PurchasesDefaultAccountCode The default purchases account code for contacts
SalesTrackingCategories The default sales tracking categories for contacts
PurchasesTrackingCategories The default purchases tracking categories for contacts
TrackingCategoryName The name of the Tracking Category assigned to the contact under SalesTrackingCategories and PurchasesTrackingCategories
TrackingOptionName The name of the Tracking Option assigned to the contact under SalesTrackingCategories and PurchasesTrackingCategories
PaymentTerms The default payment terms for the contact - see Payment Terms

Example of minimum elements required to add a new contact

POST https://api.xero.com/api.xro/2.0/Contacts
$contact = new \XeroPHP\Models\Accounting\Contact($xero);
$contact->setName("ABC Limited");
$contact->save();
    
ArrayOfContact arrayContact = new ArrayOfContact();
Contact contact = new Contact();
contact.setName("ABC Limited");
arrayContact.getContact().add(contact);
List<Contact> newContact = client.createContact(arrayContact.getContact());
    
πŸ“‡ = .πŸ’‘
πŸ“‡.πŸ“› = "ABC Limited"

Example of minimum elements required to add many contacts

POST https://api.xero.com/api.xro/2.0/Contacts
/* not implemented Β―\_(ツ)_/Β― */
    
/* not implemented Β―\_(ツ)_/Β― */
    
/* not implemented Β―\_(ツ)_/Β― */
    
/* not implemented Β―\_(ツ)_/Β― */

Example of creating a contact record with additional contact people

POST https://api.xero.com/api.xro/2.0/Contacts
$person = new \XeroPHP\Models\Accounting\Contact\ContactPerson($xero);
$person->setFirstName("John")
    ->setLastName("Smith")
    ->setEmailAddress("john.smith@24locks.com")
    ->setIncludeInEmail(true);

$contact = new \XeroPHP\Models\Accounting\Contact($xero);
$contact->setName('24 locks')
    ->setFirstName("Ben")
    ->setLastName("Bowden")
    ->setEmailAddress("ben.bowden@24locks.com")
    ->addContactPerson($person);

$contact->save();
    
ArrayOfContactPerson arrayOfContactPerson = new ArrayOfContactPerson();
ContactPerson person = new ContactPerson();
person.setFirstName("John");
person.setLastName("Smith");
person.setEmailAddress("john.smith@24locks.com");
arrayOfContactPerson.getContactPerson().add(person);

ArrayOfContact arrayContact = new ArrayOfContact();
Contact contact = new Contact();
contact.setName("24 locks");
contact.setFirstName("John");
contact.setLastName("Bowden");
contact.setEmailAddress("ben.bowden@24locks.com");
contact.setContactPersons(arrayOfContactPerson);

arrayContact.getContact().add(contact);
List<Contact> newContact = client.createContact(arrayContact.getContact());

Example of updating a contact

POST https://api.xero.com/api.xro/2.0/Contacts/eaa28f49-6028-4b6e-bb12-d8f6278073fc
$contact = $xero->loadByGUID('Accounting\\Contact', "eaa28f49-6028-4b6e-bb12-d8f6278073fc");

$address = new \XeroPHP\Models\Accounting\Address($xero);
$address->setAddressType(\XeroPHP\Models\Accounting\Address::ADDRESS_TYPE_POBOX)
    ->setAddressLine1("P O Box 123")
    ->setCity("Wellington")
    ->setPostalCode("6011");

$contact->setName("ABC Limited")
    ->setFirstName("John")
    ->setLastName("Smith")
    ->setEmailAddress("john.smith@gmail.com")
    ->setContactNumber('ID001')
    ->setBankAccountDetail('01-0123-0123456-00')
    ->setTaxNumber('12-345-678')
    ->setAccountsReceivableTaxType('OUTPUT')
    ->setAccountsPayableTaxType('INPUT')
    ->setDefaultCurrency('NZD')
    ->addAddress($address);
$contact->save();
    
Contact contact = client.getContact("eaa28f49-6028-4b6e-bb12-d8f6278073fc");

ArrayOfAddress arrayOfAddress = new ArrayOfAddress();
Address address = new Address();
address.setAddressType(AddressType.POBOX);
address.setAddressLine1("P O Box 123");
address.setCity("Wellington");
address.setPostalCode("6011");
arrayOfAddress.getAddress().add(address);

ArrayOfContact arrayContact = new ArrayOfContact();
contact.setName("ABC Limited");
contact.setFirstName("John");
contact.setLastName("Smith");
contact.setEmailAddress("john.smith@gmail.com");
contact.setContactNumber("ID001");
contact.setBankAccountDetails("01-0123-0123456-00");
contact.setTaxNumber("12-345-678");
contact.setAccountsReceivableTaxType("OUTPUT");
contact.setAccountsPayableTaxType("INPUT");
contact.setDefaultCurrency(CurrencyCode.NZD);
contact.setAddresses(arrayOfAddress);

arrayContact.getContact().add(contact);
List<Contact> newContact = client.updateContact(arrayContact.getContact());

Example of archiving a contact

POST https://api.xero.com/api.xro/2.0/Contacts/9b9ba7f9-7eab-465d-8d10-d74d4f8a9ab7
$contact = $xero->loadByGUID('Accounting\\Contact', "9b9ba7f9-7eab-465d-8d10-d74d4f8a9ab7");
$contact->setContactStatus(\XeroPHP\Models\Accounting\Contact::CONTACT_STATUS_ARCHIVED);
$contact->save();
    
Contact contact = client.getContact("9b9ba7f9-7eab-465d-8d10-d74d4f8a9ab7");

ArrayOfContact arrayContact = new ArrayOfContact();
contact.setContactStatus("ARCHIVED");

arrayContact.getContact().add(contact);
List<Contact> newContact = client.updateContact(arrayContact.getContact());
    

πŸ“‡ = .🀷("9b9ba7f9-7eab-465d-8d10-d74d4f8a9ab7")
πŸ“‡.πŸ”₯

Uploading an Attachment

You can upload up to 10 attachments(each up to 3mb in size) per contact, once the contact has been created in Xero. To do this you'll need to know the ID of the contact which you'll use to construct the URL when POST/PUTing a byte stream containing the attachment file. e.g. https://api.xero.com/api.xro/2.0/Contacts/ f0ec0d8c-6fce-4330-bb3b-8306278c6fd8/Attachments/ image.png. See the Attachments page for more details.

Example of uploading an attachment to a contact

POST https://api.xero.com/api.xro/2.0/Contacts/f0ec0d8c-4330-bb3b-83062c6fd8/Attachments/Image002932.png
Headers:
Authorization: OAuth...
Content Type: image/png
Content-Length: 10293
Body:
{RAW-IMAGE-CONTENT}

PUT Contacts

Use this method to create one or more contact records. This method works very similar to POST Contacts but if an existing contact matches your ContactName or ContactNumber then you will receive an error.

Webhooks

You can create a subscription to get contact events. Create and update events are available (incuding when contacts are archived). See the Webhooks page for more details.

Retrieving History

View a summary of the actions made by all users to the contact. See the History and Notes page for more details.

Example of retrieving a contact's history

GET https://api.xero.com/api.xro/2.0/Contacts/{Guid}/History

Add Notes to a Contact

Add a note which will appear in the history against a contact. See the History and Notes page for more details.

Example of creating a note against a contact

PUT https://api.xero.com/api.xro/2.0/Contacts/{Guid}/History