Looking for the Xero Partner Hub login? Go to Xero’s login page. This article explains how to connect Xero Partner Hub (XPH), formerly Xero Practice Manager (XPM), to AccountKit.

AccountKit keeps your Xero Partner Hub client list and AccountKit in sync, so your team maintains one client list. See how AccountKit works with Xero Partner Hub and what Xero Partner Hub changes for XPM practices.

Overview

The purpose of this integration to synchronise your client list in Xero Partner Hub with AccountKit and keep them in sync, so you're not maintaining multiple client lists.

Before you start...

Before you make a start, there are a couple things you need to do and note:

The initial connection should be initially completed by a user with Administrator Access in XPH, to ensure there are sufficient rights for AccountKit to write back to XPH.

Integration Limitations

We love all things Xero as much as the next person, but there are some limitations with the XPM API which you need to be aware of so as to not be taken by surprise when something doesn't synchronise quite the way you would expect. In most instances a change in XPH will be picked by AccountKit and vice versa, but here's what we've come across so far.

Information that isn't picked up in XPH when changed in AccountKit

Requires a manual update also to be completed in XPH.

Creating a new group with no one within the group won't flow through.
Setting up new business types in AccountKit will not update XPH automatically. Either enter the structure type in both XPH and AccountKit with identical details, or just do it in XPH and force a full re-sync.
Changing an entity from Prospect to Client .
- If the change is made in AccountKit , the API does NOT allow this to flow through to XPH. Thereby requiring a manual update within XPH after making the change in AccountKit.
- If the change is made in XPH, a new client ID is created resulting in a new client being created in AccountKit. The best way to manage this to change prospect to a customer in AccountKit, then update the XPH ID to match the newly created client in XPH. This way you get the full history of the client when they were still a prospect carrying through to the client record.

Client fields that have no equivalent in XPH

At times we will add fields that have no corresponding equal in XPH - these obviously won't sync. For example:

Client description - is a field where you're able to leave a short description as to what the role each entity plays within a family group client map. There is no equivalent in XPH.
Business name - this is linked to the Business Name register, which has no corresponding link into XPH fields.
Client notes - These are bespoke notes that are shared amongst entities across AccountKit and have no equivalent in XPH.
Relationship differences - Generally speaking our relationships are identical to XPH, with the following exceptions
- Unitholder Relationship - In AccountKit you can create a unitholding relationship with applicable unit holdings and descriptor. When we sync with XPH, we create a "Beneficiary Relationship" within XPH.
- Shareholder Descriptor - this field simply enables you to name shares (such as Class A, Ordinary etc). This field does not flow back to XPH.
- Sibling Relationship - This relationship enables us to show where a client has a family relationship with another brother / sister. This relationship type is not available in XPH.

How do you use it?

To connect to Xero Partner Hub:

First ensure that you have the appropriate user permissions within Xero Partner Hub . You need to have the authority ticked for "Authorise 3rd Party Full Access"
Now go to the AccountKit User Menu then Practice Settings and select the " Integrations " tab.
Hover over the XPH logo and select the 3 dot menu with the option to connect to XPH. Press the Connect green button and follow the directions with logging in to Xero to authorisation the connection.
Where you have more than one XPH authority, select the applicable XPH org and select ok.

Once you've been returned back to AccountKit and the icon has turned green, simply wait until you receive a notification in the notification strip at the top of the page, identifying that the synchronisation has completed.
Once synchronised, you will be able to start using any and all of the tools with AccountKit associating any entries against the applicable clients.

Settings, Update all and Disconnect buttons:

With your XPH connected and the icon turned green, when you hover over this area, the three-dot menu will now give you other functions: Settings, Update all and Disconnect.

Settings - You can choose if you want to keep a one-way or a two-way sync between AccountKit and Xero Partner Hub.

Update All - Once you've synced the first time, you can use this button to force a check of all clients within XPH compared to AccountKit.

Disconnect - Select this option to disable the integration.

No data is lost when you disconnect from XPH, unless you then connect to a different XPH org, at which point you'll likely end up with an odd mismatch of client data. Not recommended.

Integration Details, Bulk Connect & Options

The Xero Partner Hub Icon:

Wherever you see and click on the Xero Partner Hub icon, the colour will identify its status and therefore any context-sensitive options.

