External API Gateway Migration

What is it?

Mulesoft is the replacement system for our existing APIGEE gateway, which is used for managing API products within ACC. This change aligns with ACC’s strategic goals and systems and enables further investment in the API products we offer.

What are the benefits?

Mulesoft provides full lifecycle API management. This is purely a technical change that won’t impact existing services immediately, as we will be supporting APIGEE and Mulesoft in parallel. Mulesoft will also provide a new Developer Portal (replacement for the Developer Resource Centre) for improved experience understanding and working with our products. This is a required change to allow further investment in ACC’s API services.

What is changing?

We are currently developing and migrating the API’s between the systems to allow for a like for like experience. The Developer Portal (to replace Developer Resource Centre) will be available at a later stage.

There a few changes to be aware of during this transition to Mulesoft that may impact you when the changes are released.

This will affect the following API groups:

API Name

API proxy

Claims

/api/v2/claims

Medical Certificates

/api/v2/claims/medical-certificates

Diagnoses

/api/v2/claims/change-diagnosis

Invoices

/api/v2/claims/vendors

Documents v1

/api/v1/documents

Documents v2

/api/v2/documents

Integrated Care Pathways

/fhir/v1/integratedcarepathway

We are asking all products to have accommodated the changes in production by Monday, 31 March 2025.

Note: Due to the Integrated Home and Community Support APIs not being actively used currently, the changes outlined do NOT apply to that set.

 

Changes to the API Endpoints

The host (domain) for our production and compliance endpoints are changing for all Provider APIs.

The resource paths will remain unchanged.

Environment

Current host (domain)

New host (domain)

Production

https://provider.api.acc.co.nz

https://apiservices.acc.co.nz

Compliance

https://provider.api-compliance.acc.co.nz

https://apiservicesnpe.acc.co.nz

The resource path for all APIs will remain unchanged to ensure the ease of integration and compatibility.

 For example, updating the claim submission endpoint for production, would only require changing the host and no changes to the actual resource path: /api/v2/claims

  • Current state:  https://provider.api.acc.co.nz/api/v2/claims
  • Future state:    https://apiservices.acc.co.nz/api/v2/claims

Error Message Changes

There are a few error changes, specifically that relate to authentication which will change. We recommend that you review these changes to determine whether they will impact your customers and apply any necessary changes to your PMS application. All error messages that relate to business or data validations will remain unchanged.

 Please refer to the table below:

Scenario

Current state error response

Future state error response

Using an invalid or expired digital certificate

400 Bad Request

 

<html>

<head>

    <title>400 No required SSL certificate was sent</title>

</head>

<body>

    <center>

        <h1>400 Bad Request</h1>

    </center>

    <center>No required SSL certificate was sent</center>

    <hr>

    <center>server</center>

</body>

</html>

400 Bad Request

 

{

    "code": "400",

    "error": "No required SSL certificate was sent or client certificate validation failed"

}

Using an invalid api key

401 Unauthorized

 

{

    "fault": {

        "faultstring": "Invalid ApiKey",

        "detail": {

            "errorcode": "oauth.v2.InvalidApiKey"

        }

    }

}

401 Unauthorized

 

{

    "error": "Invalid Client"

}

API Keys

API keys will remain unchanged, you can continue to use your existing compliance and production keys to connect to the new endpoints. In future, you will be able to create and manage new API keys through the new developer resource centre once it becomes available. In the meantime, if you require new API keys to use for the new endpoints, please contact digitaloperations@acc.co.nz who will be able to assist you.

Health New Zealand - Te Whatu Ora Districts requiring IP whitelisting

Certain Health New Zealand technology environments do not permit outbound connections to unknown domains. The change to our domains means that they will now resolve to a new set of IP addresses. If your environment has required IP whitelisting to connect to our APIs in the past, and if you are unable to connect to our new domains, we recommend you contact our Digital Operations team. 

Dates of importance

We are planning to make the new versions of all Provider API products available in production from early May 2024. We will advise a date once confirmed. These products will also be available in compliance for connection and verification testing in a non-production environment from this date.

We are asking all external consumers to have accommodated the changes in production by Monday, 31 March 2025.

Tools / Resources

Testing the changes in our Compliance environment

The new endpoints are already available in our compliance environment. We encourage you to test connectivity to our APIs using our new compliance endpoints prior to adopting the production endpoints.

Other Support

Before reaching out, review the support page through Developer Resource Centre | Support Expectations 

For general API related questions refer to Developer Resource Centre | Frequently Asked Questions

Contact for further information

For questions and concerns please email: digitaloperations@acc.co.nz