Xero Network API v1 Reference
Please Note, This API has been superseded with the API v2. Support for API v1 has been discontinued.
View our change log to see all recent changes for API v1.
| Interface | Description |
| GET /api.xro/1.0/accounts | Gets all account codes |
| POST /import.xro | Allows the bulk importing of draft invoices into the Xero system through a generic interface. |
| GET /api.xro/1.0/contact | Gets a contact record |
| POST /api.xro/1.0/contact | Saves a contact record |
| GET /api.xro/1.0/contacts | Gets a batch of contact records |
| POST /api.xro/1.0/contacts | Saves a batch of contact records |
| GET /api.xro/1.0/invoice | Gets an invoice record |
| GET /api.xro/1.0/invoices | Gets a batch of invoice records |
| PUT /api.xro/1.0/invoice | Inserts an invoice record |
| PUT /api.xro/1.0/invoices | Inserts a batch of invoice records |
| GET /api.xro/1.0/tracking | Gets all tracking categories |
All examples given are based on the NZ Demo Company and can be recreated at any time by creating or resetting an NZ demo.
Architecture
Xero’s API is organized around RESTful principles – each resource has a unique URI and HTTP verbs are used to specify the action to perform on that resource.
In order to write or modify a client application for Xero, you should use a full-featured HTTP client library that supports the following:
· Ability to make HTTPS (i.e., secure) requests
· HTTP verbs: GET, POST, PUT, DELETE
Xero’s API uses a custom per request authentication system. All calls to the API must use the API Key provided to you by Xero. If the API Key is incorrect then the server will respond with an HTTP status code of 401 Unauthorized.
Every request irrespective of the input content type will get an XML response (content type text/xml). If an application exception occurs during the execution of the request then the server will respond with an HTTP status code 500, however some requests will respond with an HTTP status code of 200 even if errors have occurred during the processing of the document. 200 OK is the default status code for any successful request.
Business Rules
The following business rules apply to both the Customer API and Xero Network API (specifically save requests).
Invoices
1. When trying to save an invoice, the invoice has a contact record. If the contact does not exist it will be created in Xero.
2. An invoice is either Accounts Receivable (ACCREC) or Accounts Payable (ACCPAY) from the perspective of the Xero user.
3. The Invoice <Total> should be the sum of the <SubTotal> and <TotalTax>.
4. The individual line item <LineAmount> should be the product of <Quantity> X <UnitAmount>, i.e. tax exclusive.
5. Xero supports negative line items. For example an Accounts Receivable invoice might have credits to a revenue account (like sales) and also debits to an expense account (like a management fee). Enter a negative amount to signify the negative item that should be flipped.
For example
| Sales | 100 |
| less Management Fee | -10 |
| Invoice Total | 90 |
will result in
| Dr | Accounts Receivable | 90 |
| Dr | Management Fee | 10 |
| Cr | Sales | 100 |
6. Xero will attempt to match the Account Code. If it does not match it will be unassigned.
7. Xero will attempt to match the Tracking Categories and Options provided. If matches can’t be found they will be unassigned.
8. All invoices are created as Drafts. The status of each invoice entered via the API will initially be set to DRAFT
Invoices can have the following InvoiceStatus :
| InvoiceStatus | Description |
| AUTHORISED | Approved invoices awaiting payment |
| DELETED | Draft invoices that are deleted |
| DRAFT | Invoices saved as draft or entered via API |
| PAID | Invoices approved and fully paid |
| SUBMITTED | Invoices entered by an employee awaiting approval |
| VOIDED | Approved invoices that are voided |
9. Only inserts are allowed. Updates are currently not supported by either API.
10. A TaxType can be provided with each LineItem. If the tax type does not exist then it will be unassigned. If TaxType is not provided then it will default to the default TaxType assigned to the Account selected (if one exists). The following TaxTypes are allowed:
| TaxType | Description | Supported Region(s) |
| NONE | No GST | NZ/UK |
| EXEMPTINPUT | VAT on expenses exempt from VAT (UK only) | UK |
| INPUT | GST/VAT on expenses | NZ/UK |
| ZERORATEDINPUT | Expense purchased from overseas (UK only) | UK |
| RRINPUT | Reduced rate VAT on expenses (UK Only) | UK |
| EXEMPTOUTPUT | VAT on sales exempt from VAT (UK only) | UK |
| OUTPUT | GST/VAT on sales | NZ/UK |
| ZERORATEDOUTPUT | Sales made from overseas (UK only) | UK |
| RROUTPUT | Reduced rate VAT on sales (UK Only) | UK |
| ZERORATED | Zero-rated supplies/sales from overseas (NZ Only) | NZ |
Contacts
1. Contact Number is the identifier to the Contact in the source application. It is just a field in Xero.
2. ContactID is the unique identifier for a Contact within the Xero system. The only supported data type for a ContactID is a GUID (Globally Unique Identifier).
3. ContactStatus can be ACTIVE or DELETED.
4. AddressType can be STREET or POBOX
5. PhoneType can be DEFAULT, DDI, MOBILE or FAX