Unique Student Identifier

Transcription

1 Unique Student Identifier Technical Service Contract for the Unique Student Identifier Web Service Comprising the following service operations: Verify single USI Verify multiple USIs Create single USI Create multiple USIs (processed asynchronously) Retrieve the result of a request to create multiple USIs Update Personal Details Update Contact Details Get Non DVS Document Types Contract Version 1.5 February 2015 Copyright Commonwealth of Australia

2 Document Details Security classification Unclassified Dissemination limiting marking None Author Department of Industry Document Status Approved February 2015 Copyright Commonwealth of Australia

3 Document Administration Service Name Contract version 1.5 File Location File Name Revision History USI Web Service USI Document SharePoint Document: USI TSC.docx Diagram masters: USI TSC feeder.pptx Revision Date Author Details Oct 2012 Malcolm Young First Draft Dec 2012 Malcolm Young Added WSDL Dec 2012 Malcolm Young Review comments inc Dec 2012 Malcolm Young Final revision Dec 2012 Malcolm Young Updated following additional comments Feb 2013 Luke Elliott Fixed syntax errors, remove unnecessary fields, some clarification Feb 2013 Luke Elliott Major revision to the WSDL, XSD and various fields Mar 2013 Luke Elliott, Trent Kerin Updated WSDL and corrected details based on review feedback Mar 2013 Ben Bildstein Polish Apr 2013 Luke Elliott, Trent Kerin Actioning comments from USI Task Force Apr 2013 Ben Bildstein Polish May 2013 Ben Bildstein, David Spencer Incorporate David Spencer s changes May 2013 Ben Bildstein, Luke Elliott Bulk verify July 2013 Jason Chase Updated validation rules for DVS documents July 2013 Jason Chase Updated phone number minimum length validations July 2013 Patrick McNamara Added production end point addresses Aug 2013 Trent Kerin Added WSDL with WCF section Sep 2013 Jason Chase Updated Bulk Verify sections Oct 2013 Ben Bildstein Updated example requests and responses Nov 2013 Trent Kerin Removed Change of Name and Marriage documents Dec 2013 Trent Kerin Updated definition of ErrorType allowable codes. Mentioned that some of the codes in Fault Values appear as regular errors Dec 2013 Nick Evans Updated the Medicare card document type. And Updated the WSDL to match Jan 2014 Kurt Marr Updated to include contact details changes Jan 2014 Ben Bildstein Update to contract version Jan 2014 David Spencer Minor wording revisions Mar 2014 Harold Hotham Updates for ImmiCard, Error 1002 and new passport number Page 3 of 90 Version 1.5 February 2015

4 Mar 2014 Harold Hotham Update for WSDL and preferred contact method Apr 2014 Harold Hotham Update for unique address Apr 2014 Harold Hotham Contract version 1.2, some minor changes to field names and validation rules May 2014 Ben Bildstein Merged David Spencer s document version 1.21 with Harold Hotham s document version May 2014 Kurt Marr Modified UserReference Element May 2014 Patrick McNamara Update error code list May 2014 Trent Kerin Specify Visa CountryOfIssue as 1-80 chars May 2014 Trent Kerin Update WSDL endpoints and SOAP actions to target implementation. Added brief section about service identifiers June 2014 Trent Kerin, Neville Schroder Removed service identifiers section, in favour of the AppliesTo argument for STS being identical to the USI endpoint URL. Updated WSDL to reflect latest changes. Cut out most of Appendix D as the new WSDL now auto-configures everything except client certificate. Corrections to textual descriptions of DVSCheckRequired and FirstName and FamilyName elements in the Personal Details Type July 2014 Trent Kerin Fixed typo in single name Bulk Verify example July 2014 Harold Hotham Rewrite of birth certificate section to include conditional field info August 2014 Patrick McNamara Updated the validation rules for TownCityOfBirth, SuburbTownCity, Address1, Address2 and InternationalAddress. Removed blank Address2 from the sample requests. WSDL updated to reflected these changes September 2014 Harold Hotham Updated Endpoints and Operations section with prod urls October 2014 Patrick McNamara Added GetNonDvsDocumentType, UpdatePersonalDetails and UpdateContactDetails. Replaced wdsl xml in November December December 2014 Harold Hotham Kurt Marr Kurt Marr appendix to link to the real wsdl. Added Error 3250, this error already existed but did not have a code. Should be very difficult to hit this error. It represents an unexpected error when performing schema validation. Added error 3370 for suspended DVS document types Fixed Medicare IndividualRefNumber valid values Page 4 of 90 Version 1.5 February 2015

5 December Harold Hotham Dec. 14 Harold Hotham Updated VerifyUSIResponse to indicate fields are not mandatory Added Locate USI Page 5 of 90 Version 1.5 February 2015

6 Release notes 3PT Deployment date Production deployment date New features and enhancements 12/11/14 11/12/14 Description Breaking 1 / Non-breaking 2 1. New method for updating personal details via Web Service Non-breaking 2. New method for updating contact details via Web Service Non-breaking 3. New method to get a list of Non-DVS ID documents Non-breaking 4. Update to Create USI to handle two new claims for Non-DVS IDs Non-breaking Bug fixes None - Known issues None - 1 Breaking change - Indicates that this new feature/enhancement/bug fix must be implemented by the Production deployment date in order to continue using the USI Web Service. 2 Non-breaking change - Indicates this new feature/enhancement/bug fix is available, but can be adopted when appropriate. Page 6 of 90 Version 1.5 February 2015

