Documentation

Endpoints

Environment	URL
Production	T.b.d.
Acceptance	https://acc-distributor.edu-ix.nl/soap/5.1/profile
Test	https://test-distributor.edu-ix.nl/soap/5.1/profile

Downloads

WSDL
XSD

Authorization

The following roles have access to this web service:

Role
Distributor
ELO

Operation overview

login
getPersons
getSchools
deletePersons
uploadPersons

Operations

Description

The login function provides you with a sessionID after execution. This sessionID can be used to execute consecutive operations with the sessionIDHeader.

Authorization

The following roles have access to this operation:

Role
Distributor
ELO

Authentication

Name

Type

Cardinality

loginHeader

1...1

Source

 <urn:loginHeader>
    <!--Optional:-->
    <urn:username>?</urn:username>
    <!--Optional:-->
    <urn:password>?</urn:password>
 </urn:loginHeader>

Request

Empty request

Response

Name	Type	Cardinality
sessionID	string64	1...1

Error codes

Error code	Description
2	Authentication error

getPersons

Description

The getPerson operation can be used to retreive information about persons. This operation can be used either as and distributor or ELO.

ELO

As an ELO this operation can be used to retrieve personal details for the prematch process. The element profileID, userID of portalID can be used to indicate which persons to filter.

In some occasions the school makes use of an ECK ID. The prematch process isn't required in case of an ECK ID and therefore the person objects within the response do not contain any personal details.

Authorization

The following roles have access to this operation:

Role
Distributor
ELO

Authentication

You have a choice to use either the loginHeader or the sessionIDHeader to authenticate. A sessionID can be obtained by performing the login operation on beforehand.

Name

Cardinality

You have a CHOICE of the next 2 items at this level

NameTypeCardinalityloginheaderloginHeader1...1sessionIDHeadersessionIDHeader1...1

1...1

Source

 <urn:authHeader>
    <!--You have a CHOICE of the next 2 items at this level-->
    <urn:loginHeader>
       <!--Optional:-->
       <urn:username>?</urn:username>
       <!--Optional:-->
       <urn:password>?</urn:password>
    </urn:loginHeader>
    <urn:sessionIDHeader>
       <urn:sessionID>?</urn:sessionID>
    </urn:sessionIDHeader>
 </urn:authHeader>

Request

Name

Cardinality

You have a CHOICE of the next 4 items at this level

NameTypeCardinalityportalIDstring641..1profileIDprofileID1...100distributorPersonIDstring2561...100userIDstring2561...100

1..1

Source

<urn:getPersonsRequest>
    <!--You have a CHOICE of the next 4 items at this level-->
    <urn:portalID>?</urn:portalID>
    <!--1 to 100 repetitions:-->
    <urn:profileID>?</urn:profileID>
    <!--1 to 100 repetitions:-->
    <urn:distributorPersonID>?</urn:distributorPersonID>
    <!--1 to 100 repetitions:-->
    <urn:userID>?</urn:userID>
 </urn:getPersonsRequest>

Response

In case of a request by multiple profileID's, distributorPersonID's or userID's the response can be partially built up when records are not found or available.

Name	Type	Cardinality
person	person	0...n

Error codes

Error code	Description
4	Authorization error
6	Missing required field(s)

getSchools

Description

The getSchools operations outputs a list of available schools.

Authorization

The following roles have access to this operation:

Role
Distributor
ELO

Authentication

You have a choice to use either the loginHeader or the sessionIDHeader to authenticate. A sessionID can be obtained by performing the login operation on beforehand.

Name

Cardinality

You have a CHOICE of the next 2 items at this level

NameTypeCardinalityloginheaderloginHeader1...1sessionIDHeadersessionIDHeader1...1

1...1

