Contacts
| 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 |
XML Elements for 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 |
| ContactStatus | Current status of a contact – see contact status types |
| Name | Name of contact organisation (max length = 500) |
| 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 = 500) |
| 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 (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 |
| UpdatedDateUTC | UTC timestamp of last update to contact |
| ContactGroups | Displays which contact groups a contact is included in |
| 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 |
POST Contacts
Use this method to create or update one or more contact records.
Example of minimum elements required to add a new contact
<Contact> <Name>ABC Limited</Name> </Contact>
Example of minimum elements required to add many contacts
<Contacts>
<Contact>
<Name>ABC Limited</Name>
</Contact>
<Contact>
<Name>DEF Limited</Name>
</Contact>
</Contacts>
A contact can be uniquely identified by either of the following elements
| ContactID | This is a read only identifier which is generated by Xero when a contact is created either in the application or via the API. i.e. You cannot specify this element when creating a new contact |
| ContactNumber | This can be updated via the API only i.e. This field is read only on the Xero contact screen |
| Name | This can be updated via API or in the contact record in Xero |
Example of updating a contact
<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>
When you are updating a contact you don’t need to specify every element. If you exclude an element then the existing value of that field will be preserved. For example in the example above the existing phone numbers will be preserved as they were not specified.
If you are updating contacts to match those of another system we recommend that you try and update as many fields as possible.
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.
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 |
| Where | Filter by an any element (see Filters) |
| order | Order by any element returned (see Order By) |
Example response for GET 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>skype.dutchess@abclimited.com</BankAccountDetails>
<TaxNumber>skype.dutchess@abclimited.com</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>