7 Approvals Approved by: Name: Deborah Morgan Position: Manager, USI Project Signed: Date: Page 7 of 90 Version 1.5 February 2015

8 Terminology ABN ATO AUSkey Credential Device Key Digital Certificate DVS Identity Token OASIS RTO SAML SAML Assertion Security Token SMS SMS Vendor SOAP Australian Business Number Australian Taxation Office Australian Government issued digital certificate Something used to prove their digital identity AUSKey specifically for use with web services Proof of identity data Document Verification Service a service to verify evidence of identity documents. More information is available from See Security Token A standards body 'Organization for the Advancement of Structured Information Standards'. See Section 1.3, References and Related Documents. Registered Training Organisation. A provider of accredited VET courses and training. Secure Assertion Mark-up Language an OASIS standard A signed XML block asserting identity of a user. The XML conforms to the SAML Core schema. This is an industry term for an assertion about identity that is issued by an Identity Provider. In the context of this contract this is signed SAML assertion. Student management system Provider of student management systems to RTOs. Simple Object Access Protocol Student A person undertaking VET and who will require a USI from January TA State and Commonwealth authorities that oversee delivery of VET. TGA Token User USI Registrar USI Taskforce VET WS-Trust training.gov.au See Security Token An RTO staff member using an SMS to interact with the USI web services. A Registrar will be appointed, subject to legislation, to administer unique student identifiers for the VET sector. Responsible for implementation of the USI Program. Vocational Education and Training. A specification that deals with distribution of security tokens. Page 8 of 90 Version 1.5 February 2015

9 Contents 1 Introduction Purpose Audience References and Related Documents Business View Version Information About This Version Changes by Contract Version Overview and Broad Functionality Service Environments Third Party Testing Production Digital Certificate (AUSkey) Web Services Security Web Service Policy The Service Provider Interface Conditions of Use Pre-Conditions Service Call Process Post Conditions Endpoints and Operations Third Party Testing Production Message Structure Create Single USI Create Multiple USIs (BulkUpload) Retrieve create multiple USIs result (BulkUploadRetrieve) Verify a single USI Bulk Verify multiple USIs Get Non DVS Document Types Update Personal Details for USI Update Contact Details for USI Shared Data Types Fault Messages Page 9 of 90 Version 1.5 February 2015

10 4.4.1 Sample Fault Fault Values Addressing Policy Security Policy Appendix A WSDL Schema Appendix B USI Country List Appendix C Visa Country List Appendix D WSDL with a WCF Application Page 10 of 90 Version 1.5 February 2015

11 1 Introduction 1.1 Purpose The purpose of this document is to inform student management system (SMS) vendors, and RTO in house system developers about the USI web services available for their consumption. This interface description is called a 'Technical Service Contract' (TSC). 1.2 Audience This document is intended to be read by organisations and agencies intending to use the web services and covers both technical and business aspects of the services. Executive readers and business analysts should read Section 2 to gain an understanding of the business need that these services address. Technical staff implementing systems that consume the USI Web Services should read the whole document. 1.3 References and Related Documents Common Elements: Common Elements for Vanguard Services Document Revision V1.16 STS: VANguard Security Token Service Technical Service Contract v1.2 SAMLCore: Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V1.1. OASIS Standard, August WSSAML: Web Services Security: SAML Token Profile SOAP SOAP Version 1.2 Part 1: Messaging Framework (Second Edition) WSP: Web Services Policy Framework (WSPolicy) v1.2 WSECP: WS-SecurityPolicy WSEC: Web Services Security: SOAP Message Security WSA: Web Services Addressing 1.0 Core Page 11 of 90 Version 1.5 February 2015

12 2 Business View 2.1 Version Information About This Version This document describes version 1.5 of the USI Web Services. Since this document may change without impacting the service definition, i.e. non-technical changes, this document includes the date it was published (February 2015) separate to the contract version number Changes by Contract Version Important changes made in each version of the contract are listed below Version 1.1 The following changes may cause problems for implementations based on previous versions of this document: The Change of Name document type is no longer supported. The Marriage Certificate document type is no longer supported. If part of a postal address is specified, the complete postal address must now be specified. The following additions have also been made: Service for verifying multiple USIs Version 1.2 The following changes may cause problems for implementations based on previous versions of this document: The Address in Contact Details Type must now be unique in the USI Register for active USIs Version 1.3 The following changes may cause problems for implementations based on previous versions of this document: AppliesTo argument for STS being identical to the USI endpoint URL 2.2 Overview and Broad Functionality This document describes the system to system functions provided by the USI web services. The services discussed in this document allow an authorised consumer to perform the following actions: Create a USI record for an individual and receive an immediate response Submit a batch of USI creation requests for processing and (BulkUpload) Retrieve the results of a previously submitted batch request (BulkUploadRetrieve) Verify a USI for an individual and receive an immediate response Verify a batch of USIs and receive an immediate response. Added in version Service Environments The USI web services will be deployed in two distinct environments as detailed below. Page 12 of 90 Version 1.5 February 2015

