Streamline your onboarding with Xero Bulk Connections

Onboarding multiple Xero organisations is made easier with the use of Bulk Connections. In this article, we will chat through the key benefits and technical considerations for Bulk Connections and how it can be harnessed to build scalable onboarding flows.

Bulk Connections is an exciting opportunity for you to improve your customer onboarding, and potentially service new customer types or open new channels.

To access Bulk Connections you’ll need to meet the following requirements in the order below:

1. Join the Xero App Store or be a certified Financial Service integration
2. Pass a security assessment. Contact API Support to get started
3. Request Bulk Connections to be enabled on your app. API Support can help with this too.

Benefits

When onboarding an accountant or bookkeeper to your app, they can often bring with them hundreds of Xero organisations at once. Connecting those organisations to your app one by one can be a really tedious and time intensive process. Bulk Connections alleviates this manual process by allowing the person authorising the connection to select multiple organisations to be connected to an app during the flow. By reducing this onboarding friction, we believe this will ultimately help your customers connect more organisations.

Bulk Connections is an opportunity for app partners to design a scalable onboarding flow that enables a swift setup process so your customers can start using the full set of your apps features more quickly.

Bulk Connections in the OAuth 2.0 flow

Technical considerations

Our technical documentation digs into the full implementation details for Bulk Connections. The key thing to keep in mind is that Bulk Connections will mean that there are one or many organisations that you’ll need to deal with during a single OAuth 2.0 code or PKCE flow. There are also a few other things you will want to consider before you start building.

How might Bulk Connections affect your user sign up process?

You’ll need to consider if changes are needed to make the most of Bulk Connections. Here’s a few areas to think about:

• The Sign Up with Xero flow
• Your own sign up process
• Reconnecting or adding new Xero connections within your app

Here’s an example: In your Sign Up with Xero flow, it’s common to pull some data from the Xero organisation to help automatically set up the account in your app or to auto-populate fields in a form if you’ve implemented the modified Sign Up with Xero flow. Have a think about how you might want to deal with this — is it acceptable to use the first organisation in the list of organisations? Do you want to enable the customer to select the org to use? Perhaps you can delay this until later in the onboarding steps?

You might want to consider if there are times when you only want one organisation to be connected at a time e.g. perhaps you don’t have an automated account creation process during sign up. Once you’ve had the Bulk Connections functionality turned on, the feature is enabled on all authorisations by default. So, if you wish to connect one organisation at a time, you can disable the feature by appending ACR values boolean value to your authorisation URL.

&acr_values=bulk_connect:false

https://login.xero.com/identity/connect/authorize?response_type=code&client_id=YOURCLIENTID&redirect_uri=YOURREDIRECTURI&scope=openid profile email accounting.transactions&state=123&acr_values=bulk_connect:false

How do you identify connections made during the same authorisation flow?

Once the user has gone through the OAuth 2.0 authorisation flow correctly, you will have the access_token and id_token (and refresh token? if offline_access scope was used). Once you have decoded the access_token, which is a JSON Web Token (JWT), you can retrieve the authentication_event_id and save it.

{
  “nbf”: 1589363023,
  “exp”: 1589364823,
  “iss”: “https://identity.xero.com",
  “aud”: “https://identity.xero.com/resources",
  “client_id”: “91E5715B1199038080D6D0296EBC1648”,
  “sub”: “b3121b95a8afh340a7b968ee3f188f53”,
  “auth_time”: 1589361892,
  “xero_userid”: “27438a02-b5a3–4bb4-a9c3-c662287010b7”,
  “global_session_id”: “be22c5e824574af3ac123c50dfec65c3c”,
  “jti”: “4e7747cec44d6efe512bb23775166c5f”,
  “authentication_event_id”: “d0f9d142-dcf8-b3cd-74f4-f98425814dc1”,
  “scope”: [
    “email”,
     “profile”,
    “openid”,
    “accounting.transactions”,
    “accounting.settings”,
    “offline_access”
  ]
}

Next, you need to use the connections endpoint to retrieve the list of currently connected Xero tenants.

GET https://api.xero.com/connections
Authorization: “Bearer “ + access_token
Content-Type: application/json

When you receive the response back, it will be in the form of an array which includes the authEventId Guid values for each connection, example as below (note these are arbitrary values for example purpose). Refer to OAuth 2.0 code or PKCE flow for details on how the responses look.

