NATIONAL
STUDENT
INDEX
The Guide To Integrating With the National
Student Index
Specifications for integrating with the Ministry of
Education’s National Student Index System
Version 6.5 March 2016
National Student Index
c/- Ministry of Education Service Desk
Ministry of Education
P O Box 1666
Wellington
Guide to National Student Index - GINS 6.5-final.docx
Page 1 of 148
Table of Contents
Table of Contents ....................................................................................................... 2
1 Introduction ......................................................................................................... 5
1.1
Document Purpose ...................................................................................... 5
1.2
Document Audience ..................................................................................... 5
1.3
Interface Support ......................................................................................... 5
1.4
Contacts ....................................................................................................... 5
1.5
Document Revision History .......................................................................... 6
2 Getting Started .................................................................................................... 8
2.1
What is the National Student Index? ............................................................ 8
2.2
National Student Index queries .................................................................... 8
2.3
What can the NSI system be used to do? .................................................... 8
2.4
What is an NSI record? ................................................................................ 9
2.5
Who needs an NSI record? .......................................................................... 9
2.6
How do Organisations find out about changes to NSI data? ...................... 10
2.7
How can the NSI system be accessed? ..................................................... 10
2.7.1
Web Interface ..................................................................................... 10
2.7.2
REST Interface ................................................................................... 11
2.7.3
Batch File Interface ............................................................................. 11
2.8
What is the difference between the Web, REST and Batch Interfaces? .... 11
2.9
What is the best NSI system interface option for you? ............................... 12
2.10 Integration Considerations ......................................................................... 12
2.11 What next? ................................................................................................. 14
3 NSI Functional Overview ................................................................................... 16
3.1
Introduction ................................................................................................ 16
3.2
Unknown Birth date .................................................................................... 16
3.3
Search ....................................................................................................... 16
3.4
Add / Insert................................................................................................. 18
3.5
Update ....................................................................................................... 19
3.6
Merge Request .......................................................................................... 22
3.7
Change Notifications .................................................................................. 22
3.7.1
Changed Field Indicator ...................................................................... 23
3.8
Challenge ................................................................................................... 24
3.9
Create/Update Student Provider Relationships.......................................... 24
4 Web Interface .................................................................................................... 26
4.1
Overview .................................................................................................... 26
4.2
Security and Authentication ....................................................................... 27
5 REST Interface.................................................................................................. 28
5.1
What is REST? .......................................................................................... 28
Guide to National Student Index - GINS 6.5-final.docx
Page 2 of 148
5.2
Accessing the API ...................................................................................... 28
5.3
Authentication – ESAA OAuth.................................................................... 29
5.3.1
ESAA Environment URLS................................................................... 30
5.3.2
Privilege levels .................................................................................... 30
5.3.3
Authentication and Authorisation Errors.............................................. 30
5.4
API details .................................................................................................. 30
5.4.1
Naming standard ................................................................................ 30
5.4.2
Dates .................................................................................................. 31
5.4.3
JSON .................................................................................................. 31
5.4.4
Encoding ............................................................................................. 31
5.4.5
Query string parameter encoding ....................................................... 31
5.5
Result codes and messages ...................................................................... 32
5.6
REST API Resources ................................................................................ 33
5.6.1
Session Resource ............................................................................... 33
5.6.2
Student Functions ............................................................................... 33
5.6.3
The student resource .......................................................................... 33
5.7
REST Function Details ............................................................................... 40
5.7.1
Create NSI Session via REST ............................................................ 40
5.7.2
Search Request via REST .................................................................. 43
5.7.3
Add Student Record via REST ........................................................... 50
5.7.4
Modify Student Record via REST ....................................................... 61
5.7.5
Request to Merge Student Records via REST .................................... 70
5.7.6
Create / Update Student Provider Relationship (SPR) via REST ....... 74
5.7.7
Logout of the NSI via REST ................................................................ 78
6 Batch File Interface ........................................................................................... 80
6.1
Overview .................................................................................................... 80
6.2
Accessing the Batch interface .................................................................... 80
6.2.1
Batch File Types ................................................................................. 80
6.2.2
Batch File Format ............................................................................... 81
6.2.3
File Naming Conventions .................................................................... 81
6.2.4
Delimited File Footers ......................................................................... 82
6.2.5
Uploading/Downloading Batch Files ................................................... 83
6.3
Security and Authentication ....................................................................... 83
6.4
Batch File Functions .................................................................................. 85
6.4.1
Search Request File ........................................................................... 85
6.4.2
Update/Insert Batch File ..................................................................... 85
6.4.3
Merge Request Batch File .................................................................. 87
6.4.4
Change Notification Batch Files .......................................................... 87
6.4.5
Student-Provider Relationship (Add / Update) .................................... 87
6.5
Automated Upload/Download of Batch Files .............................................. 88
6.5.1
Login to the NSI through Batch Interface ............................................ 89
Guide to National Student Index - GINS 6.5-final.docx
Page 3 of 148
6.5.2
Logout from the NSI through the Batch Interface ................................ 91
6.5.3
Automated Upload of Batch files ......................................................... 93
6.5.4
Automated Download of Batch Files ................................................... 93
6.6
Delimited Batch File Formats ..................................................................... 94
6.6.1
Encoding ............................................................................................. 94
6.6.2
Search ................................................................................................ 95
6.6.3
Update/Insert ...................................................................................... 99
6.6.4
Merge Request ................................................................................. 104
6.6.5
Student-Provider Relationship (ATA) Add / Update .......................... 107
6.6.6
Change Notifications ......................................................................... 110
6.7
XML Batch File Formats .......................................................................... 111
6.7.1
Encoding ........................................................................................... 111
6.7.2
Search .............................................................................................. 112
6.7.3
Update/Insert .................................................................................... 118
6.7.4
Merge Request ................................................................................. 126
6.7.5
Student-Provider Relationship (ATA) Add/Update ............................ 130
6.7.6
Change Notifications ......................................................................... 134
7 Appendix B: Glossary of Terms....................................................................... 136
8 Appendix C: Error Codes ................................................................................ 138
9 Appendix D: Related Documents .................................................................... 144
9.1
Web Interface User Guide........................................................................ 144
9.2
NSI Web UI Learning Module .................................................................. 144
9.3
NSI Web UI Quick Reference Guide (QRG) ............................................ 144
9.4
ESAA Application Form ........................................................................... 144
10
Appendix E: REST Code Example .............................................................. 145
10.1 Encode username and password ............................................................. 145
10.2 Get Authentication token from ESAA ....................................................... 145
10.3 Create an NSI session ............................................................................. 146
10.4 Send NSI request ..................................................................................... 147
10.5 Logout using NSI session token in request header .................................. 147
Guide to National Student Index - GINS 6.5-final.docx
Page 4 of 148
1 Introduction
1.1 Document Purpose
This document explains the necessary requirements to enable your organisation /
application to integrate with the National Student Index (NSI) system. It explains the
NSI functionality and details each of the options available for integration with the
NSI.
1.2 Document Audience
This document is written for Organisations, their NSI users and those developing
systems that interface with the NSI. The first part of this document deals with
business processes and general matters relating to integration. This includes section
2 (Getting Started) through to section 3 (NSI Functional Overview).
The final part of this document deals with the technical aspects of integrating the NSI
with your systems. This includes section 4 Web Interface onwards.
1.3 Interface Support
IMPORTANT NOTE:
Please be aware that this Guide for Integrating with the NSI (GINS) is valid as at
issue date.
The Ministry reserves the right to upgrade interfaces to ensure compliance with
current industry standards, and to meet future business requirements.
We will provide notice to known users of the interfaces of changes impacting on
them.
Support for legacy interfaces will be withdrawn after a notified ‘sundown’ period.
The Ministry has made available a test version of NSI (Compliance) for use by
Vendors / providers when testing their interface with NSI.
The Compliance database is refreshed from Production on the 1st Tuesday of every
month.
1.4 Contacts
Matters relating to the scope and nature of the NSI or requests for technical support
in integrating with the NSI system should be addressed to:
National Student Index
c/- Ministry of Education Service Desk
Ministry of Education
Guide to National Student Index - GINS 6.5-final.docx
Page 5 of 148
P O Box 1666
Wellington
or emailed to:
service.desk@education.govt.nz
or call the MoE Service Desk on 0800 422 599
1.5 Document Revision History
This section records any major updates applied to this document since version 4.4.
Specifically, it lists the document version number and date and describes the
changes.
Date
Revision Sections
Changed
Description of Changes
15/12/2014 5.0
Various
NSI Replacement Version released
22/12/2014 5.1
Various
Updates based on Vendor feedback:
Section 1.2 – last paragraph –
reference corrected
Document revision history updated
Added Section 3.2 Unknown Birth
date
Clarifications in Section 3.7 Change
Notifications
Clarifications in Section 3.9 Create /
Update Student Provider
Relationships
Clarification in Section 5.7.7.2
Clarification in Section 5.5.2.1
Clarification in Section 5.5.4.1
Change of font in Section 6.5.4.1
Clarification in Section 6.5.5.1.1
Change of font in Section 6.6.4.1
Corrected last tag in Section 6.6.5.1
Clarifications and font change in
Section 6.6.5.1.1
Clarification in Appendix C - Error
message 290
11/02/2015 5.3
Various
Tidy up of document for final release
01/05/2015 5.4
Various
Accept all changes for final release
of GINS
07/07/2015 5.5
Various
Minor updates made to add further
information for vendors
Addition of the REST code example
Guide to National Student Index - GINS 6.5-final.docx
Page 6 of 148
03/02/2015
Date
Revision Sections
Changed
Description of Changes
09/07/2015 5.6
Various
Accept all changes for release of
GINS
22/07/2015 6.0
Various
Remove the XML and SOAP
Interface details into separate
documents
Update the REST code examples to
reference the correct URLs
24/02/2016 6.1
Various
Various - Update Service desk email
address
1.3 – Reference Compliance
environment
3.3 – Specify the use of ~ in search
4.2 – Reference NSI timeout period
5.3 – Updated reference to Appendix
E (REST code examples)
5.6.3 – Separated Alt Name from
student resource
5.7.2.2.1.1 – Alternate Name(s) may
be included in output from NSN
search
5.7.5.1.1 – Update Resource URL
6.2 – New section - Accessing the
Batch Interface
10.1 – Updated encoding result
24/2/2016
Various
Accepted Tracked changes (v6.1)
07/03/2016 6.3
5.2 Accessing
the API
Corrected REST Production URL
01/06/2016 6.4
5.4
Added ESAA URL’s as references
for authentication
01/08/2016 6.5
5.6.3
Date formatting specs corrected.
Removed leading space and added
third milliseconds digit.
6.2
Guide to National Student Index - GINS 6.5-final.docx
Page 7 of 148
2 Getting Started
2.1 What is the National Student Index?
The National Student Index (NSI) is a database system maintained by the Ministry of
Education and is the education sector’s core register of learner identity data.
The NSI is used to allocate a unique identifier, a National Student Number (NSN) to
every student in New Zealand. Each student should only be allocated one NSN
which will be used throughout their early childhood, school and tertiary education.
An NSN will be allocated to a student when they first enrol in early childhood
education, a school or tertiary education in New Zealand.
NSNs are required to be included for every student reported to the Ministry for
example in the Single Data Returns (SDRs). This allows information about each
student to be linked together.
2.2 National Student Index queries
The day-to-day operation of the NSI is managed by the Ministry of Education's
Service Desk.
Specifically, the Service Desk is responsible for helping organisations to start using
the National Student Index (NSI), establishing and maintaining access privileges,
distributing documentation and informational material and providing ongoing
technical and operational guidance. Organisations can contact the Ministry of
Education's Service Desk with questions or requests. Phone 0800 422 599 or email
service.desk@education.govt.nz.
2.3 What can the NSI system be used to do?
The NSI system is available for organisations to perform searches on existing
records, add new records, update existing records and to request that two or more
duplicate NSI records be merged.
Organisations can use student information from the NSI for enrolment purposes as
well as for reporting to the Ministry, TEC and NZQA.
Individuals can request a copy of their information held on the NSI. Where required,
they can submit a request for their information to be corrected through the MoE
Service Desk by providing appropriate documentation.
Guide to National Student Index - GINS 6.5-final.docx
Page 8 of 148
2.4 What is an NSI record?
An NSI record is unique to a student and records basic identification details. The
fields on an NSI record include:
 Family name
 Three Given names
 Birth date (DoB)
 Gender
 Residential status
 Record status
 Date of death
 Alternative names
 A preferred name indicator
 Verification indicators for the name & birth date fields and for the residential
status field
An NSI record can have one of two statuses with an associated Record status
reason. These are:
1) Active – the record is in use on the NSI application.
a) In use – the student record is used by the NSI application and can be
Searched for and Updated.
2) Inactive – the record has been made inactive for one of the following reasons:
a) Slave – following the receipt of a request to merge two or more student
records. Once the merge request is processed, the duplicate record(s) will be
marked as a ‘Slave’ record and linked to the ‘Master’ record.
b) Deceased – following the receipt of notification and supporting documentation
of a student’s death from an Organisation
c) Created in error – following the receipt of notification of an incorrectly created
student.
d) Do not use – following the receipt of notification that this record should not be
used.
2.5 Who needs an NSI record?
NSI records will be created for individuals who:
 Enrol in a New Zealand Early Childhood Education provider.
 Enrol in a New Zealand school.
 Register for the NCEA
 Enrol or seek to enrol with a tertiary organisation
All type “D” students (as defined in the Ministry of Education’s Single Data Return
manual) must have a corresponding NSI record with verified name, birth date and
residential status to claim student achievement component (SAC) funding.
Guide to National Student Index - GINS 6.5-final.docx
Page 9 of 148
2.6 How do Organisations find out about changes to NSI data?
To ensure that changes to NSI records are communicated to organisations that need
to know, a record of a student’s ‘relationship’ with an organisation is maintained by
the NSI system. When an NSI record is added or updated by an organisation, that
NSN is marked as having a ‘relationship’ with that organisation.
Any changes made to an NSI record will be notified to all organisations that have
requested to receive change notifications and have a current ‘relationship’ with the
student via the change notification process. Change notifications applicable to an
organisation will be available for viewing on the NSI web interface. Files may be
downloaded from the web interface or through the Batch Interface. For example, if a
Student’s Birth date is updated by an organisation, all the organisations which have
a relationship with that student will be notified.
If a student dies, the change notification process will also be used to inform all
organisations that have either a current or expired ‘relationship’ with the student.
2.7 How can the NSI system be accessed?
The NSI system can be accessed only by authorised people from:
 ECE Services
 Schools (via the ENROL system)
 NZQA
 Tertiary Education Organisations
 Tertiary Education Commission (TEC)
 Ministry of Education support staff.
Providers may wish to access the NSI through a chosen Student Management
System (SMS). Individual SMS applications will integrate with the NSI through the
REST and/or BATCH interfaces.
The NSI system can be accessed in any of three different ways. These three
methods are all offered so that you can choose the ones which are best suited to
your organisation. Please note that all new providers will need to go through a go live
process before they are given access to the NSI system. Login details and
information about the go live process can be obtained from the Ministry of Education.
MoE Service Desk (0800 422 599 or email service.desk@education.govt.nz)
The interface options are:
2.7.1 Web Interface
The NSI web site allows users to perform NSI functions which will be processed
immediately. All functionality (including additional functionality such as raising a
Challenge, viewing reports, viewing Merge status, viewing Change Notifications that
is not available through other interfaces) can be accessed by providers who are
Guide to National Student Index - GINS 6.5-final.docx
Page 10 of 148
authorised to do so. No special integration is required to use this interface other than
the need to have a valid username and password to log in with REST Interface
2.7.2 REST Interface
The REST interface allows SMS systems to integrate with NSI data and functionality,
over a standardised protocol. This allows the maintenance of your student records to
remain in your SMS software, while sending and retrieving data from NSI in the
background.
Integration with the REST interface requires custom development, which is covered
later in this document.
2.7.3 Batch File Interface
A batch file interface will be available to allow organisations to submit requests for
NSI searches, additions, updates, and merges and the creation/updating of student
relationships. Depending on the SMS implementation, as actions are carried out on
the SMS, batch files may accumulate an organisation’s requests for searches,
additions, updates, and merge requests and the creation/updating of student
relationships for the NSI system to perform.
The batch file is sent by the organisation to the NSI system for processing by the NSI
system. For each batch file processed by the NSI, a result file is generated that
reports the outcome of batch file processing. This result file will be available for
organisations to download and will then need to be loaded into the SMS.
2.8 What is the difference between the Web, REST and Batch Interfaces?
The web interface is online and does not require systems integration. Organisations
will access it using a browser in the same way that they access any other Internet
web site. A go-live process is in place for training new providers before they can
access the system.
The REST interface is also an online method of connecting with the NSI, but will
operate behind the scenes via the SMS. This means that systems which use this
interface option can expect to send requests and receive responses from the NSI
over the Internet, but the direct user interaction will be only with their SMS. In order
for this interface to work, the organisation will need to be connected to the Internet,
sending information and waiting for a response.
The batch file interface option involves the accumulation of any NSI interaction into
batches of requests to the NSI system, placing these requests into files and then
transmitting them to the NSI for processing. The files returned from the NSI can then
be uploaded into the SMS with any errors or exceptions being processed manually.
Batch files and results can be uploaded and downloaded either via the NSI Web
interface, or via an automated interface between an SMS and the NSI.
Guide to National Student Index - GINS 6.5-final.docx
Page 11 of 148
It should be noted that for functions available on multiple interfaces, the actions
performed on the NSI system are the same, regardless of the interface method used.
2.9 What is the best NSI system interface option for you?
The variety of interfaces means that a provider can utilise the method (or
combination of methods) that fits best with their existing business processes. Most
smaller organisations may use only the NSI web interface. However larger
organisations may use more than one type of interface. For example, an
organisation’s staff interacting with students may use the NSI web interface but the
batch process may be used during peak enrolment periods to send and receive NSI
data for that organisation’s students.
2.10 Integration Considerations
The NSI system and processes have been designed to be as flexible as possible. This
means that you can implement them in your own organisation in the way that best fits
with your current practice. Depending on which interface(s) you decide to implement
you should consider the following points:
1. How does the data in your SMS map to NSI data? (e.g. Family names in the
NSI can be 100 letters in length which may differ from your SMS, and Given
name(s) may not be stored in separate fields on your SMS which means
they will need to be parsed before being passed to the NSI)
2. When you are searching for an NSN do you want to check your own SMS
records first before making a call/request to the NSI system? This is
recommended.
3. If using the batch interface, how will you manage the creation and purging of
batch files? How will you manage the storage of inbound and outbound
batch files? How will you manage the distribution of batch results to the
originating requestor?
4. If you are using the REST interface, do you want to ask your developer to
restrict the number of search results that are displayed to the users of your
SMS? (the NSI will return up to 100 results per search request)
5. What changes, if any, are required to be made to your database?
6. How will you move data between your SMS and the NSI?
7. When you change student data on your SMS how will these changes be
passed to the NSI (where relevant)?
8. When students re-enrol or change their details ‘in person’ do you want to
print-off their NSI details and ask them to sign the printout?
9. What type of security do you wish to have in place when connecting with the
NSI?
Guide to National Student Index - GINS 6.5-final.docx
Page 12 of 148
The following diagram sets out some of the key factors to consider when selecting
the most appropriate interface(s) to use:
It is suggested that the decision about which NSI interface(s) to use be made in
consultation with your SMS vendor/developer.
Guide to National Student Index - GINS 6.5-final.docx
Page 13 of 148
2.11 What next?
You will need to take the following steps to start using the NSI:
 Step 1: Contact MoE Service Desk
Your organisation’s CEO or Head of IT or Academic Registrar (or equivalent)
should contact the MoE Service Desk to make arrangements for your
organisation to start using the NSI. Please note that if you are intending to
implement the batch or an online interface that you will need to contact the MoE
Service Desk at least three months before you want to start using the NSI
system.
 Step 2: Determine Interface and Make System and/or Business Process
