We are releasing the Tenancy Bond v3 API in June 2026 which will replace the Tenancy Bond v2 API. Version 2 will be marked as depreciated and will not receive enhancements from that point but will still be available till the end of the year. Version 3 will include some new operations as well as other quality updates to the existing operations.
Testing in sandbox for Tenancy Bond v3 API will be available from mid-April, with version 2 still available for those currently in development. The API definition can be viewed here.
To avoid any complexity and risks associated with mixed-version usage, we will discourage integrating both v2 and v3 endpoints concurrently.
Our recommendation is to fully adopt v3, simplifying both your implementation and our ongoing support of the depreciated API, as our preference is to maintain a single API version where possible.
Tenancy Bond API
The Tenancy Bond API allows users to interact with Tenancy Services to allow registering as a landlord in the system, lodging bonds and checking the status of a bond lodgement.
Using the API
Follow these steps to get up and running:
Read the technical details
View the API definition in our developer portal here. You can also download the definition for viewing in Swagger Editor, SwaggerHub, or other tools.
Subscribe to the API
Log in and subscribe to the Tenancy Bond API Product using the Authorisation code flow/3-legged OAuth method. Our API support team may request further information before the subscription can be approved.
View the Tenancy Bond developer registration and Authentication guide v3.0 for user set up information.
Generate an API subscription key
For full details on how to generate an API subscription key please see here.
Once your subscription has been approved you will be able use your API credentials to successfully call the API. Use the sandbox key and sandbox endpoints in your software development. Once you've completed testing simply use your production keys to access the live service.
Generate an OAuth2 token for user authorisation
There are two authentication options when subscribing to the API.
Most users will require three-legged OAuth subscription. This authentication method is used to ensure that the end user of the initiating system is authorised to perform the operation when used for registering landlords, lodging, viewing and maintaining bonds.
The GET request status operation is an exception, it uses two-legged OAuth subscription, so an additional subscription request may be submitted if access to this operation additionally is required.
Consent is provided by the end user logging in with the RealMe account that they use on the Tenancy Services site. The 3-legged token that is generated in this process can then be used in future requests for retrieving bond and bond lodgement details that the landlord is associated with.
Tenancy Bond API sandbox testing
Base path for sandbox testing:
Currently for version 2:
https://api.business.govt.nz/sandbox/tenancy-services/tenancy-bond/v2/
Version 3 is expected to be available in mid-April in the sandbox environment.
https://api.business.govt.nz/sandbox/tenancy-services/tenancy-bond/v3/
Requests sent to this endpoint will go into ABODE UAT.
If you are already fully registered with RealMe and have subscription keys for V1 or V2 you will not need to renew your subscription.
What you need to do
For current version 2 users we encourage you to plan to move to version 3 when it becomes available.
Reach out to us if you encounter any issues or need support during your build.
Sample data download here used in the API request and responses.
Fee Payment
Refer to the using property management software to complete bond transactions section on the Tenancy website to see how the payments for bond lodgements are set up and processed in production environment.