Source

 <urn:authHeader>
    <!--You have a CHOICE of the next 2 items at this level-->
    <urn:loginHeader>
       <!--Optional:-->
       <urn:username>?</urn:username>
       <!--Optional:-->
       <urn:password>?</urn:password>
    </urn:loginHeader>
    <urn:sessionIDHeader>
       <urn:sessionID>?</urn:sessionID>
    </urn:sessionIDHeader>
 </urn:authHeader>

Request

Name

Type

Cardinality

You have a CHOICE of the next 2 items at this level

NameTypeCardinalityorganisationIDorganisationID1...100portalIDstring641...1

1...1

Source

<urn:getSchoolsRequest>
    <!--You have a CHOICE of the next 2 items at this level-->
    <!--1 to 100 repetitions:-->
    <urn:organisationID>?</urn:organisationID>
    <urn:portalID>?</urn:portalID>
 </urn:getSchoolsRequest>

Response

Name	Type	Cardinality
school	school	0...n

Error codes

Error code	Description
4	Authorization error
6	Missing required field(s)

deletePersons

Description

This operations allows for deletion of a person.

Authorization

The following roles have access to this operation:

Role
Distributor

Authentication

You have a choice to use either the loginHeader or the sessionIDHeader to authenticate. A sessionID can be obtained by performing the login operation on beforehand.

Name

Cardinality

You have a CHOICE of the next 2 items at this level

NameTypeCardinalityloginheaderloginHeader1...1sessionIDHeadersessionIDHeader1...1

1...1

Source

 <urn:authHeader>
    <!--You have a CHOICE of the next 2 items at this level-->
    <urn:loginHeader>
       <!--Optional:-->
       <urn:username>?</urn:username>
       <!--Optional:-->
       <urn:password>?</urn:password>
    </urn:loginHeader>
    <urn:sessionIDHeader>
       <urn:sessionID>?</urn:sessionID>
    </urn:sessionIDHeader>
 </urn:authHeader>

Request

The request can obtain an maximum of 100 unique distributorPersonID's.

Name

Type

Cardinality

distributorPersonID

string256

1...100

Source

<urn:deletePersonsRequest>
     <!--1 to 100 repetitions:-->
     <urn:distributorPersonID>?</urn:distributorPersonID>
</urn:deletePersonsRequest>

Response

Empty response

Error codes

Error code	Description
4	Authorization error
6	Missing required field(s)
7	Record not found

uploadPersons

Description

With the uploadPersons operation you have the ability to upload persons. Either a single or multiple persons can be uploaded in a single call.

Authorization

The following roles have access to this operation:

Role
Distributor

Authentication

You have a choice to use either the loginHeader or the sessionIDHeader to authenticate. A sessionID can be obtained by performing the login operation on beforehand.

Name

Cardinality

You have a CHOICE of the next 2 items at this level

NameTypeCardinalityloginheaderloginHeader1...1sessionIDHeadersessionIDHeader1...1

1...1

Source

 <urn:authHeader>
    <!--You have a CHOICE of the next 2 items at this level-->
    <urn:loginHeader>
       <!--Optional:-->
       <urn:username>?</urn:username>
       <!--Optional:-->
       <urn:password>?</urn:password>
    </urn:loginHeader>
    <urn:sessionIDHeader>
       <urn:sessionID>?</urn:sessionID>
    </urn:sessionIDHeader>
 </urn:authHeader>

Request

Name

Type

Cardinality

person

uploadPerson

1...100

Source

<urn:uploadPersonsRequest>
    <!--1 to 100 repetitions:-->
    <urn:person>
       <urn:distributorPersonID>?</urn:distributorPersonID>
       <urn:firstName>?</urn:firstName>
       <!--Optional:-->
       <urn:preposition>?</urn:preposition>
       <urn:surname>?</urn:surname>
       <urn:postalCode>?</urn:postalCode>
       <!--Optional:-->
       <urn:houseNumber>?</urn:houseNumber>
       <!--Optional:-->
       <urn:gender>?</urn:gender>
       <!--Optional:-->
       <urn:dateOfBirth>?</urn:dateOfBirth>
       <urn:countryCode>?</urn:countryCode>
    </urn:person>
 </urn:uploadPersonsRequest>