13 2.3.1 Third Party Testing Third party testing is intended to allow software developers to integrate and test their software with a nonlive implementation of the USI web services that is guaranteed to behave the same as the live system. This environment is configured to use only test AUSkey certificates, org codes and mock version of the document verification system. Any USIs generated by the test environment are not valid in the live environment Testing Registration Developers wishing to access the third party testing environment must complete the enrolment process available from the USI Website. Once completed, participants will be issued with appropriate certificates, orgcodes and connection instructions Production Production is the live version of the USI Web Services once the scheme goes live Registration To use the USI web services in the production environment, RTOs must first be listed and current on Training.Gov.au (TGA). Other VET related organisations wishing to use web services or the web portal must register themselves with the USI Registrar. Registration will give organisations an OrgCode, from either TGA or the USI Registrar. The OrgCode must be supplied as a part of all web service calls. In the case where an ABN is associated with multiple registered organisations, it is the responsibility of the web service user to provide the appropriate OrgCode for each service call. Each organisation wishing to use the USI web services will also need to complete an additional enrolment process, agreeing to the terms and conditions of use, with the Registrar, before they can access the services in the production environment. 2.4 Digital Certificate (AUSkey) Consumers of the USI web services will require an AUSkey, and more specifically an AUSkey device credential, to verify their identity while interacting with the USI web services. These certificates can be obtained free of charge from the Australian Business Register by all ABN holders. Each organisation, RTO, VAB etc. will require their own AUSkey device credential and matching OrgCode before they can use the USI web services. Page 13 of 90 Version 1.5 February 2015

14 2.5 Web Services Security The USI Web Services are secured using the VANguard Security Token Service (STS). The STS is a WS-Trust compliant service used to validate digital credentials and generate security tokens which can then be used to create secure web service channels. A typical interaction is as follows: 1. The end user creates a request for security token message which is signed using their digital credential. This message is sent to the VANguard STS. 2. The STS validates the signature over the message and the digital credential used to sign it and returns a SAML security token. 3. This token is used to secure one or more messages sent to the USI Web Services. Request and receive security token from VANguard Security Token Service Use token obtained from VANguard to secure messages to and from USI web services. Figure 1: Interaction overview This document only describes the interaction between the client and the USI Web Services. Technical specifications for the VANguard STS are contained in the VANguard Security Token Service Technical Service Contract. Page 14 of 90 Version 1.5 February 2015

15 3 Web Service Policy All the USI services conform to the following standards: SOAP v1.2 [SOAP] WS-Policy v1.2 [WSP] WS-SecurityPolicy v1.2 [WSECP] WS-Security 1.1 [WSEC] WS-Addressing v1.0 [WSA] SAML Token Profile for WS-Security Detailed policy for all services is described in the WSDL for each service. Page 15 of 90 Version 1.5 February 2015

16 4 The Service Provider Interface 4.1 Conditions of Use Pre-Conditions In order to invoke any USI web service operation, the following conditions must be met depending on the environment the user wishes to access Third Party Testing Completing the third party testing enrolment process will result in participants being issued with the following required data: A set of organisation codes that can be used to test the web services with different organisation types (RTO, VAB etc). AUSkeys specifically for the third party testing environment Production RTOs must be listed and current on Training.Gov.au (TGA). Other VET related organisations must be registered with the USI Taskforce. The organisation will need to complete the web services enrolment process, agreeing to the web services terms and conditions of use, as specified by the Registrar. The organisation must hold a valid device AUSkey matching the ABN registered with TGA or the USI Taskforce Service Call Process Each call made to the USI web services must complete the following steps: 1. Obtain a valid and current SAML security token for the organisation from the VANguard Security Token Service (STS). This token can be used for multiple web service calls within the same session, until it expires. 2. Call the required USI web service attaching the SAML security token Post Conditions All service requests will be recorded for audit purposes. This audit log will not include any sensitive or personal information. A clear response will be provided to the client indicating success or failure. In the event of a failure to process or authenticate the request, a SOAP fault will be returned to indicate the nature of the problem. Page 16 of 90 Version 1.5 February 2015

17 4.2 Endpoints and Operations Third Party Testing Paths for the third party testing environment will be made available to participants after they have completed the enrolment process available from the USI website Production The endpoint URL for the USI Web Services is: The WSDL for the USI Web Services: The SOAP action for bulk create USI upload operation is: The SOAP action for bulk create USI retrieve operation is: The SOAP action for bulk verify USI retrieve operation is: /2013/ws/BulkVerifyUSI The SOAP action for the create USI operation is: The SOAP action for the verify USI operation is: The SOAP action for the get non-dvs document types operation is: The SOAP action for the update USI personal details operation is: The SOAP action for the update USI contact details operation is: Page 17 of 90 Version 1.5 February 2015

18 4.3 Message Structure This section details the message structures for each of the USI Web Services interfaces. The schema for all service calls is provided in Appendix A. Sample messages shown below include only the SOAP body for clarity Create Single USI The Create USI service allows a caller to submit a single application to create a USI in a synchronous manner Request Message Special Conditions It is important to note that when creating USIs, using both single and multiple create, the combination of RequestId and OrgCode must be unique for all calls to both these services and can never be reused irrespective of the outcome of the current request. Page 18 of 90 Version 1.5 February 2015

