HTTP Requests and Responses


HTTP GET

Retrieving individual resources

To retrieve a specific resource you can append its identifier to the end of the URL. The example below shows retrieving a specific contact using the HTTP GET method.

https://api.xero.com/api.xro/2.0/Contacts/fe61ead1-8afc-4f0b-beda-066620227aad
  • Successful responses return with a HTTP 200 status code
  • By default all successful API responses are returned as XML.
  • Individual Invoices and Credit Notes can also be returned in PDF format by setting the “Accept” value in the http header to “application/pdf”.
  • Some documents may have attachments. You can retrieve these via the API too. Learn More

JSON responses

JSON formatted responses are also supported by setting the “Accept” value in the http header to “application/json” when making a request.

  • Some extra elements are included on JSON responses to help with reading date values. e.g. DateString, DueDateString.
  • Elements like Date are using the default .NET Date serialisation e.g. 1326530063760 or the UpdatedDateUTC element uses the format 1326530063760 + 1300.
  • In a future version of the Xero API these formats will likely be upgraded to use the ISO-8601 format. Developers will receive prior warning of any changes with these date formats.

Retrieving modified resources


The easiest way to retrieve resources that have been created or modified since a previous request is to specify a UTC timestamp filter using the If-Modified-Since http parameter. Only items created or updated since the specified timestamp will be returned.

Retrieving a filtered set of resources

Appending a where querystring parameter to the endpoint URL will restrict the amount of data being returned.

    The “where” parameter

  • can reference any XML element in the resulting response, including all nested XML elements.
  • should be encoded using percent encoding before it is appended to the URL.

Example 1 : To retrieve all Invoices for a specific Contact ID the following filter could be used with the Invoices endpoint

Contact.ContactID = Guid("cd09aa49-134d-40fb-a52b-b63c6a91d712")

This would translate to the following URL once percent encoded.

https://api.xero.com/api.xro/2.0/Invoices?where=Contact.ContactID%20%3D%20Guid%28%22cd09aa49-134d-40fb-a52b-b63c6a91d712%22%29

Example 2 : Retrieve all unpaid ACCREC Invoices against a particular Contact Name using the Invoices endpoint

Contact.Name=="Basket Case" AND Type=="ACCREC" AND STATUS=="AUTHORISED"

Example 3 : Retrieve all Bank Accounts using the Accounts endpoint

Type=="BANK"

Example 4 : Retrieve all DELETED or VOIDED Invoices using the Invoices endpoint

Status=="VOIDED" OR Status=="DELETED"

Example 5: Retrieve all contacts with specific text in the contact name using the Contacts endpoint

Name.Contains("Peter")
Name.StartsWith("")
Name.EndsWith("")

Example 6: For optional elements such as email address, it is best that you add a not null at the starts of the query. If you don’t include it you will get an exception if any of the optional elements aren’t set. This example is using the Contacts endpoint

EmailAddress!=null&&EmailAddress.StartsWith("boom")

Example 7: List all accounts of type ‘Asset’, ordered by account code using the Accounts endpoint

where=Type=="ASSET"&order=Code

All resources

With some endpoints you may need to retrieve a full list of resources e.g. TaxRates or BrandingThemes. You can do this by simply using a HTTP GET with the resource name.

https://api.xero.com/api.xro/2.0/TaxRates

We recommend all calls to any endpoints that have large result sets use the if-modified-since parameter.

At this time only the Journals endpoint has paginated results so please use the API sensibly when working with with large data sets of objects like Invoices and Contacts.

Ordering of results

A list of items can be returned in a specific order. To specify the ordering, append an order querystring to the endpoint URL.
Example : To order contacts by email address the following url could be used

https://api.xero.com/api.xro/2.0/Contacts?order=EmailAddress

You can get results in descending order by using DESC parameter.

https://api.xero.com/api.xro/2.0/Contacts?order=EmailAddress%20DESC

HTTP POST and PUT

Creating resources

The HTTP PUT and POST methods are used for sending information to the API.

  • A PUT method will create new data in Xero, whereas a POST will either create new data or update existing data in Xero.
  • The Content-Type should be set as “application/x-www-form-urlencoded”
  • The Encoding type should be set as “UTF-8”
  • Only XML formatted requests are accepted. The XML must be sent in an html form parameter called “xml”.

You should check the response from each API call and not assume that it will be completed successfully. This includes

  • checking that you get a HTTP 200 response and a status of OK. Learn more
  • checking that you have received an identifier (e.g. InvoiceID) for the new object created.

Creating many resources

It is possible to submit more than one invoice, credit note, contact, item or other entities of the same type in a single API call. If you plan to submit more than one entity per API call, we recommend that you append the summarizeErrors=false querystring to your API call. This ensures that every entity is returned back to you, each having their own status attribute.

POST /api.xro/2.0/Invoices?summarizeErrors=false

Note: The summariseErrors option is only available for the Accounting API. The summariseErrors option will not affect AU or US Payroll API calls

The following xml is a sample response of a bulk upload to the Invoices endpoint.

  • A status attribute is included for each Invoice can be OK, WARN or ERROR.
  • If you have a validation error in any of your objects you will receive a HTTP 200 status code (rather than HTTP 400) if you are using the summarizeErrors parameter
<Invoices>  
    <Invoice status="OK">  
      ...  
    </Invoice>  
    <Invoice status="OK">  
      ...  
    </Invoice>  
    <Invoice status="WARN">  
      ...  
    </Invoice>  
    <Invoice status="ERROR">  
      ...  
    </Invoice>  
  </Invoices>  
</Response>  
  • A WARN status indicated that the entity was successfully processed, but there are additional warnings added to the response.
  • An ERROR status indicates that the entity could not be saved to Xero due to a validation error.

Updating resources

When using POST to update an invoice or contact, you can specify the id of the object being updated in the url: e.g

https://api.xero.com/api.xro/2.0/Invoices/INV-000394

Debugging requests and responses

If you receive a HTTP 400 response this is due to a validation error. The response will include an “APIException” element that contains a useful summary of the reason for the validation error. Learn more