Response

Empty response

Error codes

Error code	Description
4	Authorization error
6	Missing required field(s)

Errors

General errors

General errors may occur within every operation.

Error code	Description
0	Unkown error
1	General error This occurs in for example: database errors or internal server errors.
2	Authentication error For instance when invalid credentials are provided.
3	Login sessionID is expired The given sessionID is no longer active and has expired. Acquire a new sessionID to proceed.
4	Authorization error You do not have permission to use this operation.
5	Bad request Parsing error, for instance when invalid xml has been provided.

Specific errors

Specific errors are bound to the given input or request and depend on the operation you execute.

Error code	Description
6	Missing required field(s) One or more fields are missing within the request. In case of a choice-element at least one value must be given.
7	Record not found A given value was not found.
8	Record cannot be changed Some functions are idempotent and therefor values cannot be altered within a second request.
9	Process validation error The given request does not meet the process constraints

Complex types

person

Name	Type	Cardinality	Description
profileID	profileID	1...1	Unique identifier generated by Edu-iX.
distributorPersonID	string256	0...1	Unique identifier of the person to which this credit is connected.
firstName	string50	1...1	First name of the person
preposition	string15	0...1	Preposition of the person
surname	string50	1...1	Surname of the person
postalCode	postalCode	1...1	In case of a dutch postal code a regex check is applied.
houseNumber	houseNumber	0...1	Housenumber
gender	gender	0...1	The person his gender
dateOfBirth	dateOfBirth	0...1	Date of birt of the person
countryCode	countryCode	1...1	Country code in which the person lives
userID	string256	0...1	Unique identification of the end user. This value is also known as the prematch value.
Source <xs:complexType name="person"> <xs:sequence> <xs:element name="profileID" type="types:profileID" minOccurs="1" maxOccurs="1"/> <xs:element name="distributorPersonID" type="types:string256" minOccurs="0" maxOccurs="1"/> <xs:element name="firstName" type="types:string50" minOccurs="1" maxOccurs="1"/> <xs:element name="preposition" type="types:string15" minOccurs="0" maxOccurs="1"/> <xs:element name="surname" type="types:string50" minOccurs="1" maxOccurs="1"/> <xs:element name="postalCode" type="types:postalCode" minOccurs="1" maxOccurs="1"/> <xs:element name="houseNumber" type="types:houseNumber" minOccurs="0" maxOccurs="1"/> <xs:element name="gender" type="types:gender" minOccurs="0" maxOccurs="1"/> <xs:element name="dateOfBirth" type="types:dateOfBirth" minOccurs="0" maxOccurs="1"/> <xs:element name="countryCode" type="types:countryCode" minOccurs="1" maxOccurs="1"/> <xs:element name="userID" type="types:string256" minOccurs="0" maxOccurs="1"/> </xs:sequence> </xs:complexType>

uploadPerson

Name	Type	Cardinality	Description
distributorPersonID	string256	1...1	Unique identifier of the person to which this credit is connected.
firstName	string50	1...1	First name of the person
prepostion	string15	0...1	Preposition of the person
surname	string50	1...1	Surname of the person
postalCode	postalCode	1...1	In case of a dutch postal code a regex check is applied.
houseNumber	houseNumber	0...1	Housenumber
gender	gender	0...1	The person his gender
dateOfBirth	dateOfBirth	0...1	Date of birt of the person
countryCode	countryCode	1...1	Country code in which the person lives
Source <xs:complexType name="uploadPerson"> <xs:sequence> <xs:element name="distributorPersonID" type="types:string256" minOccurs="1" maxOccurs="1"/> <xs:element name="firstName" type="types:string50" minOccurs="1" maxOccurs="1"/> <xs:element name="preposition" type="types:string15" minOccurs="0" maxOccurs="1"/> <xs:element name="surname" type="types:string50" minOccurs="1" maxOccurs="1"/> <xs:element name="postalCode" type="types:postalCode" minOccurs="1" maxOccurs="1"/> <xs:element name="houseNumber" type="types:houseNumber" minOccurs="0" maxOccurs="1"/> <xs:element name="gender" type="types:gender" minOccurs="0" maxOccurs="1"/> <xs:element name="dateOfBirth" type="types:dateOfBirth" minOccurs="0" maxOccurs="1"/> <xs:element name="countryCode" type="types:countryCode" minOccurs="1" maxOccurs="1"/> </xs:sequence> </xs:complexType>

