| 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 |
Important Update: May 2015
The business rules around contacts in Xero will be changing in the future and 'Contact Name' may no longer be a unique field.
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 |
| TrackingCategoryOption | 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, not 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. e.g. GET https://.../Contacts?IDs=bd2270c3-8706-4c11-9cfb-000b551c3f51,eaa28f49-6028-4b6e-bb12-d8f6278073fc |
| Where | Filter by an any element (see Filters) |
| order | Order by any element returned (see Order By) |
| page | e.g. page=1 - Up to 100 contacts will be returned in a single API call. |
| includeArchived | e.g. includeArchived=true - Contacts with a status of ARCHIVED will be included in the response |
Example response for GET Contacts
GET https://api.xero.com/api.xro/2.0/Contacts
<Contacts>
<Contact>
<ContactID>bd2270c3-8706-4c11-9cfb-000b551c3f51</ContactID>
<ContactStatus>ACTIVE</ContactStatus>
<Name>ABC Limited</Name>
<FirstName>Andrea</FirstName>
<LastName>Dutchess</LastName>
<EmailAddress>a.dutchess@abclimited.com</EmailAddress>
<SkypeUserName>skype.dutchess@abclimited.com</SkypeUserName>
<BankAccountDetails>45465844</BankAccountDetails>
<TaxNumber>415465456454</TaxNumber>
<AccountsReceivableTaxType>INPUT2</AccountsReceivableTaxType>
<AccountsPayableTaxType>OUTPUT2</AccountsPayableTaxType>
<Addresses>
<Address>
<AddressType>POBOX</AddressType>
<AddressLine1>P O Box 123</AddressLine1>
<City>Wellington</City>
<PostalCode>6011</PostalCode>
<AttentionTo>Andrea</AttentionTo>
</Address>
<Address>
<AddressType>STREET</AddressType>
</Address>
</Addresses>
<Phones>
<Phone>
<PhoneType>DEFAULT</PhoneType>
<PhoneNumber>1111111</PhoneNumber>
<PhoneAreaCode>04</PhoneAreaCode>
<PhoneCountryCode>64</PhoneCountryCode>
</Phone>
<Phone>
<PhoneType>FAX</PhoneType>
</Phone>
<Phone>
<PhoneType>MOBILE</PhoneType>
</Phone>
<Phone>
<PhoneType>DDI</PhoneType>
</Phone>
</Phones>
<UpdatedDateUTC>2009-05-14T01:44:26.747</UpdatedDateUTC>
<IsSupplier>false</IsSupplier>
<IsCustomer>true</IsCustomer>
<DefaultCurrency>NZD</DefaultCurrency>
</Contact>
</Contacts>
Example response for an individual contact
GET https://api.xero.com/api.xro/2.0/bd2270c3-8706-4c11-9cfb-000b551c3f51
<Contacts>
<Contact>
<ContactID>bd2270c3-8706-4c11-9cfb-000b551c3f51</ContactID>
<ContactStatus>ACTIVE</ContactStatus>
<Name>ABC Limited</Name>
<FirstName>Andrea</FirstName>
<LastName>Dutchess</LastName>
<EmailAddress>a.dutchess@abclimited.com</EmailAddress>
<SkypeUserName>skype.dutchess@abclimited.com</SkypeUserName>
<BankAccountDetails>454611121</BankAccountDetails>
<TaxNumber>415465456454</TaxNumber>
<AccountsReceivableTaxType>INPUT2</AccountsReceivableTaxType>
<AccountsPayableTaxType>OUTPUT2</AccountsPayableTaxType>
<Addresses>
<Address>
<AddressType>POBOX</AddressType>
<AddressLine1>P O Box 123</AddressLine1>
<City>Wellington</City>
<PostalCode>6011</PostalCode>
<AttentionTo>Andrea</AttentionTo>
</Address>
<Address>
<AddressType>STREET</AddressType>
</Address>
</Addresses>
<Phones>
<Phone>
<PhoneType>DEFAULT</PhoneType>
<PhoneNumber>1111111</PhoneNumber>
<PhoneAreaCode>04</PhoneAreaCode>
<PhoneCountryCode>64</PhoneCountryCode>
</Phone>
<Phone>
<PhoneType>FAX</PhoneType>
</Phone>
<Phone>
<PhoneType>MOBILE</PhoneType>
</Phone>
<Phone>
<PhoneType>DDI</PhoneType>
</Phone>
</Phones>
<UpdatedDateUTC>2009-05-14T01:44:26.747</UpdatedDateUTC>
<IsSupplier>false</IsSupplier>
<IsCustomer>true</IsCustomer>
<DefaultCurrency>NZD</DefaultCurrency>
<PurchasesDefaultAccountCode>300</PurchasesDefaultAccountCode>
<SalesDefaultAccountCode>200</SalesDefaultAccountCode>
<SalesTrackingCategories>
<SalesTrackingCategory>
<TrackingCategoryName>Region</TrackingCategoryName>
<TrackingOptionName>Eastside</TrackingOptionName>
</SalesTrackingCategory>
</SalesTrackingCategories>
<PurchasesTrackingCategories>
<PurchasesTrackingCategory>
<TrackingCategoryName>Region</TrackingCategoryName>
<TrackingOptionName>North</TrackingOptionName>
</PurchasesTrackingCategory>
</PurchasesTrackingCategories>
<Balances>
<AccountsReceivable>
<Outstanding>849.50</Outstanding>
<Overdue>910.00</Overdue>
</AccountsReceivable>
<AccountsPayable>
<Outstanding>0.00</Outstanding>
<Overdue>0.00</Overdue>
</AccountsPayable>
</Balances>
<BatchPayments>
<BankAccountNumber>123456</BankAccountNumber>
<BankAccountName>bank acccount</BankAccountName>
<Details>details</Details>
</BatchPayments>
<PaymentTerms>
<Bills>
<Day>4</Day>
<Type>OFFOLLOWINGMONTH</Type>
</Bills>
<Sales>
<Day>2</Day>
<Type>OFFOLLOWINGMONTH</Type>
</Sales>
</PaymentTerms>
</Contact>
</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 |
| TrackingCategoryOption | 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> <Name>ABC Limited</Name> </Contact>
Example of minimum elements required to add many contacts
POST https://api.xero.com/api.xro/2.0/Contacts
<Contacts>
<Contact>
<Name>ABC Limited</Name>
</Contact>
<Contact>
<Name>DEF Limited</Name>
</Contact>
</Contacts>
Example of creating a contact record with additional contact people
POST https://api.xero.com/api.xro/2.0/Contacts
<Contacts>
<Contact>
<Name>24 locks</Name>
<FirstName>Ben</FirstName>
<LastName>Bowden</LastName>
<EmailAddress>ben.bowden@24locks.com</EmailAddress>
<ContactPersons>
<ContactPerson>
<FirstName>John</FirstName>
<LastName>Smith</LastName>
<EmailAddress>john.smith@24locks.com</EmailAddress>
<IncludeInEmails>true</IncludeInEmails>
</ContactPerson>
</ContactPersons>
</Contact>
</Contacts>
Example of updating a contact
POST https://api.xero.com/api.xro/2.0/Contacts/eaa28f49-6028-4b6e-bb12-d8f6278073fc
<Contact>
<ContactID>eaa28f49-6028-4b6e-bb12-d8f6278073fc</ContactID>
<ContactNumber>ID001</ContactNumber>
<Name>ABC Limited</Name>
<FirstName>John</FirstName>
<LastName>Smith</LastName>
<EmailAddress>john.smith@gmail.com</EmailAddress>
<Addresses>
<Address>
<AddressType>POBOX</AddressType>
<AddressLine1>P O Box 123</AddressLine1>
<City>Wellington</City>
<PostalCode>6011</PostalCode>
</Address>
</Addresses>
<BankAccountDetails>01-0123-0123456-00</BankAccountDetails>
<TaxNumber>12-345-678</TaxNumber>
<AccountsReceivableTaxType>OUTPUT</AccountsReceivableTaxType>
<AccountsPayableTaxType>INPUT</AccountsPayableTaxType>
<DefaultCurrency>NZD</DefaultCurrency>
</Contact>
Example of archiving a contact
POST https://api.xero.com/api.xro/2.0/Contacts/9b9ba7f9-7eab-465d-8d10-d74d4f8a9ab7
<Contact> <ContactID>9b9ba7f9-7eab-465d-8d10-d74d4f8a9ab7</ContactID> <ContactStatus>ARCHIVED</ContactStatus> </Contact>
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}