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.

Category

Simple representation

id

Number

Alias for "category_id".

title

String

Nullable

Title for the category.

Full representation

category_id

Number

Unique ID for category.

id

Number

Alias for "category_id".

title

String

Nullable

Title for the category.

children

Array

Children categories. Only included if tree is set, and category has children.

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.

real_title

String

Display the competence title without additional text like the parent name or "(deactivated)" which may be added to the title.

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.

survey_data

Array

Nullable

Only available for competences of type "survey" or "survey_item". Array containing objects with info about how the survey and questions should be presented.

survey_qualifications

Array

Only available for competences of type "survey_item". Describes what is required to pass the question.

survey_render_url

String

Nullable

Only available for competences of type "survey_item". URL to rendered item/question.

custom_attributes

Object

Nullable

Object containing custom attributes for competence. Custom attributes can be almost anything, but they are defined specifically for each installation of Snapper Grape, and not part of the standard Snapper Grape data model. They are presented on the form (whether or not they are presented as simple value or object with "value" and "display_value", depends on the specific implementation):

{
    custom_attribute_name: custom_attribute_value,
    other_custom_attribute_name: {
        value: other_custom_attribute_value
        display_value: other_custom_attribute_display_value
}

external_competence_id

String

Returns the external id for the competence.

Full representation

competence_id

Number

Unique ID for this competence.

id

Number

Alias for "competence_id".

title

String

Title of the competence.

real_title

String

Display the competence title without additional text like the parent name or "(deactivated)" which may be added to the title.

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”. String containing a text with how long a course typically lasts, but may be split in days, hours and minutes. For module courses, each module's duration is returned, split by a '+' character. Example of three module course: "3 dager, 18 timer + 12 timer + 20 timer".

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.

categories

Array

Nullable

Array of Category objects registered for the 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.

survey_data

Array

Nullable

Only available for competences of type "survey" or "survey_item". Array containing objects with info about how the survey and questions should be presented.

survey_qualifications

Array

Only available for competences of type "survey_item". Describes what is required to pass the question.

survey_render_url

String

Nullable

Only available for competences of type "survey_item". URL to rendered item/question.

custom_attributes

Object

Nullable

Object containing custom attributes for competence. Custom attributes can be almost anything, but they are defined specifically for each installation of Snapper Grape, and not part of the standard Snapper Grape data model. They are presented on the form (whether or not they are presented as simple value or object with "value" and "display_value", depends on the specific implementation):

{
    custom_attribute_name: custom_attribute_value,
    other_custom_attribute_name: {
        value: other_custom_attribute_value
        display_value: other_custom_attribute_display_value
}

external_competence_id

String

Returns the external id for the competence.

owner_person

Person object

Returns the person defined as owner for the competence

owner_organisation

Organisation object

Returns the organisation defined as owner for the competence

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.

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.

external_id

String

ID in external system, if competence groups is imported.

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.

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.

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.

 

Full representation

level

Number

Organisation objects and Person objects. The overall competence level. 0-100.

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.

 

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.

ConfigItem

Object representing a configuration item in Snapper Grape.

Simple representation

value

anything

Nullable

Value for configuration item. Can be number, string, array or object, depending on the config item.

Full representation

config_item_id

String

ID for configuration item.

value

anything

Nullable

Value for configuration item. Can be number, string, array or object, depending on the config item.

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.

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.

parent_event_id

Number

Parent event ID. If event has no parent then None.

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).

locked

Date

Nullable

Date when event was locked for further sign ons, etc.

travelinformations

Array

Array of TravelInformation objects associated with event.

custom_attributes

Object

Nullable

Object containing custom attributes for event. Custom attributes can be almost anything, but they are defined specifically for each installation of Snapper Grape, and not part of the standard Snapper Grape data model. They are presented on the form (whether or not they are presented as simple value or object with "value" and "display_value", depends on the specific implementation):

{
    custom_attribute_name: custom_attribute_value,
    other_custom_attribute_name: {
        value: other_custom_attribute_value
        display_value: other_custom_attribute_display_value
}

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

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.

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.

parent_event_id

Number

Parent event ID. If event has no parent then None.

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).

course_owner_person

Person object

Person object describing person defined as owner of course event

course_owner_organisation

Organisation object

Organisation defined as owner organisation for event

prerequisites_text

String

Presentation of prerequisites defined for the event. See also 'prerequisites' below. This attribute contains text which is totally independant from the 'prerequisites' attribute.

prerequisites

Array

This attribute return a list of Competence objects, list competences that need to be fulfilled before user can sign on the current course. If list is empty, now prerequisites defined.

competence_groups

Array

Returns a list of CompetenceGroup items that the competence is related to. The list can be empty. (Was previously named coursegroups.)

email

String

Return email defined for the course event

homepage

String

Return homepage defined for the course event

signed_on

Boolean

Set to True if current user is signed on to the course. This attribute is defined if user_check is set to 1 in event request.

locked

Date

Nullable

Date when event was locked for further sign ons, etc.

travelinformations

Array

Array of TravelInformation objects associated with event.

custom_attributes

Object

Nullable

Object containing custom attributes for event. Custom attributes can be almost anything, but they are defined specifically for each installation of Snapper Grape, and not part of the standard Snapper Grape data model. They are presented on the form (whether or not they are presented as simple value or object with "value" and "display_value", depends on the specific implementation):

{
    custom_attribute_name: custom_attribute_value,
    other_custom_attribute_name: {
        value: other_custom_attribute_value
        display_value: other_custom_attribute_display_value
}

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.

title

String

Display title for 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.

title

String

Display title for file.

mime_type

String

MimeType for the file.

url

String

URL for fetching the file.

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.

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.

LMSStartURL

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

Simple representation

competence_id

Number

Unique ID for competence.

competence_title

String

Title of the competence.

urls

Array

List of URLs for starting the modules of the e-course in external LMS.

Full representation

id

Number

Alias for "competence_id".

competence_id

Number

Unique ID for competence.

competence_title

String

Title of the competence.

urls

Array

List of URLs for starting the modules of the e-course in external LMS.

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.

files

File object

Contains list of APIFile objects, representing attachements sent as part of the message (return from GET, not POST (yet))

Organisation

Organisation or department with organisation.

Simple representation

id

Number

Alias for "organisation_id".

title

String

Name of organisation.

extern_organisation_id

String

Nullable

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

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.

OrganisationalFunction

NOT EDITED YET - Copy of Roles

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.

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).

representing_organisation

Organisation object

Nullable

Organisation that participant is representing for this particular course event.

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.

is_paid

Boolean

Indicates whether the current order is paid or not

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).

