| 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.
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. |
| 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 |
| summaryOnly | When set to true, this returns lightweight fields, excluding computation-heavy fields from the response, making the API calls quick and efficient. More details here. |
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" | |
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 |
The following parameters are optimised for ordering:
The default order is UpdatedDateUTC ASC, ContactID ASC. Secondary ordering is applied by default using the ContactID. This ensures consistency across pages.
Use summaryOnly=true in GET Contacts endpoint to retrieve a smaller version of the response object. This returns only lightweight fields, excluding computation-heavy fields from the response, making the API calls quick and efficient. The following fields will be excluded from the response:
https://api.xero.com/api.xro/2.0/contacts?summaryOnly=TrueThe summaryOnly parameter works with other filters, but not when filtering on the excluded fields. And when this parameter is used, pagination is enforced by default.
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")
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 Β―\_(γ)_/Β― */
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")
π.π₯
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}
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.
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 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