Types

Introduction

This is a companion to the Snapper Grape API documentation. It describes the data types returned from Snapper Grape API as of version 2.4.1

JSON data types

In addition to the standard JSON data types (number, string, boolean, array, object), we define here a data type date. Date is a string representation of a datetime object, on ISO standard format: ”2014-01-20 14:10”.

Attributes and configuration of Snapper Grape

Many of these objects are subject to configuration in Snapper Grape. Super users of Snapper Grape can turn on or off attributes at will. Some attributes may also have different meanings in different installations, and will have a rather vague description. This document describes all possible attributes of the objects. What you actually see when performing an API call most likely has fewer attributes than described here.

Login

When logging in we return some information for SSO, or simply for performing the next API call.

Simple representation

forward_url

String

Nullable

The forwarding URL given as input parameter. For SSO purposes.

hash

String

Short-lived hash for use with SSO.

ts

Date

Timestamp for short-lived hash.

password_expired

Boolean

Indicates whether password has expired for this user. If true, end system must prompt user to change password.

user_name

String

Nullable

User name of person logged in.

firstname

String

Nullable

First/given name of person logged in.

lastname

Number

email

String

Nullable

Email address of logged in person.

Full representation

session_id

String

Session ID for this logged in session. Is also returned in ”set-cookie”, but added here for simplicity.

forward_url

String

Nullable

The forwarding URL given as input parameter. For SSO purposes.

hash

String

Short-lived hash for use with SSO.

ts

Date

Timestamp for short-lived hash.

password_expired

Boolean

Indicates whether password has expired for this user. If true, end system must prompt user to change password.

user_name

String

Nullable

User name of person logged in.

firstname

String

Nullable

First/given name of person logged in.

lastname

Number

email

String

Nullable

Email address of logged in person.

Logout

Not much is information is given after a successful logout.

Full representation

forward_url

String

Nullable

The URL to redirect to after successful logout. Simply relayed from input value.

Person

A person object in Snapper Grape. Typically an employee, course participant, etc.

Simple representation

id

Number

Alias for "person_id".

user_name

String

The user name the person uses to log in. The user name can change at any time, so is not to be used as a persistent identifier of person object.

firstname

String

Nullable

Person’s first or given name

lastname

String

Nullable

Person’s last or family name

email

String

Nullable

Email address for person

Full representation

person_id

Number

ID of person object. This ID is unique (among person objects), and will never change for this object.

id

Number

Alias for "person_id".

user_name

String

The user name the person uses to log in. The user name can change at any time, so is not to be used as a persistent identifier of person object.

firstname

String

Nullable

Person’s first or given name

lastname

String

Nullable

Person’s last or family name

fullname

String

Person's full name. Firstname + space + lastname.

email

String

Nullable

Email address for person

jobtitle

String

Nullable

Free text job title for person.

nationality

String

Nullable

Name of given nationality for person.

birthdate

Date

Nullable

Birth date for person.

address

String

Nullable

Street address

city

String

Nullable

City part of address

country

String

Nullable

Country part of address

phone

String

Nullable

Phone number

mobile

String

Nullable

Mobile number

notice

String

Nullable

Comment added to person

sex

String

Gender. ”m” or ”f”.

profile_image

File object

Nullable

Profile image for person

employee_code

String

Nullable

Code used for identification of person.

code

String

Same as above, in case we need more than one.

extern_person_id

String

Nullable

Typically used for ID from external system where person is imported from

ts

Date

Timestamp for when the object was last changed

deactivated

Boolean

Flag indicating whether person object is deactivated or not.

Message

Object representing a message sent to a person in Snapper Grape. This message can be sent as email or SMS, depending on the system configuration, and what the user selected.

Simple representation

id

Number

Alias for "message_id".

subject

String

Subject or title of message.

recipient_address

String

Email address or mobile number (if SMS) the message was sent to.

is_sms

Boolean

Flag indicating if the message was sent as SMS or email.

ts

Date

Timestamp for when message was sent.

Full representation

message_id

Number

Unique ID for this message.

id

Number

Alias for "message_id".

subject

String

Subject or title of message.

recipient_address

String

Email address or mobile number (if SMS) the message was sent to.

