Frequently Asked Questions

Using our APIs

I'd like to try an API - What are Plans?

A plan is a collection of resources from one or more APIs. A plan can consist of a mixture of operation types (e.g. GET, POST) from different APIs. Plans have rate limits that determine how many requests an application is allowed to make during a specified time interval. Plans can have a common rate limit for all resources, or each resource can have a different rate limit.

You can use this portal to browse the different plans and select one that is most suitable for your requirements. Some plans are available to use straight away, and some are restricted. You can request access to use a restricted plan - we will assess your request and may contact you for more details.

How can I see my API usage?

The number of requests that your application has made to each API is shown on your application page.

Click Apps in the main menu and then click on your application. In the Product Subscriptions table you will see all plans to which your application is subscribed.

For each API under a given plan you can see your usage compared to the rate limit of the plan.

How can I test an API?

It is possible to test an API from this Portal.

When looking at the API details you can see a list of the available operations, including the method and path that can be use to invoke the operation.

Clicking on the operation in the left-hand menu shows detailed information including parameters that it expcets, what it returns, and possible response codes along with their meanings.

There is also a Call Operation button on the API details page which allows you to invoke the operation directly from the developer portal.

If the API requires a client ID and client secret then you can enter these credentials in the Parameters section above the Call Operation button.

Apps

How do I register an Application?

When you create an application you are provided with a client ID and client secret for that application. You must supply these credentials when you call an API that requires authentication.

To register an application, click on Apps in the main menu, and then click Create new App. When you have entered an application name and clicked Submit, a client ID and client secret will be generated.

The client secret can only be viewed now; it is important to make a note of it or you will you have to issue a new one next time you wish to make API calls with your app.

What are the Client ID and Client Secret?

The client ID is the public identifier of your application. It's used in every call so we can tell who is requesting information.

The client secret is the private identifier of your application. This allows us to verify your identity in the authentication step of our APIs.

Your client ID and client secret identify you, and are essential to protecting yourself and your customers. Please keep them safe at all times.

How do I reset my Application Client Secret?

Your client secret is stored encrypted, so we cannot retrieve it if you forget it.

If required, you can generate a new client secret for your application, which will replace the stored value and display the new value to you.

To reset your client secret, click Apps in the main menu, select the relevant application, and then click Reset in the Client Secret section.

Your new client secret will be displayed at the top of the page. Again, be sure to note it down as this can only be viewed now.

Getting Started

What is the API Sandbox?

The Ministry of Social Development (MSD) API Sandbox is an environment that provides access to trial versions of MSD's APIs for partners to use for trials, proof of concepts, or testing purposes.

Our sandbox allows you to make API calls that are functionally the same as those found in our production environment. The sandbox returns mock data so that you can prototype your application as if it were the real thing.

How do I get started on the API Sandbox?

You will need to create an account in the API Sandbox environment - it only takes a few minutes. Once you have an account, you'll be able to manage all your sandbox applications and APIs from one place.

Next, you'll need to create an Application under Apps. Creating an App generates the client ID and client secret credentials that you will use to access sandbox APIs.

When you have registered your application, navigate to the sandbox API you want to use and submit an API subscription request.

Once we receive your subscription request, our team will review it. If your application seems like a good fit, we may contact you for further information, or we may simply approve the subscription.

Once your subscription is approved you will be able to make test calls from your application to the API and receive mock data responses.

I haven't received an activation link, or my activation link has expired or doesn't work. What do I do?

If your activation link doesn't work when you click on it, try to copy and paste the link into a browser instead.

If that still doesn't work, please contact us and we will work to resolve the problem for you.

How can I share visibility of my API subscriptions with others on my team?

When you create an account on the portal, you must then create a Developer Organisation, which you will use to create applications and subscribe to APIs.

When you create a Developer Organisation, you automatically become the 'Organisation Owner'. As Organisation Owner, you can invite other people to join your organisation.

To do this, navigate to the Organisation Details page from your account dropdown menu. From there, click on Add a user, enter the email address they used to create their portal account, select a role, and click invite new user.

The invited user will then be able to join your Developer Organisation and view any associated applications and API subscriptions.

NB: If you choose to delete a Developer Organisation, all applications and API subscriptions associated with that organisation will be deleted.

How can I get Production API access?

When you are ready to request access to a Production API, please contact us.