19 Create USI Sample A typical Create USI request message is shown below: <soap:body xmlns:soap=" <u:createusi xmlns:u=" <u:requestid>102</u:requestid> <u:orgcode>12345</u:orgcode> <u:application> <u:applicationid>102</u:applicationid> <u:dvscheckrequired>true</u:dvscheckrequired> <u:userreference>jsmith</u:userreference> <u:contactdetails> <u:preferredmethod> </u:preferredmethod> <u:countryofresidence>australia</u:countryofresidence> <u: address>sample@test.com.au</u: address> <u:nationaladdress> <u:address1>71 Johns St</u:Address1> <u:suburbtowncity>wamboin</u:suburbtowncity> <u:state>nsw</u:state> <u:postcode>2620</u:postcode> </u:nationaladdress> </u:contactdetails> <u:personaldetails> <u:gender>m</u:gender> <u:firstname>max</u:firstname> <u:middlename>reginald</u:middlename> <u:familyname>white</u:familyname> <u:dateofbirth> </u:dateofbirth> <u:countryofbirth>australia</u:countryofbirth> <u:towncityofbirth>sydney</u:towncityofbirth> <u:countrystudyingin>australia</u:countrystudyingin> </u:personaldetails> <u:dvsdocument xmlns:xsi=" xsi:type="u:birthcertificatedocumenttype"> <u:registrationnumber>123</u:registrationnumber> <u:registrationstate>nsw</u:registrationstate> <u:registrationdate> </u:registrationdate> <u:registrationyear>1971</u:registrationyear> <u:dateprinted> </u:dateprinted> <u:certificatenumber>123</u:certificatenumber> </u:dvsdocument> </u:application> </u:createusi> </soap:body> Page 19 of 90 Version 1.5 February 2015

20 Create USI Request Description CreateUSI manages the information of who issued the call, a file identifier and any supporting information for the bulk load of applications. Attribute Constraints The combination of RequestId and OrgCode must be unique for all calls to all services that create USIs. Name Type Description Constraints RequestId string This contains the identifier that the organisation has nominated to identify the create USI request. OrgCode string Unique identifier for an organisation registered with training.gov.au or the USI Registrar. Application ApplicationType See section Application Type for details. Validation Rules: The value must not exceed 20 characters This identifier must never be re-used with the same OrgCode. A-Z, a-z, 0-9 Validation Rules: Must not exceed 6 characters Response Message Create USI Response Sample A typical response message from the Create USI service is shown below: <soap:body xmlns:soap=" <u:createusiresponse xmlns:u=" <u:requestid>12345</u:requestid> <u:application> <u:processeddate> t04:21: z</u:processeddate> <u:result>success</u:result> <u:identitydocumentverified></u:identitydocumentverified> <u:usi>h2289jj333</u:usi> <u:errors/> </u:application> </u:createusiresponse> </soap:body> Page 20 of 90 Version 1.5 February 2015

21 Create USI Response Type Description CreateUSIResponse returns the result of the USI application Constraints Attribute Name Type Description Constraints RequestId string This contains the identifier that the organisation has nominated for the create single USI request. Application ApplicationResponseType See section Application Response Type for details. Validation Rules: The value must not exceed 20 characters Page 21 of 90 Version 1.5 February 2015

22 4.3.2 Create Multiple USIs (BulkUpload) This service allows the caller to request the creation of multiple USIs, up to 500 per request. The USI applications are processed asynchronously. To retrieve the results of the request the caller must call the BulkUploadRetrieve service with the ReceiptNumber from the response of this service Request Message BulkUpload USI Sample A request to create multiple USIs is shown below: <soap:body xmlns:soap=" <u:bulkupload xmlns:u=" <u:orgcode>12345</u:orgcode> <u:requestid>123456</u:requestid> <u:noofapplications>1</u:noofapplications> <u:applications> <u:application> <u:applicationid>101</u:applicationid> <u:dvscheckrequired>true</u:dvscheckrequired> <u:userreference>jsmith</u:userreference> <u:contactdetails> <u:preferredmethod> </u:preferredmethod> <u:countryofresidence>australia</u:countryofresidence> <u: address>sample@test.com.au</u: address> <u:nationaladdress> <u:address1>71 Johns St</u:Address1> <u:suburbtowncity>wamboin</u:suburbtowncity> <u:state>nsw</u:state> <u:postcode>2620</u:postcode> </u:nationaladdress> </u:contactdetails> <u:personaldetails> <u:gender>m</u:gender> <u:firstname>max</u:firstname> <u:middlename>reginald</u:middlename> <u:familyname>white</u:familyname> <u:dateofbirth> </u:dateofbirth> <u:countryofbirth>australia</u:countryofbirth> <u:towncityofbirth>sydney</u:towncityofbirth> <u:countrystudyingin>australia</u:countrystudyingin> </u:personaldetails> <u:dvsdocument xmlns:xsi=" xsi:type="u:birthcertificatedocumenttype"> <u:registrationnumber>123</u:registrationnumber> <u:registrationstate>nsw</u:registrationstate> <u:registrationdate> </u:registrationdate> <u:registrationyear>1971</u:registrationyear> <u:dateprinted> </u:dateprinted> <u:certificatenumber>123</u:certificatenumber> </u:dvsdocument> </u:application> </u:applications> </u:bulkupload> </soap:body> Although the example includes only one USI application, up to 500 applications may be submitted per request. Page 22 of 90 Version 1.5 February 2015

23 Only one form of identity document may be supplied for each application. However each application in a request can use a different document type. The XML Schema instance mechanism is used to assert the identity document type used in each application Bulk Upload Request Type Description Constraints Bulk create manages the information of who issued the call, a request identifier and any supporting information for the bulk creation of applications. RequestId and OrgCode together must be unique for each call to the service. The maximum number of applications in a single call must not exceed 500. Attribute Name Type Description Constraints OrgCode string Unique identifier for an organisation registered with TGA or the USI Registrar RequestId string This contains the identifier that the organisation has nominated to identify the bulk create request. This identifier must never be re-used with the same OrgCode. NoOfApplications int This contains the no. of applications to expect in the bulk upload file Applications List of ApplicationType items. See section Application Type for details. A-Z, a-z, 0-9 Validation Rules: Must not exceed 6 characters Validation Rules: The value must not exceed 20 characters 0-9 Validation Rules: The value must not exceed 500 Page 23 of 90 Version 1.5 February 2015