is_sms

Boolean

Flag indicating if the message was sent as SMS or email.

ts

Date

Timestamp for when message was sent.

text

String

The actual message. May contain HTML.

reply_to

String

Nullable

Reply to address of email sent.

cc_addresses

String

Nullable

Comma-separated list of email addresses carbon copied.

sender_name

String

Nullable

Name of the person who sent the message.

CompetenceLevel

Object giving a representation of competence level. This can be related to both person objects and organisation objects.

Simple representation

title

String

Organisation objects only. Title describing what the level relates to.

has

Number

Organisation objects only. Number of required competences acquired.

should_have

Number

Organisation objects only. Number of required competences.

Array

Organisation objects only. Array of competence level details for different competence types. Objects in array:

type: <CompetenceType simple>
level: Number. 1-100. Competence level for this comptence type
has: Number. Number of required competences of this type acquired.
should_have: Number. Number of required competences of this type.

Full representation

level

String

Organisation objects only. Title describing what the level relates to.

title

String

Organisation objects only. Title describing what the level relates to.

has

Number

Organisation objects only. Number of required competences acquired.

should_have

Number

Organisation objects only. Number of required competences.

types

Array

Organisation objects only. Array of competence level details for different competence types. Objects in array:

type: <CompetenceType simple>
level: Number. 1-100. Competence level for this comptence type
has: Number. Number of required competences of this type acquired.
should_have: Number. Number of required competences of this type.

PersonCompetence

A competence, as obtained by a person.

Simple representation

competence_title

String

Title of the Competence object.

person_competence_id

Number

Nullable

ID representing this attempt at fulfilling the competence.

id

Number

Alias for "person_competence_id".

passed

Number

Nullable

0-100. Level of fulfilment. 0 or null indicates not attempted at all, 100 indicates competence is passed. For some systems, passed=50 means that the ecourse has been started, but not finished, regardless of how far you actually reached in the ecourse.

grade

String

Nullable

Grade given to the person. By default this is a floating point number in a string representation, but customization of this is possible (f.ex. A-F)

date

Date

Nullable

Time for when competence was fulfilled, registered, or when course ended.

valid_until

Date

Nullable

Indicating when competence expires.

Full representation

competence_id

Number

ID of the Competence object. Can be used to look up full view of competence.

competence_title

String

Title of the Competence object.

person_competence_id

Number

Nullable

ID representing this attempt at fulfilling the competence.

id

Number

Alias for "person_competence_id".

passed

Number

Nullable

grade

String

Nullable

Grade given to the person. By default this is a floating point number in a string representation, but customization of this is possible (f.ex. A-F)

date

Date

Nullable

Time for when competence was fulfilled, registered, or when course ended.

valid_until

Date

Nullable

Indicating when competence expires.

joined

Date

Nullable

Time when user signed on to the course.

cancelled

Date

Nullable

If set, gives time when this attempt was voided.

self_check

Date

Nullable

Only applicable for competences of type ”checklist_item”. Time when person checked the checklist item.

manager_check

Date

Nullable

manager_check_user_id

Number

Nullable

Only applicable for competences of type ”checklist_item”. User id for manager who checked the checklist item.

school

String

Nullable

Only applicable for competences of type ”formal”. Indicates school/university/etc for formal competence.

time_spent

Number

Nullable

Only applicable for competences of type ”ecourse”. Indicates in seconds how much time the person has spent taking the course. Depends on implementation in third-party LMS

certificate_url

String

Nullable

Only applicable for competences of type ”course”, ”ecourse” or ”group”. URL to certificate or diploma for fulfilled competence.

comments

String

Nullable

Comment text added to the person's competence.

Role

Persons in Snapper Grape have zero or more roles. These roles typically define which competences are required. Roles are of different types, and thus can mean slightly different things. The most important type is the ”position” role, which gives the person his/her authorization level in Snapper Grape, and also defines which Organisation he/she belongs to. For this reason, positions have a separate API call, but roles of type position is still included in this call.

Simple representation

id

Number

Alias for "role_id".

title

String

Title of role.

roletype_name

String

Name of type of role.

Full representation

role_id

Number

Unique ID for role.

id

Number