Selecting a grey icon will give you the ability to connect / link a client to the integration, if available.
You'll also have the option to bulk connect more than one Xero Orgs.
Selecting a colour icon will give you a context sensitive menu in relation to that client and the associated connected integration.

The file is not connected. Clicking on the grey icon will give you the options to:

Connect
Bulk Connect

Besides the option to Bulk Connect via the Xero icon, selecting more than one account and clicking on the three-dot menu (top right) will also give you the chance to bulk connect.

The file has been connected, and clicking on it will prompt these options:

Update this client from XPH: Utilise this if you wish to force an update from XPH to AccountKit, rather than wait for the 2 hourly sync.
View this client in XPH: Use this to jump straight to the client within XPH.
Post client to XPH: Click on this to manually push an update from AccountKit to XPH.
Change XPH Client ID: Use this only in very specific circumstances, where you have merged a duplicate client in Xero HQ (which can delete the equivalent client in XPH, create a new version of the client, which then duplicates with no data in the client and the original client - including integrations, archived. This is a legacy issue. See below.

The Xero blue file has been connected, and clicking on it will prompt these options:

Status: Click on the arrow down to see a summary of the schedules this file is currently utilised in.
Refresh Xero data: Click on this to refresh the data sent from Xero to AccountKit, and vice-versa.
Go to Xero: Use this to jump straight to the client within Xero.
Disconnect: this will disconnect the Xero blue file to AccountKit. Clicking on this will prompt you with a message that any tools utilising this data will no longer function once you disconnect the file.

XPH Data v's AccountKit Data - Which fields sync?

Across AccountKit and XPH there is a multitude of fields, but not all of them sync with each other. Here's a list showing which fields map to which fields in XPH, by entity type. Note that Affiliates do NOT sync in any way back to XPH.

Things to consider

Where a field is in XPH and not in AccountKit, most times it's because the field is NOT available via the API.
We share a lot of fields between client and contact records, which enables us to merge duplicated contact records back to a client record.
BUT this does mean there are times there are fields in Client and Contact records in AccountKit, that have no corresponding field to sync to in XPH. For example - A contact may have a phone number and mobile number, but if you merge that contact back to a client record, the client record will have both numbers in AccountKit, but in XPH, there will only be the phone number in the client record BUT the merged contact in XPH will get both numbers, since a single Client or Contact record can represent multiple clients / contacts in XPH.

Each line shows the AccountKit field, then the matching XPH field for clients / prospects and, where it applies, for contacts.

First Name → Client / Prospect: First Name
Other Name → Client / Prospect: Other Name
Last Name → Client / Prospect: Last Name
Name → Client / Prospect: Name; Contact: Name
N/A → Client / Prospect: Title
N/A → Client / Prospect: Gender
Set as primary contact → Client / Prospect: N/A; Contact: Set as primary Contact
Position → Client / Prospect: N/A; Contact: Position
Salutation → Client / Prospect: N/A; Contact: Salutation
Addressee → Client / Prospect: N/A; Contact: Addressee
Business Name → Client / Prospect: N/A; Contact: N/A
Entity Type → Client / Prospect: Business Structure; Contact: N/A
Date of Establishment / Birth → Client / Prospect: Date of Birth; Contact: N/A
Date of Death → Client / Prospect: N/A; Contact: N/A
Lodgement Due Date → Client / Prospect: Tax Form Due Date (No API); Contact: N/A
ABN → Client / Prospect: ABN; Contact: N/A
TFN → Client / Prospect: Masked to AK Full to XPH; Contact: N/A
ACN → Client / Prospect: ACN; Contact: N/A
N/A → Client / Prospect: Balance Date; Contact: N/A
N/A → Client / Prospect: Agent; Contact: N/A
N/A → Client / Prospect: Branch/CAC/ICA #; Contact: N/A
Director ID → Client / Prospect: Director ID (No API); Contact: N/A
Description → Client / Prospect: N/A; Contact: N/A
Client Groups → Client / Prospect: Groups; Contact: N/A
Client Notes → Client / Prospect: N/A; Contact: N/A
Phone → Client / Prospect: Phone; Contact: Phone Number
Mobile → Client / Prospect: N/A; Contact: Mobile
Email → Client / Prospect: Email; Contact: Email Address
Fax → Client / Prospect: Fax; Contact: N/A
Skype → Client / Prospect: N/A; Contact: N/A
Website → Client / Prospect: Website; Contact: N/A
Street Address → Client / Prospect: Physical Address; Contact: N/A
Postal Address → Client / Prospect: Post Address; Contact: N/A
Partner → Client / Prospect: Partner; Contact: N/A
Manager → Client / Prospect: Manager
Practice Type → Client / Prospect: Client
Practice Authorities - Tax Return → Client / Prospect: Prepare Tax Form
Practice Authorities - Activity Statement → Client / Prospect: Prepare Activity Statements
N/A → Client / Prospect: Activity Statements Due Date
Practice Authorities - Annual Review → Client / Prospect: N/A
Practice Authorities - others to come → Client / Prospect: N/A
Contact → Client / Prospect: Contact
Contact Of → Client / Prospect: N/A
Relationships → Client / Prospect: Relationship (AK has Unitholder, Share classes and Sibling Relationships)
N/A → Client / Prospect: Client Code
N/A → Client / Prospect: BSB Number
N/A → Client / Prospect: Account Number
N/A → Client / Prospect: Account Name
N/A → Client / Prospect: Financial Institution Name
N/A → Client / Prospect: Fee From Refund
N/A → Client / Prospect: Active ATO Client
N/A → Client / Prospect: Verified Individual
N/A → Client / Prospect: Date Verified
N/A → Client / Prospect: Verification Method
N/A → Client / Prospect: Verified by
N/A → Client / Prospect: Notes

XPH & AccountKit Workflow

In addition to having a direct link through to and ability to update client data in XPH, where you're using AccountKit workflow you can access XPH jobs and tasks directly from the task in AccountKit and post your time directly into XPH via the API integration.

The purpose of the link between AccountKit workflow and XPH is to allow direct access to billing, timesheet and workflow solutions between the 2 systems.

Update XPH Client ID

This item warrants a section all to itself. As mentioned above, when you merge a duplicate client in Xero HQ (eg. XPH Client and Xero Blue Client), depending on the direction you merge, this is what happens:

A new client with identical details is created, but with a different client ID.
The original clients' data (jobs, phone numbers etc) are merged into the newly created client and then deleted.
What this means for any integrations is that we see that the XPH Client ID disappears, and so the client is then archived and a new client is setup. This means any history, integrations etc are left with the archived client and we now have a new version of the client missing all the normal data.

We have implemented a fix that looks for these changes and automatically updates the XPH ID of the old AccountKit client to the new XPH ID, thereby ensuring continuity with the client.

Utilise the "Update XPH Client ID" option to get rid of the duplicate and re-associate the correct client in AccountKit with the new version of the client in XPH by following these steps.

Identify the original client that has all the data and integrations. Here you can see the top entity has the integration and extra detail. This is the original we want to keep.
Select the Green Xero Icon for this entity and push the " Update XPH Client ID " option
Tick the client that you're looking to take the XPH Client ID from and press Update.
Unarchive and then open the client and press save to finalise the relinking process.
What it will do then is:
- Copy the XPH Client ID from the selected client (being the new version of the client in XPH)
- Update the XPH Client ID of the original version of the client with the copied ID.
- Remove the XPH Client ID and archive this new version of the client.
- You'll now have removed the duplicate client and it won't re-archive upon sync anymore.

XPH Sync Errors

On the very rare occasion a sync with Xero will fail. When it does, sometimes the messages aren't terribly useful, but we've identified those that we've come across so far. It's important that when there is a failure, make sure to manually log in to XPH and make the XPH change there also.

503 Service Unavailable: Back-end server is at capacity - This usually means that XPH is actually offline entirely; So you'll need to wait until it's online again before updating any changes.
403 Forbidden: This means that AccountKit is no longer authorised to talk to XPH. This can happen any number of the following ways, but the way to fix is simply to reconnect once again from within Practice Settings > Integrations.
- The user who established the connection has since departed, causing their access token to expire.
- Someone has disconnected the connection either in AccountKit or within XPH.
- The permissions of the user who established the connection has changed.

XPH integration: sync Xero Partner Hub with AccountKit