24 Response Message Bulk Upload Response Sample A typical response message from the Bulk Upload service is show below: <soap:body xmlns:soap=" <u:bulkuploadresponse xmlns:u=" <u:receiptnumber>a19f0fa9-c0eb-4878-aabe-9db0493b42f3</u:receiptnumber> </u:bulkuploadresponse> </soap:body> The receipt number is used to retrieve the response, using the Bulk Upload Retrieve service operation Bulk Upload Response Description BulkUploadResponse returns a receipt number that can be used to retrieve the results of the request once they have been processed. Constraints ReceiptNumber is unique to each request regardless of originating organisation. Attribute Name Type Description Constraints ReceiptNumber string Unique identifier used to retrieve the results of a bulk create request. Validation Rules: Must not exceed 36 characters Page 24 of 90 Version 1.5 February 2015

25 4.3.3 Retrieve create multiple USIs result (BulkUploadRetrieve) The Bulk Upload Retrieve service operation is invoked to return the processed results of a Bulk Upload request submitted earlier Request Message Bulk Upload Retrieve Sample A typical request message to the Bulk Upload Retrieve service is show below: <soap:body xmlns:soap=" <u:bulkuploadretrieve xmlns:u=" <u:receiptnumber>a19f0fa9-c0eb-4878-aabe-9db0493b42f3</u:receiptnumber> </u:bulkuploadretrieve> </soap:body> The receipt number is the value returned in the response from the Bulk Upload service Bulk Upload Retrieve Type Description Bulk create retrieve is used to request the asynchronously processed results of a batch create request. Constraints ReceiptNumber must match one issued to the requesting organisation. Attribute Name Type Description Constraints ReceiptNumber string Unique identifier used to retrieve the results of a bulk create request. See section Bulk Upload Response for details Validation Rules: Must not exceed 36 characters Response Message In the case of a valid receipt number the service will return one of the following results: If the upload batch has not been processed to completion then a SOAP fault will be returned with an error message containing the text: Batch Not Completed. If the processing of the batch has been completed then a message similar to one of the samples shown below will be returned. Page 25 of 90 Version 1.5 February 2015

26 Typical Bulk Upload Retrieve Response Sample The example shown below includes only one application. Up to 500 applications may be returned in a single response. <soap:body xmlns:soap=" <u:bulkuploadretrieveresponse xmlns:u=" <u:requestid>123456</u:requestid> <u:noofapplications>1</u:noofapplications> <u:noofapplicationsfailed>0</u:noofapplicationsfailed> <u:applications> <u:application> <u:processeddate> t04:36: z</u:processeddate> <u:applicationid>101</u:applicationid> <u:result>success</u:result> <u:identitydocumentverified></u:identitydocumentverified> <u:usi>h1289ff3333</u:usi> <u:errors/> </u:application> </u:applications> </u:bulkuploadretrieveresponse> </soap:body> Bulk Create USI Retrieve Response Sample with Unsuccessful Applications. If one or more applications within the batch were unsuccessful the results will be returned as below. <BulkUploadRetrieveResponse xmlns:xsi=" xmlns:xsd=" xmlns=" <RequestId>86044</RequestId> <NoOfApplications>1</NoOfApplications> <NoOfApplicationsFailed>1</NoOfApplicationsFailed> <Applications> <Application> <ProcessedDate> T04:36: Z</ProcessedDate> <ApplicationId>657061</ApplicationId> <Result>Failure</Result> <IdentityDocumentVerified>False</IdentityDocumentVerified> <Errors> <Error> <Code>1000</Code> <Message>The field is not a valid address.</message> </Error> </Errors> </Application> </Applications> </BulkUploadRetrieveResponse> Page 26 of 90 Version 1.5 February 2015

27 Bulk Create USI Retrieve Response Description Bulk create retrieve response returns the asynchronously processed results of a batch create request. Constraints This response will only be issued when the requested batch has completed processing. Attribute Name Type Description Constraints RequestId string This contains the identifier that the organisation has nominated to identify the bulk upload file. See section Bulk Upload Response for details NoOfApplications int The number of applications submitted for processing. NoOfApplicationsFailed int Applications List of ApplicationResponse Type The number of applications that failed processing. See section Application Response Type for details Validation Rules: The value must not exceed 20 characters Page 27 of 90 Version 1.5 February 2015

28 4.3.4 Verify a single USI This service allows a caller to submit a single student s USI and personal details in order to confirm their validity Request Message Verify USI Sample for two names A typical Verify USI message is shown below: <soap:body xmlns:soap=" <u:verifyusi xmlns:u=" <u:orgcode>123456</u:orgcode> <u:usi>abcdefghjk</u:usi> <u:firstname>john</u:firstname> <u:familyname>smith</u:familyname> <u:dateofbirth> </u:dateofbirth> </u:verifyusi> </soap:body> Verify USI Sample for a single name A typical Verify USI message for a student with a single name is shown below: <soap:body xmlns:soap=" <u:verifyusi xmlns:u=" <u:orgcode>123456</u:orgcode> <u:usi>abcdefghjk</u:usi> <u:singlename>fred</u:singlename> <u:dateofbirth> </u:dateofbirth> </u:verifyusi> </soap:body> Page 28 of 90 Version 1.5 February 2015