representing_organisation

Organisation object

Nullable

Organisation that participant is representing for this particular course event.

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.

is_paid

Boolean

Indicates whether the current order is paid or not

debitor_organisation

Organisation object

Returns an organisation object indicating debitor organisation for order connected to the person event.

debitor_person

Person object

Returns a Person object indicating debitor person for order connected to the person event.

order_due

Date

Nullable

Date for when order payment is due.

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.

birthdate_fmt

Date

Nullable

Birth date for person, formatted as a string according to locale for server.

address

String

Nullable

Street address

postcode

String

Nullable

Post code for person's 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.

PersonCompetence

A competence, as obtained by a person.

Simple 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.

competence_type

CompetenceType object

Competence type, returned as CompetenceType object.

date

Date

Nullable

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

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)

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.

person_competence_id

Number

Nullable

ID representing this attempt at fulfilling the competence.

valid_until

Date

Nullable

Indicating when competence expires.

person

Person object

The Person object this object belongs to.

history

Boolean

Indicates whether or not PersonCompetences has history objects.

Full representation

cancelled

Date

Nullable

If set, gives time when this attempt was voided.

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.

competence

Competence object

Competence object for PersonCompetence

competence_type

CompetenceType object

Competence type, returned as CompetenceType object.

date

Date

Nullable

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

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)

id

Number

Alias for "person_competence_id".

joined

Date

Nullable

Time when user signed on to the course.

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.

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.

person_competence_id

Number

Nullable

