Tips for developers

All data and other material made available via the API constitutes Crown copyright administered by Careers New Zealand. Unless otherwise specified, content produced by Careers New Zealand is licensed under the Creative Commons Attribution 3.0 New Zealand licence.

This means that you are free to copy, distribute and adapt the work, as long as you attribute the work to Careers New Zealand and abide by the other licence terms.

Requests that return multiple results will be displayed as 10 items per page by default. You can change the number of results displayed per page using the limit parameter, up to 100 responses per page.

We limit requests to 500 per 24 hours.

When everything goes well, we'll send the response code 200 along with your data. If there is a problem, you will receive a response with error details formatted in JSON. Error responses will have one of the following HTTP status codes:

• 400 Bad Request – when there was a problem with the request.

• 401 Unauthorized – when you don't provide a valid key.

• 429 Too Many Requests (formerly 412) – when you've gone over your request rate limit.

• 500 Internal Server Error – if we messed up, please let us know.

The 400 Bad Request response is a catch-all, sent if you have incorrect or missing parameters, exceed your API limits or request an unsupported format. The response body will have more detail. When an error occurs its corresponding status line appears in the status field of the error response object rather than in the response header. For example:

{
"userMessage": "Something went wrong",
"developerMessage": "Resource \"WorkflowTransition\" was not found"
}