Introduction

This document describes API for Individual Sales Service (also referred to with abbreviation ISS) in the information system ALIVE Platform. API for Individual Sales Service was developed for card issuers (mostly universities) that issue digital only cards by themselves, but the student pays for the card from his/her side through online payment gateway. The API also allows to manage cardholders, card validity, status and other related parameters.

High level description of the whole process (more detailed description at the end of this tutorial):

1/ University creates a cardholder.

2/ University uploads photo for a cardholder (this step is not mandatory).

3/ University sends API request for new card issuance or for validity extension.

4/ The API returns back URL for a website, where the student (cardholder) puts additional personal data, contact data and pays for the card. Payment gateway with several payment methods is integrated into the whole process.

API specification

Authentication
• All API endpoints are secured so the client must be successfully authenticated to be able to call them.
• Client authentication is secured by Bearer Token which must be sent in the header of each API request as Authorization: Bearer xxx (xxx substituted by the token). The API is not session based.
• To obtain valid token the client is requested to call authentication service endpoint using unique authentication credentials provided by his ISIC account manager.
• The validity of the token is very short (token validity is a part of the authentication endpoint response) thus we recommend to ask for a new token before every set of the API requests.
• Data transfers are encrypted using SSL.

Content Type
• Most of the requests and responses use JSON data format (application/json content-type). Clients should also include request header parameter Accept: application/json to receive correct response data format.
• Images are uploaded using multipart/form-data encoding type. Besides a path to the image stored in the local device (as permanent or temporary file) the request must contain also cardholder_id attribute to identify the cardholder to whom the image is being uploaded. Base64 encoded images are not supported. A direct image data format is also not supported.
• Images are downloaded as general binary data (octet-stream) with appropriate MIME Content-Type header. Base64 encoded images are not supported.

Charset
• All requests should be sent with UTF-8 charset specified in the header.

Parameter and Attribute Validations
• The API validates query parameters and attributes of created or modified objects.
• Any errors are in the body of HTTP 422 response (see object model “Errors”).
• The error messages are only in English language.
• The API uses logical operator AND between query parameters.
• Date data type attributes are expected and returned in format “yyyy-MM-dd”.
• Datetime data type attributes uses ISO 8601 extended format

In API requests, date and time values are expected in local timezone with specification of the offset from UTC (e.g. for UTC+5 timezone the format should be “2020-08-03T14:35:26+05:00” meaning you would like to get data for specified day and time with time shift of 5 hours ahead of UTC).

In API responses, date and time values are always in UTC.

Listings Pagination
• The API supports “limit” and “offset” parameters in data listings to reduce data traffic for individual requests.
• The “limit” parameter is mandatory, its maximal value is not restricted.
• The “offset” parameter is zero-based index of the first returned record.

Responses Handling
• Clients are requested to ignore all unknown attributes in API responses to preserve compatibility in the future.
• The order of parameters in JSON responses is not significant and may change over time. Clients are requested to not rely on it.

Data Model

General Object Models

API Responses

API responses contain from HTTP code and response body with pre-defined structure as described below. In case of error the human readable error messages should be used only for debugging purposes and are not meant to be displayed to the end users.

[MODEL] API Response

Attribute Name	Data Type	Description

Attribute Name	Data Type	Description
message	String	Human readable API request result (provided only in English).
data	Array	Nested array of objects based on API endpoint relation (e.g. [MODEL] Card).
code	Integer	In case of error this attribute contains numeric error code.
errors	Array	Optional nested array of objects representing individual validation or error messages (see [MODEL] Errors).

[MODEL] Errors

Attribute Name	Data Type	Description

Attribute Name	Data Type	Description
property_name	String	Optional name of the attribute which the error message is related to.
message	String	Human readable error message (provided only in English).
code	String	Internal alphabet error code.

General Numeric Error Codes

Code Range	Description

Code Range	Description
1001	Invalid data.
1002	Given JWT token is malformed and does not contain required attributes.
1003	Given media type is not supported.
2001	Invalid credentials.
2002	Authentication required.
3001	Entity not found.

Sample Response Body - Success

{
"message": "OK",
"data": [
{
"card_id": 12345
},
{
"card_id": 127455
}
]
}

Sample Response Body – Error

{
"message": "Cardholder not found.”,
“data”: [],
“code”: 3001
}

OR

{
“message”: “Invalid data.”,
“data”: [],
“code”: 1001,
“errors”: [
{
“property_name”: “access_key_id”,
“message”: “This value should not be blank.”,
“code”: “IS_BLANK_ERROR”
},
{
“property_name”: “secret_access_key”,
“message”: “This value should not be blank.”,
“code”: “IS_BLANK_ERROR”
}
]
}