29 Verify USI Request Type Description Verify is used to ensure that the combination of USI, name(s) and DOB matches the USI record. Constraints When providing values for the name fields the consumer must provide either FirstName and Surname or SingleName Attribute Name Type Description Constraints OrgCode string Unique identifier for an organisation registered in the system. USI string Contains the USI value to be verified FirstName string The first name to be verified with the USI value. FamilyName string The family name to be verified with the USI value. SingleName string The single name to be verified with the USI value. A-Z, a-z, 0-9 Validation Rules: Must not exceed 6 characters Length = 10 characters Valid values upper case A-Z [ excluding O & I ], number 2-9 unless SingleName provided The value must not exceed 40 characters unless SingleName provided The value must not exceed 40 characters if FirstName and FamilyName have not been provided. False if either FirstName or FamilyName is provided. The value must not exceed 40 characters. Page 29 of 90 Version 1.5 February 2015

30 DateOfBirth Date The date of birth to be verified with the USI value. Format: yyyy-mm-dd Page 30 of 90 Version 1.5 February 2015

31 Response Message Verify USI Response Sample A typical response message is as follows: <soap:body xmlns:soap=" <u:verifyusiresponse xmlns:u=" <u:usistatus>valid</u:usistatus> <u:firstname>match</u:firstname> <u:familyname>match</u:familyname> <u:dateofbirth>match</u:dateofbirth> </u:verifyusiresponse> </soap:body> Verify USI Response Type Description Returns the result of an attempt to verify USI details Constraints If the USI field is invalid then all other fields will return no match. Returned names will match the request i.e. FirstName and FamilyName will be returned if these were the values passed in the request. Attribute Name Type Description Constraints USIStatus string Contains the result of locating or an alternate status of the USI Valid, Invalid, Deactivated FirstName string The first name result according to the USI. False Match, No Match Validation Rules: If the USI value is Invalid then this value will be No Match. FamilyName string The family name result according to the USI. False Match, No Match Page 31 of 90 Version 1.5 February 2015

32 Validation Rules: If the USI value is Invalid then this value will be No Match. SingleName string The single name result according to the USI. False Match, No Match Validation Rules: If the USI value is Invalid then this value will be No Match. DateOfBirth Date The date of birth result according to the USI. False Match, No Match Validation Rules: If the USI value is Invalid then this value will be No Match. Page 32 of 90 Version 1.5 February 2015

33 4.3.5 Bulk Verify multiple USIs The Bulk Verify USI service allows a caller to submit multiple USI details for verification in the same manner as Verify USI allows a single verification. A maximum of 500 USI verifications can be submitted in each batch request. The Bulk Verify USI service is a synchronous operation Request Message Bulk Verify USI Sample for two names A typical Bulk Verify USI message is shown below: <soap:body xmlns:soap=" <u:bulkverifyusi xmlns:u=" <u:orgcode>123456</u:orgcode> <u:noofverifications>2</u:noofverifications> <u:verifications> <u:verification> <u:recordid>1</u:recordid> <u:usi>abcdefghjk</u:usi> <u:firstname>john</u:firstname> <u:familyname>smith</u:familyname> <u:dateofbirth> </u:dateofbirth> </u:verification> <u:verification> <u:recordid>2</u:recordid> <u:usi>abcdefghj2</u:usi> <u:firstname>joe</u:firstname> <u:familyname>bloggs</u:familyname> <u:dateofbirth> </u:dateofbirth> </u:verification> </u:verifications> </u:bulkverifyusi> </soap:body> Bulk Verify USI Sample for a single name A typical Bulk Verify USI message is shown below: Page 33 of 90 Version 1.5 February 2015

34 <soap:body xmlns:soap=" <u:bulkverifyusi xmlns:u=" <u:orgcode>123456</u:orgcode> <u:noofverifications>2</u:noofverifications> <u:verifications> <u:verification> <u:recordid>1</u:recordid> <u:usi>abcdefghj2</u:usi> <u:singlename>joe</u:singlename> <u:dateofbirth> </u:dateofbirth> </u:verification> <u:verification> <u:recordid>2</u:recordid> <u:usi>abcdefgh22</u:usi> <u:singlename>fred</u:singlename> <u:dateofbirth> </u:dateofbirth> </u:verification> </u:verifications> </u:bulkverifyusi> </soap:body> Page 34 of 90 Version 1.5 February 2015

35 Bulk Verify USI Type Description Bulk Verify is used to ensure that the combination of USI, name(s) and DOB matches the USI records. Constraints When providing values for the name fields the consumer must provide either FirstName and Surname or SingleName Attribute Name Type Description Constraints OrgCode String Unique identifier for an organisation registered in the system. NoOfVerifications Int Number of verification requests in the batch. Verifications List of Verification Types See Verification Type below A-Z, a-z, 0-9 Validation Rules: Must not exceed 6 characters Validation Rules: Must be between 1 and 500. Page 35 of 90 Version 1.5 February 2015

