Frequently asked questions


Getting Started
7 questions
Limits
7 questions
Authentication
9 questions
Permissions
5 questions
API Updates
4 questions

  View all questions

  • How do I get a Xero account to develop/test against?

    The first step is to sign up for a free Xero account. Once you have done that, you have two options as to how you can begin development without incurring any cost:

    • Use the demo company (recommended)
    • Start a trial or paid Xero organisation subscription

    Check out our Development Accounts guide for more details.



  • What app type should I use?

    Xero has three types of API applications: Private, Public and Partner. The different app types have different authentication methods and are designed to suit different use cases. Check out our API Application Types guide for all the details.


  • What kind of App should I build?

    That's really up to you! Get connected with accountants and business owners to find out how you can help them be successful. There are plenty of resources like our business forums, developer forums and UserVoice page to get you started with some ideas.


  • How do I connect Xero to my Salesforce/SQL Database/thing you have no SDK for?

    We've got SDKs to cover the most used technologies in the community but we'll never cater for everyone. If we don't support your particular tech then your best bet is to look for help on our developer forums.


  • What are some best practices for building an integration?

    For some of the basics check out our Integration Best Practices guide. After that, browse through the rest of our how-to guides to find more guidance specific to your integration.


  • How do I get support for building my integration?

    Hopefully everything you need to know is on developer.xero.com but if you're still stuck then you can reach out to other developers on community or stack overflow. If you're really stuck you can even hire Xero certified developer to help you out.


  • How can I try out the API?

    The quickest way to try out the API is to set up your demo company and dive into the API Previewer. Most of the API functionality is supported and you can quickly start playing with real calls against demo data.


  • What are the Xero API rate limits?

    There are limits to the number of API calls that your application can make against a particular Xero organisation.

    • Minute Limit: 60 calls in a rolling 60 second window
    • Daily Limit: 5000 calls in a rolling 24 hour window

    If you exceed either rate limit you will receive a HTTP 503 (Service Unavailable) response. For a full list of API limits, pleace check our API Limits page



  • Can I get my rate limits increased?

    No, our rate limits are the same for all apps connecting to the API. If you are hitting rate limits there are a number of things you can do to make your integration more efficient.


  • What if I need to do lots of creating and updating?

    Quite often, applications that you might believe would exceed the Xero API rate limits, can in fact work within the limits by analysing the structure of how you intend to use the Xero API

    You can do more than one thing in a single request: For example, you can create more than one Invoice in a single PUT or POST Invoices API call. While there is no upper limit in the number of nodes that can be sent at one time, a ceiling of about 50 nodes per request is practical - this will ensure a request does not exceed the maximum size of 3.5MB. You should also review our notes on summarizing validation errors.



  • What if I need to retrieve large amounts of data from Xero?

    If you are hitting rate limits because you retrieve a large amount of data from Xero there are couple of features you should be taking advantage of:

    • You can use pagination to retrieve line item details for 100 items (e.g. Invoices) at a time. Endpoints on the Accounting API that currently support pagination are invoices, contacts, bank transactions and manual journals. All major endpoints on the Payroll, Files and Assets APIs also support paging.
    • Use the If-Modified-Since header to retrieve only what's changed since your previous request


  • What is the best way to handle rate limits on my side?

    It is recommended that applications queue requests to the Xero API. This will allow you to ensure requests are within the supported limits, and will also allow your application to function even in the event that it cannot reach the Xero API temporarily.


  • Does my application only have 5000 requests for all my users?

    Applications that connect to more than one Xero organisation (Public and Partner) have a per organisation usage limit. For example if two separate Xero organisations are connected to an application, each connection would have 5000 API calls available in a given 24 hour period.


  • Are there any recommended usage limits for Xero?

    Xero is not suitable for all types of business, particularly those with very high transaction volumes. Please see our notes on system limits.


  • What Authentication do you support?

    We only support OAuth 1.0a. This means we don't support API keys or basic password authentication


  • Can you give me an API key?

    The Xero API does not support basic API Key authentication. Our API uses OAuth1.0a which means you need to register your app to get a consumer key and consumer secret which you use to access the API. Depending on the type of app you register you may also need to upload a X509 Public Key Certificate.


  • Whats with OAuth1a? Any plans for OAuth2?

    OAuth1.0a has served us well but we appreciate that it's less convenient than OAuth2.0. We will look to transition to OAuth2.0 in the future but no specific details to share at the moment.


  • How do I redirect back to my app once a Xero user has authorised my app?

    In order to redirect a user back to your app, you'll need to specify a callback URL parameter. The base of the URL will need to match the callback domain you set when registering the app. You can find more details on our OAuth Callback Domains page.


  • I'm getting an OAuth error. How do I fix it?

    We have a list of the most common OAuth errors and potential fixes on our OAuth Issues page.


  • How does OAuth differ between app types?

    A Private app uses RSA-SHA1 for signing and two-legged OAuth 1.0a. This generates a token that never expires.

    Public apps use HMAC-SHA1 for signing and three-legged OAuth 1.0a. The generated token expires after 30 minutes and then the user must re-authenticate to get a new access token.

    Partner apps use RSA-SHA1 for signing and three-legged OAuth 1.0a. The generated token expires after 30 minute like Public apps, but with Partner apps the developer can renew the token when it expires without the user reauthenticating.



  • What is three-legged auth?

    This is where the end user is redirected to Xero to login and granted an access token to the app. The OAuth Bible has a great explanation.


  • What is two-legged auth?

    During the creation of a Private App, the developer will select a single Xero org to connect to and generates a token. This token is used to sign requests and never expires, so no access token renewal is needed. It's commonly known as two-legged but is actually one legged, when you register the app. The OAuth Bible has a great explanation.


  • Is it possible for my app to have multiple active connections to a single Xero Organisation?

    Yes. If multiple Xero users from the same organisation have authorised a connection to your app you could have multiple active connections. Your app will need to be able to keep track of the each connection's token in order for this to work.

    There's no real benefit to managing multiple connections though, it just makes your token management more complicated. It won't give you additional rate limits.



  • I need to build an integration but the owner doesn't want to allow me access to their data. What do I do?

    Integrations should be fully built and tested before being connected to a live organisation. Once the integration is complete, you can hand it over to a Standard or Adviser level user to connect. Please see our Development Account page for ways to test your integration without cost.


  • What permissions does an app have when using the API?

    Generally apps using the API have the permissions of a Standard level user. To access reporting APIs the authorising user must have Reports access and for Payroll APIs the authorising user must be a payroll admin.


  • Can I restrict the permissions given to an app?

    Currently it's not possible to grant a subset of permissions to App using the API. Apps have the same permissions that a Standard user would.


  • What permissions does a user need to connect an App via the API?

    The API essentially works on behalf of the user that authorised it to connect. Since the API acts with Standard user permissions, the user that connects the integration has to have at least Standard user permissions.


  • Why is my organisation missing from the drop down when authorising an app?

    If your organisation isn't showing in the organisation dropdown, this means either that you don't have Standard or Adviser level permissions in that organisation, or you already connected that particular app to the organisation.


  • Can the API be used on all Xero plans/SKUs?

    The API can be used with all Xero plans, but not all features will necessarily be available. Payroll API requires a Payroll plan. Cashbook and Ledger plans exclude certain features (e.g. invoicing) but can still be connected to via tha API.


  • How does this accounting thing work? (WHY am I getting an error that the tax rate can't be used with the account code?)

    It's best to become familiar with the Xero platform and basic accounting principles before designing an integration. Xero accounts are free, and each comes with a fully functional Demo Company. The Demo company is populated with sample data to give you an idea of what items should look like. We also have an extensive Help Centre with information on each feature as well as how-to guides specific to the API. You may also want to consult with a Xero Certified Adviser who can instruct you on the accounting requirements many clients may have.


  • Does the Xero API use defaults for things like tax rates, account codes etc?

    The Xero API uses very few of the defaults that can be set through the Xero UI. The only defaults it will use are the tax rate from the account code if the tax rate isn't sent, and the description, account code and price on inventory items (but not tax rate). All other information must be specified in your call.


  • Will you make changes to your API that will leave my integration unusable?

    Whenever we make a change to the API we try to do so in an additive way that won't break existing integrations. However, occasionally things can change in a way that isn't backwards compatible. Make sure that you stay in touch so we can let you know when things do.


  • When is feature X going to be supported/available?

    In the Xero Developer team we try and be as transparent as possible letting developers know what we're up to using our public roadmap.


  • Can you add this feature I want to the API?

    If you want to show your support for a feature not currently in the API then please add your votes and comments to our UserVoice page.


  • How do you decide which features get on the roadmap?

    The roadmap is driven by a number of factors such as developer feedback, User Voice feature requests and Xero's internal product goals. Priorities and circumstances are constantly changing so please use the roadmap as an insight into our current plans rather than a binding commitment.