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)
BankAccountDetails	Bank account number of contact
TaxNumber	Tax number of contact
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.

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)

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>
    <Addresses>
      <Address>
        <AddressType>POBOX</AddressType>
          <AddressLine1>P O Box 123</AddressLine1>
          <City>Wellington</City>
          <PostalCode>6011</PostalCode>
        </Address>
      <Address>
        <AddressType>STREET</AddressType>
      </Address>
    </Addresses>
    <Phones>
      <Phone>
        <PhoneType>DEFAULT</PhoneType>
      </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>
  </Contact>
</Contacts>

Developer

Contacts