Alias for "role_id".

title

String

Title of role.

roletype_name

String

Name of type of role.

description

String

Nullable

Description of role.

organisation_id

Number

Nullable

ID of organisation the role is linked to for person. Can indicate that person belongs to this organisation, but may have other meanings too.

organisation_ids

Array

Nullable

Array of organisation_ids. For special roles, indicates which parts of the organisation tree the role is valid.

Position

Position for a person. A person has 0 or 1 position for each organisation he/she belongs to. Every position is linked to an organisation.

Simple representation

title

String

Title of role.

roletype_name

String

Name of type of role.

Full representation

role_id

Number

Unique ID for role.

title

String

Title of role.

roletype_name

String

Name of type of role.

description

String

Nullable

Description of role.

organisation_id

Number

Nullable

ID of organisation the role is linked to for person. Indicates that person belongs to (is employed in) organisation.

Competence

A competence in Snapper Grape, is the definition of a course, e-course, certificate or any other kind of training/skill/qualification that a person can either have or not, and that can be either required or not. This object does not take into account how it relates to the logged in (or any other)s person, only how it is defined.

Simple representation

id

Number

Alias for "competence_id".

title

String

Title of the competence.

competence_type

String

Name of the competence type.

code

String

Internal code for the competence.

weight

Number

Weighting of course, compared to others. Can be used for course credits, etc.

Full representation

competence_id

Number

Unique ID for this competence.

id

Number

Alias for "competence_id".

title

String

Title of the competence.

competence_type

String

Name of the competence type.

code

String

Internal code for the competence.

valid_for

String

Defines for how long the competence is valid, from the time it is acquired by a person.

duration

String

Applies to competences of type ”course”. Defines how many days the course typically lasts.

short_description

String

Nullable

Short description of the competence.

description

String

Nullable

Full description of the competence.

colorcode

String

Nullable

Hex color code for the competence.

modified

Date

The last time the competence object was changed.

checked_by

String

Nullable

Applicable for competences of type ”checklist_item”. Values: ”self”/”manager”/”both”/”either”. Indicates what is requied for the checklist item to be regarded as fulfilled.

children

Array

Applicable for competences of type ”group”, ”checklist”, ”complex”, ”competence”. List of children Competence objects (simple view).

files

Array

File objects for files added to competence.

locale

String

Nullable

Locale code (”no”/”en”) representing the language of the competence.

languages_available

Array

List of all available languages for competence.

organisations

Array

List of Organisation objects that this competence is restricted to.

min_age

Number

Nullable

Minimum age for participants for this event.

max_age

Number

Nullable

Maximum age for participants for this event.

prerequisites

Array

Array of Competence objects. These competences are required for participants before they can sign on to event/start ecourse/etc.

prerequisites_text

String

Nullable

Text describing prerequisites for competence.

attributes

Array

Nullable

Array of CompetenceAttribute registered for the competence.

instructors

Array

Nullable

Array of Persons registered as instructors for the competence. This is only available for competence of type "course".

durations

Array

Nullable

Array of Duration objects.

weight

Number

Weighting of course, compared to others. Can be used for course credits, etc.

CompetenceGroup

A CompetenceGroup is an organisational object for organizing competences. While the competence groups themselves are strictly hieriarchal, a single competence can belong to 0 or more competence groups.

Simple representation

id

Number

Alias for "competence_group_id".

title

String

Title of the competence group.

sort_index

Number

Nullable

Sorting number indicating order of the competence group, relative to other competence groups on same level.

Full representation

competence_group_id

Number

Unique ID of competence group.

id

Number

Alias for "competence_group_id".

title

String

Title of the competence group.

sort_index

Number

Nullable

Sorting number indicating order of the competence group, relative to other competence groups on same level.

external_id

String

ID in external system, if competence groups is imported.

children

Array

List of CompetenceGroup objects belong to this one.

CompetenceAttribute

Simple representation

id

Number

Alias for "competence_attribute_id".

title

String

Title for the competence attribute.

Full representation

competence_attribute_id

Number

Unique ID for competence attribute.

id

Number

Alias for "competence_attribute_id".

title

String

Title for the competence attribute.

File

