HTTP GET
The HTTP GET method is used for requesting information out of Xero.
A simple HTTP request to obtain the organisation details would look like this:
GET /api.xro/2.0/Organisation HTTP/1.1 Authorization: OAuth...
Note: you will only ever get one organisation record when connecting to the organisation API endpoint, however the Contacts and Invoices endpoints can return potentially thousands of items. To help increase the speed of selecting data from the API, we would recommend that you specify a filter to return only the data that is required. See the filters section below for more information.
To obtain a specific item from the api, the ID of the item can be appended to the url, like this:
GET /api.xro/2.0/Contacts/8E5EB259-1E77-4EF0-A73C-F65AC8A54EDE HTTP/1.1 Authorization: OAuth...
Most items stored in Xero have a secondary identifier, such as the Invoice Number, Contact Number or Account Code. This secondary identifier can also be used in the endpoint URL. As this identifier is used in the URL, any non-alphanumeric characters should be percent-encoded to ensure the URL is valid.
By default all API responses are returned as XML. All our endpoints also support JSON formatted responses by setting the “Accept” value in the http header to “application/json”.
Individual invoices and credit Notes can also be returned in PDF format by setting the “Accept” value in the http header to “application/pdf”.
Example 1: Retrieve an invoice by the invoice number:
GET /api.xro/2.0/Invoices/INV-00384 HTTP/1.1 Authorization: OAuth...
Example 2: Retrieve an contact by the contact number:
GET /api.xro/2.0/Contacts/0006841301 HTTP/1.1 Authorization: OAuth...
Filtering by Last Modified date
When selecting multiple items from the API, you can specify a date which is used to filter the result set. Only items created or updated since the specified date will be returned. If specified, the date must be in UTC. This date is specified as the If-Modified-Since http parameter.
GET /api.xro/2.0/Invoices Authorization: OAuth... If-Modified-Since=Sun, 06 Nov 1994 08:49:37 GMT
Note: We would recommend that all calls to list Invoices and Contacts from the API uses this If-Modified-Since parameter.
The Invoice endpoint will filter on the <UpdatedDateUTC> element on each invoice. This field is updated to the current UTC date when the invoice is edited, changed status or paid.
The Contacts endpoint will filter on the <UpdatedDateUTC> element on each contact. This field is updated to the current UTC date when the contact is edited.
Additional custom filters
The API has a very customisable filter. 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.
GET /api.xro/2.0/{endpoint}?where={where filter}
Note: The ‘where’ parameter should be encoded using percent encoding before it is appended to the URL. Be careful not to double-encode the where parameter before it is used, as some programming languages may automatically encode the querystring.
Example 1: Retrieve all Invoices for a specific Contact ID:
Contact.ContactID = Guid("cd09aa49-134d-40fb-a52b-b63c6a91d712")
represented as:
GET /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:
Contact.Name=="Basket Case" AND Type=="ACCREC" AND STATUS=="AUTHORISED"
represented as:
GET /api.xro/2.0/Invoices?where=Contact.Name%3d%3d%22Basket%20Case%22%20AND%20Type%3d%3d%22ACCREC%22%20AND%20Status%3d%3d%22AUTHORISED%22
Example 3: Retrieve all Invoices PAID between certain dates
FullyPaidOnDate >= DateTime(2011, 10, 01) AND FullyPaidOnDate <= DateTime(2011, 10, 30)
represented as:
GET Invoices?where=FullyPaidOnDate%20%3E%3D%20DateTime%282011%2C%2010%2C%2001%29%20AND%20FullyPaidOnDate%20%3C%3D%20DateTime%282011%2C%2010%2C%2030%29
Example 4: Retrieve all Bank Accounts:
Type=="BANK"
represented as:
GET /api.xro/2.0/Accounts?where=Type%3d%3d%22BANK%22
Example 5: Retrieve all DELETED or VOIDED Invoices:
Status=="VOIDED" OR Status=="DELETED"
represented as:
GET /api.xro/2.0/Invoices?where=Status%3d%3d%22VOIDED%22%20OR%20Status%3d%3d%22DELETED%22
Example 5: Retrieve all contacts with specific text in the contact name:
Name.Contains("Peter")
Name.StartsWith("")
Name.EndsWith("")
represented as:
GET /api.xro/2.0/Invoices?where=Name.Contains%28%22Peter%22%29 GET /api.xro/2.0/Invoices?where=Name.StartsWith%28%22Peter%22%29 GET /api.xro/2.0/Invoices?where=Name.EndsWith%28%22Peter%22%29
Ordering of results
A list of items can be returned in a specific order. To specify the ordering, append a order querystring to the endpoint URL.
Example 1: Order contacts by email address
GET /api.xro/2.0/Contacts?order=EmailAddress
Example 2: List all accounts of type ‘Asset’, ordered by account code
where=Type=="ASSET"&order=Code
GET /api.xro/2.0/Accounts?where=Type%3d%3d%22ASSET%22&order=Code