Changes (if required)
The information in section 2.9 will help you to determine the best interface or
interfaces for your organisation. This decision will need to be made in conjunction
with considering your student administration business processes, and liaison with
your SMS supplier or in-house IT developer.
Depending on the interface(s) you implement, changes may need to be made to
your SMS or the way in which you manage students’ personal information. The
specifications for the online and batch interfaces are set out in the following
sections:
Web Interface – refer to section 4
REST Interface – refer to section 5
Batch File Interface – refer to section 6
Before implementing any systems changes it is recommended that consideration
be given to the points set out in section 2.10, and that a decision be made as to
which staff within your organisation will use the NSI.
 Step 3: Perform Testing
If you are using the REST or Batch interfaces then you will need to carry out
testing prior to using the NSI. Your testing will need to include the sending of data
or files. The MoE Service Desk will assist you through this process.
If you are testing an integrated online interface you will also have to perform
specific tests with the MoE Service Desk before being allowed live access to the
system.
 Step 4: Data Load
The final step in preparation before using the NSI is to load your existing records
into the NSI system. This means that when you go live your students will already
have NSI records. Again, the MoE Service Desk will help you with the data load
to ensure that the process is successful.
Guide to National Student Index - GINS 6.5-final.docx
Page 14 of 148
Note that depending on the size of your organisation it may be preferable to
begin the data load before step 3 (above) is completed. The data load process
may take several weeks depending on the number of students you have.
 Step 5: Go Live
Your organisation can start using the NSI system once the data load is finished,
testing has been completed, and a date has been agreed with the MoE Service
Desk.
Guide to National Student Index - GINS 6.5-final.docx
Page 15 of 148
3 NSI Functional Overview
3.1 Introduction
This section details the functions available to organisations via any of the three NSI
interface options. Where there is a difference in the way the function operates that
arises because of the interface option used, it is mentioned in brief here and detailed
later in the section relating to that option.
All of the functions available for searching, adding or updating NSI records, or
requesting a merge, require a predefined set of information to be passed to the NSI.
Similarly, each of the functions will return a predefined set of information to the
requestor.
This information falls into one of two categories: mandatory or optional. The
information which is passed to, and returned from, the NSI functions is identified in
the detailed sections that follow. That which is mandatory is clearly indicated.
3.2 Unknown Birth date
Where a student’s birth date is recorded in the NSI database as unknown, the REST
and Web UI interfaces will return ‘Unknown’ to represent an unknown birth date. A
birth date of 11/11/1918 will be returned in batch and other legacy outputs from the
NSI to the providers representing an unknown birth date.
When a birth date of 11/11/1918 is received by the NSI, it will be treated by the NSI
as an unknown birth date.
3.3 Search
The search facility is used to search for students in the NSI database. Searches can
be performed using only the NSN (NSN search) or using a student’s name and other
fields (Criteria search).
It is highly recommended searches which do not include NSN, include the student’s
full name (Family and Given name(s)) and Birth date.
NSN search: Direct lookup. The result will always be an exact match with one NSI
record, unless it does not exist or is invalid.
Criteria search: This will search for the student by the following parameters:
 Student name (‘main’ name and ‘alternative’ names will be searched); there
will be some allowance for variance in spelling of names and additional given
names.
Guide to National Student Index - GINS 6.5-final.docx
Page 16 of 148


Birth date, it is highly recommended the birth date is included in a criteria
search to increase the reliability of search results. There will be some
allowance for ‘close’ birth dates (e.g. 01/10/1988 and 01/10/1989).
The tilde symbol ‘~’ can be used in addition to one single name when the
student has only one name.
Each record returned in a search will be given a score to indicate the likelihood of
match of the returned record.
The score returned for each match is determined by the search software. The NSI
Search software uses probabilistic matching which incorporates the following logic:
 Transposed birth dates
 Variations in spelling
 Phonetics, etc.
For example, a search of the family name “Petersen” and Birth date “13/09/78” may
return:
Score
NSI Name
Date of Birth
086
Lyndon Neville Petersen
13/09/1978
079
Claire Elizabeth Peterson
13/09/1978
072
Kerrie Elizabeth Peterson
03/09/1978
If a record exists on the NSI database that exactly matches the search criteria
entered, (name and birth date), then the results will be returned with a score of 100.
Note that multiple records may be returned.
For example: a search of Given name 1 “Lyndon”, Family name “Petersen” and Birth
date “13/09/78” may return:
Score
NSI Name
Date of Birth
100
Lyndon Neville Petersen
13/09/1978
100
Lyndon Petersen
13/09/1978
And a search of Given name 1 “Lyndon”, Given name 2 “Neville”, Family name
“Petersen” and Birth date “13/09/78” would return:
Score
NSI Name
Date of Birth
100
Lyndon Neville Petersen
13/09/1978
Guide to National Student Index - GINS 6.5-final.docx
Page 17 of 148
It is also possible that you may get a single result returned that is not considered an
Exact match, or a Definite match. For example, a search of Given name 1 “Neville”,
Family name “Petersen” and Birth date “13/09/78” would return:
Score
NSI Name
Date of Birth
85
Lyndon Neville Petersen
13/09/1978
Please note – Alternative name matches: When performing a search it is
important to be able to display all names returned for a single NSI record.
Alternative names as well as main names will be returned in the search results
(where they match the criteria entered).
A user must be able to accept an alternative name back into their SMS without
having to perform a change to where the name sits on the NSI record.
Why? The NSI is a means to identify a student and can hold multiple names for one
student. Student records have a ‘main name’ and as many ‘alternative names’ as
required.
3.4 Add / Insert
The add facility is used to create new NSI records. Before adding a record a search
must have been performed in order to confirm that the student being added does not
already have a NSI record.
REST and BATCH add requests automatically initiate the prerequisite search.
When adding (inserting) a student into the NSI, it is recommended you provide
verification of the data on the student record. For example, if you have sighted the
student’s passport, you can pass in ‘P’ for Name & birth date verification and
Residential status verification. Once a student records details have been verified, the
data cannot be updated (see ‘Updating NSI records’ section for more information on
updating existing NSI records)
As well as verifying a student record, it is important to enter the name of the student
as it appears on the verification document, as well as other student details you are
verifying. When entering a name in the NSI, the name will be saved in exactly the
same case as entered. For example if the name is entered as “John LaRose”, it will
be saved in NSI as “John LaRose”. The NSI system will not change the case of
“LaRose” to “Larose”. Alternatively if the name is entered as “jOhN”, it will be saved
in NSI as “jOhN”.
Guide to National Student Index - GINS 6.5-final.docx
Page 18 of 148
Definite match - If a record already exists that the NSI considers a ‘Definite match’
(a search result which has a score high enough to be over the NSI determined
threshold) a new student record cannot be added. The NSN of the ‘Definite match’ is
returned to the user who can either use that NSI record, or if you know the student
record matched is a different student to the one you are trying to add to the NSI, you
can raise a challenge against the matched student and submit supporting
information to the MoE Service Desk who can add the record for you.
Possible match - If a record already exists that the NSI considers a ‘Possible match’
(a search result which has a score high enough to be over the NSI determined
threshold for ‘Possible matches’ but not high enough to be considered a ‘Definite
match’) a user must confirm the addition of the student record after reviewing the
details of the ‘possible matches’.
Through the Web Interface, this is achieved via a confirmation button, the BATCH
interface and the REST service will provide the user with an override code which
can be used to add the new record if the user is certain that they are dealing with a
different student to the one which has been found on the NSI. The NSI will require
this override code to be included in a subsequent request to add the record.
No matching records - Where no matches are returned from the prerequisite
search, the student record will be added and the new NSN will be returned to the
user. The user ID, organisation code and date of creation are recorded with that
record.
3.5 Update
The update facility is used to update existing NSI records. Updating a record in the
NSI requires that an NSN be provided to identify the record being changed. Updates
will be initiated when, for example, a student changes their name or residential
status.
It is important to note that when entering a name in the NSI, the name will be saved
in exactly the same case as entered. For example if the name is entered as “John
LaRose”, it will be saved in NSI as “John LaRose”. The NSI system will not change
the case of “LaRose” to “Larose”. Alternatively if the name is entered as “jOhN”, it will
be saved in NSI as “jOhN”.
Updating Birth Date of NSI Records
Birth date can only be modified by users in the following scenarios:


The user logged in is logged in as the provider organisation which created the
student record within a certain time period (currently set at 90 days) before
the modify date
o In this case, if the Name & birth date verification has been either ‘Birth
register’ verified, or verified by MoE, it cannot be modified.
The birth date is ‘Unknown’
Guide to National Student Index - GINS 6.5-final.docx
Page 19 of 148
Outside of these scenarios, birth date cannot be modified. If you believe the birth
date on a student record is incorrect, you can raise a challenge to the MoE Service
Desk with supporting documentation to get the birth date updated. Where a user
attempts to update a birth date through the legacy interfaces (XML, SOAP, and
Batch) and does not meet the rules to be able to do so, the NSI system will return
error #305. Through the REST interface, the NSI system will return error #957.
Verified NSI Records
Users cannot update name and birth date information when it is verified on a student
record (unless the birth date is being modified and it is in one of the scenarios given
above). Residential status information can be modified unless it is verified by ‘Birth
register’ or by MoE.

Where an organisation has evidence that the verified details of a student are
incorrect, a challenge can be raised on the web interface and supporting
documentation can be forwarded to the MoE Service Desk who can update
the record.

Where an NSI record already has a verified name and a user wishes to add
another name by which the student is known, whether verified or not, this
name can be added as an alternative name.
Error messages
Where a user attempts to modify either name or birth date and it is verified, the
following message will be returned.
Where Name & birth date verification is any verification other than ‘Birth register’ and
is not verified or verification is confirmed by MoE and a user is modifying name
and/or Birth date and/or Name & birth date verification
274
Cannot modify verified data.
Where Name & birth date verification is ‘Birth register’ and a user is modifying name
and / or Birth date AND where Residential status verification is ‘Birth register’ and a
user is modifying Residential status
369
BDM verified fields cannot be modified.
Where Name & birth date verification is any verification other than ‘Birth register’ and
is verified or verification is confirmed by MoE and a user is modifying name and / or
Birth date AND where Residential status verification is verified or verification is
confirmed by MoE and a user is modifying Residential status
290
Cannot change Ministry of Education verified data.
Editable fields
Guide to National Student Index - GINS 6.5-final.docx
Page 20 of 148
The following table defines fields that are ‘Locked’ in each scenario when updating a
student record.
Primary name and Birth date fields. The top row specifies the value for ‘Name & birth
date verification:
‘Birth
Verified Verified (not Birth
register’ by MoE register)
‘Unverified’
Primary name
Locked
Locked
Locked
Editable
Birth date
Locked
Locked
Locked
(Unless user created
the record – see
‘Update birth date’
rules.)
Locked
(unless user created
the record or Birth
date is ‘Unknown’ –
see ‘Update birth
date’ rules)
Name & birth
date
verification
Locked
Locked
Locked
Editable
Residential status. The top row specifies the value for ‘Residential status verification:
‘Birth
Verified Verified (not Birth
register’ by MoE register)
‘Unverified’
Residential
status
Locked
Locked
Editable
Editable
Residential
status
verification
Locked
Locked
Editable
Editable
Other Student fields can be updated as follows:
Editable fields
Insert-able fields
Gender
Alternative name
Preferred name indicator
Alternative name verification
(not ‘M’ – Birth register)
Record status and Reason (MoE
only)
Date of Death (MoE only)
Multiple Field Updates
If the update request (where a valid NSN is supplied) includes any data that
represents a change to locked data on a verified NSI record, even if it also contains
changes to editable fields, it will result in an error.
Guide to National Student Index - GINS 6.5-final.docx
Page 21 of 148
In order to update editable fields, the request must either contain no information in
the locked fields, or exactly the same information for the record being updated. This
must be supplied in conjunction with the NSN and the updated data in the editable
fields.
Unverified NSI Records
Where a student’s name can be updated (an unverified name), full name details
should be supplied. For example, if a student exists as ‘Sarah Wallace’ on the NSI
and you wish to update the information to ‘Sarah Jane Wallis’, all of the name fields
must be supplied in the input files. When the ‘main name’ fields are updated, the
original main name will be added as an alternative name for the student (where the
names are not duplicates).
Notification of updates
Changes to an NSI record will be notified to all organisations recorded in the NSI
system as having an active “Student-Provider relationship (SPR)” with the student,
via the change notification facility (See 3.7 Change Notifications)
3.6 Merge Request
Where an organisation believes there are multiple NSI records for one student, a
request to merge the student records can be submitted to the NSI.
There are three potential outcomes of a merge request:
 Merge approved: Where NSI determined criteria is met, the NSI records will
be merged and the user will be notified of the single NSN to continue to use
as the students NSN.
 Merge requires manual intervention: Where NSI determined criteria for merge
approval are not met, the merge request will be lodged with the MoE Service
desk to be considered and approved or declined as appropriate. (They may
request supporting documentation to justify the Merge request, for example, a
copy of a marriage certificate may be supplied to support a merge of records
with two very different names).
 Merge rejected: Where the submitted records are not appropriate for a merge
request (e.g. too many NSNs submitted, Invalid NSNs submitted) the merge
request will be rejected. The user will need to rectify the error and re-submit
the request.
3.7 Change Notifications
The change notification facility communicates NSI student data changes to
organisations that have requested to know about the changes. Where an
organisation has requested to receive change notifications (arrange this via MoE
Service Desk), they will be able to receive notification of changes to NSI records that
are recorded as having a “Student-Provider relationship (SPR)” with that
organisation.
Guide to National Student Index - GINS 6.5-final.docx
Page 22 of 148
Organisations can request Change notifications as often as required (change
notifications will not automatically be sent to providers, they must be requested via
the web or batch interface).
When an organisation retrieves change notifications they can choose to either:
 Receive changes made to student records since the last date (and time)
change notifications were generated (up to 12 months in the past)
 Through the web interface users can request to view changes made over a