A file can belong to a number of other objects: Person, Competence, PersonCompetence, Event, etc. It will typically have different meanings in different contexts.

Simple representation

id

Number

Alias for "file_id".

filename

String

Name or title for the file.

mime_type

String

MimeType for the file.

url

String

URL for fetching the file.

Full representation

file_id

String

Name or title for the file.

id

Number

Alias for "file_id".

filename

String

Name or title for the file.

mime_type

String

MimeType for the file.

url

String

URL for fetching the file.

Event

An event represents a course being held at a certain place and time.

Simple representation

id

Number

Alias for "event_id".

title

String

Title of the event

startdate

Date

Start date and time for the event.

enddate

Date

End date and time for the event.

publishdate

Date

Nullable

Date from when event is available for sign on for normal users. If Null, event is not published. Note that super users are able to override this, and can always sign persons on to events, regardless of publish date, sign on deadline, etc.

location

String

Name of the location where the event is held.

joinable

Boolean

Whether or not this event is available for sign on for the logged in user.

short_description

String

Nullable

Short description of the event.

description

String

Nullable

Full description of the event.

haschildren

Boolean

Flag indicating whether this event has children modules.

min_age

Number

Nullable

Minimum age required for participant.

max_age

Number

Nullable

Maximum age required for participants.

max_participants

Number

Maximum number of participants allowed for this event.

participants_count

Number

Nullable

Number of participants currently signed on to event.

available_count

Number

Nullable

Number of available places for event.

host_name

String

Nullable

Title of the host organisation object.

external_sign_on

Boolean

Is sign on through API allowed or not.

payment

Boolean

Is payment (online or invoice) set up for this event.

certificates_url

String

Nullable

Relative URL to get certificates for participants. Note that only participants who have passed the event will be included, and that only finished events are eligible for certificates.

If logged in user is superuser, admin or instructor for the course, ALL passed participants will be included.
If logged in user is manager/employeemanager, all participants belonging to user's organisations (recursively) will be included.
If GET parameter "pids" is added to URL (multiple allowed: pids=11&pids=12&...), only participants with these person IDs will be included (given that user is allowed to).
If GET parameter "oid" is added to URL (only one: oid=10), it overrides "pids", and includes all participants from that organisation (recursively).
If user is trying to do something he is not allowed to, the resource will respond with an "Unauthorized" response code (and a login form).

Full representation

event_id

Number

Unique ID of the event object.

id

Number

Alias for "event_id".

title

String

Title of the event

startdate

Date

Start date and time for the event.

enddate

Date

End date and time for the event.

publishdate

Date

Nullable

location

String

Name of the location where the event is held.

cost

Number

Nullable

Cost/price for course

joinable

Boolean

Whether or not this event is available for sign on for the logged in user.

short_description

String

Nullable

Short description of the event.

description

String

Nullable

Full description of the event.

sign_on_deadline

Date

The deadline date for signing up for the event.

sign_off_deadline

Date

The deadline date for signing off for the event.

haschildren

Boolean

Flag indicating whether this event has children modules.

children

Array

Nullable

Array with children Event objects.

organisations

Array

List of Organisation objects this event is restricted to.

min_age

Number

Nullable

Minimum age required for participant.

max_age

Number

Nullable

Maximum age required for participants.

max_participants

Number

Maximum number of participants allowed for this event.

participants_count

Number

Nullable

Number of participants currently signed on to event.

available_count

Number

Nullable

Number of available places for event.

attributes

Array

Nullable

Array of CompetenceAttribute registered for the event.

instructors

Array

Nullable

Array of Persons registered as instructors for the event.

host_name

String

Nullable

Title of the host organisation object.

host

Organisation object

Nullable

Simple representation of Organisation object set as host for the event.

external_sign_on

Boolean

Is sign on through API allowed or not.

payment

Boolean

Is payment (online or invoice) set up for this event.

payment_types

Array

Nullable

Which payment types are allowed. Array of strings.

durations

Array

Nullable

Array of Duration objects.

certificates_url

String

Nullable

Relative URL to get certificates for participants. Note that only participants who have passed the event will be included, and that only finished events are eligible for certificates.

