IPONZ API

The IPONZ API provides a range of functions related to the Intellectual Property (IP) registers for patents, trade marks, and designs. These include:

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.

Please note that the API uses a mixture of data formats as it is a collection of operations previously provided as separate services. It includes SOAP and REST operations, with some using JSON format and some XML format. The data models for XML-based operations are not included in the API definition, the associated schema files and data dictionaries can be downloaded on this page.

Subscribe to the API

Log in and subscribe to the IPONZ API Product using the same RealMe login that you use for the IPONZ website. Our API support team may request further information before the subscription can be approved.

Generate an API subscription key and call the API

For full details on how to generate an API subscription key, and optionally an OAuth2 bearer token for additional security, 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.

Fee payment

Some API operations require payment of an official fee. These operations require that the API subscriber is a registered user of the IPONZ system with a direct debit or direct credit payment set up to get production access. The RealMe login used for subscribing to the API should be the same used to log in to the IPONZ system.

Fees will be invoiced on a monthly basis in the same invoice as fees for all the user's IPONZ transactions via API or website.

API operations with fees are:

REST API operations

The API provides a range of REST operations with JSON data format for renewing IP cases and searching for client records used in the IP registers. The API definition contains full details of the request and response formats for these operations.

Renew patent, trade mark, and design registrations

There are three renewal operations that allow you to check whether a specified patent, trade mark, or design case has a renewal or maintenance fee that is due. If a fee is payable the response shows the amount that will be charged for renewal.

The three renewal POST operations allow registered IPONZ users to pay the renewal or maintenance fee.

Search and retrieve client details

IPONZ client records are the public name and address details of organisations or people that have a role in cases on the IP registers, e.g. applicants, agents, inventors etc. The API provides two operations to search and get details of client records. This can be useful to find the ID of an existing client to use in the applicant details of a patent or trade mark application, or in a trade mark search.

The client search operation (GET /clients) uses the following logic:

  • Search is case insensitive.

  • A client search must include at least two characters of the client name.  

  • The % character may be used as a wildcard to represent zero or more occurrences of characters (including punctuation and spaces) in name and address parameters.  

  • Results are returned for client records with names that contain the name search term. 

  • An address may be optionally included to refine the search. For example, where there are multiple matching client records with similar or identical names it may be useful to specify a city or street name in the address parameter to reduce the number of results.

  • When provided, the address parameter is matched against the three address lines and city held for IPONZ clients, for any address type (physical, postal, and service).  

XML data operations

Get bibliographic data

The API provides a group of operations for retrieving public data from the IP registers.

There are operations that return a list of patents, trade marks, or designs updated in a specified date range, including new applications submitted. There is also an operation to return a list of designs registered in a date range.

If you have the case number for a patent, trade mark, or design you can use this to return the full public information from the register. You may have obtained this number from a variety of sources, including the API operation for listing updated cases or from your own IP portfolio.

Data is returned in an XML format which is not described in the API definition. The schemas and data dictionaries below define the details of the responses for these operations.

XML schemas

Patent information schema Trade mark information schema Design information schema

Data dictionaries

Patent Information data dictionary Trade Mark Information data dictionary Design Information data dictionary

SOAP API operations

IPONZ has provided SOAP APIs for interacting with the register for many years. These functions as described below are included in the IPONZ v5 API as POST operations. The API definition shows the operation path and SOAPAction header but does not include the data model for request and response content. Refer instead to the WSDL, schema, and data dictionary files.

SOAP requests may return a 200 HTTP response even if the request was not successful. The body of the request will include details of an error related to the request data. Response statuses and scenarios are described below.

Search the trade mark register

The POST /trademarksearch operation provides a search of the trade marks register using a reduced set of the search criteria available on the IPONZ website. Search criteria include:

  • Title

  • Date

  • Status

  • Nature

  • Type

  • Owner or agent ID

Results will be returned for up to 2,000 trade marks that match all the search criteria included in the request. If no trade marks match the search criteria an empty ListTradeMarksResponseData element will be returned in the response.

For a general guide on trade mark searches see here.

WSDL and schema

Trade Mark Search WSDL and schema

Data dictionary

Trade Mark Search data dictionary

Submit patent and trade mark applications

The API provides operations for submitting a patent request for entry into national phase (PCT patent application) or a trade mark application.

A PCT patent application request requires the application number of a WIPO published PCT application and details of the New Zealand applicant. Most details will be retrieved from the WIPO application. The request may optionally include an amended specification for examination and a translation of an application published in a foreign language. These documents can be provided within the request as base64 encoded inline elements.

A successful request will return the application number allocated to the patent or trade mark along with details as created in the register.

Refer to the patents and trade marks sections of the IPONZ website for more details about the application and the examination processes.

WSDLs and schemas

Submit Patent WSDL and schema Submit Trade Mark WSDL and schema

Data dictionaries

Submit patent data dictionary Submit Trade Mark data dictionary

Manage correspondence

All communication with IPONZ about IP applications and registrations is managed through the IPONZ case management system. Registered users have an online inbox that shows:

  • Tasks that must be completed by a set deadlines, e.g. when an examination report has issued and needs a response. Tasks must be responded to via the inbox.

  • Formal communication in the form of a notification and optionally an attached document, known as discussions. E.g. notification that a task has been assigned, or that a Trade Mark application was registered (with Registration Certificate and letter attached).

An email notification is sent to the registered user whenever a discussion is sent.

If you are an IP agent or other user with a large IP portfolio that has frequent interaction with IPONZ then the API can be used to significantly reduce the amount of manual effort required for receiving and responding to correspondence. You can fully automate the process of retrieving and loading notifications and documents into your own case management systems.

The API provides functions for working with tasks and discussions as listed below. These functions are used by sending a POST /taskcorrespondence or POST /discussioncorrespondence request with a SOAPAction header.

  • Search your assigned tasks by date, case number, or case reference

  • Get full details of a specified task

  • Respond to a task, including submitting any required documents

  • Search your inbox for discussions by date, case number, or case reference

  • Get full details of a specified discussion

Task and discussion details will also include identifiers for any attached documents. These identifiers can be used in the document download operation.

WSDLs and schemas

Task Correspondence WSDL and schema Discussion Correspondence WSDL and schema

Data dictionaries

Task Correspondence data dictionary Discussion correspondence data dictionary

Download a document

The API provides a SOAP operation to download a specified document from the IPONZ register in Base64 encoded form. The document identifier to use in the request is obtained from one of the other API operations related to Trade Mark Information, Patent Information, Design Information, Trade Mark Search, Task Correspondence, or Discussion Correspondence.

There is no defined limit to the size of the document that can be retrieved, however an error will be returned if the service exceeds a 120 second timeout.

WSDL and schemas

Download Document WSDL and schema

Data dictionary

Download Document data dictionary