ID representing this attempt at fulfilling the competence.

representing_organisation

Organisation object

Return information on which organisation the person signed on to the given course represents. 

school

String

Nullable

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

self_check

Date

Nullable

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

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

valid_until

Date

Nullable

Indicating when competence expires.

person

Person object

The Person object this object belongs to.

history_personcompetences

Array

Array of PersonCompetence objects. These are the previously fulfilled PersonCompetences for the same Person and Competence as this one.

history

Boolean

Indicates whether or not PersonCompetences has history objects.

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.

person_event_id

Number

Unique ID for PersonEvent.

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.

passed

Boolean

Indicates whether the event was marked as passed or not for current participant

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.

confirmed

Boolean

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

host_name

String

Specifies the name of organisation that hosts the course event

history

Boolean

Set to True if there are historical elements for the current personevent. I.e., it here has been more than one completion of the competence. Example: The user has attended a course more than once, run an e-course more than once etc.

event

Event object

Event object for this PersonEvent. Some attributes will be duplicates in PersonEvent and Event, this may be cleaned up in later version.

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.

is_paid

Boolean

Indicates whether the current order is paid or not

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.

person_event_id

Number

Unique ID for PersonEvent.

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.

passed

Boolean

Indicates whether the event was marked as passed or not for current participant

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. Note that we only include the children of the Event that the person is actually signed on to.

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.

confirmed

Boolean

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

host_name

String

Specifies the name of organisation that hosts the course event

representing_organisation

Person object

Returns an Organisation object indicating which organisation the person represents within the context of the order. Useful if a person is member of severale organisation units, but the order should be "connected" to just one of the organisations

history

Boolean

Set to True if there are historical elements for the current personevent. I.e., it here has been more than one completion of the competence. Example: The user has attended a course more than once, run an e-course more than once etc.

event

Event object

Event object for this PersonEvent. Some attributes will be duplicates in PersonEvent and Event, this may be cleaned up in later version.

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.

is_paid

Boolean

Indicates whether the current order is paid or not

debitor_organisation

Organisation object

Returns an organisation object indicating debitor organisation for order connected to the person event.

debitor_person

Person object

Returns a Person object indicating debitor person for order connected to the person event.

order_due

Date

Nullable

Date for when order payment is due.

PersonTravelInformation

Object for storing a participant's travel information for an event. Some of these fields are subject to interpretation, based on how the corresponding TravelInformation object is configured.

Simple representation

arrival_location

String

Nullable

Arrival location for participant. Typically name of airport, bus station, etc.

arrival_info

String

Nullable

Extra information about arrival. Can be anything, based on TravelInformation configuration. However, it is typically used for flight numbers, etc.

departure_time

Date

Nullable

Departure time for participant.

departure_location

String

Nullable

Departure location for participant.

departure_info

String

Nullable

Extra information about departure. Can be anything, based on TravelInformation configuration. However, it is typically used for flight numbers, etc.

comment

String

Nullable

Comment given by participant.

hotel

Boolean

Nullable

Indicates whether participant requires/requests a hotel room to be booked.

hotel_room_type

String

Nullable

"double" or "single". Indicates participant's wish for a double or single room.

hotel_roomie_name

String

Nullable

Name of person that participants requests to share a double room with.

pick_up

Boolean

Nullable

Whether or not participant requests to be picked up on arrival.

changed

Date

When this information was last changed.

Full representation

arrival_time

Date

Nullable

Arrival time for participant.

arrival_location

String

Nullable

Arrival location for participant. Typically name of airport, bus station, etc.

arrival_info

String

Nullable

Extra information about arrival. Can be anything, based on TravelInformation configuration. However, it is typically used for flight numbers, etc.

departure_time

Date

Nullable

Departure time for participant.

departure_location

String

Nullable

Departure location for participant.

departure_info

String

Nullable

Extra information about departure. Can be anything, based on TravelInformation configuration. However, it is typically used for flight numbers, etc.

comment

String

Nullable

Comment given by participant.

hotel

Boolean

Nullable

Indicates whether participant requires/requests a hotel room to be booked.

hotel_room_type

String

