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

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 (max length = 50)
AccountNumber This can be updated via the API and the Xero UI (max length = 50)
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
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
UpdatedDateUTC UTC timestamp of last update to contact
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
The following are optional elements for PUT/POST requests and only retrieved on GET requests for a specific contact or when pagination is used
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
The following are only returned on a GET request for a specific contact or using pagination
ContactGroups Displays which contact groups a contact is included in
Website Website address for contact (read only)
BrandingTheme Default branding theme for contact (read only) – see Branding Themes
BatchPayments batch payment details for contact (read only)
Discount The default discount rate for the contact (read only)
Balances The AccountsReceivable(sales invoices) and AccountsPayable(bills) outstanding and overdue amounts (read only)
PaymentTerms The default payment terms for the contact (read only) – see Payment Terms
HasAttachments A boolean to indicate if a contact has an attachment


XML Elements for ContactPerson

A maximum of five contact persons are allowed per contact.

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.

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>

Example of creating a contact record with additional contact people

<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>

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.

Example of archiving a contact

  <Contact>
    <ContactID>9b9ba7f9-7eab-465d-8d10-d74d4f8a9ab7</ContactID>
    <ContactStatus>ARCHIVED</ContactStatus>
  </Contact>

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.

e.g.

POST /api.xro/2.0/Contacts/f0ec0d8c-4330-bb3b-83062c6fd8/Attachments/Image002932.png
Authorization: OAuth...
Content Type: image/png
Content-Length: 10293

{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.


GET Contacts

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)
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

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)

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>

Example response for GET Contacts/bd2270c3-8706-4c11-9cfb-000b551c3f51

Note more details (e.g. payment terms, balances, batch payments) are returned when retrieving a specific contact

<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>
    <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>