specified time period (not exceeding six months from date of request)
Change notification files will be available for download from the NSI web interface or
can be downloaded via the Batch Interface (this will require SMS integration).
When the NSI is notified of a student’s death, all organisations with either a current
or expired relationship with the student will be notified of the student’s death via the
change notification process.
3.7.1 Changed Field Indicator
The Change Notification files include a Changed Field indicator which allows the
recipient to determine which fields have been changed. The Changed_field_indicator
field will be populated using an integer number (which has an implied binary coded
decimal nature) that is derived in the following way:
Changed Field
Decimal
Value
master_nsn
1
surname
2
forename1
4
forename2
8
forename3
16
gender
32
preferred_name_indicator
64
dob
128
dod
256
name_dob_verification
512
residential_status
1024
residential_status_verification
2048
nzqa_paid
4096
student_status
8192
Guide to National Student Index - GINS 6.5-final.docx
Page 23 of 148
The “changed_field_indicator” will be set to the sum of the decimal values attributed
to the fields changed allowing an organisation to determine the field(s) that have
changed in each change notification record.
NOTE: The ‘nzqa_paid’ field is a legacy field that is no longer stored in the NSI. It will
never be updated. The flag will be returned in the results file to support applications
that have been integrating with the NSI before the replacement application. The
returned value will always be ‘U’
3.8 Challenge
A facility to challenge a change made to an NSI record is available on the NSI web
interface. This may be used, for example, if two records have been merged and a
user believes this to have been incorrect, or if the user believes that some verified
information on a student record is incorrect.
Using the Challenge function available on the Web interface (URL is:
https://nsi.education.govt.nz/), search for the NSN, register a challenge, including
the reason for the challenge. This will then be submitted to the MoE Service Desk for
consideration. Supporting documentation can be emailed separately to the NSI team
at nsi.unit@education.govt.nz
3.9 Create/Update Student Provider Relationships
A Student-Provider Relationship (SPR) records the relationship between an
organisation and an NSI record. The purpose of an SPR is to ensure organisations
are notified of NSI record changes (see 3.7 Change Notifications section for more
details) to student records which may impact them.
The list of students ‘SPR’s’ is maintained within the NSI. When an NSI record is
added or updated by an organisation, an SPR is created (or updated if it already
exists) between the student and the organisation.
The duration of an SPR for a student is determined by the ‘SPR duration’ for each
provider. The SPR duration specifies how long a Student-Provider relationship will
exist between the provider and student. The default period is 1 year, any alteration to
this period may be advised to the MoE Service Desk.
When the SPR duration between the organisation and that student is reached, the
relationship will be marked as ‘expired’ but will not be deleted. This allows historical
relationship information to be recorded.
SPRs can be maintained through the REST and Batch Interfaces through the
following services:
 REST: Create/update SPR
 Batch: ATA file upload.
Guide to National Student Index - GINS 6.5-final.docx
Page 24 of 148
SPRs may be maintained for the following reasons:
 A provider re enrols a student, but has no updates to make to the student’s
details. Updating their SPR will ensure the provider receives Change
Notifications about the student prior to the provider submitting their SDR
information.
 A provider wishes to amend the default relationship period for a student.
(Note if a different SPR duration is desired to be applied to all students for a
provider it is recommended that the SPR duration for the provider is updated.
This can be done by contacting MoE Service Desk.)
Guide to National Student Index - GINS 6.5-final.docx
Page 25 of 148
4 Web Interface
4.1 Overview
The NSI web interface allows all of the NSI functions to be accessed over the
Internet. Simply access the Ministry’s NSI web interface,
(https://nsi.education.govt.nz/), login using your Education Sector Authentication
(ESAA) login. The following functions will be available to you via the Web Interface:
 Student search
 Add Student
 View Student (including History)
 Modify a Student
 Request merges
 View Merge Request status
 Raise a Challenge
 View or download change notification result files
 Upload or download batch files as required
 Access reports
Actions performed against the NSI database using the web interface are effected
immediately, with users performing NSI-based actions interactively.
Transferring data from your SMS to the NSI and back again will be a manual
operation via the web interface. The web interface is not designed to be integrated
with an SMS.
The NSI web interface Uniform Resource Locator (URL) could be integrated with
your SMS to make the linking from your system to the NSI as seamless as possible,
although this is not required. You may also choose to have the NSI web interface
URL recorded as a “favourite” in your web browser.
The NSI web interface URL is: https://nsi.education.govt.nz/
Once you have launched a browser and have logged into the NSI web interface, the
NSI functionality is there and ready to be used.
The best place to learn more about how to use and navigate around the NSI web
interface is the NSI Web Interface User Guide. See Appendix D for the link to this
document.
Guide to National Student Index - GINS 6.5-final.docx
Page 26 of 148
The following browser versions were supported by the Ministry at the time this
document was written1 :
Browser
Internet Version
Internet Explorer
Version 8.0-10.0
Firefox
Current Version (mid 2014)
Chrome
Current Version (mid 2014)
In order to use the site successfully, browsers will need to be JavaScript enabled.
4.2 Security and Authentication
When entering the web interface, you will be prompted to enter your user name and
password. The MoE Service Desk must have established this for you in order for you
to gain access. If you require this to be set up for you, please either contact the MoE
Service Desk (0800 422 599 or email service.desk@education.govt.nz)
Any NSI session will time out after 20 minutes of inactivity. Users will be required to
log into NSI again in order to continue using the functionality. The 20 minutes starts
from when the session token is issued and is reset each time there activity against
the NSI database.
1
Here supported means that the browser or operating system has been tested and is known to
enable the core functionality of the NSI system.
Guide to National Student Index - GINS 6.5-final.docx
Page 27 of 148
5 REST Interface
This section explains the necessary requirements to enable your application to
integrate with the National Student Index (NSI) system using the REST interface and
the NSI functionality available through REST.
5.1 What is REST?
REST (REpresentation State Transfer) is a common standard for online interfaces. It
uses a definition of a resource (e.g. a student), and allows a range of actions for it.
The HTTP protocol is leveraged to communicate more clearly:
 Different HTTP verbs are used (GET, PUT (update), POST (create), etc)
 HTTP response codes help differentiate success, security checking and
validation responses.
 The URL helps describe which resource is being accessed (e.g.
/student/13),
 HTTP headers are used to transmit auxiliary information not part of the
resource e.g.: The security token.
5.2
Accessing the API
Base URL for all API queries:
 https://{site URL}/API/{version}/
Key notes:
 The REST API will be versioned. This document describes ‘v1’. This allows
for future versions, while maintaining backwards compatibility with v1.

The API must be accessed over SSL

Environment URLs for production and compliance are:
o Production: https://nsi.education.govt.nz/api/V1
o Compliance: https://nsi.compliance.education.govt.nz/api/V1
Example template for detailed queries:

Base URL: https://{site URL}/API/{version}/{resource}/[{params}]

NSI Authentication token in the header for all operations, bar Login

{params} to identify current resource (retrieve (GET) operations)

HTTP-Body properties for appropriate HTTP verbs (PUT, POST)
Guide to National Student Index - GINS 6.5-final.docx
Page 28 of 148
5.3
Authentication – ESAA OAuth
Authentication to the NSI REST interface involves MoE’s ESAA single sign-on (SSO)
platform. To login to the NSI system, you are required to have signed in with the
ESAA SSO, and have retrieved a valid ESAA token. Logging into the NSI system will
return an NSI auth token, which will be required for all subsequent NSI API calls.
This NSI token will be supplied in the HTTP header – not part of the main body
payload. See Appendix E for REST code examples.
Diagram – NSI Login sequence:
Guide to National Student Index - GINS 6.5-final.docx
Page 29 of 148
5.3.1 ESAA Environment URLS

Environment URLs for production and compliance are:
o Production: https://security.education.govt.nz/
o Compliance: https://ppsecurity.education.govt.nz/
All requests (with the exception of login) require a valid NSI auth token, and will
return the standard HTTP response codes if the token is invalid:
 401 – Unauthorized
o The NSI token supplied is not valid

403 – Forbidden
o The current user is not authorized to perform that given action
5.3.2 Privilege levels
ESAA provides users with one of the following levels of access:
 Student search only

Access to all API calls described in this document
5.3.3 Authentication and Authorisation Errors
The following messages will be returned where Authentication / authorisation has
failed:
Trigger
HTTP Code Response
Session token not supplied
401
Session token invalid / expired
401
User does not have permission to access the function
(i.e. User does not have permissions to update a
student)
403
5.4
API details
5.4.1 Naming standard
MoE has chosen title case as its naming standard for entities and resource names.
This simply means that ‘names’ all start with a capital letter.
E.g.: A hypothetical example:
{
“FamilyName”: <family name>,
"Given1Name” : <given name (1)>,
Guide to National Student Index - GINS 6.5-final.docx
Page 30 of 148
"BirthDate": <birth date>,
"NameBirthDateVerification: <name & birth date verification>
}
5.4.2 Dates
Dates use the UTC format: yyyy-MM-ddTHH:mm:ss
 E.g.: 2013-11-28T14:35:24
5.4.3 JSON
NSI REST API will use JSON formatting. Example request & response objects in this
document are given as JSON.
HTTP headers for JSON:
Content-Type: application/json
Accept: application/json
5.4.4 Encoding
The NSI REST results will be UTF-8 encoded.
Diacritics and special characters (other than ‘~’ for Given name 1) will not be
accepted by the NSI system. Where diacritics are submitted to the NSI, the following
error message will be returned
Error code
Description
272
{0} must only contain alphabetic characters, space, hyphen,
apostrophe or a single '~'. Space hyphen and apostrophe cannot be
used without another character or repeated. Names must start with
an apostrophe or an alphabetic character.).
5.4.5 Query string parameter encoding
Arguments passed in the query string must be URL encoded.
e.g.: In the example below, the spaces are encoded to ‘%20’. And the characters ‘?’,
‘=’ and ‘&’ are part of the standard query string syntax, so remain:
/student/?FamilyName=Van%20Der%20Name&Given1Name=Person
Guide to National Student Index - GINS 6.5-final.docx
Page 31 of 148
5.5
Result codes and messages
All result codes and descriptions will be passed back to interfacing systems as an
array, allowing a single or multiple errors to be returned to a user if required.
Client applications may perform business logic based on specific error code IDs, but
the content of the error code message may change over time. Parsing text from the
message content is not supported/recommended.
The result codes and descriptions will be returned in the following format:
{
“MessageList”: [
{
“MessageCode”: <error/info code1>,
“MessageDescription”: <error/info description1>
}
]
}
Where there are multiple validation errors resulting from a particular input request,
they will all be returned to the interfacing system in the format below.
{
“MessageList”: [
{
“MessageCode”: <error/info code1>,
“MessageDescription”: <error/info description1>
},
{
“MessageCode”: <error/info code2>,
“MessageDescription”: <error/info description2>
}
]
}
Field Definitions
Label / Field
Type/Length
Description
MessageCode
Alphanumeric (10)
Relevant NSI message code
MessageDescription Alphanumeric (300)
Guide to National Student Index - GINS 6.5-final.docx
Relevant NSI message description
Page 32 of 148
5.6
REST API Resources
The NSI system will provide the following resources to interfacing systems. This
section defines the fields and structure of each resource. This information is
referenced within the specific function details to avoid replication.
5.6.1 Session Resource
Available operations:
Operation
REST Verb
Resource URL
Create NSI Session
POST
session/
Logout
DELETE
session/
5.6.2 Student Functions
Available operations:
Operation
REST Verb
Resource URL
Search
GET
Student/<NSN>
Search
GET
Student/<Search params>
AddStudent
POST
Student/
ModifyStudent
PUT
Student/
5.6.3 The student resource
The following student resource is used in all Student operations. Some fields are
read-only, and will only be present on a Student GET. For Add and Modify, the
submit fields are specified under the ‘Inputs’ section for each function, for clarity.
Resource
Response Body (JSON)
Student
{
"NSN" : <nsn>,
“FamilyName” : <family name>,
"Given1Name" : <given name (1)>,
"Given2Name" : <given name (2)>,
"Given3Name" : <given name (3)>,
"PreferredName": <preferred name>,
"Gender": <gender>,
"BirthDate": <birth date>,
"NameBirthDateVerification": <name birth date
verification>,
"NameBirthDateVerifiedBy": <name birth date verified
by>,
Guide to National Student Index - GINS 6.5-final.docx
Page 33 of 148
Resource
Response Body (JSON)
"NameBirthDateVerifiedDate": <name birth date verified
date>,
"NameBirthDateVerificationConfirmedByMoe": <verification
confirmed by moe (name & birth date verification)>,
"ResidentialStatus": <residential status>,
"ResidentialStatusVerification": <residential status
verification>,
"ResidentialStatusVerifiedBy": <residential status
verified by>,
"ResidentialStatusVerifiedDate": <residential status
verified date>,
"ResidentialStatusVerificationConfirmedByMoe":
<verification confirmed by moe (residential status
verification)>,
"DeathDate": <date of death>,
"RecordStatus": <record status>,
"RecordStatusReason": <record status reason>,
"CreatedDate": <created date>,
"CreatedByUserId": <created by userid>,
"CreatedByProviderCode": <created by provider code>,
"MatchScore": <score>,
"MatchIndicator": <match indicator>,
"AltNameList": [AltName – See separate definition]
}
Alt Name definition:
AltName
{
"AltFamilyName": <alternative family name>,
"AltGiven1Name": <alternative given name (1)>,
"AltGiven2Name": <alternative given name (2)>,
"AltGiven3Name": <alternative given name (3)>,
"PreferredName": <alternative preferred name indicator>,
"AltNameBirthDateVerification": <alternative name birth
date verification>
}
Field definitions:
Field
Type/Length
Description
NSN
Numeric (10)
The NSN of the record.
Guide to National Student Index - GINS 6.5-final.docx
Page 34 of 148
Field
Type/Length
Description
FamilyName
Alphanumeric (100)
The surname of the student found.
Given1Name
Alphanumeric (100)
The first given name of the student
found.
Given2Name
Alphanumeric (100)
The second given name of the student
found.
Given3Name
Alphanumeric (100)
The third given name of the student
found.
PreferredName
Boolean
Indicates whether or not this name is set
as the preferred name for the student.
Values can be:
 true
 false
Gender
Alphanumeric (1)
The gender of the student.
Values can be:
 Male (M)
 Female (F)
 Unknown (U)
BirthDate
Alphanumeric (20)
The birth date of the student.
Values can be:
 Date eg. 1980-12-09
 ‘Unknown’
When a date is entered, format must
meet the following format:
 Format: yyyy-MM-dd e.g. 201311-31
NameBirthDateVer Alphanumeric (1)
ification
The verification method used to verify
the name and birth date.
Values can be:
 Unverified (U)
 Passport (P)
 Birth certificate (B)
 Birth register (M)
 Other (O)
NameBirthDateVer Alphanumeric (10)
ifiedBy
Read-only
The provider code of the provider that
verified the name and birth date data.
Guide to National Student Index - GINS 6.5-final.docx
Page 35 of 148
Field
Type/Length
Description
NameBirthDateVer Date/Time (20)
ifiedDate
Read-only
The date and time the Name & birth
date verification was set for the student
record
 Format: yyyy-MMddTHH:mm:ss.mss
e.g. 2013-11-28T14:35:24.001
NameBirthDateVer Boolean
ificationConfirmed Read-only
ByMoe
Indicates whether the Name & birth date
verification for the student record has
been verified by the Ministry of
Education.
Values can be:
 true
 false
ResidentialStatus
Alphanumeric (1)
The residential status of the student.
Values can be:
 NZ Citizen (C)
 NZ Permanent resident (P)
 Australian citizen (A)
 Overseas (O)
 Unknown (U)
ResidentialStatus
Verification
Alphanumeric (1)
The method used to verify the
residential status.
Values can be:
 Unverified (U)
 Passport (P)
 Birth certificate (B)
 Birth Register (M)
 Other (O)
ResidentialStatus
VerifiedBy
Alphanumeric (10)
Read-only
The provider code of the provider that
verified the Residential status.
ResidentialStatus
VerifiedDate
Date/Time (20)
Read-only
The date and time the Residential status
verification was set for the student
record
 Format:“yyyy-MMddTHH:mm:ss.mss” e.g. “201311-28T14:35:24.001”
Guide to National Student Index - GINS 6.5-final.docx
Page 36 of 148
Field
Type/Length
Description
ResidentialStatus
VerificationConfir
medByMoe
Boolean
Read-only
Indicates whether the Residential status
verification for the student record has
been verified by the Ministry of
Education
Values can be:
 true
 false
DeathDate
Date/Time (20)
Read-only
The date of death of the student.
 Format: yyyy-MM-dd e.g.201311-28
RecordStatus
Alphanumeric (1)
Read-only
The status of the record.
Values can be:
 Active (A)
 Inactive (I)
RecordStatusReas Alphanumeric (100)
on
Read-only
Description of record status.
Values can be:
 In Use
 Deceased
 Created in error
 Do not use
CreatedDate
Date/Time (20)
Read-only
The date and time the record was
created.
 Format:“yyyy-MM-ddTHH:mm:ss”
e.g.“2013-11-28T14:35:24”
CreatedByUserId
Alphanumeric (200)
Read-only
The User ID of the user that created the
record.
CreatedByProvide
rCode
Alphanumeric (10)
Read-only
The associated provider code of the
user that created the record
See “Field Definitions – Alt Name”
AltNameList
The following are only displayed for student search (including ‘Add’ prerequisite
search):
MatchScore
Numeric (10)
Read-only
Guide to National Student Index - GINS 6.5-final.docx
The match score attributed to the
returned record.
Where the search was an NSN search,
score returned will be 100
Only returned for SEARCH and ADD
student.
Page 37 of 148
Field
Type/Length
Description
MatchIndicator
Numeric (10)
Read-only
Which name on the record contained
the match
 0 = Primary name of master
record
AltNameId‘ = 0 and Master NSN
= NSN
 2 = Alternate name of master
record
AltNameId‘ > 0 and Master NSN
= NSN
Only returned for SEARCH and ADD
student.
Field definitions – Alt Name
Field
Type/Length
Description
AltFamilyName
Alphanumeric (100)
The alternative family name of the
student.
AltGiven1Name
Alphanumeric (100)
The alternative first given name of the
student.
AltGiven2Name
Alphanumeric (100)
The alternative second given name of
the student.
AltGiven3Name
Alphanumeric (100)
The alternative third given name of the
student.
PreferredName
Boolean
Indicates whether or not this name is set
as the preferred name of the student.
Values can be:
 true
 false
AltNameBirthDate
Verification
Alphanumeric (1)
The method used to verify the Name
and Birth date for the alternative name.
Values can be:
 Unverified (U)
 Passport (P)
 Birth certificate (B)
 Birth register (M)
 Other (O)
Guide to National Student Index - GINS 6.5-final.docx
Page 38 of 148
Other fields returned / submitted:
Field
Type/Length
Description
NSISessionToke
n
Alphanumeric (36)
Session token to be used in subsequent
calls.
OrgID
Alphanumeric (10)
Organisation ID of User logging in
OverrideCode
Numeric (10)
NSN + 1
If returned then the process has
determined that there is at least one
student already in the database that
could possibly match the criteria to be
inserted.
ProviderCode
Alphanumeric (10)
The provider code of the provider that
the NSI record will have a relationship
with (when creating a SPR)
ActiveUntilDate
Date/Time (20)
Date student provider relationship will
expire
 Format: yyyy-MM-dd e.g. 201311-28
ESAAAccessTok
en
<Defined by ESAA –
not an NSI field>
ESAA Access Token as retrieved from
OAuth.
Guide to National Student Index - GINS 6.5-final.docx
Page 39 of 148
5.7 REST Function Details
The following sections specify the requirements for each function available for the REST interface.
5.7.1 Create NSI Session via REST
This function creates a session with the NSI system by logging the user in. This function will be used to ensure that the user
performing the call has the necessary security privileges set and stored within ESAA.
In order to gain access to the NSI, users will submit a login request to ESAA, which will contain their username and password.
Refer to the REST code example for details on how to login to ESAA. Once the login to ESAA has been successful, ESAA will
return an ESAA access token to the user which is then passed through to the NSI system in the below Create NSI Session request.
Once the NSI system receives this ESAA access token, NSI will validate that the token is valid before returning an NSI session
token, which is then used in subsequent calls to the NSI system.
Guide to National Student Index gins
Page 40 of 148
5.7.1.1 Create NSI Session Function - Inputs
5.7.1.1.1 Input Function Syntax
Operation
REST Verb
Resource URL
Header payload
Body Payload (JSON)
Create NSI
Session
POST
session/
Content-Type
{
”ESAAAccessToken” : <esaa access token>,
“OrgID” : <orgid>
}
5.7.1.1.2 Input Data Fields
Field
Type/Length
Content-Type
Description
Requirement
Indicates the "type" associated with the message body's byte
sequence. Must read “application/json”
Mandatory
Message #789
ESAAAcessToken
<Defined by ESAA – not ESAA Access Token as retrieved from OAuth.
an NSI field>
Mandatory
Message #257
Message #513
OrgID
Alphanumeric (10)
Mandatory
Message #257
Message #339
Guide to National Student Index - GINS 6.5-final.docx
Organisation ID of User logging in
Page 41 of 148
5.7.1.2 Create NSI Session Function – Outputs
5.7.1.2.1 Output Function Syntax
The following table explains the returned HTTP response message passed over the HTTPS medium for each Create NSI Session
request and the relevant NSI messages sent back. As REST uses the existing HTTP protocols, the returning message will include
an HTTP response code and if required, a JSON message which will include the NSI error message code and descriptions.
Operation Status
HTTP Code
Response
Response Header
Response Body (JSON)
Create
NSI
Session
Successful login
200
NSISessionToken
<none>
Not authenticated
401
Result message details – section 5.5
Message #513
Not authorised
403
Result message details – section 5.5
Message #515
Message #521
Bad request
400
Result message details – section 5.5
Message #257
Message #339
Message #1283
Bad syntax
500
Result message details – section 5.5
Message #789
Guide to National Student Index - GINS 6.5-final.docx
Page 42 of 148
Message
5.7.2 Search Request via REST
There are two types of search requests that can be performed:
1. NSN search – Where an NSN is provided
2. Match search – Where an NSN is not provided but other information is provided to search the NSI system
5.7.2.1 Search Function – Inputs
5.7.2.1.1 Input Data Syntax (NSN Search)
Operation
REST Verb
Resource URL
Header payload
Body Payload (JSON)
Search
GET
Student/<NSN>
NSISessionToken
<none>
5.7.2.1.2 Input Data Fields (NSN Search)
Field
Type/Length
Description
Requirement
NSISessionToken
Alphanumeric (36)
Session token returned from previous Login Call
Mandatory
Message #257
Message #528
NSN
Numeric (10)
The NSN of the student to search for.
Mandatory
Message #257
Guide to National Student Index - GINS 6.5-final.docx
Page 43 of 148
5.7.2.1.3 Input Data Syntax (Match Search)
Operation
REST Verb
Resource URL
Header payload
Query string parameters
Search
GET
Student/<params>
NSISessionToken
“FamilyName”=<family name>,
"Given1Name"=<given name (1)>,
"Given2Name"=<given name (2)>,
"Given3Name"=<given name (3)>,
“BirthDate”=<birth date>
E.g.: ?FamilyName=Smith&Given1Name=Joe
5.7.2.1.4 Input Data Fields (Match Search)
Field
Type/Length
Description
Requirement
NSISessionToken
Alphanumeric (36)
NSI Session token returned from previous Login Call
Mandatory
Message #257
Message #258
FamilyName
Alphanumeric (100)
The surname of the student to be searched for.
Mandatory
Message #257
Message #272
Given1Name
Alphanumeric (100)
The first given name of the student to be searched for.
Mandatory
Message #257
Message #272
Guide to National Student Index - GINS 6.5-final.docx
Page 44 of 148
Field
Type/Length
Description
Requirement
Given2Name
Alphanumeric (100)
The second given name of the student to be searched for.
Conditionally
mandatory if
Given name (3)
provided
Message #257
Message #272
Given3Name
Alphanumeric (100)
The third given name of the student to be searched for.
Optional.
Message #272
BirthDate
Alphanumeric (20)
The birth date of the student. Values can be:
 Date eg. 1980-12-09
 ‘Unknown’
Optional, but can
only be used if
name is
submitted
Message #304
Message #305
Message #945
Message #951
When a date is entered, format must meet the following
format:
 yyyy-MM-dd e.g. 2013-11-31
Guide to National Student Index - GINS 6.5-final.docx
Page 45 of 148
5.7.2.2 Search Function – Outputs
The following tables explain the returned HTTP response message passed over the HTTPS medium for each search request and
the relevant NSI messages sent back. As REST uses the existing HTTP protocols, the returning message will include an HTTP
response code and if required, a JSON message which will include the NSI error message code and descriptions.
5.7.2.2.1 Matched records
5.7.2.2.1.1 Output Function Syntax
For each matched record found the following fields will be returned. NOTE: The matched name will be returned for each matched
student record including the AltName List if relevant and if only one NSN was returned.:
Operation Status
Search
Successful –
match found
HTTP Code
Response
Response Header
Response Body (JSON)
200
NSISessionToken
{
“Students” : [
{Student Resource – section
5.6.3}
],
“MessageList” : [NULL]
}
Guide to National Student Index - GINS 6.5-final.docx
Page 46 of 148
Message
Operation Status
Search
Successful – more
than 100 matches
found
HTTP Code
Response
Response Header
Response Body (JSON)
Message
200
NSISessionToken
{
Message #784
“Students” : [
{Student Resource – section
5.6.3}
],
“MessageList” : [
{Result message details –
section 5.5}
]
}
Guide to National Student Index - GINS 6.5-final.docx
Page 47 of 148
5.7.2.2.2 Errors
5.7.2.2.2.1 Output Function Syntax
 If no records are found an error message will be returned (No matches found)
 If there is an error with the submitted search criteria, an error message will be returned (Bad request)
Operation
Status
HTTP Code
Response
Response Header
Response Body (JSON)
Message
Search
No matches found
200
NSISessionToken
{
Message #785
“Students” : [NULL],
“MessageList” : [
{Result message details –
section 5.5}
]
}
Bad request
400
NSISessionToken
{
“Students” : [NULL],
“MessageList” : [
{Result message details –
section 5.5}
]
}
Guide to National Student Index - GINS 6.5-final.docx
Page 48 of 148
Message #012
Message #257
Message #272
Message #304
Message #305
Message #337
Message #945
Message #951
Operation
Status
HTTP Code
Response
Response Header
Response Body (JSON)
Message
Not Authorised
401
NSISessionToken
{
Message #257
Message #528
“Students” : [NULL],
“MessageList” : [
{Result message details –
section 5.5}
]
}
Guide to National Student Index - GINS 6.5-final.docx
Page 49 of 148
5.7.3 Add Student Record via REST
The NSI System will search the NSI using the information supplied in the Add Request. Depending on whether matches are found
above the Add Definite Match Threshold a new record will be added or an override code returned.
5.7.3.1 Add Student Record Function – Inputs
5.7.3.1.1 Input Data Syntax
Operation
REST Verb
Resource URL
Header payload
Body Payload (JSON)
AddStudent
POST
Student/
Content-Type
NSISessionToken
{
Optional:
?OverrideCode=
<override code>
Guide to National Student Index - GINS 6.5-final.docx
"FamilyName": <family name>,
"Given1Name": <given name (1)>,
"Given2Name": <given name (2)>,
"Given3Name": <given name (3)>,
"PreferredName": <preferred name>,
"Gender": <gender>,
"BirthDate": <birth date>,
"NameBirthDateVerification": <name birth
date verification>,
"ResidentialStatus": <residential status>,
"ResidentialStatusVerification":
<residential status verification>,
"AltNameList": [
{
"AltFamilyName": <alternative family name>,
"AltGiven1Name": <alternative given name
(1)>,
"AltGiven2Name": <alternative given name
(2)>,
Page 50 of 148
Operation
REST Verb
Resource URL
Header payload
Body Payload (JSON)
"AltGiven3Name": <alternative given name
(3)>,
"PreferredName": <alternative preferred
name indicator>,
"AltNameBirthDateVerification":
<alternative name birth date verification>
}
]
}
5.7.3.1.2 Input Data Fields
Field
Type/Length
Content-Type
Description
Requirement
Indicates the "type" associated with the message body's byte
sequence. Must read “application/json”
Mandatory
Message #789
NSISessionToken
Alphanumeric (36)
Session token returned from previous Login Call.
Mandatory
Message #257
Message #528
FamilyName
Alphanumeric (100)
The family name of the student.
Mandatory
Message #257
Message #272
Given1Name
Alphanumeric (100)
The first given name of the student.
Mandatory
Message #257
Message #272
Guide to National Student Index - GINS 6.5-final.docx
Page 51 of 148
Field
Type/Length
Description
Requirement
Given2Name
Alphanumeric (100)
The second given name of the student.
Conditionally
mandatory if
Given name (3)
provided
Message #257
Message #272
Given3Name
Alphanumeric (100)
The third given name of the student.
Optional
Message #272
PreferredName
Boolean
Value specifying that this name is the preferred name. Values
can be:
 true
 false
Mandatory
Message #257
Message #409
Gender
Alphanumeric (1)
The gender of the student. Values can be:
 Male (M)
 Female (F)
 Unknown (U)
Mandatory
Message #257
Message #288
BirthDate
Alphanumeric (20)
The birth date of the student. Values can be:
 Date eg. 1980-12-09
 ‘Unknown’
Mandatory
Message #257
Message #304
Message #305
Message #945
Message #951
When a date is entered, format must meet the following
format: Format: yyyy-MM-dd e.g. 2013-11-31
Guide to National Student Index - GINS 6.5-final.docx
Page 52 of 148
Field
Type/Length
Description
Requirement
NameBirthDateVerific
ation
Alphanumeric (1)
The verification method used to verify the name and birth
date. Values can be:
 Unverified (U)
 Passport (P)
 Birth certificate (B)
 Other (O)
Mandatory
Message #257
Message #275
ResidentialStatus
Alphanumeric (1)
The residential status. Values can be:
 NZ Citizen (C)
 NZ Permanent resident (P)
 Australian citizen (A)
 Overseas (O)
 Unknown (U)
Mandatory
Message #257
Message #309
ResidentialStatusVeri
fication
Alphanumeric (1)
The verification method used to verify the residential status.
Values can be:
 Unverified (U)
 Passport (P)
 Birth cert (B)
 Other (O)
Mandatory
Message #257
Message #409
AltFamilyName
Alphanumeric (100)
The alternative family name for the student.
Conditionally
Mandatory if
Alternative given
name (1) is
supplied
Message #257
Message #272
Guide to National Student Index - GINS 6.5-final.docx
Page 53 of 148
Field
Type/Length
Description
Requirement
AltGiven1Name
Alphanumeric (100)
The alternative first given name for the student.
Conditionally
Mandatory if
Alternative family
or Alternative
given name (2) is
supplied
Message #257
Message #272
AltGiven2Name
Alphanumeric (100)
The alternative second given name for the student.
Conditionally
Mandatory if
Alternative given
name (3) is
supplied
Message #257
Message #272
AltGiven3Name
Alphanumeric (100)
The alternative third given name for the student.
Optional
Message #272
PreferredName
Boolean
Value specifying that this name is the preferred name. Values
can be:
 true
 false
Conditionally
Mandatory. if
Alternative family
name is supplied
Message #257
Message #409
Guide to National Student Index - GINS 6.5-final.docx
Page 54 of 148
Field
Type/Length
Description
Requirement
AltNameBirthDateVer
ification
Alphanumeric (1)
The verification method used to verify the name and birth
date. Values can be:
 Unverified (U)
 Passport (P)
 Birth certificate (B)
 Other (O)
Conditionally
Mandatory. if
Alternative family
name is supplied
Message #257
Message #275
OverrideCode
Numeric (10)
Indicates that the record should be added despite the known
existence of a possible matching record already in the NSI
database. The value will be the same as that returned by the
previous attempt to add a record.
Optional
Message #942
Guide to National Student Index - GINS 6.5-final.docx
Page 55 of 148
5.7.3.2 Add Student Record Function – Outputs
There are four different outputs, depending on the outcome of the add request.
 Successful addition
 Close/Possible match found (override code returned) - A possible match is when a record is found that matches the details
entered as part of the add request, and the matching record has a score between the Possible match threshold and the Add
Definite match threshold.
 Definite/Exact match found (record not added) – A definite match is when a record is found that matches the details entered
as part of the add request, and the matching records has a score higher than the Add Definite match threshold. The
matching record will be returned with an error message and error description.
 Error code and description. If there are any issues with the input, an error message and description will be returned back to
the user.
The following tables explain the returned HTTP response message passed over the HTTPS medium for each add request and the
relevant NSI messages sent back. As REST uses the existing HTTP protocols, the returning message will include an HTTP response
code and if required, a JSON message which will include the NSI error message code and descriptions.
Guide to National Student Index - GINS 6.5-final.docx
Page 56 of 148
5.7.3.2.1 Successful Addition of a student record
Where a record has been added successfully, the fields returned are as follows:
5.7.3.2.1.1
Output Function Syntax
Operation
Status
HTTP Code
Response
Response Header
Response Body (JSON)
Message
Add
Successful
200
NSISessionToken
{
Message #025
Message #939
Message #941
“NSN”: <NSN>,
“MessageList” : [
{Result message details –
section 5.5}
]
}
Guide to National Student Index - GINS 6.5-final.docx
Page 57 of 148
5.7.3.2.2 Possible Match found and Override Code returned
An override code is generated when a record with a score between the Add Possible match threshold and the Add Definite match
threshold is found, and then returned with the most closely matched NSN(s). If an override code is returned then the user must
check whether the student details they hold match the NSN(s) returned. If the results are a match, the user should use the returned
NSN in their system. If they are certain the NSN does not match their student’s details, they must submit the Add Student Record
request again, this time supplying the override code returned by the previous call.
An override code is calculated by adding 1 to the NSN of the closest matched record. For example: If the add request finds a
possible match on NSN 11, the override code returned will be 12.
5.7.3.2.2.1
Output Function Syntax
Operation
Status
HTTP Code
Response
Response Header
Response Body (JSON)
Message
Add
Conflict
409
NSISessionToken
{
Message #021
Message #942
“OverrideCode” : <override
code>,
“PossibleMatches”: [
{Student resource – see
section 5.6.3}
],
“DefiniteMatchNSN”: null,
“MessageList”: [
{Result message details – see
section 5.5}
]
}
Guide to National Student Index - GINS 6.5-final.docx
Page 58 of 148
5.7.3.2.3 Definite/exact match found
When a record is found that has a score above the Add Definite match threshold, the system will return the NSN of the record with
the highest score above the Add Definite match threshold
5.7.3.2.3.1
Output Function Syntax
Operation
Status
HTTP Code
Response
Response Header
Response Body (JSON)
Message
Add
Conflict
409
NSISessionToken
{
Message #921
“OverrideCode” : null,
“PossibleMatches”: null,
“DefiniteMatchNSN”: <NSN>,
“MessageList”: [
{Result message details – see
section 5.5}
]
}
Guide to National Student Index - GINS 6.5-final.docx
Page 59 of 148
5.7.3.2.4 Errors
5.7.3.2.4.1 Output Function Syntax
Operation
Status
HTTP Code
Response
Response Header
Response Body (JSON)
Message
Add
Bad request
400
NSISessionToken
Result message details – section 5.5
Message #023
Message #027
Message #257
Message #272
Message #275
Message #276
Message #288
Message #304
Message #305
Message #321
Message #409
Message #945
Message #951
Unauthorised
401
NSISessionToken
Result message details – see section
5.5
Message #257
Message #528
Forbidden
403
NSISessionToken
Result message details – see section
5.5
Message #529
Bad syntax
500
NSISessionToken
Result message details – see section
5.5
Message #789
Guide to National Student Index - GINS 6.5-final.docx
Page 60 of 148
5.7.4 Modify Student Record via REST
The NSI System will search the NSI for the NSN supplied in the modify request. Provided all validation is passed the NSI System
will then modify the NSN record using the supplied information in the request.
This web service is used to modify records already on the NSI system. The NSN is provided along with the data to be modified.
5.7.4.1 Modify Student Record Function – Inputs
When a Modify request is submitted through the REST interface, only the fields that the user wishes to modify are required to be
submitted to the NSI system, along with the mandatory fields. The input fields for the modify request are detailed below.
5.7.4.1.1 Input Data Syntax
Operation
REST Verb
Resource URL
Header payload
Body Payload (JSON)
Modify
PUT
Student/
Content-Type
NSISessionToken
{
Guide to National Student Index - GINS 6.5-final.docx
“NSN”: <nsn>,
"FamilyName": <family name>,
"Given1Name": <given name (1)>,
"Given2Name": <given name (2)>,
"Given3Name": <given name (3)>,
"PreferredName": <preferred name>,
"Gender": <gender>,
"BirthDate": <birth date>,
"NameBirthDateVerification": <name birth
date verification>,
"ResidentialStatus": <residential status>,
"ResidentialStatusVerification":
<residential status verification>,
Page 61 of 148
Operation
REST Verb
Resource URL
Header payload
Body Payload (JSON)
"AltNameList": [
{
"AltFamilyName": <alternative family name>,
"AltGiven1Name": <alternative given name
(1)>,
"AltGiven2Name": <alternative given name
(2)>,
"AltGiven3Name": <alternative given name
(3)>,
"PreferredName": <alternative preferred
name indicator>,
"AltNameBirthDateVerification":
<alternative name birth date verification>
}
]
}
5.7.4.1.2 Input Data Fields
Field
Type/Length
Content-Type
NSISessionToken
Alphanumeric (36)
Guide to National Student Index - GINS 6.5-final.docx
Description
Requirement
Indicates the "type" associated with the message body's byte
sequence. Must read “application/json”
Mandatory
Message #789
Session token returned from previous Login Call.
Mandatory
Message #257
Message #528
Page 62 of 148
Field
Type/Length
Description
Requirement
NSN
Numeric (10)
The NSN of the student to modify.
Mandatory
Message #257
Message #409
FamilyName
Alphanumeric (100)
The family name of the student.
Optional
Message #257
Message #272
Given1Name
Alphanumeric (100)
The first given name of the student.
Optional
Message #257
Message #272
Given2Name
Alphanumeric (100)
The second given name of the student.
Optional
Message #257
Message #272
Given3Name
Alphanumeric (100)
The third given name of the student.
Optional
Message #272
PreferredName
Boolean
Value specifying that this name is the preferred name. Values
can be:
 true
 false
Optional
Message #409
Gender
Alphanumeric (1)
The gender of the student. Values can be:
 Male (M)
 Female (F)
 Unknown (U)
Optional
Message #288
Guide to National Student Index - GINS 6.5-final.docx
Page 63 of 148
Field
Type/Length
Description
Requirement
BirthDate
Alphanumeric (20)
The birth date of the student. Values can be:
 Date eg. 1980-12-09
 ‘Unknown’
When a date is entered, format must meet the following
format:
 yyyy-MM-dd e.g. 2013-11-31
Optional
Message #304
Message #305
Message #945
Message #951
NameBirthDateVerific
ation
Alphanumeric (1)
The verification method used to verify the name and birth
date. Values can be:
 Unverified (U)
 Passport (P)
 Birth certificate (B)
 Other (O)
Optional
Message #275
ResidentialStatus
Alphanumeric (1)
The residential status. Values can be:
 NZ Citizen (C)
 NZ Permanent resident (P)
 Australian citizen (A)
 Overseas (O)
 Unknown (U)
Optional
Message #309
ResidentialStatusVeri
fication
Alphanumeric (1)
The residential status verification. Values can be:
 Unverified (U)
 Passport (P)
 Birth cert (B)
 Other (O)
Optional
Message #409
Guide to National Student Index - GINS 6.5-final.docx
Page 64 of 148
Field
Type/Length
Description
Requirement
AltFamilyName
Alphanumeric (100)
The alternative family name for the student.
Conditionally
Mandatory if
Alternative given
name (1)
provided
Message #257
Message #272
AltGiven1Name
Alphanumeric (100)
The alternative first given name for the student.
Conditionally
Mandatory if
Alternative family
name or
Alternative given
name (2)
provided
Message #257
Message #272
AltGiven2Name
Alphanumeric (100)
The alternative second given name for the student.
Conditionally
Mandatory if
Alternative given
name (3)
provided
Message #257
Message #272
AltGiven3Name
Alphanumeric (100)
The alternative third given name for the student.
Optional
Message #272
Guide to National Student Index - GINS 6.5-final.docx
Page 65 of 148
Field
Type/Length
Description
Requirement
PreferredName
Boolean
Value specifying that this name is the preferred name. Values
can be:
 true
 false
Conditionally
Mandatory if
Alternative family
name is supplied
Message #257
Message #409
AltNameBirthDateVer
ification
Alphanumeric (1)
The verification method used to verify the name. Values can
be:
 Unverified (U)
 Passport (P)
 Birth certificate (B)
 Other (O)
Conditionally
Mandatory if
Alternative family
name is supplied
Message #257
Message #275
* If alternative name information is included this will be treated as an addition of a new alternative name.
Guide to National Student Index - GINS 6.5-final.docx
Page 66 of 148
5.7.4.2 Modify Student Record Function – Outputs
There are two different outputs, depending on the outcome of the modify request.
1. Successful modification
2. Unsuccessful modification
The following tables explain the returned HTTP response message passed over the HTTPS medium for each modify request and
the relevant NSI messages sent back. As REST uses the existing HTTP protocols, the returning message will include an HTTP
response code and if required, a JSON message which will include the NSI error message code and descriptions.
5.7.4.2.1 Successful modification
Where a record has been modified successfully, the fields returned are as follows:
5.7.4.2.1.1
Output Function Syntax
Operation
Status
HTTP Code
Response
Response Header
Response Body (JSON)
Message
Modify
Successful
200
NSISessionToken
{
Message #025
Message #938
Message #939
Message #941
Message #943
Student resource – Section
5.6.3,
“MessageList” : [
{Result message details –
section 5.5}
]
}
Guide to National Student Index - GINS 6.5-final.docx
Page 67 of 148
5.7.4.2.2 Unsuccessful modification
5.7.4.2.2.1 Output Function Syntax
Where a record has been modified unsuccessfully, the fields returned are as follows:
Operation
Status
HTTP Code
Response
Response Header
Response Body (JSON)
Message
Modify
Bad request
400
NSISessionToken
Result message details – section 5.5
Message #023
Message #027
Message #034
Message #257
Message #272
Message #275
Message #276
Message #277
Message #279
Message #288
Message #290
Message #304
Message #305
Message #320
Message #321
Message #337
Message #370
Message #409
Message #422
Message #789
Message #934
Guide to National Student Index - GINS 6.5-final.docx
Page 68 of 148
Operation
Status
HTTP Code
Response
Response Header
Response Body (JSON)
Message
Message #945
Message #951
Message #957
Message #1282
Unauthorised
401
NSISessionToken
Result message details – section 5.5
Message #257
Message #528
Forbidden
403
NSISessionToken
Result message details – section 5.5
Message #529
Bad Syntax
500
NSISessionToken
Result message details – section 5.5
Message #789
Guide to National Student Index - GINS 6.5-final.docx
Page 69 of 148
5.7.5 Request to Merge Student Records via REST
This web service receives and processes a request to merge between 2 and up to 10 NSI student records.
5.7.5.1 Request to Merge Student Record Function – Inputs
5.7.5.1.1 Input Data Syntax
Operation
REST Verb
Resource URL
Header payload
Body Payload (JSON)
Submit Merge
Request
POST
MergeRequest/
Content-Type
NSISessionToken
{
"NSNList": [
{"NSN": <NSN1> },
{"NSN": <NSN2> },...]
}
5.7.5.1.2 Input Data Fields
Field
Type/Length
Content-Type
Description
Requirement
Indicates the "type" associated with the message body's byte
sequence. Must read “application/json”
Mandatory
Message #789
NSISessionToken
Alphanumeric (36)
Session token returned from previous login call.
Mandatory
Message #257
Message #528
NSN
Numeric (10)
First NSN to be included in the set of records to be merged.
Mandatory
Message #257
Message #819
NSN
Numeric (10)
Second NSN to be included in the set of records to be
merged.
Mandatory
Message #257
Message #819
Guide to National Student Index - GINS 6.5-final.docx
Page 70 of 148
Field
Type/Length
Description
Requirement
NSN
Numeric (10)
Third NSN to be included in the set of records to be merged.
Optional
Up to ten NSN’s can be included in a merge request. The fourth through to the tenth NSN submitted will have the same attributes
and messages as the third NSN described above.
Guide to National Student Index - GINS 6.5-final.docx
Page 71 of 148
5.7.5.2 Request to Merge Student Record Function – Outputs
5.7.5.2.1 Output Function Syntax
The following tables explain the returned HTTP response message passed over the HTTPS medium for each merge request and the
relevant NSI messages sent back. As REST uses the existing HTTP protocols, the returning message will include an HTTP response
code and if required, a JSON message which will include the NSI error message code and descriptions.
Operation
Status
HTTP Code
Response
Response Header
Response Body (JSON)
Message
Merge
request
Successful –
Merge
automatically
approved
200
NSISessionToken
Result message details – section 5.5
Message #055
Successful –
Merge sent for
Manual
Intervention
200
NSISessionToken
Result message details – section 5.5
Parent
Message:
Message #915
Sub-messages:
Message #817
Message #898
Message #899
Message #902
Message #903
Message #916
Message #944
Guide to National Student Index - GINS 6.5-final.docx
Page 72 of 148
Operation
Status
HTTP Code
Response
Response Header
Response Body (JSON)
Message
Successful –
Merge Rejected
200
NSISessionToken
Result message details – section 5.5
Parent
message:
Message #956
Sub-messages:
Message #897
Message #338
Bad request
400
NSISessionToken
Result message details – section 5.5
Message #257
Message #337
Message #353
Message #819
Message #956
Unauthorised
401
NSISessionToken
Result message details – section 5.5
Message #257
Message #528
Forbidden
403
NSISessionToken
Result message details – section 5.5
Message #529
Bad Syntax
500
NSISessionToken
Result message details – section 5.5
Message #789
Guide to National Student Index - GINS 6.5-final.docx
Page 73 of 148
5.7.6 Create / Update Student Provider Relationship (SPR) via REST
This web service allows the creation/updating of Student Provider relationships. Where an Active until date is provided this will be
used to set the date the relationship will expire. Where no date is provided the default duration of the Provider’s relationships will be
used.
5.7.6.1 Create / Update Student-Provider Relationship Function – Inputs
5.7.6.1.1 Input Data Syntax
Operation
REST Verb
Resource URL
Header payload
Body Payload (JSON)
Add or Update
Student
Provider
Relationship
POST
Student Provider
Relationship/
Content-Type
NSISessionToken
{
“ProviderCode” : <Provider code>,
“NSN” : <NSN>,
“ActiveUntilDate” : <Active until date>
}
5.7.6.1.2 Input Data Fields
Field
Type/Length
Content-Type
NSISessionToken
Alphanumeric (36)
Guide to National Student Index - GINS 6.5-final.docx
Description
Requirement
Indicates the "type" associated with the message body's byte
sequence. Must read “application/json”
Mandatory
Message #789
Session token returned from previous Login Call.
Mandatory
Message #257
Message #528
Page 74 of 148
Field
Type/Length
Description
Requirement
ProviderCode
Alphanumeric (10)
The provider code of the provider that the NSI record will
have a relationship with
Optional (This is
the provider the
SPR is to be set
up with. Default is
the user’s
Provider
organisation. If
supplied, the
user’s provider
organisation must
be authorised to
submit Student
Provider
relationships ‘on
behalf’ of other
organisations.)
Message #060
Message #339
NSN
Numeric (10)
The NSN of the record the relationship is created/updated for
Mandatory
Message #257
Message #409
Guide to National Student Index - GINS 6.5-final.docx
Page 75 of 148
Field
Type/Length
Description
Requirement
ActiveUntilDate
Date/Time (20)
Date student provider relationship will expire
 yyyy-MM-dd e.g. 2013-11-28
Optional. If not
provided use the
default active at
period as set in
the Provider
Details for the
uploading
organisation (if
provided),
otherwise the
organisation
associated with
the user sending
the request.
Message #304
Message #305
Message #423
Guide to National Student Index - GINS 6.5-final.docx
Page 76 of 148
5.7.6.2 Create / Update Student-Provider Relationship Function – Outputs
5.7.6.2.1 Output Function Syntax
The following tables explain the returned HTTP response message passed over the HTTPS medium for each request and the relevant
NSI messages sent back. As REST uses the existing HTTP protocols, the returning message will include an HTTP response code
and if required, a JSON message which will include the NSI error message code and descriptions.
Operation
Status
HTTP Code
Response
Response Header
Response Body (JSON)
Student
Successful
Provider
Bad Request
Relationship
200
NSISessionToken
<none>
400
NSISessionToken
Result message details – section 5.5
Message #060
Message #257
Message #304
Message #305
Message #337
Message #339
Message #409
Message #422
Unauthorised
401
NSISessionToken
Result message details – section 5.5
Message #257
Message #528
Forbidden
403
NSISessionToken
Result message details – section 5.5
Message #529
Bad Syntax
500
NSISessionToken
Result message details – section 5.5
Message #789
Guide to National Student Index - GINS 6.5-final.docx
Page 77 of 148
Message
5.7.7 Logout of the NSI via REST
This function ends a session with the NSI system by logging the user out.
5.7.7.1 Logout Function - Inputs
A logout operation results in deletion of the NSI Session Token from session table and request to ESAA for termination of the ESAA
session token.
5.7.7.1.1 Input Data Syntax
Operation
REST Verb
Resource URL
Header payload
Body Payload (JSON)
Logout
DELETE
session/
<NSISessionToken> none
5.7.7.1.2 Input Data Fields
Label / Field
Type/Length
Description
Requirement
NSISessionToken
Alphanumeric (36)
Session Token returned from previous Login Call
Mandatory
Message #257
Message #528
Guide to National Student Index - GINS 6.5-final.docx
Page 78 of 148
5.7.7.2 Logout Function – Outputs
5.7.7.2.1 Output Data Syntax
The following table explains the returned HTTP response message passed over the HTTPS medium for each logout request and
the relevant NSI messages sent back. As REST uses the existing HTTP protocols, the returning message will include an HTTP
response code and if required, a JSON message which will include the NSI error message code and descriptions.
Operation
Status
HTTP Code
Response
Logout
Successful logout
Not Authorised
Response Body (JSON)
Error
200
Result message details – section 5.5
Message #088
401
Result message details – section 5.5
Message #257
Message #528
Guide to National Student Index - GINS 6.5-final.docx
Response Header
Page 79 of 148
6 Batch File Interface
6.1 Overview
The batch interface mechanism allows organisations to build up a batch of requests
in a batch file over the course of a day (or any period that suits the organisation’s
business processes). These files are then uploaded to the NSI system for batch
processing.
6.2
Accessing the Batch interface
Base URL for all Batch queries:
 https://nsi.education.govt.nz/interface/batch_
Key notes:
 following the “batch_”, the batch function is entered i.e. login.asp or
upload.asp

Environment URLs for production and compliance are:
o Production: https://nsi.education.govt.nz/interface/batch_
o Compliance: https://nsi.compliance.education.govt.nz/interface/batch_
To access the NSI Web UI (required to view Batch files available to be
downloaded), use the following URL’s:
o Production: https://nsi.education.govt.nz/
o Compliance: https://nsi.compliance.education.govt.nz/
6.2.1 Batch File Types
There are four batch file types available for upload to the NSI:
 Search Request,
 Update/Insert Request, and
 Merge Request files
 Student-Provider Relationship add/update (ATA)
These files are described in full in the following sections.
Once a batch file has been submitted via the NSI Web Application, the file is
processed and then a results file is made available for the organisation to download.
This file reports all outcomes of the request file.
Guide to National Student Index gins
Page 80 of 148
6.2.2 Batch File Format
Batch files can be supplied in one of two formats (the results files returned to the
organisation will be in the corresponding format):
1. Delimited, or
2. XML
Please note the NSI system will not accept any batch files larger than 2MB.
6.2.3 File Naming Conventions
6.2.3.1 Inbound File Naming Convention
All inbound request files must conform to the following naming convention:
tttnnnnn.fff
Where: ttt = file type i.e. SEA, UPI, MER or ATA
nnnnn = organisation's unique file reference, e.g. 10345 or au926
fff = file format, which must be either “xml” or “txt”
For example:
MER00001.xml would be a merge request file in xml format.
SEA008td.txt would be a search file in txt format.
UPI90302.txt would be an update/insert file in txt format
ATA12345.xml would be an ATA file in xml format.
Organisations should keep a record of their unique file reference (nnnnn above) to
allow them to cross-reference the request file with the outbound results file.
6.2.3.2 Outbound File Naming Convention
There are five result files that are generated by the NSI system for organisations.
These files are:
1. Search Results.
2. Update/Insert Results.
3. Merge Results.
4. ATA Results
5. Change Notification.
These five output files produced by the NSI will conform to the following naming
convention:
REtnnnnn.fff
Guide to National Student Index - GINS 6.5-final.docx
Page 81 of 148
Where
RE = Indicates “results” file
t = file type indicator (defined below)
nnnnn = organisation's unique file reference
fff = file format (“xml” or “txt”)
The one-char file type indicators are
 S (Search),
 U (Update/Insert),
 M (Merge),
 C (Change Notification) and
 A (Student-Provider Relationship - ATA)
So, REM00001.xml would be a merge request results file in xml format.
6.2.4 Delimited File Footers
Delimited file formats must include information in the footer as specified below.
6.2.4.1 Inbound File Footer Convention
Information contained within the footer record of each inbound pipe-delimited text file
must conform to the following layout:
ZZXXCCZZXXCC | provider_code | input filename | date file
created | time file created | file type long description |
record count
where:
Fieldname
Description
Example (where
applicable)
ZZXXCCZZXXCC
A literal indicating that this is a footer
line.
-
provider_code
The Ministry organisation code.
9999
input filename
The name of the file.
UPI00001.txt
date file created
The date the file was created in the
format yyyymmdd.
20010915
time file created
The time the file was created in the
format hhmmss.
140000
file type long
description
Text describing the file contents,
Update/Insert. For UPI files the footer
must include the text ‘Update/Insert’ in
this field.
Update/Insert/Sear
ch
Merge/Active At
Guide to National Student Index - GINS 6.5-final.docx
Page 82 of 148
Fieldname
Description
Example (where
applicable)
record count
A total of all lines in the input file
(including the footer record).
-
6.2.4.2 Outbound File Footer Convention
Information contained within the footer record of each outbound pipe-delimited file
will conform to the following layout:
ZZXXCCZZXXCC | provider_code | output filename | original input
filename | date outfile created | time outfile created | file
type long description | record count
Where the record (line) count includes footer record, file type long description is
"Batch xxxxx Results" where xxxxx is one of Search, Merge or Update/Insert.
Change Notification files do not have a footer.
6.2.5 Uploading/Downloading Batch Files
Batch files can be uploaded and downloaded via the Web Interface (manually) or via
the Batch interface (automated through your SMS).
Uploading and downloading batch files via the web interface requires the manual
upload of the file. Users can also view all results files available for their organisation
and choose to download those files.
The automated method of uploading your batch files requires an HTTPS Upload
process to be set up in conjunction with the MoE Service Desk.
Please contact the MoE Service Desk if you wish to automate either of these
processes.
Please note: Each file uploaded via the Batch Interface must have a unique
filename. This applies even if the file is being run a second time after errors have
been cleaned up.
6.3 Security and Authentication
This will be achieved using HTTPS Upload and user authentication via the
connection to the NSI application. Please talk with the MoE Service Desk if you want
to establish secure access to the NSI using a server-based login and password to
authenticate. This must be done well in advance of sending any batch files.
Guide to National Student Index - GINS 6.5-final.docx
Page 83 of 148
When login and password authentication is being used, note that three incorrect
logon attempts will result in you being ‘locked out’ of the NSI, and you will need to
contact the MoE Service Desk to regain access to the system via
.service.desk@education.govt.nz or .
0800 422 599
Where a logon has expired or been ‘locked out’, the following error code will be
returned:
Error code
Description
528
Session has timed out, or session not established.
Those integrating at a server level will need to trap for this code being returned in
order to ensure that SMS users are aware of why their access is being denied, and
know what action to take.
Guide to National Student Index - GINS 6.5-final.docx
Page 84 of 148
6.4
Batch File Functions
6.4.1 Search Request File
The NSI System will perform an NSN search on each provided NSN in the Search
Request file or will perform a match search on each non-NSN criteria provided.
6.4.2 Update/Insert Batch File
Organisations can upload an Update/Insert request file at any time. Additionally, prior
to an organisation using the NSI system, their student data will be loaded into the
NSI system using this method. The same file format will be used for both of these
cases.
When an existing NSN is supplied in an Update/Insert file, the request will be treated
as an update to this record. When the NSN is not supplied (but other search criteria
such as names and birth date are) the request will be treated initially as a search and
then, if no matches are found above a threshold, an insert will be made. If a ‘definite’
match is found, that record will be returned to the user and a new record will NOT be
added (to add a record you will need to contact the MoE Service Desk with
documentation to prove the student records are different). If a ‘possible’ match is
found, an override code will be returned. In this case, in order for the record to be
added, this override code must be supplied in the batch file in a subsequent request.
The process will be conducted for each separate request in the file and the results
returned accordingly. A file formatting error anywhere in the file will result in a failure
of the whole file to process.
Guide to National Student Index - GINS 6.5-final.docx
Page 85 of 148
The following diagram shows the Update/Insert batch file process flow.
NSN
provided?
Yes
No
ADD
UPDATE
Validate input
for Add request
Validation
passed?
Validate input
for Update
request
Yes
Process Match
Search
Definite
match found?
No
Possible match
found?
Yes
Yes
Return
definite match
in results
Override code
supplied?
Guide to National Student Index gins
No
Add Student and
send new NSN
Yes
Yes
Validation
passed?
No
No
Generate
override code
Return override
code in results
Page 86 of 148
Validation
passed?
Yes
Update Student
6.4.3 Merge Request Batch File
Where an organisation believes there are multiple NSI records for one student, a
request to merge the student records can be submitted to the NSI.
There are three basic outcomes of a merge request that will be returned from a merge
request. These are:
1. Successful merge – master NSN automatically selected.
2. Merge rejected – merge set sent to merge denied list.
3. Merge sent to manual intervention.
6.4.4 Change Notification Batch Files
Change Notification files contain details of any records which have an ‘SPR’ with an
organisation the organisation requesting the file, where changes have occurred since
the last change notification file was downloaded (see section 3.6) which have
changed.
6.4.5 Student-Provider Relationship (Add / Update)
The Active At file contains a list of NSNs and associated providers. If the record
passes validation a student-provider relationship is created or the existing active until
date updated for each record.
Guide to National Student Index - GINS 6.5-final.docx
Page 87 of 148
6.5 Automated Upload/Download of Batch Files
The automated method of uploading your batch files requires an HTTPS Upload
process to be set up in conjunction with the MoE Service Desk. Similarly, it is possible
for results files to be downloaded via HTTPS Download. Please contact the MoE
Service Desk if you wish to automate either of these processes.
The automated method of uploading and downloading Batch files requires users to
login/logout through the Batch Interface, as well as send specific requests to defined
URLs.
The basic steps required to be performed for uploading files include:
1. Login – by posting the Login Request as per section 6 to
https://nsi.education.govt.nz/interface/batch_login.asp
2. Post files to
https://nsi.education.govt.nz/interface/batch_upload.asp?
3. Logout – by posting the Logout Request as per section 6 to
https://nsi.education.govt.nz/interface/batch_login.asp
Similarly, it is possible for results files to be downloaded via HTTPS Download.
The basic steps required to be performed include:
1. Login – by posting the Login Request as per section 6 to
https://nsi.education.govt.nz/interface/batch_login.asp
2. Get list of files to download from
https://nsi.education.govt.nz/interface/batch_download.asp?list
3. Get each file from
https://nsi.education.govt.nz/interface/batch_download.asp?file={filename}
4. Logout – by posting the Logout Request as per section 6 to
https://nsi.education.govt.nz/interface/batch_login.asp
Guide to National Student Index - GINS 6.5-final.docx
Page 88 of 148
6.5.1 Login to the NSI through Batch Interface
6.5.1.1 Input
The following details the XML format users must comply with when logging into the
NSI through the Batch Interface as the input:
<?xml version="1.0" encoding="ISO-8859-1" ?>
<login version="1.0">
<user_id></user_id>
<password></password>
<org_id></org_id>
</login>
The following detail describes the XML tags detailed above to guide users of this
document who may not be familiar with XML (this table does not describe data fields)
Tag
Description
<?xml version="1.0" encoding="ISO-8859-1" ?>
Common XML header
<login version="1.0">
Start of login record
</login>
End of login record
The following table details the data fields associated to each of the input fields
described above. The table details the data type of the field, the description of that
field and the business requirement for including the field in the request file.
Field
Type/Length
Description
Requirement
user_id
Character (200)
User ID of user logging in.
Mandatory.
password
Character (32)
Password of user logging in.
Mandatory.
org_id
Character(10)
The organisation the user is
signing in on behalf of.
Mandatory.
Guide to National Student Index - GINS 6.5-final.docx
Page 89 of 148
6.5.1.2 Outputs
<?xml version="1.0" encoding="ISO-8859-1" ?>
<result version="1.0">
<code></code>
<description></description>
</result>
Field
Type /Length
Description
code
32-bit signed Integer
Outcome of login attempt
description
Character (255)
Description of error message
The following detail describes the XML tags detailed above to guide users of this
document who may not be familiar with XML (this table does not describe data fields)
Tag
Description
<?xml version="1.0" encoding="ISO-8859-1" ?>
Common XML header
<result version="1.0">
Start of result record
</result>
End of result record
Guide to National Student Index - GINS 6.5-final.docx
Page 90 of 148
6.5.2 Logout from the NSI through the Batch Interface
6.5.2.1 Input
The following details the XML format users must comply with when logging out of the
NSI through the Batch Interface as the input:
<?xml version="1.0" encoding="ISO-8859-1" ?>
<logout/>
The following detail describes the XML tags detailed above to guide users of this
document who may not be familiar with XML (this table does not describe data fields)
Tag
Description
<?xml version="1.0" encoding="ISO-8859-1" ?>
Common XML header
<logout/>
logout record
The following table details the data fields associated to each of the input fields
described above. The table details the data type of the field, the description of that
field and the business requirement for including the field in the request file.
Field
Type/Length
Security Key
Guide to National Student Index - GINS 6.5-final.docx
Description
Requirement
Cookie from login response
header containing the security
key to be used in successive
requests.
Mandatory
Page 91 of 148
6.5.2.2 Outputs
<?xml version="1.0" encoding="ISO-8859-1" ?>
<result version="1.0">
<code></code>
<description></description>
</result>
Field
Type /Length
Description
code
32-bit signed Integer
Outcome of login attempt
description
Character (255)
Description of error message
The following detail describes the XML tags detailed above to guide users of this
document who may not be familiar with XML (this table does not describe data fields)
Tag
Description
<?xml version="1.0" encoding="ISO-8859-1" ?>
Common XML header
<result version="1.0">
Start of result record
</result>
End of result record
Guide to National Student Index - GINS 6.5-final.docx
Page 92 of 148
6.5.3 Automated Upload of Batch files
Once you have logged into the NSI through the Batch Interface, you can POST your
batch file to the following URL:
https://nsi.education.govt.nz/interface/batch_upload.asp?Page=2
6.5.3.1 Successful Upload Output
When you have uploaded a file successfully using the automated upload function, you
will get the following output:
Msg:<message description>
File: File Name : <uploaded filename>
Size: File Length: <file size>
6.5.3.2 Unsuccessful Upload Output
When an error has occurred when uploading a batch file using the automated batch
upload function, you will get the following out:
<br><error description><br>
6.5.4 Automated Download of Batch Files
6.5.4.1 Download List
To view if there are any files available for download for your organisation, you will
need to send a get request to the following URL:
https://nsi.education.govt.nz/interface/batch_download.asp?list
The returned results will only display files that have not yet been downloaded from the
NSI for your organisation. The output will be returned as a space delimited list
6.5.4.2 Download File
To use the automated download of a file from the NSI system, you must know the
name of the results file you wish to download. Once the file name is known, you will
need to send a GET request to the following URL:
https://nsi.education.govt.nz/ interface/batch_download.asp?file={filename}
The name of the file you wish to download will be populated in the {filename} field
above.
Guide to National Student Index - GINS 6.5-final.docx
Page 93 of 148
6.6
Delimited Batch File Formats
6.6.1 Encoding
Delimited batch file results will be ANSI encoded.
Diacritics and special characters (other than ‘~’ for Given name 1) will not be accepted
by the NSI system. Where diacritics are submitted to the NSI, the following error
message will be returned
Error code
Description
272
{0} must only contain alphabetic characters, space, hyphen, apostrophe
or a single '~'. Space hyphen and apostrophe cannot be used without
another character or repeated. Names must start with an apostrophe
or an alphabetic character.).
Guide to National Student Index - GINS 6.5-final.docx
Page 94 of 148
6.6.2 Search
The following sections detail the input and output requirements for delimited Search
batch files
6.6.2.1 Inputs
The following details the Delimited format users must comply with when requesting a
search for student details using a .txt (delimited) file type as the input:
nsn | name | dob | gender | residential_status |
provider_reference
Please note: Spaces are used between field names and delimiter in examples for
clarity only. Spaces between delimiters and data should not be supplied in any
batch files as they will cause the file to fail processing.
An example of the correct format is:
122|||||1001
or
|Joe Bloggs|19800101|M|C|1001
All delimited files require a footer record. Refer to section 6.1.4 Delimited File Footers
for information on the file footer requirements.
The following table details the data fields associated to each of the input fields
described above.
Parameter
Type
Description
Requirement
nsn
32-bit signed
Integer
The NSN of the student to
search for.
Mandatory if no
other
parameters are
supplied.
name
Character (403)
The name to be searched for.
Mandatory if
NSN is not
supplied.
dob
Character (8)
The date of birth of the student
in format yyyymmdd e.g.
19890621
Optional – may
only be used in
conjunction with
Name.
Guide to National Student Index - GINS 6.5-final.docx
Page 95 of 148
Parameter
Type
Description
Requirement
gender
Character (1)
The gender of the student,
where U stands for unknown.
Valid values for Gender:
 M (Male)
 F (Female)
 U (Unknown)
