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.
Use the Getting started guide to find out how to access our sandbox (mock services) and test environments.
Gateway service capability for the document service
The document service provides the following capabilities through defined service operations:
|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.
|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|