If logged in user is superuser, admin or instructor for the course, ALL passed participants will be included.
If logged in user is manager/employeemanager, all participants belonging to user's organisations (recursively) will be included.
If GET parameter "pids" is added to URL (multiple allowed: pids=11&pids=12&...), only participants with these person IDs will be included (given that user is allowed to).
If GET parameter "oid" is added to URL (only one: oid=10), it overrides "pids", and includes all participants from that organisation (recursively).
If user is trying to do something he is not allowed to, the resource will respond with an "Unauthorized" response code (and a login form).

PersonEvent

A person’s participation in an event.

Simple representation

id

Number

Alias for "event_id".

competence_id

Number

ID of the competence this event is instance of.

title

String

Title for the event.

startdate

Number

Start date and time for the event.

enddate

Date

End date and time for the event.

location

String

Name of the location where the event is held.

joined

Date

Time when person signed on to event.

waitlist

Boolean

Whether or not person is on wait list for event.

cancelled

Date

Nullable

If set, indicates when person’s participation was cancelled.

haschildren

Boolean

Flag indicating whether this event has children modules.

person

Person object

Person object representing the person this sign on belongs to. Only included when fetching PersonEvents for an organisation unit, otherwise it's implied.

order_id

Number

Nullable

Only available if order system is turned on. This is the ID of the order object the sign on belongs to.

confirmed

Boolean

Is person confirmed on this event. Defaults to true for most installations.

Full representation

event_id

Number

Unique ID of the event. Same as for event object.

id

Number

Alias for "event_id".

competence_id

Number

ID of the competence this event is instance of.

title

String

Title for the event.

startdate

Number

Start date and time for the event.

enddate

Date

End date and time for the event.

location

String

Name of the location where the event is held.

joined

Date

Time when person signed on to event.

waitlist

Boolean

Whether or not person is on wait list for event.

cancelled

Date

Nullable

If set, indicates when person’s participation was cancelled.

short_description

String

Nullable

Short description of the event.

description

String

Nullable

Full description of the event.

comments

String

Nullable

Comments added to person’s particpation.

haschildren

Boolean

Flag indicating whether this event has children modules.

children

Array

Array with children PersonEvent objects.

person

Person object

Person object representing the person this sign on belongs to. Only included when fetching PersonEvents for an organisation unit, otherwise it's implied.

order_id

Number

Nullable

Only available if order system is turned on. This is the ID of the order object the sign on belongs to.

confirmed

Boolean

Is person confirmed on this event. Defaults to true for most installations.

Location

Simple representation

id

Number

Alias for "location_id".

title

Number

Location's title.

address

String

Nullable

Location's street address.

postcode

String

Nullable

Post code part of address.

city

String

Nullable

City part of address.

capacity

Number

Nullable

Maximum capacity for location.

description

String

Nullable

Description text for location.

latitude

Number

Nullable

Latitude for location. On float format.

longitude

Number

Nullable

Longitude for location. On float format.

Full representation

location_id

Number

Location's unique ID.

id

Number

Alias for "location_id".

title

Number

Location's title.

address

String

Nullable

Location's street address.

postcode

String

Nullable

Post code part of address.

city

String

Nullable

City part of address.

capacity

Number

Nullable

Maximum capacity for location.

description

String

Nullable

Description text for location.

latitude

Number

Nullable

Latitude for location. On float format.

longitude

Number

Nullable

Longitude for location. On float format.

Participant

A participant in an event. This is the flip side of the PersonEvent object, looking at the participant, rather than the participation.

Simple representation

id

Number

Alias for "person_id".

event_id

Number

ID for the event

competence_id

Number

ID of the competence for the event

user_name

String

Person's user name.

firstname

String

Person's first name.

lastname

String

Person's last name.

birthdate

Date

Nullable

Person's birth date.

email

String

Nullable

Person's email address.

mobile

String

Nullable

Person's mobile phone number.

waitlist

Boolean

Whether or not the participant is on wait list.

waitlist_number

Number

Nullable

What number in line the participant is for getting a seat on the event. Null if participant is not on waitlist.

passed

Number

Participant's status for course. 0-100. 100 means that participant has passed the course.

met

Boolean

Nullable

Whether or not the participant met for the event. Will be null until the event has finished, regardless of what is saved.