Optional – may
only be used in
conjunction with
Name.
residential_stat Character (1)
us
The residential status of the
student. Valid values for
Residential status:
 C (NZ citizen)
 P (NZ Permanent resident)
 A (Australian citizen)
 O (Other)
 U (Unknown)
Optional – may
only be used in
conjunction with
Name.
provider_refer
ence
A reference passed from an
SMS to the NSI in order for it to
be returned in the output.
Optional.
Character (30)
Guide to National Student Index - GINS 6.5-final.docx
Page 96 of 148
6.6.2.2 Outputs
A new section starting with an ‘S’ line will appear in the results file for each name
submitted to the search.
6.6.2.2.1 Successful Match – Definite Match
Search string:
S | search string
i.e. S | nsn | name | dob | gender | residential_status |
provider_reference
Exact match
U | nsn | surname | forename1 | forename2 | forename3 |
preferred_name_indicator | dob | name_dob_verification |
name_dob_verified_by | residential_status |
residential_status_verification | residential_status_verified_by
| gender | created_date | created_by_userid |
created_by_provider_code | dod | nzqa_paid | record_status |
ranking | alternate_surname | alternate_forename1 |
alternate_forename2 | alternate_forename3 |
alternate_preferred_name_indicator | match_indicator |
provider_reference
U refers to unique match.
For every alternative name found, a separate ‘U’ line will be returned following the ‘U’
line which contains the main record details. For example, if a record has two
alternative names, three ‘U’ lines will be present, one containing the main record
details, and a subsequent line for each alternative name.
6.6.2.2.2 Successful Match – Possible Match(es)
Search String:
S | search string
i.e. S | nsn | name | dob | gender | residential_status |
provider_reference
Inexact (partial) match (search on criteria excluding NSN):
P | ranking | nsn | surname | forename1 | forename2 | forename3
| dob | gender | preferred_name_indicator | residential_status |
residential_status_verified_by | created_date |
created_by_provider_code | match_indicator | provider_reference
P refers to partial match.
Guide to National Student Index - GINS 6.5-final.docx
Page 97 of 148
6.6.2.2.3 Unsuccessful search – No matches found/Error returned
Search string:
S | search string
i.e. S | nsn | name | dob | gender | residential_status |
provider_reference
Errors:
E | error code | error description | provider_reference
6.6.2.2.4 File Footer
The Results file footer will be display directly after the final processed record
ZZXXCCZZXXCC | provider code | output filename | input filename
| created date | created time | Batch Search Results | record
count
Guide to National Student Index - GINS 6.5-final.docx
Page 98 of 148
6.6.3 Update/Insert
The following sections detail the input and output requirements for delimited
Update/Insert batch files
6.6.3.1 Inputs
The pipe character ‘|’ (ASCII 124) will be used as the delimiter. The file must be in
DOS format, that is, each line must be terminated with a Carriage Return (ASCII 13)
and a Line Feed (ASCII 10).
nsn | surname | forename1 | forename2 | forename3 | gender |
preferred_name_indicator | dob | name_dob_verification |
residential_status | residential_status_verification |
alternate_surname | alternate_forename1 | alternate_forename2 |
alternate_forename3 | alternate_preferred_name_indicator |
override_code | provider_reference
Please note: Spaces are used between field names and delimiter in examples for
clarity only. Spaces between delimiters and data should not be supplied in any
batch files as they will cause the file to fail processing.
An example of the correct format is:
122|Bloggs|Joe|William|Tom|M|Y|19181111|U|C|P|Blogs|Joseph|||||1001
All delimited files require a footer record. Refer to section 6.1.4 Delimited File Footers
for information on the file footer requirements.
The following table details the data fields associated to each of the input fields
described above.
Parameter
Type
Description
Requirement
nsn
32-bit signed
Integer
The NSN of the student to
search for.
Mandatory
surname
Character (100)
Surname of the student
Mandatory
forename1
Character (100)
First forename of the student
Mandatory for
an Insert
request
forename2
Character (100)
Second forename of the
student
Conditionally
mandatory if
Forename3 is
supplied
forename3
Character (100)
Third forename of the student
Optional
Guide to National Student Index - GINS 6.5-final.docx
Page 99 of 148
Parameter
Type
Description
Requirement
gender
Character (1)
M, F or U. The gender of the
student, where U stands for
unknown
Optional
preferred_nam
e_indicator
Character (1)
Y or N specifying that this name Optional
is the preferred name.
dob
Character (8)
The date of birth of the student
in format yyyymmdd e.g.
19890621
Mandatory for a
Insert request
name_dob_ver Character (1)
ification
The verification method used to
verify name/dob. Can be
Unverified, Passport, Birth Cert,
or Other primary id.
Optional
residential_stat Character (1)
us
The residential status of the
student. NZ Citizen, NZ
Permanent resident, Australian
citizen, Overseas or Unknown.
Optional.
residential_stat Character (1)
us_verification
The residential status
verification. Can be Unverified,
Passport, Birth Cert, or Other
primary id.
Optional
alternative_sur
name
Character (100)
The last name of an alternative
name used by the student
Optional
alternative_for
ename1
Character (100)
The first name of an alternative
name used by the student
Optional
alternative_for
ename2
Character (100)
The second name of an
alternative name used by the
student
Optional
alternative_for
ename3
Character (100)
The third name of an alternative Optional
name used by the student
alternative_pre
ferred_name_i
ndicator
Character (1)
Y or N specifying whether this
alternative name is the
preferred name.
Optional
override_code
Character (10)
Indicates that the record should
be added despite the known
existence of a partially
matching record/s already in
the NSI database. The value
will be the same as that
returned by a previous attempt
to add the record
Optional
Guide to National Student Index - GINS 6.5-final.docx
Page 100 of 148
Parameter
Type
Description
Requirement
provider_refer
ence
Character (30)
A reference passed from an
SMS to the NSI in order for it to
be returned in the output
Optional
Footer lines must be terminated with a Carriage Return (ASCII 13).
Guide to National Student Index - GINS 6.5-final.docx
Page 101 of 148
6.6.3.2 Outputs
6.6.3.2.1 Student Added / Definite Match Returned / Successful Update
When
 no matching records are returned and the student record is added successfully