loginHeader

Name

Type

Cardinality

Description

username

string100

0...1

password

string64

0...1

Source

<xs:complexType name="loginHeader">
 <xs:sequence>
    <xs:element name="username" type="types:string100" minOccurs="0" maxOccurs="1"/>
    <xs:element name="password" type="types:string64" minOccurs="0" maxOccurs="1"/>
 </xs:sequence>
</xs:complexType>

school

Name	Type	Cardinality
organisationID	organisationID	1...1
name	string100	1...1
street	string50	0...1
houseNumber	houseNumber	0...1
houseNumberAddition	string10	0...1
postalCode	postalCode	0...1
city	string50	0...1
countryCode	countryCode	1...1
brin	string10	0...1
Source

sessionIDHeader

Name

Type

Cardinality

Description

sessionID

string64

1...1

Unique token which can be acquired by executing the login operation.

Source

<xs:complexType name="sessionIDHeader">
 <xs:sequence>
    <xs:element name="sessionID" type="types:string64" minOccurs="1" maxOccurs="1"/>
 </xs:sequence>
</xs:complexType>

Simple types

Name	Type	Possible values / format	Description
string10	String	Max length: 10 characters	String limited by a number of maximum allowed characters.
string15	String	Max length: 15 characters	String limited by a number of maximum allowed characters.
string50	String	Max length: 50 characters	String limited by a number of maximum allowed characters.
string64	String	Max length: 64 characters	String limited by a number of maximum allowed characters.
string100	String	Max length: 100 characters	String limited by a number of maximum allowed characters.
string256	String	Max length: 256 characters	String limited by a number of maximum allowed characters.
postalCode	String	Max length: 10 characters	In case of a dutch postal code the following regex should be applied: [0-9]{4} [A-Z]{2}
houseNumber	Integer	Minimal value must be atleast 1
countryCode	Enum	Official ISO 3166-1 alpha-2 notation of a country code
gender	Enum	Possible values: M F U	M = male, F = female & U = unspecified
dateOfBirth	Date
profileID	Integer	Minimal value must be at least 1	A profile ID is an positive integer number with maximum 10 characters.
organisationID	String	Min length: 1 character Max length: 160 characters	Unique identifier of a school

Appendix

Terms

Term	Description
ECK	Educatieve contentketen. More information on: https://www.eck-id.nl/
ECK ID	Unique identifier of a person according to the ECK standard
ELO	Elektronische leeromgeving (electronic learning environment)
Specification	Specification is the proces of sending credits from Edu-iX to the publisher. Each specification contains information about the end user and the credit itself. After the specification is completed the credit is available for user by the end user.
Prematch	Prematch is the process of connecting the unique identifier of the end user, available in the ELO, to order data (personal details and credit information) in Edu-iX.

Profile 5.1

Documentation

Endpoints

Downloads

Authorization

Operation overview

Operations

login

Description

Authorization

Authentication

Request

Response

Error codes

getPersons

Description

ELO

Authorization

Authentication

Request

Response

Error codes

getSchools

Description

Authorization

Authentication

Request

Response

Error codes

deletePersons

Description

Authorization

Authentication

Request

Response

Error codes

uploadPersons

Description

Authorization

Authentication

Request

Response

Error codes

Errors

General errors

Specific errors

Complex types

person

uploadPerson

loginHeader

school

sessionIDHeader

Simple types

Appendix

Terms