Xero - beautiful accounting software

Xero Developer Help Center

Xero Developer Community

Community > API Endpoints >

Organisation ShortCode

Started by Ronan Quirke (Community Manager) -   in API Endpoints

With our release this week, we now expose what we call an Organisation ShortCode.

This is a unique identifier of a Xero organisation (or 'file' in old terminology).
The ShortCode is less than 10 characters and contains a string with numbers, letters and special characters.

Why we are exposing this
There are many situations where you might need to uniquely identify the organisation that you are connected to. Retrieving existing data such as the organisation name might give you this, but there is no guarantee it is truly unique.

Potential uses

Be sure you are connected to a given organisation
OAuth provides an access token to identify an authenticated session, and in the case of the partner API, a session handle, but these are unique only to the OAuth session itself, not the organisation. In situations where a user re-connects, you can use the organisation shortcode to ensure the organisation that has been reconnected to, is the correct one.

Communicating with 3rd parties
More and more applications that integrate with Xero are also integrating with each other. Using the Xero ShortCode as an identifier of the Xero organisation between these systems will allow developers to ensure their is no confusion as to which Xero organisation they are interfacing with.

Deep Links
By using the ShortCode, you can construct a deeplink to a document in Xero that will reference the correct Xero organisation.
e.g. https://go.xero.com/organisationlogin/default.aspx?shortcode=!x-wj6&redirecturl=/Contacts/View.aspx?contactID=A8CB2A69-F2F4-4EB6-A240-FF51EE93DD74

Payment Services
ShortCodes can be used as part of a payment service integration to correctly identify a Xero customer.

More users coming soon
The organisation ShortCode may be used in some interesting new interactions between Xero and external services in the future. Look out for announcements on this in the coming months.

Best practice
We recommend storing the organisation shortcode when a user connects a Xero organisation to your application - it might come in handy in the future, even if you don't have a use for it right now.


Have a potential use or question? Let me know!
This is great Ronan, really pleased to see this. I've had to deal with several cases whether people were connected to organisation a. then disconnected at some point and connected to organisation b by mistake. This will give us something solid to check against.
 

Phil Gale  

When using the <Setup> xml, will the response include the company shortcode?
Alexander
 

MYOB to Xero Conversion  

@Alexander - no plans to add that right now, but will make a note to take a look at it.
 

Ronan Quirke (Community Manager)  

I mentioned further use cases in my original post.

With the new payment services release today, (http://help.xero.com/#PaymentServices) custom urls are now available for online invoices. You can link an online invoice to your own URL. The SHORTCODE variable is one of those that is made available in custom urls and would be useful if your application integrates with more than one Xero organisation:
- Your application is connected with a number of Xero organisations
- When a user clicks the button on the online invoice, you are passed in the invoice number and short code
- Using the short code, you identify which Xero organisation this invoice relates to, retrieve the invoice details via the API, process payment and (ideally) apply a payment to it via the API
 

Ronan Quirke (Community Manager)  

Deep links
We have been doing some work under the hood at Xero to support deeplinking to documents in the Xero application. While this has been possible already, if a user is active in a different Xero organisation than to the one that the URL refers, they can see some odd errors.

By using the ShortCode, you can construct a deeplink to a document in Xero that will reference the correct Xero organisation.
e.g. https://go.xero.com/organisationlogin/default.aspx?shortcode=!x-wj6&redirecturl=/Contacts/View.aspx?contactID=A8CB2A69-F2F4-4EB6-A240-FF51EE93DD74

So in two steps:
1. You pass in the shortcode parameter https://go.xero.com/organisationlogin/default.aspx?shortcode=$ShortCode
2. The redirecturl contains the relative path of the final location you wish to reference redirecturl=/Contacts/View.aspx?contactID=A8CB2A69-F2F4-4EB6-A240-FF51EE93DD74
 

Ronan Quirke (Community Manager)  

Works well, thanks!
 

Wayne Robinson  

I'd just like to say that this is awesome!
I was gonna email you about adding this as a feature as my addons allow you jump between the application and Xero. However, now that I support multiple connections concurrently, it can get out of sync. This fixes that, so I guess I'll have another release tonight.
 

Ruairi M