HTTP Requests and Responses
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.
- 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
- 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 (accurate to the second).
Please note: Not all changes will trigger a change of the UpdatedDateUTC field. These include changes to partially paid transactions which don’t generate a journal such as DueDate or SentToContact, and Contact fields pulled from other sources such as Balances, IsSupplier, and isCustomer. As a result, transactions with these changes may not be returned with an If-Modified-Since query.
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 most XML elements in the resulting response.
- 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.
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
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
Example 7: List all accounts of type ‘Asset’, ordered by account code using the Accounts endpoint
Example 8: Retrieve invoices with an invoice date between a date range
Date >= DateTime(2015, 01, 01) && Date < DateTime(2015, 12, 31)
Note: Long complex WHERE clauses can cause the query to time out. For optimal performance, recommend that the number of WHERE parameters be limited to three or less, and that the request be structured to use AND instead of OR whenever possible since AND queries are far more efficient in our system.
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.
We recommend all calls to any endpoints that have large result sets use the if-modified-since parameter.
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
You can get results in descending order by using DESC parameter.
HTTP POST and PUT
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.
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, WARNING 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="WARNING"> ... </Invoice> <Invoice status="ERROR"> ... </Invoice> </Invoices> </Response>
- A WARNING 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.
When using POST to update an invoice or contact, you can specify the id of the object being updated in the url: e.g
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