OR
 a definite match is returned OR
 an update has been processed successfully,
the result will contain either, the created student record, the updated student record or
the matched student record. The format is:
M | nsn | surname | forename1 | forename2 | forename3 | gender |
preferred_name_indicator | dob | name_dob_verification |
name_dob_verified_by | residential_status |
residential_status_verification | residential_status_verified_by
| nzqa_paid | dod | student_status | created_date |
created_by_userid | created_by_provider_code | alternate_surname
| alternate_forename1 | alternate_forename2 |
alternate_forename3 | alternate_preferred_name_indicator |
alternate_name_dob_verification | override_code |
provider_reference
6.6.3.2.2 Possible Match(es) Returned
The submitted details of the student record will be returned in an ‘M’ line along with an
override code. This will be followed by the matching record(s) as an “S” line. The
format is:
M | nsn | surname | forename1 | forename2 | forename3 | gender |
preferred_name_indicator | dob | name_dob_verification |
name_dob_verified_by | residential_status |
residential_status_verification | residential_status_verified_by
| nzqa_paid | dod | student_status | created_date |
created_by_userid | created_by_provider_code | alternate_surname
| alternate_forename1 | alternate_forename2 |
alternate_forename3 | alternate_preferred_name_indicator |
alternate_name_dob_verification | override_code |
provider_reference
S | nsn | surname | forename1 | forename2 | forename3 | gender |
preferred_name_indicator | dob | name_dob_verification |
name_dob_verified_by | residential_status |
residential_status_verification | residential_status_verified_by
| nzqa_paid | dod | student_status | created_date |
created_by_userid | created_by_provider_code | ranking |
match_indicator | provider_reference
Guide to National Student Index - GINS 6.5-final.docx
Page 102 of 148
6.6.3.2.3 Error
When an error has occurred with the submitted information, the submitted details of
the student will be returned in an “M” line (as above), followed by the error details in
an “E” row as detailed below:
E | code | description | provider_reference
6.6.3.2.4 File Footer
The Results file footer will be display directly after the final processed record
ZZXXCCZZXXCC | provider code | output filename | input filename
| created date | created time | Batch Update/Insert Results |
record count
6.6.3.2.5 Processing Statistics
Below the results file footer, the batch file will contain statistics on the processing of
the file:
New NSNs issued: nn
Matches Not Requiring Manual Intervention: nn
Matches Requiring Manual Intervention: nn
Records updated: nn
Records failed validation: nn
Total Records processed: nn
Guide to National Student Index - GINS 6.5-final.docx
Page 103 of 148
6.6.4 Merge Request
The following sections detail the input and output requirements for delimited Merge
Request batch files,
6.6.4.1 Inputs
nsn | nsn | nsn | nsn | nsn | nsn | nsn | nsn | nsn | nsn
Please note: Spaces are used between field names and delimiter in examples for
clarity only. Spaces between delimiters and data should not be supplied in any
batch files as they will cause the file to fail processing.
An example of the correct format is:
122|13
Or
13|26|39|45|58|61|67|80|96|122
All delimited files require a footer record. Refer to section 6.1.4 Delimited File Footers
for information on the file footer requirements.
The following table details the data fields associated to each of the input fields
described above. The table details the data type of the field, the description of that
field and the requirement for including the field in the request file.
Field
Type/Length
Description
Requirement
nsn1
32-bit signed
Integer
NSN of a record to be included
in the set of records to be
merged
Mandatory
nsn2
32-bit signed
Integer
NSN of a record to be included
in the set of records to be
merged
Mandatory
nsn3
32-bit signed
Integer
NSN of a record to be included
in the set of records to be
merged
Optional
nsn4
32-bit signed
Integer
NSN of a record to be included
in the set of records to be
merged
Optional
nsn5
32-bit signed
Integer
NSN of a record to be included
in the set of records to be
merged
Optional
nsn6
32-bit signed
Integer
NSN of a record to be included
in the set of records to be
merged
Optional
Guide to National Student Index - GINS 6.5-final.docx
Page 104 of 148
Field
Type/Length
Description
Requirement
nsn7
32-bit signed
Integer
NSN of a record to be included
in the set of records to be
merged
Optional
nsn8
32-bit signed
Integer
NSN of a record to be included
in the set of records to be
merged
Optional
nsn9
32-bit signed
Integer
NSN of a record to be included
in the set of records to be
merged
Optional
nsn10
32-bit signed
Integer
NSN of a record to be included
in the set of records to be
merged
Optional
Guide to National Student Index - GINS 6.5-final.docx
Page 105 of 148
6.6.4.2 Outputs
The following sections define the syntax for all potential outcomes of a merge request
in delimited format.
6.6.4.2.1 Records merged successfully
Student records merged, master NSN is returned along with the NSNs included in the
request.
M | Request string
N | new_master_nsn | surname | forename1 | forename2 | forename3
6.6.4.2.2 Merge rejected
Merge request not submitted. NSNs in request returned to the user with the related
error code and description.
M | Request string
E | error code | Merge Rejected | reason text
6.6.4.2.3 Manual Intervention required
Merge request created and submitted to MoE for review. NSN’s included in the merge
request returned along with the related error code and description.
M | Request string
E | error code | Manual Intervention Required | reason text
6.6.4.2.4 Error
Merge request not submitted. Error with request, NSNs included in request are
returned to the user with the related error code and description.
M | Request string
E | error code | reason text
6.6.4.2.5 Processing Statistics
Below the results file footer, the batch file will contain statistics on the processing of
the file:
Successful Merge:
nn
Rejected Merge:
nn
Manual Intervention Required:
nn
Total Records processed:
nn
Guide to National Student Index - GINS 6.5-final.docx
Page 106 of 148
6.6.5 Student-Provider Relationship (ATA) Add / Update
The following sections detail the input and output requirements for delimited ATA
batch files
6.6.5.1 Inputs
Provider Code | NSN | Active Until Date
Please note: Spaces are used between field names and delimiter in examples for
clarity only. Spaces between delimiters and data should not be supplied in any
batch files as they will cause the file to fail processing.
An example of the correct format is:
6022|13|20160101
All delimited files require a footer record. Refer to section 6.1.4 Delimited File Footers
for information on the file footer requirements.
The following table details the data fields associated to each of the input fields
described above. The table details the data type of the field, the description of that
field and the requirement for including the field in the request file.
6.6.5.1.1 Data Fields
Parameter
Type
Description
Requirement
provider_code
Character(10)
The Ministry assigned provider
code.
Conditionally
mandatory
(This is the
provider the
SPR is to be set
up with. Default
is the user’s
Provider
organisation. If
supplied, the
user’s provider
organisation
must be
authorised to
submit Student
Provider
relationships ‘on
behalf’ of other
organisations.)
Guide to National Student Index - GINS 6.5-final.docx
Page 107 of 148
Parameter
Type
Description
Requirement
nsn
32-bit signed
Integer
The NSN of the student to
search for.
Mandatory
Valid date in format yyyymmdd
e.g. 19890621
Optional. If not
provided use
the default
active at period
as set in the
Provider Details
for the
uploading
organisation (if
provided),
otherwise the
organisation
associated with
the user
sending the
request.
active_until_da Character(8)
te
Guide to National Student Index - GINS 6.5-final.docx
Page 108 of 148
6.6.5.2 Outputs
6.6.5.2.1 Successful Active At creation
For a successful Active At creation, no message is reported back to the user.
6.6.5.2.2 Errors returned
Error records are reported first:
E | Error Code | Error Description | Input record (see inbound
file)
6.6.5.2.3 Processing statistics
Statistics are returned in all result files (errors and successful additions).
Summary of processing: nn
Records created/updated for provider code nnnn: nn
Records failed validation for provider code nnnn: nn
Records created/updated: nn
Records failed validation: nn
Total records processed: nn
Guide to National Student Index - GINS 6.5-final.docx
Page 109 of 148
6.6.6 Change Notifications
The following sections detail the delimited Change Notification batch files. There are
no related Change Notification inputs.
6.6.6.1 Inputs
N/A
6.6.6.2 Outputs
The pipe character ‘|’ - ASCII 124 - will be used as the delimiter.
Changed Records:
Denoted by a C at the start of the line, these records are used to report a data change
as follows:
C | modified_date | nsn | master nsn | surname | forename1 |
forename2 | forename3 | preferred_name_indicator | gender | dob
| dod | name_dob_verification | residential_status |
residential_status_verification | nzqa_paid | student_status |
modified_by_provider_code | changed_field_indicator
Merge Denied Records:
Denoted by a D at the start of the line, these records are used to report that a merge
request from the organisation has been denied. Up to 10 NSN’s may be reported on this
record. All delimiters will be present despite the number of NSN’s reported:
D | NSN | NSN | NSN | NSN | NSN | NSN | NSN | NSN | NSN | NSN
Guide to National Student Index - GINS 6.5-final.docx
Page 110 of 148
6.7
XML Batch File Formats
6.7.1 Encoding
XML batch file results will be ISO 8859-1 encoded.
Diacritics and special characters (other than ‘~’ for Given name 1) will not be accepted
by the NSI system.
Where diacritics are submitted to the NSI, the following error message will be returned
Error code
Description
272
{0} must only contain alphabetic characters, space, hyphen, apostrophe
or a single '~'. Space hyphen and apostrophe cannot be used without
another character or repeated. Names must start with an apostrophe
or an alphabetic character.).
.
Guide to National Student Index - GINS 6.5-final.docx
Page 111 of 148
6.7.2 Search
The following sections detail the input and output requirements for XML Search batch
files.
6.7.2.1 Inputs
The following details the XML format users must comply with when requesting a
search for student details using an .xml file type as the input. The student_list can
contain one or more student elements:
<?xml version=”1.0” encoding=”ISO-8859-1” ?>
<student_list version=”1.0”>
<student>
<nsn></nsn>
<name></name>
<dob></dob>
<gender></gender>
<residential_status></residential_status>
<provider_reference></provider_reference>
</student>
</student_list>
The following detail describes the XML tags detailed above to guide users of this
document who may not be familiar with XML (this table does not describe data fields)
Tag
Description
<?xml version="1.0" encoding="ISO-8859-1"
?>
Common XML header
<student_list version= "1.0">
Start of list of students
</student_list>
End of list of students
<student>
Start of student record within
student list
<student>
Start of student record within
student list
</student>
End of student record within
student list
6.7.2.1.1 Data Fields
The following table details the data fields associated to each of the input fields
described above. The table details the data type of the field, the description of that
field and the requirement for including the field in the request file.
Guide to National Student Index - GINS 6.5-final.docx
Page 112 of 148
Parameter
Type
Description
Requirement
nsn
32-bit signed
Integer
The NSN of the student to
search for.
Mandatory if no
other
parameters are
supplied.
name
Character (403)
The name to be searched for.
Mandatory if
NSN is not
supplied.
dob
Character (8)
The date of birth of the student
in format yyyymmdd
e.g. 19890621
Optional – may
only be used in
conjunction with
Name.
gender
Character (1)
The gender of the student,
where U stands for unknown.
Valid values for Gender:
 M (Male)
 F (Female)
 U (Unknown)