Data Object Models

Cardholders

[MODEL] Cardholder

Attribute Name	Data Type	Validations	Description
cardholder_id	Integer	-	Unique, primary cardholder’s identifier.
external_id	String	Unique per card issuer	Cardholder’s identifier from the third-party’s system.
institution_id	Integer	-	Internal identifier of the academic institution (client) in NCDB.
academic_degree_before_name	String	Free	Cardholder’s pre-nominal academic degrees.
first_name	String	Free	Cardholder’s first name.
last_name	String	Free	Cardholder’s last name.
academic_degree_after_name	String	Free	Cardholder’s post-nominal academic degrees.
date_of_birth	Date	Not in future	Cardholder’s date of birth.
birth_number	String	Valid national format	Cardholder’s birth number.
gender	String	Enum	Cardholder’s gender.
email	String	Unique per card issuer	Cardholder’s e-mail address.
phone_number	String	Regex [0-9, (, ), +, -]	Cardholder’s phone number.
language	String	Enum	Preferred communication language, 2 letter language code.
personal_id	String	Free	Free cardholder’s identifier (student ID, membership ID, personal ID).
class_name	String	Free	Name of the school class.
grade	Integer	Values 1-9	Study grade.
roles	Object	-	Nested object (see [MODEL] Role).
student_status	String	Enum	If student, cardholder’s student status.
addresses	Array	-	Nested array of objects (see [MODEL] Address).
legal_representatives *	Array	-	Nested array of objects (see [MODEL] Legal Representative).
custom_fields **	Array	-	Nested array of objects (see [MODEL] Custom Field).

*At least one Legal Representative’s data must be specified in case the cardholder is younger than an age required by local law (15 years in the Czech Republic).

** Custom fields may be set as mandatory or optional based on client’s agreement with the ISIC account manager. Ask your ISIC account manager for the list of mandatory custom fields applicable for your account.

[MODEL] Role

Roles which are not included in the request are considered as the client doesn't know such information.
NOTE: Crossed out values will be supported in the future API development phases.

Attribute Name	Data Type	Validations	Description
graduate	Boolean	-	Successfully graduated person.
student	Boolean	-	Active student with all student privileges granted by local law.

[MODEL] Address