36 Verification Type Description Contains the record data for each verification request in a Bulk Verify USI Request. Constraints Attribute Name Type Description Constraints RecordId Int A unique record identifier (within a request batch) used to identify verifications. USI string Contains the USI value to be verified. FirstName string The first name to be verified with the USI value. FamilyName string The family name to be verified with the USI value. SingleName string The single name to be verified with the USI value. Validation Rules: Must be unique within the batch. Length = 10 characters Valid values upper case A-Z [ excluding O & I ], number 2-9 unless SingleName provided The value must not exceed 40 characters unless SingleName provided The value must not exceed 40 characters if FirstName and FamilyName are not provided. False if FirstName or FamilyName is provided. The value must not exceed 40 characters. Page 36 of 90 Version 1.5 February 2015

37 DateOfBirth Date The date of birth to be verified with the USI value. Format: yyyy-mm-dd dd= mm= yyyy = from 110 years ago to 10 years ago Response Message Bulk Verify USI Response Sample A typical response message is as follows: <soap:body xmlns:soap=" <u:bulkverifyusiresponse xmlns:u=" <u:verificationresponses> <u:verificationresponse> <u:usistatus>valid</u:usistatus> <u:firstname>match</u:firstname> <u:familyname>match</u:familyname> <u:dateofbirth>match</u:dateofbirth> <u:usi>hgdfsgyhig</u:usi> <u:recordid>1</u:recordid> </u:verificationresponse> <u:verificationresponse> <u:usistatus>valid</u:usistatus> <u:firstname>match</u:firstname> <u:familyname>match</u:familyname> <u:dateofbirth>match</u:dateofbirth> <u:usi>jhabveuykj</u:usi> <u:recordid>2</u:recordid> </u:verifyusiresponse> <u:verificationresponse> <u:usistatus>valid</u:usistatus> <u:singlename>match</u:singlename> <u:dateofbirth>match</u:dateofbirth> <u:usi>abcdefgh22</u:usi> <u:recordid>3</u:recordid> </u:verifyusiresponse> </u:verificationresponses> </u:bulkverifyusiresponse> </soap:body> Page 37 of 90 Version 1.5 February 2015

38 Bulk Verify USI Type Description Bulk Verify response returns the result of an attempt to verify USI details in bulk. Constraints Attribute Name Type Description Constraints VerificationResponses List of VerificationResponse Types See Verification Response below Verification Response Type Description Contains the record data for each verification response from a Bulk Verify USI Request. Constraints If the USI field is invalid then all other fields will return no match. Returned names will match the request i.e. FirstName and LastName will be returned if these were the values passed in the request. Attribute Name Type Description Constraints RecordId Int A unique record identifier (within a response batch) used to identify verification results. USI string Contains the USI value that was verified. USIStatus string Contains the result of locating or an alternate status of the USI Validation Rules: Must be unique within the batch. Length = 10 characters Valid values upper case A-Z [ excluding O & I ], number 2-9 Valid, Invalid, Deactivated Page 38 of 90 Version 1.5 February 2015

39 FirstName string The first name result according to the USI. FamilyName string The family name result according to the USI. SingleName string The single name result according to the USI. DateOfBirth Date The date of birth result according to the USI. Match, No Match Validation Rules: If the USI value is Invalid then this value will be No Match. Match, No Match Validation Rules: If the USI value is Invalid then this value will be No Match. Match, No Match Validation Rules: If the USI value is Invalid then this value will be No Match. Match, No Match Validation Rules: If the USI value is Invalid then this value will be No Match. Page 39 of 90 Version 1.5 February 2015

40 4.3.6 Get Non DVS Document Types The Get Non DVS Document Types service allows a caller to retrieve a list of Non DVS documents that can then be used when overriding DVS for Create USI and Update Personal detail methods. The Get Non DVS Document Types service is a synchronous operation Request Message Get Non DVS Document Types Request Sample A typical request message to the Get Non DVS Document Types for USI service is show below: <s:body xmlns:xsi=" xmlns:xsd=" <GetNonDvsDocumentTypes xmlns=" <OrgCode>0001</OrgCode> </GetNonDvsDocumentTypes> </s:body> Get Non DVS Document Types Request Description GetNonDvsDocumentTypes manages the information of who issued the call. Constraints Nil Attribute Name Type Description Constraints OrgCode string Unique identifier for an organisation registered with training.gov.au or the USI Registrar Response Message Get Non DVS Document Types Request Response A-Z, a-z, 0-9 Validation Rules: Must not exceed 6 characters A typical response message from the Get Non DVS Document Types service is shown below: <s:body xmlns:xsi=" xmlns:xsd=" <GetNonDvsDocumentTypesResponse xmlns=" <NonDvsDocumentTypes> <NonDvsDocumentType> <Id>1</Id> <DocumentType>Other</DocumentType> <SortOrder>9000</SortOrder> </NonDvsDocumentType> Page 40 of 90 Version 1.5 February 2015

41 <NonDvsDocumentType> <Id>4</Id> <DocumentType>Proof of Age Card</DocumentType> <SortOrder>1000</SortOrder> </NonDvsDocumentType> <NonDvsDocumentType> <Id>5</Id> <DocumentType>Student Card</DocumentType> <SortOrder>1000</SortOrder> </NonDvsDocumentType> <NonDvsDocumentType> <Id>6</Id> <DocumentType>International Drivers Licence</DocumentType> <SortOrder>1000</SortOrder> </NonDvsDocumentType> <NonDvsDocumentType> <Id>7</Id> <DocumentType>International Birth Certificate</DocumentType> <SortOrder>1000</SortOrder> </NonDvsDocumentType> </NonDvsDocumentTypes> </GetNonDvsDocumentTypesResponse> </s:body> Get Non DVS Document Types Response Description GetNonDvsDocumentTypesResponse returns an array of current Non-DVS Document Types. Constraints Nil Attribute Name Type Description Constraints NonDvsDocu menttypes List of Non Dvs Document Types See section Non DVS Document Type below for details. Page 41 of 90 Version 1.5 February 2015

