| 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: 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 |
| 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, 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
Example response for an individual contact
GET https://api.xero.com/api.xro/2.0/bd2270c3-8706-4c11-9cfb-000b551c3f51
If you are a UK organisation or contractor registered under Construction Industry Scheme, you can retrive CIS settings for your contacts to identify if it is a CIS subcontractor and also get the CIS deduction rate.
To retrieve the CIS settings, the GET request is similar retrieving an individual contact with ContactID but you need to additionally specify CISettings in your url . Refer to the request and response sample.
| 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
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
Example of minimum elements required to add many contacts
POST https://api.xero.com/api.xro/2.0/Contacts
Example of creating a contact record with additional contact people
POST https://api.xero.com/api.xro/2.0/Contacts
Example of updating a contact
POST https://api.xero.com/api.xro/2.0/Contacts/eaa28f49-6028-4b6e-bb12-d8f6278073fc
Example of archiving a contact
POST https://api.xero.com/api.xro/2.0/Contacts/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 apear 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