Optional – may
only be used in
conjunction with
Name.
residential_stat Character (1)
us
The residential status of the
student. Valid values for
Residential status:
 C (NZ citizen)
 P (NZ Permanent resident)
 A (Australian citizen)
 O (Overseas)
 U (Unknown)
Optional – may
only be used in
conjunction with
Name.
provider_refer
ence
A reference passed from an
SMS to the NSI in order for it to
be returned in the output.
Optional.
Character (30)
Guide to National Student Index - GINS 6.5-final.docx
Page 113 of 148
6.7.2.2 Outputs
Where more than one search has been submitted in the XML input file, a separate
<student/> element within each <result/> tag will be present in the output for each in
the result_list.
The following details the XML format of the XML results files returned to a user when a
download request is processed:
6.7.2.2.1 Successful Match – One result found
<?xml version=”1.0” encoding=”ISO-8859-1”?>
<result_list version=”1.0”>
<result>
<criteria>
<nsn></nsn>
<surname></surname>
<forename1></forename1>
<forename2></forename2>
<forename3></forename3>
<dob></dob>
<gender></gender>
<residentialstatus></residentialstatus>
<provider_reference></provider_reference>
</criteria>
<student_list>
<student>
<nsn></nsn>
<surname></surname>
<forename1></forename1>
<forename2></forename2>
<forename3></forename3>
<gender></gender>
<preferred_name_indicator></preferred_name_indicator>
<dob></dob>
<name_dob_verification></name_dob_verification>
<name_dob_verified_by></name_dob_verified_by>
<residential_status></residential_status>
<residential_status_verification></residential_status_verificatio
n>
<residential_status_verified_by></residential_status_verified_by>
<nzqa_paid></nzqa_paid>
<dod></dod>
Guide to National Student Index - GINS 6.5-final.docx
Page 114 of 148
<student_status></student_status>
<created_by_userid></created_by_userid>
<created_date></created_date>
<created_by_provider_code></created_by_provider_code>
<ranking></ranking>
<match_indicator> </match_indicator>
<name_list>
<name>
<surname></surname>
<forename1></forename1>
<forename2></forename2>
<forename3></forename3>
<preferred_name_indicator></preferred_name_indicator>
<name_dob_verification></name_dob_verification>
</name>
</name_list>
</student>
</student_list>
</result>
</results_list>
6.7.2.2.2 Successful Match – Possible Match(es)
If more than one record is found then the returned XML block will follow the above
structure, and contain a separate </student> tag for each record, showing the
following fields within each <student/> element:
<nsn/>
<surname/>
<forename1/>
<forename2/>
<forename3/>
<gender/>
<preferred_name_indicator/>
<dob/>
<name_dob_verification/>
<name_dob_verified_by/>
<residential_status/>
<residential_status_verification/>
<residential_status_verified_by/>
<nzqa_paid/>
Guide to National Student Index - GINS 6.5-final.docx
Page 115 of 148
<dod/>
<student_status/>
<created_date/>
<created_by_userid/>
<created_by_provider_code/>
<ranking/>
<match_indicator/>
<name_list/>
6.7.2.2.3 Unsuccessful search – No matches found/Error returned
<?xml version=”1.0” encoding=”ISO-8859-1” ?>
<result_list version=”1.0”>
<result>
<criteria>
<nsn></nsn>
<surname></surname>
<forename1></forename1>
<forename2></forename2>
<forename3></forename3>
<dob></dob>
<gender></gender>
<residentialstatus></residentialstatus>
<provider_reference></provider_reference>
</criteria>
<error>
<code></code>
<description></description>
</error>
</result>
</results_list>
The following detail describes the XML tags detailed above to guide users of this
document who may not be familiar with XML.(This table does not describe data fields)
Tag
Description
<?xml version="1.0" encoding="ISO-8859-1" ?>
Common XML header
<result_list version= "1.0">
Start of result list
</result_list>
End of result list
<result>
Start of result record within
results list
Guide to National Student Index - GINS 6.5-final.docx
Page 116 of 148
Tag
Description
</result>
End of result record within
results list
<criteria>
Start of data input
</criteria>
End of data input
<student_list>
Start of list of students
</student_list>
End of list of students
<student>
Start of student record within
student list
</student>
End of student record within
student list
<name_list>
Start of list of names for
student record
</name_list>
End of list of names for
student record
<name>
Start of name record for
student within name list
</name>
End of name record for
student within name list
<error>
Start of error record for
student
</error>
End of error record for
student
Guide to National Student Index - GINS 6.5-final.docx
Page 117 of 148
6.7.3 Update/Insert
The following sections detail the input and output requirements for XML Update/Insert
batch files.
6.7.3.1 Inputs
<?xml version=”1.0” encoding=”ISO-8859-1” ?>
<student_list version=”1.0”>
<student>
<nsn></nsn>
<surname></surname>
<forename1></forename1>
<forename2></forename2>
<forename3></forename3>
<dob></dob>
<name_dob_verification></name_dob_verification>
<preferred_name_indicator></preferred_name_indicator>
<residential_status></residential_status>
<residential_status_verification></residential_status_verification>
<gender></gender>
<override_code></override_code>
<provider_reference></provider_reference>
<alternate_name>
<surname></surname>
<forename1></forename1>
<forename2></forename2>
<forename3></forename3>
<preferred_name_indicator></preferred_name_indicator>
<alternate_name></alternate_name>
</student>
</student_list>
The following detail describes the XML tags detailed above to guide users of this
document who may not be familiar with XML (this table does not describe data fields)
Tag
Description
<?xml version="1.0" encoding="ISO-8859-1" ?>
Common XML header
<student_list version= "1.0">
Start of list of student records
<student>
Start of student record within
match list
Guide to National Student Index - GINS 6.5-final.docx
Page 118 of 148
Tag
Description
</student>
End of student record within
match list
<alternate_name>
Start of alternate name
record within student record
</alternate_name >
End of alternate name record
within student record
</student_list>
End of list of student records
6.7.3.1.1 Data Fields
The following table details the data fields associated to each of the input fields
described above. The table details the data type of the field, the description of that
field and the requirement for including the field in the request file.
Parameter
Type
Description
Requirement
nsn
32-bit signed
Integer
The NSN of the student to
search for.
Mandatory for
an update
request
surname
Character (100)
Surname of the student
Mandatory for
an Insert
Request
forename1
Character (100)
First forename of the student
Mandatory for
an Insert
request
forename2
Character (100)
Second forename of the student
Conditionally
mandatory if
Forename3 is
supplied
forename3
Character (100)
Third forename of the student
Optional
gender
Character (1)
M, F or U. The gender of the
student, where U stands for
unknown
Optional
preferred_nam
e_indicator
Character (1)
Y or N specifying that this name
is the preferred name.
Optional
dob
Character (8)
The date of birth of the student
in format yyyymmdd e.g.
19890621
Mandatory for a
Insert request
The verification method used to
verify name/dob. Can be
Unverified, Passport, Birth Cert,
or Other primary id.
Optional
name_dob_ver Character (1)
ification
Guide to National Student Index - GINS 6.5-final.docx
Page 119 of 148
Parameter
Type
Description
Requirement
residential_stat Character (1)
us
The residential status of the
student. NZ Citizen, NZ
Permanent resident, Australian
citizen, Overseas or Unknown.
Optional.
residential_stat Character (1)
us_verification
The residential status
verification. Can be Unverified,
Passport, Birth Cert, or Other
primary id.
Optional
alternative_sur
name
Character (100)
The last name of an alternative
name used by the student
Optional
alternative_for
ename1
Character (100)
The first name of an alternative
name used by the student
Optional
alternative_for
ename2
Character (100)
The second name of an
alternative name used by the
student
Optional
alternative_for
ename3
Character (100)
The third name of an alternative
name used by the student
Optional
alternative_pre
ferred_name_i
ndicator
Character (1)
Y or N specifying whether this
Optional
alternative name is the preferred
name.
override_code
Character (10)
Indicates that the record should
be added despite the known
existence of a partially matching
record/s already in the NSI
database. The value will be the
same as that returned by a
previous attempt to add the
record
Optional
provider_refer
ence
Character (30)
A reference passed from an
SMS to the NSI in order for it to
be returned in the output
Optional
Guide to National Student Index - GINS 6.5-final.docx
Page 120 of 148
6.7.3.2 Outputs
6.7.3.2.1 Student Added / Definite Match Returned / successful update
When
 no matching records are returned and the student record is added successfully
