Consolidating the Xero Practice Manager API: Moving from v3.0 to v3.1

For several years, Xero has maintained two versions of the Xero Practice Manager (XPM) API: v3.0 (Integer-based) and v3.1 (UUID-based). To ensure we can continue to scale our infrastructure and provide better performance, we are now beginning the process of consolidating onto a single version.

Migrate to v3.1 by April 30, 2027, to unlock greater integration efficiency and features

While v3.1 has been available for some time, this 12-month notice marks the start of the formal deprecation period for v3.0. We are encouraging all app partners and developers to migrate to v3.1 to take advantage of improved data handling and to ensure service continuity.

Why migrate to v3.1 now?

Beyond the April 2027 deadline, v3.1 offers significant functional advantages that help you build more efficient integrations:

• JSON Support: On Practice Manager 3.1, endpoints support both XML and JSON. You choose the format using standard Accept and Content-Type headers, and JSON responses use camelCase field names. See documentation for more detail.
• Payload Optimisation (Field Selection): On v3.1, a fields query parameter lets you request just the data you need, and the docs highlight how to use it across core areas like Clients, Jobs, Staff, and Custom Fields.
• Managing “Data Out” Costs: As Xero moves toward usage-based models for data transfer, the ability to limit your payload size via Field Selection and JSON will be a critical tool for managing your integration’s operational costs.
• Expanded Data Sets: v3.1 includes the new Job States endpoint and several new Client fields to ensure parity with the latest XPM UI features:
• New Demographic Fields: Support for DateOfDeath and Place of Birth (City and CountryCode) for individual and sole trader clients.
• UK Region Updates: Dedicated fields for MiddleName and Title for UK-based individual and sole trader clients.
• Universal Identifiers: A dedicated Client Reference Code field (now available across all regions) and read-only Industry / IndustryTitle labels.
• OpenAPI Spec & API Explorer (Next Week): We are currently developing an OpenAPI specification for the XPM API v3.1. This will bring v3.1 into our API Explorer for JSON-based requests, providing an interactive sandbox to test endpoints and view schemas. Please note that the API Explorer will exclusively support JSON, further streamlining the development process for partners moving away from XML.

Your Migration Path

Because v3.1 has existed alongside v3.0, many of you may already be seeing UUIDs in your current payloads. The migration is designed to be low-friction:

1. Map your IDs: v3.0 responses already include UUID fields. If you haven’t already, begin persisting these UUIDs in your database now.
2. Update your Base URL: Switch your requests from /practicemanager/3.0/ to /practicemanager/3.1/.
3. Update your Paths: Replace Integer IDs in your URL paths with the corresponding UUIDs.
4. No Scope Changes: Your existing OAuth 2.0 scopes remain valid. No re-authentication or permission changes are required for this move.

Key Dates to Track

• Now: v3.1 is fully operational and the recommended version for all new development.
• April 30, 2027: v3.0 will be retired and no longer accept traffic.

Next Steps

• Identify V3.0 Traffic: To see if you are still using v3.0, visit the Xero Developer Console, select your app, and navigate to the Logs tab. Use the Filter tool to search for “3.0” in the URL field. This will instantly identify any active requests still hitting the V3.0 endpoints.

• Start storing UUIDs: v3.0 responses already include UUID fields. Begin persisting these in your database now to make your eventual switch a simple ID swap.
• Test the switch: Plan and implement the base URL change to /practicemanager/3.1/ in your demo environment to verify your integration’s data handling.
• Roll out to production: Complete your migration well ahead of the April 30, 2027 deadline to ensure zero service disruption.