grade

String

Nullable

Participant's grade for this course. Will be null until the event has finished, regardless of what is saved.

joined

Date

When the person was signed on the event.

comments

String

Comments attached to the participation.

certificate_url

String

Nullable

URL for the certificate. Will be null if participant hasn't passed course (or course hasn't finished).

Full representation

person_id

Number

Person's unique ID

id

Number

Alias for "person_id".

event_id

Number

ID for the event

competence_id

Number

ID of the competence for the event

user_name

String

Person's user name.

firstname

String

Person's first name.

lastname

String

Person's last name.

birthdate

Date

Nullable

Person's birth date.

email

String

Nullable

Person's email address.

mobile

String

Nullable

Person's mobile phone number.

waitlist

Boolean

Whether or not the participant is on wait list.

waitlist_number

Number

Nullable

What number in line the participant is for getting a seat on the event. Null if participant is not on waitlist.

passed

Number

Participant's status for course. 0-100. 100 means that participant has passed the course.

met

Boolean

Nullable

Whether or not the participant met for the event. Will be null until the event has finished, regardless of what is saved.

grade

String

Nullable

Participant's grade for this course. Will be null until the event has finished, regardless of what is saved.

joined

Date

When the person was signed on the event.

comments

String

Comments attached to the participation.

certificate_url

String

Nullable

URL for the certificate. Will be null if participant hasn't passed course (or course hasn't finished).

Organisation

Organisation or department with organisation.

Simple representation

id

Number

Alias for "organisation_id".

title

String

Name of organisation.

Full representation

organisation_id

Number

Unique identification of organisation object.

id

Number

Alias for "organisation_id".

title

String

Name of organisation.

main_organisation

Organisation object

Nullable

Organisation object defined as a ”main” organisation in Snapper Grape’s organisation hierarchy. Depends on customer’s configuration.

managers

Array

List of persons defined as managers for this organisation object.

code

String

Nullable

Code identifiying organisation/department.

organisation_number

String

Nullable

Official organisation number.

address

String

Nullable

Street address.

postcode

String

Nullable

Postal code/zip code.

city

String

Nullable

City part of address.

country

String

Nullable

Country part of address.

postal_address

String

Nullable

Postal street address

postal_postcode

String

Nullable

Postal code/zip code for postal address.

postal_city

String

Nullable

City for postal address.

postal_country

String

Nullable

Visit street address.

visit_address

String

Nullable

Visit street address.

visit_postcode

String

Nullable

Postal code/zip code for visit address.

visit_city

String

Nullable

City for visit address.

visit_country

String

Nullable

Country for visit address.

phone

String

Nullable

Telephone number.

email

String

Nullable

Email address for organisation.

opened

Date

When organisation/department was added/opened.

closed

Date

Nullable

When organisation/department was closed.

department

Number

Nullable

Additional department name.

web

String

Nullable

Web address for organisation.

parent_id

Number

Nullable

ID of parent in the organisation hierarchy.

extern_organisation_id

String

Nullable

ID of organisation in external system, used if organisation is imported.

deactivated

Boolean

True if organisation has been deactivated.

CompetenceType

Type object for competences. Different competence types have different behavior and meaning.

Simple representation

id

Number

Alias for "competence_type_id".

competence_type

String

Unique and persistent string identifying competence type object. Used frequently as input parameter.

title

String

Title for competence type.

Full representation

competence_type_id

Number

Unique ID for competence type object.

id

Number

Alias for "competence_type_id".

competence_type

String

Unique and persistent string identifying competence type object. Used frequently as input parameter.

title

String

Title for competence type.

Duration

Duration for courses and competences. Has a label (optional) a number, and a type (hours/days/etc).

Simple representation

duration

Number

The number part of the duration.

type

String

The type part of the duration. Typically "hours" or "days".

label

String

Nullable

Optional label for duration.

Full representation

id

Number

Internal ID for Duration object.

duration

Number

The number part of the duration.

type

String

The type part of the duration. Typically "hours" or "days".

label

String

Nullable

Optional label for duration.

LMSStartURL

Object representing start URLs for e-course with mapping from Snapper Grape to external LMS.