Nullable

"double" or "single". Indicates participant's wish for a double or single room.

hotel_roomie_name

String

Nullable

Name of person that participants requests to share a double room with.

pick_up

Boolean

Nullable

Whether or not participant requests to be picked up on arrival.

changed

Date

When this information was last changed.

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.

owner_organisation

Organisation object

Nullable

Organisation that is set as owner for this position.

owner_person

Person object

Nullable

Person that is set as owner for this position.

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.

owner_organisation

Organisation object

Nullable

Organisation that is set as owner for this position.

owner_person

Person object

Nullable

Person that is set as owner for this position.

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.

rolemetatype

String

Nullable

Provdes the role meta type. The meta type can be either 'role', 'specialrole' or 'position'. See also /api/roles on how to filter on this attrbute.

owner_organisation

Organisation object

Nullable

Organisation object that is set as owner for this role.

owner_person

Person object

Nullable

Person that is set as owner for this 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 in.

rolemetatype

String

Nullable

Provdes the role meta type. The meta type can be either 'role', 'specialrole' or 'position'. See also /api/roles on how to filter on this attrbute.

organisations

Organisation object

Contains a list of organisation objects which defined under which organisational unites this role is valid. 

Please note: This attribute is returned for superuser accounts only. Regular users will not receive this information.

owner_organisation

Organisation object

Nullable

Organisation object that is set as owner for this role.

owner_person

Person object

Nullable

Person that is set as owner for this role.

required_competences

Array

Array of Competence objects (simple view) that are required for this role. Note that if there are organisational restrictions on any of the competences, these are not taken into account here, all competences are listed, regardless of their validity in different parts of the organisational structure.

optional_competences

Array

Array of Competence objects (simple view) that are set as optional/suggested for this role. Note that if there are organisational restrictions on any of the competences, these are not taken into account here. All competences are listed, regardless of their validity in different parts of the organisational structure.

SurveyAnswer

SurveyAnswer is a special case for Event and PersonCompetence. It relates to a survey, which is a type of Competence, in the same way that an Event relates to an event-type Competence. It has a start date (when the first answer was submitted) and an end date (when the last answer was submitted), it as a list of children and many other attributes from Event. It also has a "passed" state like a PersonCompetence, and contains information about the Person/Organisation that answered the survey.

Simple representation

event_id

Number

Alias for id.

competence_id

Number

ID for competence, or survey object.

survey_id

Number

Alias for competence_id.

title

String

Title for object. Usually the same as for the competence.

passed

Number

Nullable

Passed state for person/organisation. 0-100 or null.

passed_set_ts

Date

Nullable

Timestamp for when "passed" was last set.

person_id

Number

Nullable

ID for person who answered.

organisation_id

Number

Nullable

ID for organisation that answered.

short_description

String

Nullable

Short description for survey question.

description

String

Nullable

Description for survey question.

modified

Date

Nullable

Last modified date for event.

children

Array

Nullable

Array of SurveyAnswer objects that are children (survey items or sub-items), corresponding to the Competence structure.

survey_data

Array

Nullable

Array containing objects with info about how the survey and questions should be presented.

survey_qualifications

Array

Only available for survey items. Describes what is required to pass the question.

survey_render_url

String

Nullable

Only available for survey items. URL to rendered item/question.

Full representation

id

Number

ID for SurveyAttribute object (technically, CourseEvent object).

event_id

Number

Alias for id.

competence_id

Number

ID for competence, or survey object.

survey_id

Number

Alias for competence_id.

title

String

Title for object. Usually the same as for the competence.

passed

Number

Nullable

Passed state for person/organisation. 0-100 or null.

passed_set_ts

Date

Nullable

Timestamp for when "passed" was last set.

person

Person object

Nullable

Person who answered.

organisation

Organisation object

Nullable

Organisation that answered.

short_description

String

Nullable

Short description for survey question.

description

String

Nullable

Description for survey question.

modified

Date

Nullable

Last modified date for event.

children

Array

Nullable

Array of SurveyAnswer objects that are children (survey items or sub-items), corresponding to the Competence structure.