Response:

[
  {
    “id”: “5c5aec92–8f81–476b-986f-0ba323695db0”,
    “authEventId”: “7eba2984-da7c-4c52-a303–775ab099c4d8”,
    “tenantId”: “90a2aa56–0565–464a-82de-9d694664dec9”,
    “tenantType”: “ORGANISATION”,
    “tenantName”: “Test Org 1”,
    “createdDateUtc”: “2023–08–09T12:15:31.1845830”,
    “updatedDateUtc”: “2023–08–15T11:17:12.8912480”
  },
  {
    “id”: “3db27649–61b6–4587-bf17-fe1dc7c54585”,
    “authEventId”: “d0f9d142-dcf8-b3cd-74f4-f98425814dc1”,
    “tenantId”: “730e589a-8c67–4a72-abe5-ae891524b340”,
    “tenantType”: “ORGANISATION”,
    “tenantName”: “Test Org 2”,
    “createdDateUtc”: “2023–08–25T01:33:35.7381010”,
    “updatedDateUtc”: “2023–09–01T19:21:07.9457310”
  },
  {
    “id”: “f75043b9–3552–431c-a25a-6edb6db95d5b”,
    “authEventId”: “d0f9d142-dcf8-b3cd-74f4-f98425814dc1”,
    “tenantId”: “1dbd78b4–2917–4269-b4b9–97ebaee6a6ae”,
    “tenantType”: “ORGANISATION”,
    “tenantName”: “Test Org 3”,
    “createdDateUtc”: “2023–08–25T01:33:36.2717380”,
    “updatedDateUtc”: “2023–09–01T19:21:08.5739590”
  }
 ]

These ID values will match the authentication_event_id of the access_token indicating that the corresponding organisations were connected in the same authorisation flow i.e. your customer used Bulk Connections.

You will need to loop through the array in order to ensure you create all of the Xero tenants in your app. Have a read of our next question “How can you level up your onboarding experience?” for some thoughts on what to do next.

How can you level up your onboarding experience?

It’s important to keep user experience at the forefront of any changes you make to your onboarding experience.

Our Bulk Connections documentation goes into great detail about mapping organisations either manually, automatically or a combination of both. We strongly recommend that if you keep Xero organisations separate in your app, you implement the mapping capability so you can ensure the correct data is synced to the right place in your app. An example of this would be a point of sale app where organisations are represented by individual stores.

If you’re representing Xero organisations uniquely and need each organisation to have individual settings configured, have a think about if you need to streamline this. Is the user able to create different settings templates to apply to all the organisations? Are there default settings? Do you need to make some tweaks to your first time configuration wizard?

Another benefit is when you bring Bulk Connections together with Rapid Sync — another feature available exclusively for Xero app partners. Rapid Sync lifts the minute and day rate limits for the first 30 minutes of a new connection initiated from the Xero App Store. Together, that makes for a fast and easy onboarding process as data is synced quickly between Xero and your app.

How do you test your Bulk Connections flow?

It’s worth getting Bulk Connections up and running on a test Xero app before we enable it on your production app. We won’t be able to turn on Bulk Connections for your Xero app until you’ve completed a security assessment; however, testing of the feature can be carried out before completion of the assessment. If you need some help with your test Xero app, chat to our API Support team.

You will be able to connect a demo company to your bulk connections flow, if you don’t have another test Xero organisation, chat to API Support about getting access to one.

There is no limit to how many organisations can be selected and connected during one authorisation flow. You should plan to handle anywhere from one to hundreds or even thousands of Xero organisations with Bulk Connections.

What if you are only dealing with a 1:1 connection?

This could be the right opportunity for you to rework your accounts architecture. Even if you aren’t working with accountants or bookkeepers, there are plenty of Xero users who have multiple Xero organisations for their various businesses and side hustles. Making some changes might enable you to target new audiences e.g. accountants, bookkeepers or even franchises.

What documentation do you need to update?

Don’t forget your user documentation! Make sure you update your help articles, email templates and info for your sales team. Of course, it’s a feature worth mentioning on your Xero App Store listing too, check out how to self service your Xero App Store listing changes.

We hope that you have taken away a few ideas about how you can streamline your onboarding process using Bulk Connections. Get in touch with your partner manager or API Support to get started.