Skip to main content
Check out our new content, navigation and design for digital service providers.

COVID-19 - Level 2/3 If you've been affected by COVID-19, we may be able to help. Find out more

The document service enables the transmission of electronic documents between a customer, partner or intermediary and Inland Revenue.

If you have any questions about the document service or using gateway services for the document service, email GatewayServices@ird.govt.nz

How the document service works

When integrated through our gateway services, the document service can be used to:

  • send us electronic documents
  • view previously submitted electronic documents
  • receive electronic documents that we've sent 
  • remove electronic documents submitted by mistake.

Documents used in this service can include:

  • mail we've generated for communicating with customers
  • documents we've requested from a customer
  • documents a customer voluntarily provides us.

We provide documents in PDF format, while documents provided to us can be in many different file formats including PDF, DOC, DOCX, XLSX, TXT, JPG, JPEG, PNG, TIF and ODS. 

Software developer kit (SDK)

View and download the document service software developer kit (SDK) to help you integrate:

  • test scenarios
  • test data
  • sample request and response messages
  • the Open API YAML file
  • the build pack that provides the data definitions for the request and response messages.

Document service software developer kit (SDK) on GitHub


Use the Getting started guide to find out how to access our sandbox (mock services) and test environments.

Getting started guide

Gateway service capability for the document service

The document service provides the following capabilities through defined service operations:

Service operation Description
Create Enables documents to be sent to us electronically.
Read Retrieves a specific identified document (or list of documents) from us.
Update Marks a mistakenly-sent document to be reversed.

Document service business use cases

The following are examples of use cases of the document service operations that could be used to achieve a specific business outcome. The numbers for each use case are the order in which these operations should be called when using this service.

Number Use case Create Read Update
1 Submit documents to Inland Revenue in response to a request for information 1    
2 Submit documents to Inland Revenue to provide supporting information for a return 1    
3 View a list of previously submitted electronic documents
 1  
4 View a submitted electronic document
 1  
5 Remove a document submitted by mistake
   1

Supporting services

Identity and access services

Notifications service