JSON formatted responses are also supported by setting the “Accept” value in the http header to “application/json” when making a request.
At Xero we use .NET, and used the Microsoft .NET JSON date format available at the time of original development. We know it's ugly but not something we can fix without a breaking change or a new version of the API. We're really sorry about this. To help you along, below we explain how to handle this date format. An example date/time in JSON is returned like this:
"DateTimeUTC": "\/Date(1439434356790)\/" or "PeriodLockDate": "\/Date(1419937200000+0000)\/"In both cases, the date/time value is a unix timestamp value, but in miliseconds rather than seconds (so divide by 1,000 for seconds). For some elements we also include a date string value on JSON responses to help with reading date values. e.g. DateString, DueDateString.
https://api.xero.com/api.xro/2.0/TaxRatesWe recommend all calls to any endpoints that have large result sets use the if-modified-since parameter.
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.
To ensure efficiency when retrieving multiple records, paging is recommended.
Paged results are available on the Invoices, Contacts, CreditNotes, BankTransactions, ManualJournals, Payments, PurchaseOrders, Prepayments and Overpayments endpoints. Paged results will have extra detail (e.g. line items) and may mean you don't have to retrieve individual resources to get the information you need.
To utilise paging you must 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. It is not possible to specify the page size.
The number of parameters is only limited by the maximum url length. To ensure you receive a timely response from the API, we recommend you look to retrieve in a batch of 40.
Our busiest endpoints ( Invoices and Contacts ) have explicit query parameters for commonly used filters. These parameters allow you to pass a comma-separated list of values in a single request. For faster response times we recommend using these where available.
GET https://.../Invoices?IDs=220ddca8-3144-4085-9a88-2d72c5133734,88192a99-cbc5-4a66-bf1a-2f9fea2d36d0Example 2 : Retrieve all Invoices for a specific set of Contacts
GET https://.../Invoices?ContactIDs=3138017f-8ddc-420e-a159-e7e1cf9e643d,4b2df4a1-7aa5-4ce3-9e9c-3c55794c5283Example 3 : Retrieve all unpaid Invoices against a particular Contact
GET https://.../Invoices?ContactIDs=3138017f-8ddc-420e-a159-e7e1cf9e643d&Statuses=AUTHORISEDExample 4 : Retrieve all DELETED or VOIDED Invoices
The where parameter allows you to filter on endpoints and elements that don't have explicit parameters.
Please note: even though the where filter supports complex queries we recommend you keep them as simple as possible. Long, complex where queries can cause time outs. To ensure your calls run efficiently against larger organisations it's a good idea to restrict your queries to simple == operations.
Example 1 : Retrieve all Bank Accounts using the Accounts endpoint
Type=="BANK"This would translate to the following URL once percent encoded.
https://api.xero.com/api.xro/2.0/Accounts?where=Type%3D%3D%22BANK%22Example 2: Retrieve all contacts with specific text in the contact name using the Contacts endpoint
Name.Contains("Peter") Name.StartsWith("P") Name.EndsWith("r")Example 3: 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 4: Retrieve invoices with an invoice date between a date range
Date >= DateTime(2015, 01, 01) && Date < DateTime(2015, 12, 31)
Use summaryOnly=true in GET Contacts and Invoices endpoint to retrieve a smaller version of the response object. This returns only lightweight fields, excluding computation-heavy fields from the response, making the API calls quick and efficient.
Please note: This query parameter works with other filters, but not when filtering on the fields that are exluded in the response. To get more details around what fields are excluded, please refer to the Contacts and Invoices documentation.Example 1 : Retrieve smaller lightweight response for Get Invoices
https://api.xero.com/api.xro/2.0/invoices?summaryOnly=TrueExample 2 : Retrieve smaller lightweight response for Get Contacts
https://api.xero.com/api.xro/2.0/Contacts?order=EmailAddressYou can get results in descending order by using DESC parameter.
Secondary ordering, using the ID field, is now applied by default across a range of endpoints - Contacts, Payments, Batch Payments, Credit Notes, Invoices and Bank Transactions. This will ensure consistency in ordering across pages. The default order is UpdatedDateUTC ASC, [ID] ASC.
POST /api.xro/2.0/Invoices?summarizeErrors=falseNote: The summarizeErrors option is only available for the Accounting API. The summarizeErrors option will not affect AU Payroll API calls.