Documentation
Endpoints
Environment | URL |
---|---|
Production | T.b.d. |
Acceptance | |
Test |
Downloads
WSDL
XSD
Authorization
The following roles have access to this web service:
Role |
---|
Distributor |
ELO |
Operation overview
login
getPersons
getSchools
deletePersons
uploadPersons
Operations
login
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
...
loginHeader
...
1...1
Source
...
Zie Technical documentation voor het actuele overzicht.
Authorization
The following roles have access to this web service:
Role |
---|
Distributor |
ELO |
Operation authentication
All operations, except login, need either the loginHeader or the sessionIDHeader to authenticate. A sessionID can be obtained by performing the login operation beforehand.
Name | Type | Cardinality | Description | ||
---|---|---|---|---|---|
loginHeader sessionIDHeader | 1...1 1...1 | You can use either one of the variables | |||
Source
|
|
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
|
Operation overview
Operations
login
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 | loginHeader | 1...1 | ||
Source
|
|
|
|
|
Request
...
Name
...
Cardinality
You have a CHOICE of the next 4 items at this level
NameTypeCardinalityportalIDstring641..1profileIDprofileID1...100distributorPersonIDstring2561...100userIDstring2561...100
...
1..1
Source
Code Block |
---|
<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
|
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 |
Request
Name | Cardinality | |||
---|---|---|---|---|
You have a CHOICE of the next 4 items at this level Name Type Cardinality portalID string64 1..1 profileID profileID 1...100 distributorPersonID string256 1...100 userID string256 1...100 | 1..1 | |||
Source
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
...
|
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 |
---|
You have a CHOICE of the next 2 items at this level
person | person | 0... |
1...1
Source
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 |
Request
Name | Type | Cardinality | ||
---|---|---|---|---|
You have a CHOICE of the next 2 items at this level Name Type Cardinality organisationID organisationID 1...100 portalID string64 1...1 | 1...1 | |||
Source
|
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.
...
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
...
Request
The request can obtain an maximum of 100 unique distributorPersonID's.
Name | Type | Cardinality |
---|---|---|
distributorPersonID | string256 | 1... |
100 | |||
Source
|
|
|
|
|
|
|
Request
...
|
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 |
Request
Name | Type | Cardinality |
---|
person |
uploadPerson | 1...100 | |||
Source
|
|
|
|
|
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
|
|
|
|
|
|
|
|
Request
...
Name
...
Type
...
Cardinality
...
person
...
uploadPerson
...
1...100
Source
Code Block |
---|
<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
|
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
|
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 |
houseNumber
applied. | |||
houseNumber | houseNumber | 0...1 | Housenumber |
gender | gender | 0...1 | The person his gender |
dateOfBirth | dateOfBirth | 0...1 |
Housenumber
gender
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
Date of birt of the person | ||
countryCode | countryCode | 1...1 |
The person his gender
Country code in which the person lives | |||||
Source
|
|
|
|
|
|
|
|
|
|
|
|
|
loginHeader
Name | Type | Cardinality | Description | ||
---|---|---|---|---|---|
username | string100 | 0...1 | An identification used by a person to login. | ||
password | string64 | 0...1 | A secret word or phrase used for authentication. | ||
Source
|
|
|
|
|
|
uploadPerson
Name
Type
Cardinality
Description
distributorPersonID
|
school
Name | Type | Cardinality | Description |
---|---|---|---|
organisationID | organisationID | 1...1 | Unique identifier of the school to which this credit is connected. |
name | string100 | 1...1 | Name of the school. |
street | string50 | 0...1 | Street address of the school. |
houseNumber | houseNumber | 0...1 | Street number of the school. |
houseNumberAddition | string10 | 0...1 | Street number addition of the school. |
postalCode | postalCode | 0...1 | Postal code of the school. |
city | string50 | 0...1 | City in which the school is located. |
countryCode | countryCode | 1...1 |
Unique identifier of the person to which this credit is connected.
firstName
string50
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
Country in which the school is located. | ||
brin | string10 | 0...1 |
First name of the person
The BRIN(Basisregistratie instellingen) is an identifier. The first four characters are alphanumerical and represent an educational institution. The last characters are numerical and represent an identifier for the location of a educational institution. | |||||
Source
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
...
|
Fault
Name | Type | Cardinality | Description | ||
---|---|---|---|---|---|
code | integer | 1...1 | Code to identify the fault type. | ||
message | string | 1...1 | Specific message which describes the fault. | ||
Source
|
FaultPerPerson
Name | Type | Cardinality | Description |
---|
personFault |
personFault | 0... |
password
string64
n | A collection of personFault distinguished per person. | ||||
Source
|
|
|
...
personFault
Name | Type | Cardinality |
---|
Description
organisationID
organisationID
Description | |||
---|---|---|---|
distributorPersonID | string256 | 1...1 | Unique identifier of the person for whom the fault occured. |
code | integer | 1...1 |
name
houseNumberAddition
string10
0...1
postalCode
postalCode
0...1
city
string50
0...1
countryCode
countryCode
1...1
brin
string10
0...1
Source
Code to identify the fault type. | ||
message | string | 1...1 |
street
string50
0...1
houseNumber
houseNumber
0...1
Specific message which describes the fault. | |||||
Source
|
sessionIDHeader
Name | Type | Cardinality | Description | ||
---|---|---|---|---|---|
sessionID | string64 | 1...1 | Unique token which can be acquired by executing the login operation. | ||
Source
|
...
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 = 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, e.g. “digiDeliveryId”. |
...
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. |