42 4.3.7 Update Personal Details for USI The Update Personal Details for USI service allows a caller to update personal details for a USI for which they have update permission. Only one field can be updated per request. The Update Personal Details for USI service is a synchronous operation Request Message Update Personal Details for USI Request Sample A typical request message to the Update Personal Details for USI service is show below: <s:body> <UpdateUSIPersonalDetails xmlns:xsi=" xmlns=" <OrgCode>0001</OrgCode> <USI>CMUQX5HRTA</USI> <DVSCheckRequired>true</DVSCheckRequired> <UserReference>23319</UserReference> <PersonalDetailsModifier>FirstName</PersonalDetailsModifier> <PersonalDetailsUpdate> <FirstName>Henry</FirstName> </PersonalDetailsUpdate> <DVSDocument xsi:type="driverslicencedocumenttype"> <LicenceNumber>111111</LicenceNumber> <State>ACT</State> </DVSDocument> </UpdateUSIPersonalDetails> </s:body> Update USI Personal Details Request Description UpdateUSIPersonalDetails manages the information of who issued the call, the USI being updated and the personal detail being updated. Attribute Constraints The personal detail being updated must be supplied. Any other personal details supplied will be ignored. Name Type Description Constraints OrgCode string Unique identifier for an organisation registered with training.gov.au or the USI Registrar. A-Z, a-z, 0-9 Validation Rules: Must not exceed 6 characters Page 42 of 90 Version 1.5 February 2015

43 USI string The USI being updated. DVSCheckRequired boolean Allows the organisation to override the DVS identity verification check. NonDvsDocumentTyp eid NonDvsDocumentTyp eother int string This value should only be set to false if the organisation has DVS override permission or the personal detail being updated does not require a DVS check. When overriding DVS this is the other document viewed to prove the students identity. Is the document used to verify a students identity when it is not listed in the non-dvs document list. Length = 10 characters Valid values upper case A-Z [ excluding O & I ], number 2-9 true, false (lower case only) False Must match one of the IDs returned from GetNonDvsDocumentTypes web method. when NonDvsDocumentTypeId = 1 (Other) Validation Rules: The value cannot exceed 50 characters. UserReference string This value contains the identifier of the user who created the application Validation Rules: The value cannot exceed 40 characters. Page 43 of 90 Version 1.5 February 2015

44 PersonalDetailsModifier PersonalDetailsModifi er PersonalDetailsUpdat e PersonalDetailsType The personal detail being updated. See section Personal Details Type below DVSDocument DVSDocumentType See section DVS Document Type below FirstName, MiddleName, FamilyName, SingleName, DateOfBirth, CountryOfBirth, TownCityOfBirth, Gender, CountryStudyingIn Note: The field being updated is mandatory. Any other supplied fields are ignored. if DVSCheckRequired is Response Message Update Personal Details for USI Response A typical response message from the Update Personal Details service is shown below: <s:body xmlns:xsi=" xmlns:xsd=" <UpdateUSIPersonalDetailsResponse xmlns=" <Result>Success</Result> <IdentityDocumentVerified></IdentityDocumentVerified> </UpdateUSIPersonalDetailsResponse> </s:body> Update USI Personal Details ResponseType Description UpdateUSIPersonalDetailsResponse returns the result of the Update Personal Details for USI Constraints Attribute Name Type Description Constraints Page 44 of 90 Version 1.5 February 2015

45 Result string Whether the USI Record has been updated successfully or not. IdentityDocu mentverified string If the identity document provided was verified successfully. Errors List of Error items See Error Type for details Success, Failure, False, NotVerified if Result is Failure. Page 45 of 90 Version 1.5 February 2015

46 4.3.8 Update Contact Details for USI The Update Contact Details for USI service allows a caller to update the contact details for USI for which they have update permission. Any contact details supplied will be updated on the USI record. Existing values cannot be cleared. The Update Contact Details for USI service is a synchronous operation Request Message Update Contact Details for USI Request Sample A typical request message to the Update Contact Details for USI service is show below: <s:body> <UpdateUSIContactDetails xmlns:xsi=" xmlns=" <OrgCode>0001</OrgCode> <USI>CMUQX5HRTA</USI> <UserReference>58775</UserReference> <ContactDetailsUpdate> <PreferredMethod> </PreferredMethod> <CountryOfResidence>Australia</CountryOfResidence> < Address>testperson@somewhere.com</ Address> <Phone> <Home> </Home> <Mobile> </Mobile> </Phone> <NationalAddress> <Address1>12 Main St</Address1> <SuburbTownCity>Page</SuburbTownCity> <State>ACT</State> <PostCode>2614</PostCode> </NationalAddress> </ContactDetailsUpdate> </UpdateUSIContactDetails> </s:body> Update USI Contact Details Request Description UpdateUSIContactDetails manages the information of who issued the call, the USI being updated and the contact details being updated. Attribute Constraints The address details supplied must be appropriate for the Country of Residence of the student (Australian address vs International address). If preferred contact method is changed, the selected contact method must have a value set. Name Type Description Constraints Page 46 of 90 Version 1.5 February 2015