Attribute Name	Data Type	Validations	Description
type	String	Enum	Address type.
address_line_1	String	Free	First address line, usually street and house number.
address_line_2	String	Free	Second address line.
city	String	Free	City.
district	String	Enum	State/Province/County.
postal_code	String	Free	Postal (ZIP) code.
country	String	Enum	ISO 3166-1 alpha-3 country code (3 letter). (https://www.iso.org/iso-3166-country-codes.html )

[MODEL] Custom Field

Custom fields are created and assigned to individual card issuers by ISIC ER users based on the mutual agreement. Their setup range related to this API is key, mandatory/optional, and min. and max. allowed length of the string.

Attribute Name	Data Type	Validations	Description
name	String	Assigned field	Custom field’s name.
value	String	Field settings	Custom field’s value.

Cards

[MODEL] Card

Attribute Name	Data Type	Validations	Description
card_id	Integer	-	Unique, primary card identifier.
cardholder_id	Integer	-	Unique, primary cardholder’s identifier.
number	String	Assigned card number ranges	Card number.
type	String	Enum	Card type.
form	String	Enum	Card form.
status	String	Enum	Card status.
valid_from	Date	Available card validity cycles	Card validity start.
valid_to	Date	Available card validity cycles	Card validity end.
valid_to_plastic	Date	Available card validity cycles	Plastic card validity end (may be the same or shorter than the main card validity end).
design	String	Assigned card designs	Card design part number.
design_plastic	String	Assigned card designs	Plastic card design part number.
institution_id	Integer	NCDB’s institution database	ID of the institution where the cardholder studies/teaches/works as stored in NCDB’s institution database.
institution_name_line_1	String	Free	First line of the institution name where the cardholder studies/teaches/works as stated on a card.
institution_name_line_2	String	Free	Second line of the institution name where the cardholder studies/teaches/works as stated on a card.
smart_technologies	Array	-	Nested array of objects (see [MODEL] Smart Technology).
custom_fields	Array	-	Nested array of objects (see [MODEL] Custom Field).

[MODEL] Custom Field

Custom fields are created and assigned to individual card issuers by ISIC ER users based on the mutual agreement. Their setup range related to this API is key, mandatory/optional, and min. and max. allowed length of the string.

Attribute Name	Data Type	Validations	Description
name	String	Assigned to card issuer	Custom field name.
value	String	Field setup	Custom field value.

Enums

Cardholders

[ENUM] Gender

Value	Description
FEMALE	Female.
MALE	Male.
OTHER	Other.

[ENUM] Language

Preferred language for communication with a cardholder.

Value	Description
cs	Czech.
en	English.

[ENUM] Student Status

Value	Description
FULL_TIME	Full time student.
PART_TIME	Part time student.

[ENUM] District (State/Province/County)

Dependent on a country where the card issuer's profile is created. For the list of available values ask your ISIC account manager.

[ENUM] Country

ISO 3166-1 alpha-3 country codes (https://www.iso.org/iso-3166-country-codes.html).

Cards

[ENUM] Card Type

Value	Description
ISIC	ISIC card (for full-time students).
ISIC_SCHOLAR	ISIC SCHOLAR card (in the Czech Republic it is also known as ISIC Školák).
ITIC	ITIC card (for teachers).
IYTC	IYTC card (for youth people).
ALIVE	ALIVE card (for members of sport associations and other companies, issued only in the Czech Republic).
ALIVE_STUDENT	ALIVE Student card (for part-time students, issued only in the Czech Republic).
ALIVE_STAFF	ALIVE Staff card (for non-teaching staff of schools, issued only in the Czech Republic).
ALIVE_ALUMNI	ALIVE Alumni card (for university graduates, issued only in the Czech Republic).
ALIVE_ID_ALUMNI	ALIVE ID Alumni card (for university graduates].

[ENUM] Form

Value	Description
DIGITAL	Digital card.
DIGITAL_PLASTIC	Digital and plastic card.

[ENUM] Status

Value	Description
ACTIVE	Active card (does not inform about card validity period!).
CANCELLED	Cancelled card (e.g., damaged, lost, stolen).
RETURNED	Returned card (its number will be used for new cardholder).

Resources

Authentication

The authentication service is accessible without any credentials. In the request body the client must sent unique pair of authentication credentials provided by his ISIC account manager.

POST /authentication.authenticate

Request Body Parameters

Parameter Name	Data Type	Mandatory	Note
access_key_id	String	Yes	Unique API access key identifier (username equivalent).
secret_access_key	String	Yes	Unique API secret access key identifier (password equivalent).

Response
In the response the client may find an attribute expires_in informing about the token’s validity (in seconds).

• HTTP 200 – OK + Bearer Token

Sample Request Body

Sample Response Body

Cardholders

POST /cardholders.set

Create or update cardholder. For update you must include cardholder_id parameter in the request body. Cardholder updates are not differential. Within every request the client must send all cardholder’s data. Data missing in the request will be considered as for removal and will be deleted with no way to recover.
NOTE: The University should update cardholder data at the moment the new data is available, so the cardholder is still up to date.

Request Body Parameters

Parameter Name	Data Type	Mandatory	Note
cardholder_id	Integer	depends ->	Applicable only in case of the cardholder’s update, then mandatory. Anonymized cardholders cannot be updated.
external_id	String	No
academic_degree_before_name	String	No
first_name	String	Yes
last_name	String	Yes
academic_degree_after_name	String	No
date_of_birth	Date	Yes	Date cannot be in future. Format “yyyy-MM-dd”.
birth_number	String	No
gender	String	No
email	String	Yes	Valid e-mail address format. E-mail must be unique per all cardholders within the card issuer. All cards of a single person should be linked to the same cardholder identified by the cardholder_id.
phone_number	String	No
language	String	No
personal_id	String	No
roles	Object	Yes
graduate	Boolean	Yes
student	Boolean	Yes
student_status	String	Yes
addresses	Array	No	Addresses are not mandatory but if sent, it must contain all its parameters marked below as mandatory.
type	String	Yes
address_line_1	String	Yes
address_line_2	String	No
city	String	Yes
district	String	No
postal_code	String	Yes
country	String	Yes
custom_fields	Array	depends ->	Custom fields may be mandatory or optional based on client’s agreement with the ISIC account manager. Ask your ISIC account manager for the list of mandatory custom fields applicable for your account. If mandatory, it must contain all its parameters marked below as mandatory.
name	String	Yes
value	String	Yes

Response

• HTTP 200 – OK + [MODEL] Cardholder

Sample Request Body

Sample Response Body

POST /cardholders.setPhoto

Upload cardholder’s photo. When a photo is already present the next request will overwrite it. The previous photo will not be available to recover.

Based on the contract the photo is mandatory.

Validations
• JPG, JPEG or PNG file with RGB color space. PNG images with transparent background are transferred to an image with white background.
• Minimal image resolution is limited to 450 x 540 pixels (recommended at 300 DPI).
• Maximal image file size is limited to 3 MB.

Recommendations
• For best photo quality displayed/printed on a card the recommended image aspect ratio is 5:6.
• Photo should be in color containing a whole head of the cardholder. No sunglasses, no head covers.
• Photo background should be neutral (one color or soft color gradient).

Request Body

Request must be sent as multipart/form-data encoding type.

Parameter Name	Data Type	Mandatory	Note
cardholder_id	Integer	Yes
photo	File	Yes	Address of the photo file in the client’s folder structure.

Response
• HTTP 200 – OK

Sample Response Body

POST /cardholders.anonymize

Request anonymization of the cardholder identified by cardholder_id sent in the request body. The API will accept or reject the request. In case of the acceptance the cardholder’s data (including data of his/her cards) will be anonymized within next 48 hours.

Validations
• Cardholder does not own any valid card (see valid_to property on the [MODEL] Card).
• Cardholder has not been anonymized yet.

Sample Request Body

Sample Response Body

GET /cardholders.list

Get data of cardholders filtered based on specified query parameters. Returned data are sorted by date of last modification in descending order (last modified record first).

Query Parameters

All query parameters of string data type are case-insensitive.

Parameter Name	Data Type	Mandatory	Description
external_id	String	No	Cardholder’s external identifier.
first_name	String	No	Cardholder’s first name.
last_name	String	No	Cardholder’s last name.
date_of_birth	Date	No	Cardholder’s date of birth.
email	String	No	Cardholder’s e-mail address.
phone_number	String	No	Cardholder’s phone number.
modified_from	Datetime	No	Return records created or modified after specified date and time (for option of incremental updates on the API client’s side).
offset	Integer	No	Result paging offset (zero based index of the first returned item).
limit	Integer	Yes	Result page size (how many items to return).

Response
• HTTP 200 – OK + collection of [MODEL] Cardholder

GET /cardholders.get

Get data of the cardholder specified in the query parameter.

Query Parameters

Parameter Name	Data Type	Mandatory	Description
cardholder_id	Integer	Yes	Unique cardholder’s identifier.

Response
• HTTP 200 – OK + [MODEL] Cardholder

GET /cardholders.getPhoto

Get photo of the cardholder specified in the query parameter.

Query Parameters

Parameter Name	Data Type	Mandatory	Description
cardholder_id	Integer	Yes	Unique cardholder’s identifier.

Response
• HTTP 200 – OK + cardholder’s photo as direct PNG or JPG image file data (octet-stream) with appropriate content-type header (image/png or image/jpg).

Cards

POST /cards.selfRequest

Using this endpoint, the University defines that specific card should be ordered for student with defined cardholder_id.

Request Body Parameters

Parameter Name	Data Type	Mandatory	Note
cardholder_id	Integer	Yes	Unique identifier of the cardholder to whom the card should be issued.
type	String	Yes	Allowed values are based on client’s agreement with the ISIC account manager. Ask your ISIC account manager for the list of card types allowed for your account. See [ENUM] Card Type for the list of available values.
form	String	Yes	DIGITAL
valid_from	Date	Yes	Date must comply with card validity cycles available for selected card type at the time when the card is reported. Format “yyyy-MM-dd”.
valid_to	Date	Yes	Date must comply with card validity cycles available for selected card type at the time when the card is reported. Format “yyyy-MM-dd”.
custom_fields	Array	depends ->	Custom fields may be mandatory or optional based on client’s agreement with the ISIC account manager. Ask your ISIC account manager for the list of mandatory custom fields applicable for your account. If mandatory, it must contain all its parameters marked below as mandatory.
name	String	Yes
value	String	Yes

Sample Request Body

Sample Response Body

Within the API response, the data is returned as well as a unique link for the website, to which the student should be redirected. On this site, he/she can check (and complete, if needed) the personal data and the request for card, and then is redirected to payment gate. After successful payment, the student is redirected to thank you page.

POST /cards.selfChangeValidityRequest

Using this endpoint, the university asks for validity extension for a card with defined card_id. End of new validity needs to be sent through the request.

Parameter Name	Data Type	Mandatory	Note
card_id	Integer	Yes	Unique identifier of the card for which the validity should be changed.
valid_to	Date	Yes	New end of validity of the card. Date must comply with card validity cycles available for selected card type at the time when the card is reported. Format “yyyy-MM-dd”.

Sample Request Body

Sample Response Body

As in case of new card issuance, also in this case, the student should be redirected to URL returned by the API, where the payment for validity extension needs to be made. Afer successful payment, the student is redirected to Thank you page.

POST /cards.changeStatus

Endpoint for the case when status of existing card needs to be changed (for example the university needs to cancel a card).

Parameter Name	Data Type	Mandatory	Note
card_id	Integer	Yes	Unique identifier of the card which validity should be changed.
status	String	Yes	See [ENUM] Status for the list of available values. Status of returned cards cannot be changed.

Sample Request Body

Sample Response Body

Within the response, data about the card and its new status is returned.

GET /cards.list

Get data of cards filtered based on specified query parameters. Returned data are sorted by date of last modification in descending order (last modified record first).

Query Parameters

All query parameters of string data type are case-insensitive.

Parameter Name	Data Type	Mandatory	Description
cardholder_id	Integer	No	Unique cardholder’s identifier.
number	String	No	Card number.
status	String	No	Card status (see [ENUM] Status).
type	String	No	Card type (see [ENUM] Card Type).
modified_from	Datetime	No	Return records created or modified after specified date and time (for option of incremental updates on the API client’s side).
offset	Integer	No	Result paging offset (zero based index of the first returned item).
limit	Integer	Yes	Result page size (how many items to return).

Response
• HTTP 200 – OK + collection of [MODEL] Card

GET /cards.get

Get data of the card specified in the query parameter.

Query Parameters

Parameter Name	Data Type	Mandatory	Description
card_id	Integer	Yes	Unique card identifier.

Response
• HTTP 200 – OK + [MODEL] Card

Workflows

How to order a new ISIC, ITIC or ALIVE card

The standard process of ISIC/ITIC/ALIVE card issuance is the following (the process can slightly differ for individual universities and it of course strongly depends on how the internal school information system is designed and conneted to the API):

0/ Univeristy wants to order new ISIC/ITIC/ALIVE card for its student/teacher/staff.

1/ University checks in its internal information system whether the student already has ISIC/ITIC/ALIVE card or whether he had a card in the past. In case the stuednt is not found, the university creates a cardholder using POST /cardholders.set and saves cardholder_id for further usage. Each future action with this cardholder should be called using corresponding cardholder_id. Also, if any personal data regarding this cardholder is updated within school information system during the term, corresponding cardholder should be updated through POST /cardholders.set endpoint.

2/ University uploads photo for a cardholder (optional) using POST /cardholders.setPhoto. This step is not mandatory, the card can be issued also without any photo. In such case, the student needs to proactively upload the photo through mobile ALIVE App to be able to use the digital card.

3/ University sends API request for new card issuance using POST /cards.selfRequest. Within the request, it is specified for which cardholder the action is requested. In case the student is entitled to have more card types, it must be decided which card type is the one to be ordered. The API returns link for order completion and payment. This link should be displayed/emailed to the student to complete the card order and pay for it.

4/ When the order is completed and paid, the student receives email with his card number and additional information how to display this card within ALIVE App mobile application. Using it, he can activate digital card within mobile ALIVE App.

Important: Once a cardholder is created, the university should immediately save its cardholder_id which is returned through the API. Any further operation with the same cardholder should be done using this cardholder_id.

How to change validity of existing card

0/ In summer months, the university can offer to its students/teachers/staff the possibility of validity extension. The validity extension should be offered only to those who have valid or expired card.

1/ In case the student asks for the card to be revalidated, the university should call POST /cards.selfChangeValidityRequest. The API returns link for order completion and payment. This link should be displayed/emailed to the student to complete the order for validity extension and to pay for it.

2/ When the order is completed and paid, the validity of digital card is changed automatically.

Basic flow of the process is described in the below diagram:

Environments and Credentials

Test Environment

The following details are necessary for web service integration testing. Please ask your ISIC account manager for authentication details and card issuer’s setup based on your contract specification.

Documentation in Postman: will be specified after its completion

Base URL: https://api.test.aliveplatform.com/v1

Access Key ID: ask your ISIC account manager

Secret Access Key: ask your ISIC account manager

Card Issuer Type: INSTITUTION

Production Environment

Access details to the production environment will be provided after full implementation and successful tests against the test environment.

Base URL: https://api.aliveplatform.com/v1

Access Key ID: ask your ISIC account manager

Secret Access Key: ask your ISIC account manager

Card Issuer Type: INSTITUTION

Technical Support

For all support queries please contact the ALIVE Platform support team at support@aliveplatform.com.