OR
 a definite match is returned OR
 an update has been processed successfully,
the result will contain either, the created student record, the updated student record or
the matched student record. When a definite match is returned, the <student/> tag
contains a full record. The format is:
<?xml version=”1.0” encoding=”ISO-8859-1” ?>
<result_list version=”1.0”>
<result>
<student>
<nsn></nsn>
<surname></surname>
<forename1></forename1>
<forename2></forename2>
<forename3></forename3>
<gender></gender>
<preferred_name_indicator></preferred_name_indicator>
<dob></dob>
<name_dob_verification></name_dob_verification>
<name_dob_verified_by></name_dob_verified_by>
<residential_status></residential_status>
<residential_status_verification></residential_status_verification
>
<residential_status_verified_by></residential_status_verified_by>
<nzqa_paid></nzqa_paid>
<dod></dod>
<student_status></student_status>
<created_date></created_date>
<created_by_userid></created_by_userid>
<created_by_provider_code></created_by_provider_code>
<alternate_name>
<surname></surname>
<forename1></forename1>
<forename2></forename2>
<forename3></forename3>
Guide to National Student Index - GINS 6.5-final.docx
Page 121 of 148
<preferred_name_indicator></preferred_name_indicator>
<name_dob_verification></name_dob_verification>
<alternate_name></alternate_name>
<override_code></override_code>
<provider_reference></provider_reference>
</student>
</result>
</result_list>
6.7.3.2.2 Possible Match(es) Returned
Where a possible match is returned the <student/> tag is not reporting a new record
inserted to the NSI. Instead it is reporting the information that has been submitted to
the system as well as an override code. A <match_list> block will detail all matching
students with a score above the NSI determined parameter for possible matches. The
format is:
<?xml version="1.0" encoding="ISO-8859-1"?>
<result_list version="1.0">
<result>
<student>
<nsn><nsn/>
<surname></surname>
<forename1></forename1>
<forename2></forename2>
<forename3> </forename3>
<dob></dob>
<name_dob_verification></name_dob_verification>
<preferred_name_indicator/>
<residential_status></residential_status>
<residential_status_verification></residential_status_verification
>
<gender></gender>
<override_code></override_code>
<provider_reference></provider_reference>
<alternate_name>
<surname> <surname/>
<forename1><forename1/>
<forename2><forename2/>
<forename3><forename3/>
<preferred_name_indicator><<preferred_name_indicator/>
<alternate_name></alternate_name>
Guide to National Student Index - GINS 6.5-final.docx
Page 122 of 148
</student>
<match_list>
<student>
<nsn></nsn>
<surname> </surname>
<forename1> </forename1>
<forename2></forename2>
<forename3></forename3>
<gender></gender>
<preferred_name_indicator></preferred_name_indicator>
<dob></dob>
<name_dob_verification></name_dob_verification>
<name_dob_verified_by></name_dob_verified_by>
<residential_status></residential_status>
<residential_status_verification></residential_status_verificatio
n>
<residential_status_verified_by></residential_status_verified_by>
<nzqa_paid></nzqa_paid>
<dod></dod>
<student_status></student_status>
<created_date></created_date>
<created_by_userid> </created_by_userid>
<created_by_provider_code></created_by_provider_code>
<ranking></ranking>
<match_indicator></match_indicator>
</student>
</match_list>
</result>
</result_list>
6.7.3.2.3 Batch XML Error Codes
When an error has occurred with the submitted information, the submitted details of
the student will be returned in the <student> tag, followed by the error details in
<error> tags as detailed below:
All error codes output by the batch XML interface are in the following format:
<?xml version=”1.0” encoding=”ISO-8859-1” ?>
<result_list version=”1.0”>
<result>
<student>
<nsn></nsn>
Guide to National Student Index - GINS 6.5-final.docx
Page 123 of 148
<surname></surname>
<forename1></forename1>
<forename2></forename2>
<forename3></forename3>
<gender></gender>
<preferred_name_indicator></preferred_name_indicator>
<dob></dob>
<name_dob_verification></name_dob_verification>
<name_dob_verified_by></name_dob_verified_by>
<residential_status></residential_status>
<residential_status_verification></residential_status_verification
>
<residential_status_verified_by></residential_status_verified_by>
<nzqa_paid></nzqa_paid>
<dod></dod>
<student_status></student_status>
<created_date></created_date>
<created_by_userid></created_by_userid>
<created_by_provider_code></created_by_provider_code>
<alternate_name>
<surname></surname>
<forename1></forename1>
<forename2></forename2>
<forename3></forename3>
<preferred_name_indicator></preferred_name_indicator>
<name_dob_verification></name_dob_verification>
<alternate_name></alternate_name>
<override_code></override_code>
<provider_reference></provider_reference>
</student>
<error>
<code></code>
<description></description>
</error>
</result>
</result_list>
6.7.3.2.4 Processing statistics
The batch file will contain statistics on the processing of the file:
Guide to National Student Index - GINS 6.5-final.docx
Page 124 of 148
<stats>
<new_nsns_issued></new_nsns_issued>
<matches_not_requiring_manual_intervention></matches_not_requiring_m
anual_intervention>
<matches_requiring_manual_intervention></matches_requiring_manual_in
tervention>
<records_updated></records_updated>
<records_failed_validation></records_failed_validation>
<total_records_processed></total_records_processed>
</stats>
<?xml version=”1.0” encoding=”ISO-8859-1” ?>
<result_list version=”1.0”>
<result>
<criteria>
<nsn></nsn>
<surname></surname>
<forename1></forename1>
<forename2></forename2>
<forename3></forename3>
<dob></dob>
<gender></gender>
<residentialstatus></residentialstatus>
<provider_reference></provider_reference>
</criteria>
<error>
<code></code>
<description></description>
</error>
</result>
</results_list>
Errors will be returned in NSI XML responses depending on where the error occurred
in the input block, usually at the record level. This means that they will appear just
inside the end of a record tag (as shown above).
Guide to National Student Index - GINS 6.5-final.docx
Page 125 of 148
6.7.4 Merge Request
The following sections detail the input and output requirements for XML Merge
Request batch files.
6.7.4.1 Inputs
<?xml version="1.0" encoding="ISO-8859-1" ?>
<student_list version=”1.0”>
<student>
<nsn></nsn>
<nsn></nsn>
<nsn></nsn>
<nsn></nsn>
<nsn></nsn>
<nsn></nsn>
<nsn></nsn>
<nsn></nsn>
<nsn></nsn>
<nsn></nsn>
</student>
</student_list>
A minimum of 2 and maximum of 10 NSI records can be submitted within one merge
request. Any number of merge request groups can be submitted in a batch merge
request file.
All 10 <nsn> tags are not required when submitting a batch merge request. For
example, a request to have two records merged need only contain two <NSN> tags.
The number of tags required depends on the number of duplicate records. So if there
are only two duplicates which the organisation wishes to merge together, you should
only submit two tags.
The following detail describes the XML tags detailed above to guide users of this
document who may not be familiar with XML (this table does not describe data fields)
Tag
Description
<?xml version="1.0" encoding="ISO-8859-1" ?>
Common XML header
<student_list version= "1.0">
Start of list of student records
<student>
Start of student record within
list of students
</student>
End of student record within
list of students
Guide to National Student Index - GINS 6.5-final.docx
Page 126 of 148
The following table details the data fields associated to each of the input fields
described above. The table details the data type of the field, the description of that
field and the business requirement for including the field in the request file.
Field
Type/Length
Description
Requirement
nsn1
32-bit signed
Integer
NSN of a record to be included
in the set of records to be
merged
Mandatory
nsn2
32-bit signed
Integer
NSN of a record to be included
in the set of records to be
merged
Mandatory
nsn3
32-bit signed
Integer
NSN of a record to be included
in the set of records to be
merged
Optional
Up to 10 NSN’s can be included in a merge request. NSN’s 4 – 10 will be
validated as per NSN3 above.
Guide to National Student Index - GINS 6.5-final.docx
Page 127 of 148
6.7.4.2 Outputs
The <request_string/> returned will contain the details previously submitted in the
<student/> XML tag as shown above.
6.7.4.2.1 Records merged successfully
<?xml version=”1.0” encoding=”ISO-8859-1” ?>
<result_list version=”1.0”>
<result>
<request_string>
<nsn></nsn>
<nsn></nsn>
<nsn></nsn>
<nsn></nsn>
<nsn></nsn>
<nsn></nsn>
<nsn></nsn>
<nsn></nsn>
<nsn></nsn>
<nsn></nsn>
</request_string>
<new_master_nsn></new_master_nsn>
<surname></surname>
<forename1></forename1>
<forename2></forename2>
<forename3></forename3>
</result>
6.7.4.2.2 Merge rejected/Manual Intervention required/Error returned
In the case of a rejected merge request or a merge request that requires manual
intervention, the information contained in the request file will be returned in the results
file along with the appropriate message code and description.
<result>
<request_string>
<nsn></nsn>
<nsn></nsn>
<nsn></nsn>
<nsn></nsn>
<nsn></nsn>
<nsn></nsn>
<nsn></nsn>
Guide to National Student Index - GINS 6.5-final.docx
Page 128 of 148
<nsn></nsn>
<nsn></nsn>
<nsn></nsn>
</request_string>
<error_code></error_code>
<error_description></error_description>
</result>
6.7.4.2.3 Processing Statistics
Below the result_list element, the batch file will contain statistics on the processing of
the file:
<stats>
<successful_merge></successful_merge>
<rejected_merge></rejected_merge>
<manual_intervention_required></manual_intervention_required>
<total_records_processed></total_records_processed>
</stats>
Tags for XML formatting (not data fields)
Tag
Description
<?xml version="1.0" encoding="ISO-8859-1" ?>
Common XML header
<result_list version= "1.0">
Start of result list
</result_list>
End of result list
<result>
Start of result record within
results list
</result>
End of result record within
results list
<stats>
Start of statistics for batch file
</stats>
End of statistics for batch file
Guide to National Student Index - GINS 6.5-final.docx
Page 129 of 148
6.7.5 Student-Provider Relationship (ATA) Add/Update
The following sections detail the requirements for ATA Batch files in XML format.
6.7.5.1 Inputs
XML files will be formatted as follows:
<?xml version=”1.0” encoding=”ISO-8859-1” ?>
<active_at version=”1.0”>
<student>
<provider_code></provider_code>
<nsn></nsn>
<active_until_date></active_until_date>
</student>
</active_at>
The following detail describes the XML tags detailed above to guide users of this
document who may not be familiar with XML (this table does not describe data fields)
Tags for XML formatting (not data fields)
Tag
Description
<?xml version="1.0" encoding="ISO-8859-1" ?>
Common XML header
<active_at version= "1.0">
Start of list of active at
records
<student>
Start of active at record within
list
</student>
End of active at record within
list
</active_at >
End of list of active at records
6.7.5.1.1 Data Fields
The following table details the data fields associated to each of the input fields
described above. The table details the data type of the field, the description of that
field and the requirement for including the field in the request file.
Guide to National Student Index - GINS 6.5-final.docx
Page 130 of 148
Parameter
Type
Description
Requirement
provider_code
Character(10)
The Ministry assigned provider
code.
Conditionally
Mandatory
(This is the
provider the
SPR is to be set
up with. Default
is the user’s
Provider
organisation. If
supplied, the
user’s provider
organisation
must be
authorised to
submit Student
Provider
relationships ‘on
behalf’ of other
organisations.)
nsn
32-bit signed
Integer
The NSN of the student to
search for.
Mandatory.
Valid date in format yyyymmdd
e.g. 19890621
Optional. If not
provided use
the default
active at period
as set in the
Provider Details
for the
uploading
organisation (if
provided),
otherwise the
organisation
associated with
the user
sending the
request.
active_until_da Character(8)
te
Guide to National Student Index - GINS 6.5-final.docx
Page 131 of 148
6.7.5.2 Outputs
6.7.5.2.1 Successful Active At creation
For a successful Active At creation, no message is reported back to the user.
6.7.5.2.2 Errors returned
Where an error has occurred, the criteria submitted in the request will be returned
followed by the appropriate error code and description.
<?xml version=”1.0” encoding=”ISO-8859-1” ?>
<result_list version=”1.0”>
<result>
<criteria>
<provider_code></provider_code>
<nsn></nsn>
<active_until_date></active_until_date>
</criteria>
<error>
<code></code>
<description></description>
</error>
</result>
</result_list>
6.7.5.2.3 Processing statistics
Statistics are returned for all result files (errors and successful additions).
<stats>
<provider_success>
<provider>
<provider_code></provider_code>
<created_or_updated></created_or_updated>
</provider>
</provider_success>
<provider_failure>
<provider>
<provider_code></provider_code>
<created_or_updated></created_or_updated>
</provider>
</provider_failure>
<records_created_or_updated></records_created_or_updated>
<records_failed_validation></records_failed_validation>
Guide to National Student Index - GINS 6.5-final.docx
Page 132 of 148
<total_records_processed></total_records_processed>
</stats>
Tags for XML formatting (not data fields)
Tag
Description
<?xml version="1.0" encoding="ISO-8859-1" ?>
Common XML header
<result_list version= "1.0">
Start of result list
</result_list>
End of result list
<result>
Start of result record within
results list
</result>
End of result record within
results list
<criteria>
Start of active at record within
list
</criteria>
End of active at record within
list
<error>
Start of error record for
student
</error>
End of error record for
student
<stats>
Start of statistics for batch file
</stats>
End of statistics for batch file
Guide to National Student Index - GINS 6.5-final.docx
Page 133 of 148
6.7.6 Change Notifications
The following sections detail the XML Change Notification batch files. There are no
related Change Notification inputs.
6.7.6.1 Inputs
N/A
6.7.6.2 Outputs
Changed records and merge denials are both reported back to organisations in the
same XML block, as shown here:
<notification_list>
<update_notification_list>
<update_notification>
<modified_date></modified_date>
<nsn></nsn>
<master_nsn></master_nsn>
<surname></surname>
<forename1></forename1>
<forename2></forename2>
<forename3></forename3>
<preferred_name_indicator></preferred_name_indicator>
<gender></gender>
<dob></dob>
<dod></dod>
<name_dob_verification></name_dob_verification>
<residential_status></residential_status>
<residential_status_verification></residential_status_verification
>
<nzqa_paid></nzqa_paid>
<student_status></student_status>
<modified_by_provider_code></modified_by_provider_code>
<changed_field_indicator></changed_field_indicator>
</update_notification>
</update_notification_list>
<merge_denied_list>
<merge_denied>
<nsn></nsn>
<nsn></nsn>
<nsn></nsn>
<nsn></nsn>
Guide to National Student Index - GINS 6.5-final.docx
Page 134 of 148
<nsn></nsn>
<nsn></nsn>
<nsn></nsn>
<nsn></nsn>
<nsn></nsn>
<nsn></nsn>
</merge_denied>
</merge_denied_list>
</notification_list>
Guide to National Student Index - GINS 6.5-final.docx
Page 135 of 148
7 Appendix B: Glossary of Terms
BDM
Births Deaths and Marriages
The BDM Office registers all births, deaths and marriages which take place in New
Zealand, and provides access to this registered information through a variety of
products and services. BDM also provides a number of other services, including
changes of name by statutory declaration and the appointment of marriage celebrants.
The BDM Office is a section of the Department of Internal Affairs (see below).
DIA
The Department of Internal Affairs
The New Zealand government department that works to:
· safeguard and strengthen communities
· support executive and local government
· provide New Zealanders with records of personal identity
· ensure gaming is fair, legal and honest.
HTTPS
Secure Hypertext transfer protocol
HTTPS is a Web protocol developed by Netscape and built into its browser that
encrypts and decrypts user page requests as well as the pages that are returned by
the Web server. HTTPS is really just the use of Netscape's Secure Socket Layer (SSL)
as a sub layer under its regular HTTP application layering. (HTTPS uses port 443
instead of HTTP port 80 in its interactions with the lower layer, TCP/IP.) SSL uses a
40-bit key size for the RC4 stream encryption algorithm, which is considered an
adequate degree of encryption for commercial exchange
NCEA
National Certificates of Education Achievement
An NCEA is a standards-based qualification that will attest to a broad range of New
Zealand Curriculum related education outcomes. There are three National Certificates
of Educational Achievement: Level 1 NCEA, Level 2 NCEA, and Level 3 NCEA. A
student will be awarded a National Certificate when she/he has accumulated sufficient
credits by being successfully assessed against NQF standards.
NSN
National student number
The unique identifier for a record in the NSI system.
ROA
Record of Achievement
An individual learner's transcript of unit standards credited and national qualifications
completed, provided by NZQA from a national database.
REST
REpresentation State Transfer
(REpresentation State Transfer) is a common standard for online interfaces. It uses a
definition of a resource (e.g. a student), and allows a range of actions for it.
SMS
Student management system
System that exists for organisations to enrol and retain information on their students.
SOAP
Simple object access protocol
Guide to National Student Index - GINS 6.5-final.docx
Page 136 of 148
SOAP is a way for a program running in one kind of operating system (such as
Windows 2000) to communicate with a program in the same or another kind of an
operating system (such as Linux) by using the World Wide Web's Secure Hypertext
Transfer Protocol (HTTPS) and its Extensible Markup Language (XML) as the
mechanisms for information exchange.
STEO
Services for tertiary education organisations
The Ministry’s Tertiary website which provides password-controlled access to the
Course Register, Qualifications Register, NZSCED and the Single Data Return
Validation Program.
TEC
Tertiary Education Commission
The Tertiary Education Commission (TEC) Te Amorangi Matauranga Matua, is a
crown entity established under the provisions of the Education (Tertiary Reform)
Amendment Act 2002. TEC is responsible for funding all post-compulsory education
and training offered by universities, polytechnics, colleges of education, wananga,
private training establishments, foundation education agencies, industry training
organisations and adult and community education providers.
UNICODE
Unicode Standard Character Coding System
The Unicode standard is a character coding system designed to support the
interchange, processing, and display of the written texts of diverse languages.
URL
Uniform Resource Locator
A URL is the address of a file (resource) accessible on the Internet. The type of
resource depends on the Internet application protocol. Using the World Wide Web's
secure protocol, the Secure Hypertext Transfer Protocol (HTTPS), the resource can be
an HTML page (like the one you're reading), an image file, a program such as a
common gateway interface application or Java applet, or any other file supported by
HTTPS. The URL contains the name of the protocol required to access the resource, a
domain name that identifies a specific computer on the Internet, and a hierarchical
description of a file location on the computer.
UTF-8
Unicode Transformation Format 8-bit encoding form
UTF-8 is the Unicode Transformation Format that serializes a Unicode scalar value
(code point) as a sequence of one to four bytes.
XML
Extensible mark up language
XML is a flexible way to create common information formats and share both the format
and the data on the World Wide Web, intranets, and elsewhere. For example,
computer makers might agree on a standard or common way to describe the
information about a computer product (processor speed, memory size, and so forth)
and then describe the product information format with XML. Such a standard way of
describing data would enable a user to send an intelligent agent (a program) to each
computer maker's Web site, gather data, and then make a valid comparison. XML can
be used by any individual or group of individuals or companies that wants to share
information in a consistent way.
Guide to National Student Index - GINS 6.5-final.docx
Page 137 of 148
8 Appendix C: Error Codes
The following table lists all errors that can be returned from the NSI from the external
interfaces (XML, SOAP, Batch and REST). This table is up to date as at 08/12/2014.
Note: Error codes output via the SOAP interface will be output as the NSI message
code minus an offset of 2146828288. This rule applies to all messages returned
through each SOAP function.
e.g. Message code ‘528’ is output as ‘-2146827760’
Notes:
 Errors returned through the automated batch upload function only return
message descriptions without the message codes.
 Message descriptions that include “{}” are dynamic messages, where the “{}”
can be populated with various values i.e. the message will be returned for
various fields
 Some REST messages consist of a single message with another message
embedded within the description that provides more information. These relate
to the following messages:
o Message #956 can be embedded with:
 Message #338 or
 Message #897
o Message #915 can be embedded with:
 Message #916 or,
 Message #898 or,
 Message #899 or,
 Message #902 or,
 Message #903 or,
 Message #944
Code
2
Interface2 Message Value
0
B
Success.
012
R
Please enter a minimum of two names, or one name and a
birth date. Birth date, Gender and Residential status may only
be used in conjunction with at least one name.
013
B
Type mismatch.
B = Batch, R = REST
Guide to National Student Index - GINS 6.5-final.docx
Page 138 of 148
Code
Interface2 Message Value
021
R
Record(s) that closely match this record have been found.
Please confirm whether you wish to add this record.
023
R
Name & birth date and Residential status verification cannot be
set to anything other than 'Unverified' when 'Birth date' and / or
Residential status is 'Unknown'.
025
R
Student record successfully saved.
027
R
Names which exactly match another name on the student
record cannot be added.
034
R
This record contains verified name and birth date information.
If you wish to update this information please raise a challenge.
055
R
Student records have been automatically merged. The master
record is {0}.
060
R
No such Provider exists. Please check and re-enter.
074
B
Please ensure the file you are uploading has either a .txt or
.xml extension.
075
B
Please ensure the file you are uploading has either a ATA,
SEA, MER, or UPI prefix.
076
B
Please ensure the file you are uploading has a ATA, SEA, or
MER or UPI prefix then 5 characters then a ‘.txt’ or ‘.xml’
extension.
088
R
You have been logged out of the NSI.
256
B
{0} is invalid.
257
B,R
Please enter values for the following mandatory field(s):\n{0}
258
S
NSN required to update an NSN record.
259
B
Name, DoB, Residential Status and Gender cannot be
supplied as search criteria with NSN.
272
B,R
{0} must only contain alphabetic characters, space, hyphen,
apostrophe or a single '~'. Space hyphen and apostrophe
cannot be used without another character or repeated. Names
must start with an apostrophe or an alphabetic character.
273
B
Verification Flag cannot be set without corresponding data.
274
B
Cannot modify verified data.
275
B,R
Invalid verification flag.
276
B,R
Verification Flag cannot be set to BDM.
277
R
You cannot update {0} when {1} is 'Birth register'.
279
B,R
{0} cannot be changed from a verified value to 'Unverified'.
Guide to National Student Index - GINS 6.5-final.docx
Page 139 of 148
Code
Interface2 Message Value
280
B
Birth date AND name details may not be updated together. If
required, submit the updates & supporting information as a
Challenge to nsi.unit@education.govt.nz using the student
NSN as a reference number.
281
B
BDM verification flags cannot be changed.
288
B,R
Invalid gender.
290
B,R
Cannot change Ministry of Education verified data.
304
B,R
Invalid date format.
305
B,R
You must have permission to update this field. {0} must be
earlier than today's date and be in one of the following formats:
dd/mm/yyyy, yyyymmdd or yymmdd.
309
B,R
Residential status is invalid.
320
B,R
Preferred name indicator is invalid.
321
B,R
Preferred name indicator set for more than one name.
336
B,R
Invalid NSN.
337
B,R
NSI record {0} does not exist.
338
B,R
{0} is already a slave of record {1}. Slave records cannot be
merged.
339
R
Invalid Provider Code. Only Standard characters (A-Z, 0-9)
are permitted. Leading or trailing spaces are not permitted.
352
B
Request failed to be lodged with NSI Unit - too few records
identified in group (minimum is 2).
353
B,R
A maximum of ten unique student records can be included in a
merge request.
369
B
BDM verified fields cannot be modified.
370
B,R
NSI Record is inactive and cannot be updated.
409
R
Unexpected validation Error.
416
B
Incorrect File Format.
417
B
Incorrect Format for file footer record.
418
B
Incorrect Record Format.
422
B,R
NSN found is a slave record.
423
B,R
Student Provider Relationship period is out of range.
424
B
Invalid provider code.
513
B,R
Invalid user name or password.
515
B,R
Organisation is not valid for user.
Guide to National Student Index - GINS 6.5-final.docx
Page 140 of 148
Code
Interface2 Message Value
521
B,R
The {0} interface is not enabled for you.
528
B,R
Session has timed out, or session not established.
529
B,R
Access denied.
768
B
Unexpected validation error.
769
B
{0} is not a valid XML command.
784
R
More than {0} records have been found matching the search
criteria. The top {0} records have been returned. Please refine
your search criteria.
785
B,R
No search results found.
789
B,R
A system fault means that the NSI is temporarily unavailable. If
the problem persists contact the MoE Service Desk. Please
accept our apologies for any inconvenience.
800
B
Update denied student has been merged.
817
R
Your merge request has been forwarded to the NSI Team. Can
you please forward supporting documentation through to
nsi.unit@education.govt.nz
818
B
{0} exist in the merge denied list. Merge request requires
manual intervention.
819
R
At least two unique student records are required for merge.
820
B
Merge request requires manual intervention.
821
B
Merge request cannot be processed – invalid status.
822
B
NSN records >1 NSI records have NZQA paid flag set to Y or
N ({0}, {1}) have got NZQA paid flag set to Y or N. Merge
request requires manual intervention.
823
B
Merge request includes BDM verified records. Merge request
requires manual intervention.
897
R
The following NSN(s) are included in a merge request that is
currently awaiting processing and cannot be merged. {0}
898
R
The following NSN(s) have been verified by the Birth register:
{0}
899
R
The following NSN(s) have been previously denied: {0}
902
R
Records in the merge group are not a close enough match for
automatic merging.
903
R
The following NSN(s) have current challenges: {0}
915
R
Merge request requires manual intervention for the following
reason(s). Please contact the MoE Service Desk if you require
more information.
Guide to National Student Index - GINS 6.5-final.docx
Page 141 of 148
Code
Interface2 Message Value
916
R
The following NSN(s) have an Inactive status: {0}
921
R
Record(s) that match this record have been found. Please
review match(es) returned. If you wish to have a new record
added, the information and verification must be submitted to
the MoE Service Desk as a Challenge of the existing student
details. The NSI team will process your challenge via e-mail.
Supporting information can be forwarded separately to
nsi.unit@education.govt.nz using the student NSN as a
reference number.
934
R
You are attempting to change the Birth date AND name details
of this student. If you wish to continue with this update the
information and verification must be submitted to the MoE
Service Desk as a Challenge of the existing student details.
The NSI team will process your challenge via e-mail.
Supporting information can be forwarded separately to
nsi.unit@education.govt.nz using the student NSN as a
reference number.
938
R
This student is part of a merge request that is awaiting
processing - Contact the MoE Service Desk if you require
further information.
939
R
Student record successfully saved. Please note this record has
an unknown birth date.
941
R
Student record successfully saved. Please note this record has
'Unverified' details.
942
R
Invalid override code.
943
R
Student record successfully saved. Please note verified
Residential status details have been updated.
944
R
The following NSN's have student provider relationships with
NZQA: {0}. The following NSN's don’t have student provider
relationships with NZQA: {1}
945
R
Birth date cannot be today's date.
951
R
{0} cannot be later than current date.
953
B
Unknown File Type {0}
954
B
Incorrect file extension (.xml/.txt)
955
B
Your file name should have 1 to 5 characters after the 3 letter
prefix. {0}
956
R
Merge request has been rejected.
957
R
Birth date cannot be modified.
1282
R
NSN record has not been modified.
Guide to National Student Index - GINS 6.5-final.docx
Page 142 of 148
Code
Interface2 Message Value
1283
R
You cannot access the NSI. Your organisation's Go Live date
has not yet been reached. Please contact the MoE Service
Desk.
1284
B
FILE SUCCESSFULLY UPLOADED
Please Note: It is recommended that systems are developed to interpret
message codes, not message text. Message text may change over time.
Guide to National Student Index - GINS 6.5-final.docx
Page 143 of 148
9 Appendix D: Related Documents
The following is a list of links to documents which relate to integration with the NSI.
9.1 Web Interface User Guide
The best place to learn more about how to use and navigate around the NSI web
interface is the NSI Web Interface User Guide. The latest version of this guide is
available for download from the Ministry of Education’s website.
Or contact Service.Desk@education.govt.nz or call 0800 422 599 to request a copy.
9.2 NSI Web UI Learning Module
An online NSI Web UI Learning Module has been developed for Web UI users.
Providers using an in house or vendor Student Management System may also find
this useful to look over. It is available from the Ministry of Education’s website.
This module will show you how to work through the common processes within the NSI
web interface. The module will take you approximately 20 to 25 minutes to work
through.
9.3 NSI Web UI Quick Reference Guide (QRG)
This QRG for the NSI application is a short check list covering the basic business
activities for Web UI users. It is available from the Ministry of Education’s website.
9.4 ESAA Application Form
You can download an ESAA application form from the Ministry’s STEO website at
http://info.identity.education.govt.nz/esaa/
Guide to National Student Index - GINS 6.5-final.docx
Page 144 of 148
10 Appendix E: REST Code Example
The following contains code examples of how to consume the REST service in NSI. This
example is supplied here as is and is not the only way that the REST interface can be
consumed, nor is this necessarily the recommended way to consume the REST interface.
10.1 Encode username and password
Get a Base64 Encoded string of your login details. Encode your username and password
in this format: Username:Password
public static string Base64Encode(string plainText)
{
var plainTextBytes = System.Text.Encoding.UTF8.GetBytes(plainText);
return System.Convert.ToBase64String(plainTextBytes);
}
For example:
var plainTextBytes = System.Text.Encoding.UTF8.GetBytes("STNSIUNIT1:myPassword123");
string ss = System.Convert.ToBase64String(plainTextBytes);
returns:
ss = U1ROU0lVTklUMTpteVBhc3N3b3JkMTIz==
10.2 Get Authentication token from ESAA
Get Authentication token using User ID and the Encoded string - calling ESAA
//Get access token
using (var client = new HttpClient())
{
var parameters = new Dictionary<string, string>
{
{ "grant_type", "client_credentials" },
{ "end_user_id", username}, //username e.g STNSIUNIT1
{ "scope", "APP_NSI2" }
};
Uri theUriHost = new
Uri("https://ppsecurity.education.govt.nz/oauth2/access_token?");
//Building the Uri
var builder = new UriBuilder(theUriHost.ToString());
var query = HttpUtility.ParseQueryString(builder.Query);
Guide to National Student Index - GINS 6.5-final.docx
Page 145 of 148
//Add parameters to Uri
foreach (KeyValuePair<string, string> value in parameters)
{
query[value.Key] = value.Value;
}
builder.Query = query.ToString();
string url = builder.ToString();
// url ends up like this:
https://SECURITY.education.org.nz/oauth2/access_token?grant_type=client_credentia
ls&end_user_id= STNSIUNIT1&scope=APP_NSI2
//Adding the headers
client.DefaultRequestHeaders.Accept.Add(new
MediaTypeWithQualityHeaderValue("application/json"));
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic",
encodedUserLogin); //encodedUserLogin is the string returned in step 1
client.DefaultRequestHeaders.Host = theUriHost.Host;
var content = new FormUrlEncodedContent(parameters);
var response = await client.PostAsync(url, content);
//await allows you to do
parallel processing while the application is awaiting a reponse from the server
}
The reponse will include an access token which is used for the login request. An example
is shown below.
{
"token_type": "Bearer",
"access_token": "N0Y1HGVCRjUtMERFDC1BN0Y0LTY2MDUtCzRFQjMyAzIyMDQ3"
}
10.3 Create an NSI session
Create an NSI session using authentication token - returns NSI session token in
response header
//Request NSI session
using (var client = new HttpClient())
{
Uri theUri = new Uri("https://nsi.compliance.education.govt.nz/api/v1/session");
//Adding the headers
client.DefaultRequestHeaders.Accept.Clear();
client.DefaultRequestHeaders.Accept.Add(new
MediaTypeWithQualityHeaderValue("application/json"));
client.DefaultRequestHeaders.Host = theUri.Host;
var parameters = new Dictionary<string, string>
{
Guide to National Student Index - GINS 6.5-final.docx
Page 146 of 148
from the
{ "EsaaAccessToken", responseTokens["access_token"]}, //Using the access token
reponse in step 2
{ "OrgId", "-1" }
};
var content = new FormUrlEncodedContent(parameters);
var response = await client.PostAsync(theUri, content);
}
The reponse will send back an NSISessionToken in the header; this token will be used in
all subsequent requests (Search student, Update student, Add student, Logout etc) for
NSI. It looks something like this: 1239495d-b059-12f2-bd1f-39d0114a7e02
10.4 Send NSI request
Use NSI session token in request header for your request e.g. search, update etc
//(GET) Search student by NSN
using (var client = new HttpClient())
{
String studentToSearch = nsnNumber;
String uriWithStudent = "https://nsi.compliance.education.govt.nz/api/v1/student/"
+ studentToSearch;
Uri theUri = new Uri(uriWithStudent);
//Adding the headers
client.DefaultRequestHeaders.Accept.Clear();
client.DefaultRequestHeaders.Accept.Add(new
MediaTypeWithQualityHeaderValue("application/json")); //Could be xml
client.DefaultRequestHeaders.Add("NSISessionToken", responseTokens["NSISessionToken"]);
client.DefaultRequestHeaders.Host = theUri.Host;
var response = await client.GetAsync(theUri);
}
Searching a student in the system by their NSN number. Put the NSISessionToken into
the header of the request to do search.
10.5 Logout using NSI session token in request header
using (var client = new HttpClient())
{
Uri theUri = new Uri("https://nsi.compliance.education.govt.nz/api/v1/session");
client.DefaultRequestHeaders.Accept.Clear();
client.DefaultRequestHeaders.Accept.Add(new
MediaTypeWithQualityHeaderValue("application/json"));
Guide to National Student Index - GINS 6.5-final.docx
Page 147 of 148
client.DefaultRequestHeaders.Add("NSISessionToken",
responseTokens["NSISessionToken"]);
client.DefaultRequestHeaders.Host = theUri.Host;
Console.WriteLine("Loggingout");
var response = await client.DeleteAsync(theUri);
Using Delete operation and the NSISession Token in the header to log the user out.
Guide to National Student Index - GINS 6.5-final.docx
Page 148 of 148