files

Array

Nullable

Array of File objects. Files attached to this survey answer.

organisations

Array

Nullable

Array of organisations. Organisations that this survey is restricted to.

locked

Date

Nullable

Date that the answer was locked for further updates. If null, answer is not locked.

survey_data

Array

Nullable

Array containing objects with info about how the survey and questions should be presented.

survey_qualifications

Array

Only available for survey items. Describes what is required to pass the question.

survey_render_url

String

Nullable

Only available for survey items. URL to rendered item/question.

TravelInformation

Object holding the configuration of the travel information: what fields are active, and some labels for the information saved.

Simple representation

travel_information_type

Number

"information"/"request". Whether this object is set up to gather information from participants about how they are arriving/departing ("information"), or about how they wish the course admins to arrange their travels ("request").

name

String

Nullable

Name of the travel information.

label

String

Label for the travel information. Typically an action-based variant of name (name might be "Train", while label is "I will be arriving by train").

arrival_time

Boolean

Is arrival time on or off.

arrival_location

Boolean

Is arrival location on or off.

arrival_info

Boolean

Is arrival info on or off.

arrival_info_label

String

Nullable

Label for arrival_info.

departure_time

Boolean

Is departure time on or off.

departure_location

Boolean

Is departure location on or off.

departure_info

Boolean

Is departure info on or off.

departure_info_label

String

Nullable

Label for departure info.

comment

Boolean

Is comment on or off.

hotel

Boolean

Is hotel on or off.

hotel_room_type

Boolean

Is hotel room type on or off.

hotel_roomie_name

Boolean

Is hotel roomie name on or off.

pick_up

Boolean

Is pick up on or off.

deactivated

Boolean

Is travel information object deactivated.

Full representation

travel_information_id

Number

Nullable

ID for object.

travel_information_type

Number

"information"/"request". Whether this object is set up to gather information from participants about how they are arriving/departing ("information"), or about how they wish the course admins to arrange their travels ("request").

name

String

Nullable

Name of the travel information.

label

String

Label for the travel information. Typically an action-based variant of name (name might be "Train", while label is "I will be arriving by train").

arrival_time

Boolean

Is arrival time on or off.

arrival_location

Boolean

Is arrival location on or off.

arrival_info

Boolean

Is arrival info on or off.

arrival_info_label

String

Nullable

Label for arrival_info.

departure_time

Boolean

Is departure time on or off.

departure_location

Boolean

Is departure location on or off.

departure_info

Boolean

Is departure info on or off.

departure_info_label

String

Nullable

Label for departure info.

comment

Boolean

Is comment on or off.

hotel

Boolean

Is hotel on or off.

hotel_room_type

Boolean

Is hotel room type on or off.

hotel_roomie_name

Boolean

Is hotel roomie name on or off.

pick_up

Boolean

Is pick up on or off.

deactivated

Boolean

Is travel information object deactivated.

Workflow

Object representing the workflow object for competences. A workflow object may have several states and are tied to competences through these states (represented by WorkflowState).

Simple representation

title

String

Title for workflow

current_state

WorkflowState object

Nullable

Current WorkflowState object. Only set when Workflow is in the context of a Competence that has such a current state.

Full representation

id

Number

Unique ID for workflow

title

String

Title for workflow

current_state

WorkflowState object

Nullable

Current WorkflowState object. Only set when Workflow is in the context of a Competence that has such a current state.

WorkflowState

Object for a workflow state, connecting a Workflow object and a Competence object.

Simple representation

title

String

Title for workflow state.

action_text

String

Action text for button/action used for setting this workflow state.

set_by

Person object

Nullable

The Person who set this workflow state. Only set in the context of a Competence.

set_at

Date

Nullable

When the workflow state was set. Only set in the context of a Competence.

Full representation

id

Number

Unique ID for workflow state.

title

String

Title for workflow state.

action_text

String

Action text for button/action used for setting this workflow state.

set_by

Person object

Nullable

The Person who set this workflow state. Only set in the context of a Competence.

set_at

Date

Nullable

When the workflow state was set. Only set in the context of a Competence.