- Category
- Changes
- Cms
- Competence
- CompetenceAttributes
- CompetenceGroup
- CompetenceLevel
- CompetenceType
- ConfigItem
- Event
- Files
- Highscore
- LMSStartURL
- Location
- Login and single sign on
- Message
- Organisation
- OrganisationalFunctions
- Participant
- Person
- PersonCompetence
- PersonEvent
- PersonTravelInformation
- Player
- Position and Role
- Search
- SurveyAnswer
- Track
Category
GET /api/categories
Description
Returns list of categories
Parameters
tree
Int. Optional. 0/1. If 1, returns categories as a tree structure. Otherwise, simply a flat array. Default 0.
view
String. Optional. "simple"/"full". Whether to get simple or full versions of the objects. Default "simple".
limit
Int. Optional. Default: 20. Maximum: 100. Limit the size of the result set.
offset
Int. Optional. Default: 0. Offset the result set, starting at this index. For batching/paging.
fields
String. Optional. See Field customization.
Return
Security
Superuser, manager, person
GET /api/categories/[category_id]
Description
Returns single category
Parameters
view
String. Optional. "simple"/"full". Whether to get simple or full versions of the object. Default "full".
fields
String. Optional. See Field customization.
Return
Security
Superuser, manager, person
Changes
GET /api/changes
Description
Fetch list of objects that have changes within a certain time period. It is possible to get updates for "Events", "PersonCompetences" and "Competences".
Parameters
Type
Data type to check for (also defines the return type). Can be either 'events', 'personcompetences' or 'competences'.
startdate
Start date for changes
enddate
End date for changes (ignored for events)
organisation_id
Limit the list to a given events or personcompetences for persons within a given organisation specified with the internal organisation id (and below).
extern_organisation_id
Limit the list to a given events or personcompetences for persons within a given organisation specified by external organisaiton id (and below).
limit
Number of items to retrieve, default = 20, max = 100
offset
Offset of start when paginating
Cms
GET /api/cms/[id]
Description
Returns a content object.
Parameters
id
Id of object to collect
format
String. Optional. How data should be structured. Render/Html/json if render is specifyied the template paramameter need to be set.
template
String. Optional. Use what template to show this item.
fields
String. Optional. See Field customization.
Return
Array of Cms objects.
Security
Superuser, manager, person
GET /api/cms/[id]/pages
Description
Returns list of all children elements.
Parameters
id
Id of object to collect
format
String. Optional. How data should be structured. Render/Html/json if render is specifyied the template paramameter need to be set.
template
String. Optional. Use what template to show this item.
fields
String. Optional. See Field customization.
Return
Array of Cms objects.
Security
Superuser, manager, person
Competence
GET /api/competences
Description
Returns list of all competences defined and defined as visible for user. Not that this will not return course competences that are modules of a parent course. The modules are nested in the children attribute of the object.
Parameters
mode
String. Optional. Allowed values: "active"/"inactive"/"all". Default: "active". "Active" will return only currently active competences, "inactive" will return only those that havev been deactivated, "all" will return both.
start
DEPRECATED. Will be removed in future version. Use offset in stead.
limit
Int. Optional. Default: 20. Maximum: 100. Limit the size of the result set.
offset
Int. Optional. Default: 0. Offset the result set, starting at this index. For batching/paging.
competence_group_ids
List of ints. Optional. Restricts the result to competences added to these groups.
external_competence_group_ids
List of ids. Restrict to competences belonging to these groups. Can be used together with competence_group_ids.
types
List of strings. Optional. Competence types to restrict to.
term
String. Optional. Restrict result to competences matching search term.
category_ids
Array of ints. Optional. Restrict result to competences tagged with at least one of the categories.
attribute_ids
Array of ints. Optional. Restrict result to competences tagged with at least one of the attributes.
course_template_usage_allowed_only
Boolean. Optional. Return only competences that logged in user is allowed to create course events from. Applies to types "course" and "group" only (known collectively as "course_templates").
owner_only
Boolean. Optional. Return only competences that user (logged in or given via "user_name") is owner for.
organisation_owner_only (Not implemented, yet)
Boolean. Optional. Return only competences that is owned by organisation units user (logged in or given via "user_name") is admin for.
users_organisations_only
Boolean. Optional. Return only competences that is valid in the context of the logged in users. Mosly used when searchng for competences for admin users. When set to 1, Snapper Grape will only look down the organisation tree when looking for competences, else Snapper Grape will look up and down for admin users.
instructor_only
Boolean. Optional. Return only competences that user (logged in or given via "user_name") is instructor for.
organisation_ids
List if ints. Optional. Available only for superuser and superadmin. Limits result to competence objects valid in organisations (looking up the org tree(s)).
external_organisation_ids
List if ints. Optional. Same as organisation_ids.
custom_attributes
Dot-notation object. Example: "custom_attributes.my_attribute=123&custom_attributes.my_other_attribute=abc". Limit the result to Competences with these custom attributes. Custom attributes are defined on a per-customer basis, and can be just about anything.
view
String. Optional. Defines either 'simple' or 'full' result type.
fields
String. Optional. See Field customization.
Return
Array of Competence objects.
Security
Superuser, manager, person
GET /api/competences/[competence_id]
Description
Returns detailed view of competence.
Parameters
view
String. Optional. Defines either 'simple' or 'full' result type.
fields
String. Optional. See Field customization.
Return
Array of one Competence object.
Security
Superuser, manager, person
GET /api/competences/[competence_id]/events
Description
Returns a list of events for this competence
/api/events?competence_id=123 will yield the same result as /api/competence/123/events.
Parameters
view
String. Optional. Defines either 'simple' or 'full' result type.
fields
String. Optional. See Field customization.
Return
Array of Event objects.
Security
Superuser, manager, person
CompetenceAttributes
CompetenceGroup
GET /api/competencegroups
Description
Returns list of competence groups.
Parameters
all
Int. Optional. 0/1. If 1, return all competence groups, regardless of hierarchy. If 0, returns only root competence groups. Default 0.
limit
Int. Optional. Default: 20. Maximum: 100. Limit the size of the result set.
offset
Int. Optional. Default: 0. Offset the result set, starting at this index. For batching/paging.
fields
String. Optional. See Field customization.
Return
Array of CompetenceGroup objects.
Security
Superuser, manager, person
GET /api/competencegroups/[competence_group_id]
Description
Returns detailed view of competence group, and list of sub competence groups.
Parameters
fields
String. Optional. See Field customization.
Return
Array of one CompetenceGroup object.
Security
Superuser, manager, person
GET /api/competencegroups/[competence_group_id]/roles
Available: 2.7Description
Returns list of roles that have requirements defined within or below the requested competence group.
Parameters
fields
String. Optional. See Field customization.
Return
Array of Role objects.
Security
Superuser, manager, person (Uncertain...)
CompetenceLevel
GET /api/competencelevel
Description
Returns object describing competence level for person or organisation.
Parameters
organisation_id
Int. Optional. ID of organisation. If present, will override any user_name given.
user_name
String. Optional. Username of person. If not given (and organisation_id isn’t given), will return competence level for logged in person.
fields
String. Optional. See Field customization.
Return
Array of one CompetenceLevel object.
Security
Superuser, person’s manager, organisation’s manager and self (depending)
CompetenceType
GET /api/competencetypes
Description
List of competence types defined in the system
Parameters
fields
String. Optional. See Field customization.
Return
Array of CompetenceType objects.
Security
Superuser, manager, person
ConfigItem
GET /api/configitems/[config_item_id]
Description
Fetches a single config item from the system.
Parameters
config_item_id
String. Mandatory. URL param. ID for the config item.
view
String. Optional. Accepts "simple" and "full". Controls whether to return the full object or a simple representation.
fields
String. Optional. See Field customization.
Return
Array of single ConfigItem object.
Security
Logged in user, but some config items can not be accessed through API, due to security restrictions.
GET /api/configitems/
Description
Fetches a list of config items from the system.
Parameters
config_item_ids
Array. Mandatory. List of IDs (strings) for the config items.
view
String. Optional. Accepts "simple" and "full". Controls whether to return the full object or a simple representation.
fields
String. Optional. See Field customization.
Return
Array of ConfigItem objects.
Security
Logged in user, but some config items can not be accessed through API, due to security restrictions.
Event
GET /api/events
Description
Returns array of course events. Note that this will not return events that are modules of a parent course. These are nested in the children attribute of the object.
Parameters
view
String. Optional. Specifies either "full" or "simple" result type.
competence_id
Int. Optional. To list only events belonging to a specific competence.
organisation_ids
Array of ints. Optional. Only return events that have participants belonging to Organisations.
context_organisation_ids
Array of ints. Optional. Only return events that are available within the context of the given organisation as specified using by the organisation_id(s)
context_extern_organisation_ids
Array of ints. Optional. Only return events that are available within the context of the given organisation as specified by the extern_organisation_id(s)
host_organisation_ids
List. Optional. When specified, only courses hosted by the given organisations is returned.
host_organisation_external_ids
List. Optional. When specified, only courses hosted by the given organisations is returned.
user_check
Int. Optional 1 or 0. If set to 1, Snapper Grape will check if current logged in user (or user defined with user_name) is signed on to the course.
recursive
Int. Optional. 1 or 0. Whether or not parameter organisation_ids should result in a recursive, tree search for participants or not. If set, will return events with participants belonging to branches of organisation tree defined by organisation_ids. Default: 0
term
String. Optional. Search term, to restrict results to events matching term.
cancelled
Int. Optional. Return cancelled events or not. Default: 0
category_ids
Array of ints. Optional. Restrict result to events whose definition (competence) is tagged with categories.
attribute_ids
Array of ints. Optional. Restrict result to events that are tagged with attributes.
competence_group_ids
Array of ints. Optional. Restrict result to events whose definition (competence) is tagged in groups.
external_competence_group_ids
List of ids. Restrict to competences belonging to these groups. Can be used together with competence_group_ids.
location_id
Int. Optional. Return only events held at given location. Startdate and enddate must also be given, otherwise will be ignored.
start
DEPRECATED. Will be removed in future version. Use offset in stead.
limit
Int. Optional. Default: 20. Maximum: 100. Limit the size of the result set.
offset
Int. Optional. Default: 0. Offset the result set, starting at this index. For batching/paging.
mode
String. Optional. ”future”/”finished”/"notfinished"/”all”. Controls if we are to get future, finished, not finished events, or all. Default: ”future”
startdate
String, date on ISO format. Optional. Return only events starting on or after this time. Overrides ”mode” parameter.
enddate
String, date on ISO format. Optional. Return only events starting before this time. Overrides ”mode” parameter.
sort_direction
String. "asc"/"desc". Whether the result should be sorted ascendingly or descendingly. Default: "asc".
custom_attributes
Dot-notation object. Example: "custom_attributes.my_attribute=123&custom_attributes.my_other_attribute=abc". Limit the result to Events with these custom attributes. Custom attributes are defined on a per-customer basis, and can be just about anything.
fields
String. Optional. See Field customization.
Return
Array of Event objects.
Security
Superuser, manager, person
GET /api/events/[event_id]
Description
Returns detailed view of course event.
Parameters
view
String. Optional. Specifies if you want either 'full' or 'simple' result type.
user_check
Int. Optional 1 or 0. If set to 1, Snapper Grape will check if current logged in user (or user defined with user_name) is signed on to the course.
fields
String. Optional. See Field customization.
Return
Array of one Event object.
Security
Superuser, manager, person
GET /api/events/[event_id]/participants
Description
Returns a list of participants (Person) for the course event.
/api/participants/123 will yield the same result as /api/events/123/participants.
Parameters
view
String. Optional. Specifies if you want either 'full' or 'simple' result type.
fields
String. Optional. See Field customization.
Return
Array of Person objects.
Security
Superuser, manager, person
GET /api/events/[event_id]/check_join
Description
Check if a user can sign on to the course. Several testes are performed.
- date limits for sign on
- that the user has completed prerequisite courses (if any)
- age check for user, if there are age limits
- that there are enough free seats (at the moment)
- (configurable) that we have e-mail and mobile number for the user
- (configurable) that the user is not already signed on to another course for the given date/time period
- that the user is not already signed on to the course.
- if the course is cancelled
- if the course is locked
The check is performed either on for currently logged in user, or user as specified with user_name (see below).
Parameters
user_name
String. Optional. Specifies for which user to persform join check
Returns
Dictionary with the following attributes:
can_join
Boolean. True or False depending on whether the user can sign on to the course or not. Please note: The can_join is returned to FALSE for all reasons below, except for event_full, where can_join is True. The person may be signed on to the course, but will be added to the wait list.
places
Int. Number of free seats
reason
List og strings. Specifies one or more criterias the user did not fulfill. The criterias are:
- "conflicting_course" - the user is already signed on to another course within the same time frame as current event
- "prerequisites" - the user does not fulfill one or more of the prerequisites for the given even (as specified on the competence)
- "age" - the user does not fullfill the age requirements
- "required_fields" - one or more required fields are missing, mobile or e-mail
- "already_joined" - the user is already signed on to the given course event
- "event_full" - there are no more free seats for the event
- "cancelled" - the course is cancelled
- "locked" - the course is locked
For each of the reasons a string will be returned that indicates why the user may not sign on. The string is defined in the returned dictionary, and the key is the same as the reason item. See examples below.
Security
Superuser, manager, person (self)
Example, check failes
URL
https://peendev.snappergrape.no/api/events/7299/check_join?user_name=pe@snapper.no
Returns
{ ​can_join: false, reason: ["age", "prerequisites" ], places: 20, prerequisites: "Petter Enholm oppfyller ikke vilkår(ene) for å kunne delta på dette kurset: Vikarkurs, sykepleier, Bufetat / Barnevern, Basiskurs - Foreldre/fosterhjem", age: "Petter Enholm kan ikke meldes på kurset på grunn av aldersgrenser", }
Example, check OK
URL
https://peendev.snappergrape.no/api/events/7299/check_join?user_name=knerten
Returns
{ can_join: true, places: 20, }
Files
POST /api/files
Upload file to Snapper Grape. The file will be connected to current logged in user
Parameters
user_name
Upload file on behalf of the user defined with 'user_name', else use currently logged in user
file
File upload object (HTTP)
filetitle
File name to display for end user.
ceid
Event id to which the file should be connected. If this attribute is defined, the file will be visible both for the end user, and for the instructor within the course administration system for the event defined with ceid.
fields
String. Optional. See Field customization.
Return
list of one APIOrganisastion object if successful.
Highscore
[GET] /api/highscore
Description
Returns a resource links for users highscore lists.
Parameters
user_name
String Optional. The user name of the user you want highscore lists from.
cids
String. Optional. If spesified the system returns the highscore liste based on the course id:s.
fields
String. Optional. See Field customization.
Return
Array of Highscore objects.
Security
Superuser, manager, person
[GET] /api/highscores/[organisation_id]
Description
Returns list of highscore items for the organisation
Parameters
user_name
String Optional. The user name of the user you want highscore lists from.
store
Int. Optional. if you want the function to return highscore with store items.
limit
Int. Optional. Default: 20. Maximum: 100. Limit the size of the result set.
offset
Int. Optional. Default: 0. Offset the result set, starting at this index. For batching/paging.
fields
String. Optional. See Field customization.
Return
Array of Highscore objects.
Security
Superuser, manager, person
LMSStartURL
GET /api/lmsstarturls
Description
Returns list of start URLs for the LMS configured in the system.
Parameters
competence_ids
List of ints. Optional. If not given, all URLs for all ecourse competences are returned.
limit
Int. Optional. Default: 20. Maximum: 100. Limit the size of the result set.
offset
Int. Optional. Default: 0. Offset the result set, starting at this index. For batching/paging.
fields
String. Optional. See Field customization.
Return
Array of LMSStartURL objects.
Security
Superuser, manager, person
Location
GET /api/locations
Description
Get all locations registered in system
Parameters
term
String. Optional. Search term.
startdate
Date. String on ISO-format. Optional. Restrict result to only those who are available in the time range given by start and end.
enddate
Date. String on ISO-format. Optional. Restrict result to only those who are available in the time range given by start and end.
minimum_capacity
Int. Optional. Restrict result to those who have a registered capacity at or higher than this.
sw_latitude
Float. Latitude for the south west corner of area to search for locations in.
sw_longitude
Float. Longitude for the south west corner of area to search for locations in.
ne_latitude
Float. Latitude for the north east corner of area to search for locations in.
ne_longitude
Float. Longitude for the north east corner of area to search for locations in.
limit
Int. Optional. Default: 20. Maximum: 100. Limit the size of the result set.
offset
Int. Optional. Default: 0. Offset the result set, starting at this index. For batching/paging.
view
String. Optional. "full" or "simple" view of object.
fields
String. Optional. See Field customization.
Return
Array of Location objects
Security
All logged in users
GET /api/locations/[location_id]
Description
Get location object.
Parameters
location_id
Int. Unique ID for location object.
view
String. Optional. "full" or "simple" view of object.
fields
String. Optional. See Field customization.
Return
Single Location object
Security
All logged in users
GET /api/locations/[location_id]/events
Description
Get events for this location.
Parameters
location_id
Int. Unique ID for location object.
startdate
Date. String on ISO-format. Required. Return only events within date range.
enddate
Date. String on ISO-format. Required. Return only events within date range.
view
String. Optional. "full" or "simple" view of object.
fields
String. Optional. See Field customization.
Return
Array of Event objects
Security
All logged in users
Login and single sign on
Single Sign On - Snapper Grape is master
This SSO system assumes that Snapper Grape is master of all user data, and that the client needs to be logged directly in to Snapper Grape. This should only be necessary if you communicate with the API server-to-server, and the end user needs to access Snapper Grape directly at some point, eg. to start an e-course.
See sequence diagram below describing how the SSO system is intended to work.
Single Sign On - third party is master
The Snapper Grape API also supports SSO where a thrid party system is master of user credentials. However, this requires that all user data is present in Snapper Grape. There is no on-the-fly creation of users/persons.
Authentication is done through oAuth2, using simple web token (SWT).
Requests using this form of SSO needs to have a header named "Authorization", with value on the form "SWT
A typical SWT token looks like this:
Issuer=snapper&ExpiresOn=1446648625&username=test@snapper.no&HMACSHA256=dT4XPaBjyM8Lg1s+AG7/oiphpMCkA/ZkNG9nMklAUDQ=
"Issuer" and "ExpiresOn" are not required, but if given, they are checked. "Issuer" is checked against a configured parameter, while "ExpiresOn" is checked for expiry.
In order for Snapper Grape to know who is logged in, one of the following parameters must be present:
- username
- user_name
- person_id
- external_person_id
Alternatively, we can configure Snapper Grape to use corresponding parameter names:
- api.oauth.user_name_key
- api.oauth.person_id_key
- api.oauth.extern_person_id_key
If everything checks out, and a user is found in Snapper Grape, the user should be logged in.
POST /api/login
Description
Logs a user in to Snapper Grape.
Parameters
user_name
String. User name for user trying to log in.
password
String. Password for user trying to log in.
login
Int. Must be set to 1 in order for the underlying security system to log the user in.
forward_url
String. URL to redirect to after successful login. Redirect is not done in this call, but if we are using SSO, the value of forward_url is relayed.
Return:
Single Login object.
Security:
Anyone
GET /api/validate
Description
Validate if user has a valid session in Snapper Grape. For use in SSO with third-party system, where Snapper Grape is master. Note that this is not a normal JSON request, it actually redirects the client, in order to do make SSO happen.
Parameters
user_name
String. User name of user in question.
hash
String. Short-lived hash, delivered by the login call.
forward_url
String. URL to forward to after successful negotiation.
Return
Redirect or error object
Security
Anyone
GET /api/logout
Description
Log out of Snapper Grape.
Parameters
forward_url
String. URL to forward to after successful logout. Simply relayed to the output.
Return
Single Logout object.
Security
Anyone, but only makes sense when logged in.
POST /api/forgot_password
Description
Resets a user's password
Parameters
identification
String. Identification of user to change password for. Can be user name, email or mobile.
Return:
Simple object containing two attributes: valid (boolean) and message (String)
Security:
Anyone
GET /api/validate_auth_token
Description
Validates token and returns result. Unlike /api/validate, it does not redirect the client. This resource is meant for third parties (like LMS systems) that receive a token from Grape in the URL, and need to validate that this token is valid and belongs to a valid, logged in user.
Parameters
user_id
Int. User's ID. This is the ID we use to connect third party LMS users to Grape users.
hash
String. Token string to validate. A token is valid for 30 seconds from the time it is issued.
Return
{
"valid": true/false,
"message": Explanation
"errorcode": (only if not valid)
}
Security
Anyone
Message
GET /api/messages/
Description
Returns list of messages for person.
Parameters
start
DEPRECATED. Will be removed in future version. Use offset in stead.
limit
Int. Optional. Default: 20. Maximum: 100. Limit the size of the result set.
offset
Int. Optional. Default: 0. Offset the result set, starting at this index. For batching/paging.
user_name
String. Optional. Username identifying the person whose messages we want. If not given, will return messages for logged in person.
fields
String. Optional. See Field customization.
Return
Array of Message objects.
Security
Superuser, person’s manager and self
GET /api/messages/[message_id]
Description
Returns details for message.
Parameters
fields
String. Optional. See Field customization.
Return
Array of one Message object.
Security
Superuser, person’s manager and self
POST /api/messages
Description
Sends a message to user.
Parameters
user_name
String. Username identifying the person to send to.
title
String. Title or subject for message.
text
String. The message.
cc
String. Optional. Addresses to CC to. Separated by comma, semicolon or space
send_medium
String. Optional. ”sms”/”email”/”both”. How to send the message.
reply_to
String. Optional. None/”manager”/email address. What reply-to address to use. None will yield system’s default.
fields
String. Optional. See Field customization.
Return
Array of one Message object.
Security
Superuser, person’s manager and self
Organisation
GET /api/organisations
Description
Returns list of organisation objects.
Parameters
start
DEPRECATED. Will be removed in future version. Use offset in stead.
limit
Int. Optional. Default: 20. Maximum: 100. Limit the size of the result set.
offset
Int. Optional. Default: 0. Offset the result set, starting at this index. For batching/paging.
parent_id
Int. Optional. Restricts result set to organisation objects belong to this parent. parent_id=0 yields only root organisation objects.
user_name
String. Optional. Person’s username. If given, will return list of organisations person belongs to.
fields
String. Optional. See Field customization.
Return
Array of Organisation objects.
Security
Superuser, manager, will yield different results based on manager’s permissions
GET /api/organisations/[organisation_id]
Description
Returns detailed view of organisation object. :id is organisation ID.
fields
String. Optional. See Field customization.
Return
Array of one Organisation object.
Security
Superuser, manager, only available to manager if manager for this particular object
GET /api/organisations/[organisation_id]/persons
Description
Returns list of people in the organisation object.
/api/persons?organisation_id=123 will yield the same result as /api/organisations/123/persons.
Parameters
view
Optional. String. Either None or 'full' or 'simple'
limit
Int. Optional. Default: 20. Maximum: 100. Limit the size of the result set.
offset
Int. Optional. Default: 0. Offset the result set, starting at this index. For batching/paging.
fields
String. Optional. See Field customization.
Return
Array of Person objects.
Security
Superuser, manager, only available to manager if manager for this particular object
PUT /api/organisations/[organisation_id]/organisationalfunctions
Available: 2.8Set OrganisationalFunction to an organisation
organisationalfunction_ids Array of OrganisationalFunction-id's to add to the organisation
DOC NEEDS CLEANUP
fields
String. Optional. See Field customization.
DELETE /api/organisations/[organisation_id]/organisationalfunctions
Available: 2.8Remove organisational function from an organisation
organisationalfunction_ids Array of OrganisationalFunction-id's to remove from the organisation
DOC NEEDS CLEANUP
fields
String. Optional. See Field customization.
POST /api/organisations
Create a new organisation.
Parameters
organisation_data
Please note thet the reference to a parent organisation should be included in this parameter. If not passing or passing a parent_id=0 will make the new organisation object a root organisation.
fields
String. Optional. See Field customization.
Return
List of one Organisastion object if successful.
Examples
curl http://pet/api/login --data "user_name=peen&login=1&password=fdsafdsa"
Use "session_id" from the result and set as tg-visit cookie:
curl --cookie "tg-visit=03dd783b1051326e110487a4125c52fceafdefee" --data "organisation_data[name]=TestUnitI&organisation_data[parent_id]=10&organisation_data[email]=jost@snapper.no&organisation_data[address]=Brattvollveien+261" http://pet/api/organisations
Creates a new organisation object.
OrganisationalFunctions
GET /api/organisationalfunctions
Available: 2.8Description
Returns list of organisation’s functions
Parameters
organisation_id
Integer. Optional. Username of person. If not given, will return positions for logged in person.
role_meta_types
String. Optional. Specify one or more role meta types to list, can be one of or combination of: role, specialrole or position. Example: role_meta_type=role fetches roles only, role_meta_type=role,specialrole fetches both roles and specialroles.
fields
String. Optional. See Field customization.
Return
Array of OrganisationalFunction objects.
Security
Superuser, person’s manager and self
Examples:
https://servername/api/roles?role_meta_types=role
Returns a list of roles of meta type 'role' for currently logged in user
https://servername/api/roles?role_meta_types=role&user_name=pe@snapper.no
Returns a list of roles of meta type 'role' for user with user name 'pe@snapper.no'.
PUT /api/organisationalfunctions/[organisationalfunction_id]
Available: 2.8Description
Update details about the OrganisationalFunction
Parameters
organisationalfunctions_id
Integer. Id of the OrganisationalFunction to update
action
String. ”off”/”update”. Action to take. ”off” signs person off event.
fields
String. Optional. See Field customization.
Return
Array of one OrganisationalFunction object.
Security
Superuser, manager, self
Participant
GET /api/participants/:event_id
Description
Returns list of Participant objects for event.
Parameters
event_id
Int. ID for the event to get participants for.
waitlist
Int. Optional. 1/0. If 1, will return only participants on wait list. If 0, will return only participants not on waitlist. If unset, will return both.
passed
Int. Optional. 1/0. If 1, will return only participants who have passed the course. If 0 will return only participants who did not pass the course. If unset, will return both.
met
Int. Optional. 1/0. If 1, will return only participants who met for the course. If 0 will return only participants who did not meet for the course. If unset, will return both.
organisation_id
Int. Optional. ID of organisation, will restrict participants to only those who are employed here.
recursive
Int. Optional. 1/0. If set, organisation_id will be user recursively, looking down the organisation tree branch.
view
String. Optional. "full"/"simple". What view to use.
start
DEPRECATED. Will be removed in future version. Use offset in stead.
limit
Int. Optional. Default: 20. Maximum: 100. Limit the size of the result set.
offset
Int. Optional. Default: 0. Offset the result set, starting at this index. For batching/paging.
fields
String. Optional. See Field customization.
Return
Array of Participant objects.
Security
Superuser, organisation’s manager if organisation_id is given
GET /api/participants/:event_id/:user_name
Description
Returns single Participant for event.
Parameters
event_id
Int. ID for the event to get participant for.
user_name
String. Optional. User name for user.
view
String. Optional. "full"/"simple". What view to use.
fields
String. Optional. See Field customization.
Return
Single Participant objects.
Security
Superuser, person's manager, self
Person
GET /api/persons/[user_name]
Alias: GET /api/person
Description
Returns person info object for user name. If ”person” alias is used, will always return info for logged in user.
Parameters
fields
String. Optional. See Field customization.
Return
Array of one Person Object
Security
Superuser, person’s manager and self
GET /api/persons/
Description
Returns list of Persons objects.
Parameters
start
DEPRECATED. Will be removed in future version. Use offset in stead.
limit
Int. Optional. Default: 20. Maximum: 100. Limit the size of the result set.
offset
Int. Optional. Default: 0. Offset the result set, starting at this index. For batching/paging.
organisation_id
Int. Optional. Limits the result set to members/employees of organisation.
organisation_ids
List of ints. Optional. Limits the result set to members/employees of the specified organisations. If both organisation_id and organisation_ids are specified, then the paramters are combined and the search will use ids specified in both paramters.
event_id
Int. Optional. Limits the result set to persons signed on to event. Cannot be used in conjuction with has_competence_ids, specified below
has_competence_ids
List of ints specifying comepetences that has to be fulfilled. Cannot be used in conjunction with event_id, specified above
role_ids
List of ints: Limit result set to persons matching specified roles
fields
String. Optional. See Field customization.
Return
Array of Person objects.
Security
Superuser, organisation’s manager if organisation_id is given
PUT /api/persons/[user_name]
Description
Updates person info for user name
Parameters
person_data
Object. All are optional unless otherwise noted. Not that object must be delivered on the "modern" format: "person_data[firstname]=John&person_data[lastname]=Doe". Only fields present will update person. Can contain the following fields:
- user_name
- password
- firstname
- lastname
- jobtitle
- mobile
- birthdate
- extern_person_id
- address
- postcode
- city
- phone
- sex
- notice
- employee_code
- profile_image
- source
- code
- old_password: Required if password or user_name is present, and person is updating self. Not required if manager or superuser is updating. Must match previous password
- password_match: Required if password or user_name is present, and person is updating self. Not required if manager or superuser is updating.. Must match password.
fields
String. Optional. See Field customization.
role_ids
List of integer. List of role ids specifying roles that should be set for the specified user
Return
Array of one Person object.
Security
Superuser, person’s manager and self
DELETE /api/persons/[user_name]
Description
Updates person info for user name
Parameters
role_ids
List of integer. List of role ids specifying roles that should be removed from the specified user
Return
Status as JSON
Security
Superuser, person’s manager and self
POST /api/persons
Available: 2.4.3Creates new person. Input params are equal to the full view for APIPerson object.
Parameters
organisation_id
Int. Required. Where the new person object should reside.
role_id
Int. Reqired. What role the new person should have in connection to the passed org.
person_data
Json object. Data to update person with. Please note that the 'user_name' must be included in this object. Can contain the following fields:
- user_name
- password
- firstname
- lastname
- jobtitle
- mobile
- birthdate
- extern_person_id
- address
- postcode
- city
- phone
- sex
- notice
- employee_code
- profile_image
- source
- code
fields
String. Optional. See Field customization.
PersonCompetence
GET /api/personcompetences
Description
Returns list of passed or missing competences for person.
Parameters
person_competence_id
Int. Optional. ID to specific PersonCompetence object. The distinction between using person_competence_id and calling /api/personcompetences/[competence_id] is that if you use competence_id, you may also have to define user_name to get the object you want. Also, when using competence_id, the system will always return the "current" PersonCompetence. In other words, it will give you the latest attempt at fulfilling a competence/ecourse/course/etc. When using person_competence_id, the system will return this object, regardless of cancellations, validity, if it has been replaced by a newer object, etc. Note that when person_competence_id is specified, all other parameters are disregarded.
start
DEPRECATED. Will be removed in future version. Use offset in stead.
limit
Int. Optional. Default: 20. Maximum: 100. Limit the size of the result set.
offset
Int. Optional. Default: 0. Offset the result set, starting at this index. For batching/paging.
state
String. Optional. ”passed”/”missing”/"expired/all". Whether to return passed competences, missing competences, all competences or competences that have expired. Default: ”passed”.
user_name
String. Optional. Username identifying the person whose competences we want. If not given, will return competences for logged in person.
role_ids
List of ints. Optional. IDs of roles to restrict to. Will only yield competences mandatory for these roles.
requirement
String. Optional. None/”mandatory”/”optional”. If set to ”optional”, will return optional instead of mandatory competences. Default: None for state ”passed”, ”mandatory” for state ”missing” or if role_ids is defined
types
List of strings. Optional. Competence types to restrict to.
view
String. Optional. Accepts "simple" and "full". Controls whether to return the full object or a simple representation.
fields
String. Optional. See Field customization.
Return
Array of PersonCompetence objects.
Security
Superuser, person’s manager and self
GET /api/personcompetences/[competence_id]
Description
Returns details of competence for person.
Parameters
competence_id
Int. Parameter given in URL path. ID for competence to get. Mandatory, unless person_competence_id is given.
user_name
String. Optional. If not given, will get competence for logged in user. Only allowed for managers and superusers.
state
String. Optional. ”passed”/”missing”. Whether to return passed competence or competence that have expired. If there are no passed/expired competence, will return empty set. Default: not set, will yield current PersonCompetence object, regardless of passed/expired state.
fields
String. Optional. See Field customization.
Return
Array of one PersonCompetence object.
Security
Superuser, person’s manager and self
POST /api/personcompetences/
Description
Updates state of competence for person by creating a new PersonCompetence object. What it actually does, depends on the type of the competence:
Common for all types: Registers competence for person, sets dates (verified date and valid until date), stores a comment and file.
Checklist item: Sets the checklist’s state on or off
Signature: Signs digitally, only allowed for self
Formal competence: Sets competence and stores school/university and graduation year
Skill: Stores skill level
Parameters common for all competence types
user_name
String. Optional. If not given, will set competence for logged in user. Only allowed for managers and superusers.
competence_id
Int. Mandatory. ID for Competence to register for person.
passed
Int, 0-100. Optional, default: 100. Defines passed level for the competence, where 100 is fully passed and 0 is not at all. Mostly for skills, other types should not provide this parameter, usually.
date
String, date on ISO format. Optional, default: now. The point in time from which the competence is valid for the person.
valid_until
String, date on ISO format. Optional. The point in time where the competence is no longer valid.
comments
Text. Optional. Additional comment to the person’s competence.
file
File. Optional. File to store with the person’s competence. Typically documentation for the competence. NOT IMPLEMENTED.
fields
String. Optional. See Field customization.
Parameters applicable for specific competence types
action
String. ”on”/”off”. For checklist items. Determines which state to set the checklist item to. Note: If a person’s manager invokes this, and action is defined, the request is regarded as an attempt to check/uncheck the checklist item as per the item’s setting. However, if action is not defined, the request is regarded as an override to the check/uncheck status of the item, and the competence is set as passed for the person, regardless.
password
String. Person’s password. For signatures when user_name not given. Must be correct in order for the signature to be marked as signed.
show_course_diploma
Boolean. Optional. For courses, module courses, ecourses. If present (and any value), user will be able to download course diploma for the competence.
grade
Floating point number. Optional. For courses, module courses, ecourses. The grade given to the participant.
school
String. Optional. For formal competences. Name of school or university.
graduation_year
String, four digit year. Optional. For formal competences. Year of graduation.
Return
Array of one PersonCompetence object.
Security
Superuser, person’s manager and/or self, but depending on type and how it is configured.
PUT /api/personcompetences/[person_competence_id]
Description
Updates state of PersonCompetence object. What it actually does, depends on the type of the competence:
Common for all types: Updates, sets dates (verified date and valid until date), stores a comment and file.
Checklist item: Sets the checklist’s state on or off
Signature: Signs digitally, only allowed for self
Formal competence: Sets competence and stores school/university and graduation year
Skill: Stores skill level
Parameters common for all competence types
person_competence_id
Int. Mandatory. Parameter given in URL. ID for PersonCompetence object to update.
competence_id
Int. Optional. ID for competence, if you want to change which competence the PersonCompetence belongs to. Must be used with caution. If PersonCompetence belongs to an event that has not been registered manually (typically a classroom course), this parameter will be ignored. Consider doing a DELETE and POST in stead.
passed
Int, 0-100. Optional, default: 100. Defines passed level for the competence, where 100 is fully passed and 0 is not at all. Mostly for skills, other types should not provide this parameter, usually.
date
String, date on ISO format. Optional, default: now. The point in time from which the competence is valid for the person.
valid_until
String, date on ISO format. Optional. The point in time where the competence is no longer valid.
comments
Text. Optional. Additional comment to the person’s competence.
file
File. Optional. File to store with the person’s competence. Typically documentation for the competence. NOT IMPLEMENTED.
fields
String. Optional. See Field customization.
Parameters applicable for specific competence types
action
String. ”on”/”off”. For checklist items. Determines which state to set the checklist item to. Note: If a person’s manager invokes this, and action is defined, the request is regarded as an attempt to check/uncheck the checklist item as per the item’s setting. However, if action is not defined, the request is regarded as an override to the check/uncheck status of the item, and the competence is set as passed for the person, regardless.
password
String. Person’s password. For signatures when user_name not given. Must be correct in order for the signature to be marked as signed.
show_course_diploma
Boolean. Optional. For courses, module courses, ecourses. If present (and any value), user will be able to download course diploma for the competence.
grade
Floating point number. Optional. For courses, module courses, ecourses. The grade given to the participant.
school
String. Optional. For formal competences. Name of school or university.
graduation_year
String, four digit year. Optional. For formal competences. Year of graduation.
Return
Array of one PersonCompetence object.
Security
Superuser, person’s manager and/or self, but depending on type and how it is configured.
DELETE /api/personcompetences/[person_competence_id]
Description
Removes a competence from a person, by setting the cancelled attribute on the PersonCompetence object.
Parameters
person_competence_id
Int. Mandatory (sort of). ID for PersonCompetence to remove. Parameter given in URL path.
competence_id
Int. ID for Competence. If given, will override person_competence_id and remove ALL PersonCompetence instances for Person/Competence. If given, person_competence_id is actually not mandatory.
user_name
String. Optional. Only required if person_competence_id is not given and we are looking up the current PersonCompetence object by competence_id. Will look up object for logged in user if not given. Only allowed for managers and superusers.
fields
String. Optional. See Field customization.
Return
Array of one PersonCompetence object.
Security
Superuser, person’s manager and/or self.
GET /api/personcompetences/search
Description
Returns list of passed or partially passed competences for persons. This is a search, not tied to any specific person.
Parameters
term
String. Search for competence with name containing this.
state
String. Optional. ”passed”/"missing"/”expired”. Whether to return passed competences, missing competences or expired competences. Default: ”passed”. State "missing" not supported yet.
role_ids
List of ints. Optional. IDs of roles to restrict to. Will only yield competences mandatory for these roles.
requirement
String. Optional. None/”mandatory”/”optional”. If set to ”optional”, will return optional instead of mandatory competences. Default: None for state ”passed”, ”mandatory” if role_ids is defined
types
List of strings. Optional. Competence types to restrict to.
competence_ids
List of ints. Restrict to these competences.
organisation_ids
List of ints. Restrict to competences defined in these organisations (or their children).
external_organisation_ids
List of ints. Same as for organisation_ids.
competence_group_ids
List of ints. Restrict to competences belonging to these groups.
external_competence_group_ids
List of ids. Restrict to competences belonging to these groups. Can be used together with competence_group_ids.
view
String. Optional. Accepts "simple" and "full". Controls whether to return the full object or a simple representation.
limit
Int. Optional. Default: 20. Maximum: 100. Limit the size of the result set.
offset
Int. Optional. Default: 0. Offset the result set, starting at this index. For batching/paging.
fields
String. Optional. See Field customization.
Return
Array of PersonCompetence objects.
Security
Superuser
PersonEvent
GET /api/personevents
Description
Returns list of events for user, for organisation, or just searches for person-events if neither user_name nor organisation_id is given (this is allowed only for superuser and superadmin users).
Parameters
person_event_ids
List of ints. Optional. IDs to specific PersonEvent objects.
user_name
String. Optional. User name for user. Will NOT return for logged in user if not present.
organisation_id
Int. Optional. Return personevents for persons belonging to organiasation unit. Will override user_name parameter.
event_ids
Array of ints. Optional. Limit to these events.
mode
String. Optional. ”future”/”finished”/”all”. Controls if we are to get future or finished events, or both. Default: ”future”
waitlist
Int. Optional. 0/1. Return person events for which person is on waitlist or not. Default 0.
confirmed
Int. Optional. 0/1. Return person events that are confirmed/not confirmed. If parameter is omitted, will return both confirmed and not confirmed.
include_person
Int. Optional. Set to 1 if person information should be included to the returned PersonEvent object. When specifying organisation id, this parameter is default set to 1 (TRUE), else default 0 (FALSE).
startdate
Date. Optional. Get PersonEvents starting after this date.
enddate
Date. Optional. Get PersonEvents starting before this date.
host_organisation_ids
List of ints. Optional. Get only PersonEvents where Event is hosted by these organisations.
host_organisation_external_ids
List of ints. Optional. Same as host_organisation_ids, only using "external" organisation identifier instead.
representing_organisation_ids
List of ints. Optional. Get only PersonEvents where person is defined as representing these organisations.
representing_organisation_external_ids
List of ints. Optional. Same as representing_organisation_ids, only using "external" organisation identifier instead.
sort_direction
String. "asc"/"desc". Whether the result should be sorted ascendingly or descendingly. Default: "asc".
start
DEPRECATED. Will be removed in future version. Use offset in stead.
limit
Int. Optional. Default: 20. Maximum: 100. Limit the size of the result set.
offset
Int. Optional. Default: 0. Offset the result set, starting at this index. For batching/paging.
fields
String. Optional. See Field customization.
Return
Array of PersonEvent objects.
Security
Superuser, manager, self
GET /api/personevents/[event_id]
Description
Get detailed view of event for person. Will return empty list if person is not signed on to event.
Parameters
fields
String. Optional. See Field customization.
Return
Array of one PersonEvent object.
Security
Superuser, manager, self
POST /api/personevents/[event_id]
Description
Signs person on to course event.
Parameters
user_name
String. Optional. Username for user to be signed on.
representing_organisation_id
Int. Optional. Snapper Grape organisation_id which defines the organisation the person signed on to the course is representing. You cannot specify both context_organisation_id and context_extern_organisation_id at the same time. This will result in an error message.
representing_extern_organisation_id
Int. Optional. Snapper Grape external organisation_id which defines the organisation the person signed on to the course is representing. You cannot specify both context_organisation_id and context_extern_organisation_id at the same time. This will result in an error message.
order_id
Int. Optional. ID of order to add this sign on to. Only valid if order system is enabled.
order_reference
String. Optional. Order reference for new order that is created. Only valid if order system is enabled. Ignored if parameter order_id is given.
debitor_person_id
Int. Optional. Specify which person id that should be defined as debitor for the course sign on order.
debitor_extern_person_id
String. Optional. Same as above, but user is specified by the external id instead.
debitor_organisation_id
Int. Optional. Specify which organisation that should be defined as debitor for the course sign on order.
debitor_extern_organisation_id
String. Optional. Same as above, but debitor organisation specified using the external id.
contact_person_id
Int. Optional. Specify which person id that should be defined as contact person for the course sign on order.
contact_extern_person_id
String. Optional. Same as above, but user is specified by the external id instead.
contact_organisation_id
Int. Optional. Specify which organisation that should be defined as contact for the course sign on order.
contact_extern_organisation_id
String. Optional. Same as above, but contact organisation specified using the external id.
fields
String. Optional. See Field customization.
Return
Array of one PersonEvent object.
Security
Superuser, manager, self
PUT /api/personevents/[event_id]
Description
Signs person off course event. Or otherwise alters the sign on data (not specified or implemented yet).
Parameters
user_name
String. Username for user.
action
String. ”off”/”update”. Action to take. ”off” signs person off event.
fields
String. Optional. See Field customization.
Return
Array of one PersonEvent object.
Security
Superuser, manager, self
PersonTravelInformation
GET /api/persontravelinformations
Description
Get travel information for a person's sign on to an event. For now, we are only exposing the possibility to get a single, current PersonTravelInformation object for a person/event, no listings of multiple PersonTravelInformations (that may come in a later version)
Parameters
user_name
String. User name for user in question. If not provided, will look up PersonTravelInformation for logged in user.
event_id
Int. Mandatory. ID for event we are looking at.
view
String. Optional. "full" or "simple". Which type of object view to return.
Security
Superuser, manager, course admin or self
fields
String. Optional. See Field customization.
Return
Array of single PersonTravelInformation object.
POST /api/persontravelinformations
Description
Create new travel information for a person's sign on to an event.
Parameters
user_name
String. User name for user in question. If not provided, will look up PersonTravelInformation for logged in user.
event_id
Int. Mandatory. ID for event we are looking at.
travelinformation_id
Int. Mandatory. ID for TravelInformation.
view
String. Optional. "full" or "simple". Which type of object view to return.
arrival_time
Date. Indicates arrival time for participant.
arrival_location
String. Indicates arrival location for participant.
arrival_info
String. Extra information about arrival. Interpretation is dependant on the TravelInformation object's configuration.
departure_time
Date. Indicates departure time for participant.
departure_location
String.Indicates departure location for participant.
departure_info
String. Extra information about departure. Interpretation is dependant on the TravelInformation object's configuration.
comment
String. Participant's comment for the travel info.
hotel
Boolean. Whether or not participant wants to/needs to have a hotel room booked.
hotel_room_type
String. "double"/"single"/empty string. Double or single room.
hotel_roomie_name
String. Indicates who the participant wishes to share room with.
pick_up
Boolean. Indicates whether or not participant wants to/needs to be picked up at arrival location
fields
String. Optional. See Field customization.
Security
Superuser, manager, course admin or self
Return
Array of single PersonTravelInformation object.
PUT /api/persontravelinformations
Description
Update travel information for a person's sign on to an event.
Parameters
user_name
String. User name for user in question. If not provided, will look up PersonTravelInformation for logged in user.
event_id
Int. Mandatory. ID for event we are looking at.
travelinformation_id
Int. Mandatory. ID for TravelInformation.
view
String. Optional. "full" or "simple". Which type of object view to return.
arrival_time
Date. Indicates arrival time for participant.
arrival_location
String. Indicates arrival location for participant.
arrival_info
String. Extra information about arrival. Interpretation is dependant on the TravelInformation object's configuration.
departure_time
Date. Indicates departure time for participant.
departure_location
String.Indicates departure location for participant.
departure_info
String. Extra information about departure. Interpretation is dependant on the TravelInformation object's configuration.
comment
String. Participant's comment for the travel info.
hotel
Boolean. Whether or not participant wants to/needs to have a hotel room booked.
hotel_room_type
String. "double"/"single"/empty string. Double or single room.
hotel_roomie_name
String. Indicates who the participant wishes to share room with.
pick_up
Boolean. Indicates whether or not participant wants to/needs to be picked up at arrival location
fields
String. Optional. See Field customization.
Security
Superuser, manager, course admin or self
Return
Array of single PersonTravelInformation object.
Player
GET /api/player/[id]/data
Description
Returns a nano course object in json format
Return
A Nano course object
Security
Superuser, manager, person
POST /api/player/[id]/event
Position and Role
GET /api/positions
Description
Returns list of persons positions, with reference to which organisation objects the positions belong to.
Parameters
user_name
String. Optional. Username of person. If not given, will return positions for logged in person.
limit
Int. Optional. Default: 20. Maximum: 100. Limit the size of the result set.
offset
Int. Optional. Default: 0. Offset the result set, starting at this index. For batching/paging.
fields
String. Optional. See Field customization.
Return
Array of Position objects.
Security
Superuser, person’s manager and self
GET /api/roles
Description
Returns list of person’s roles, including positions.
Parameters
user_name
String. Optional. Username of person. If not given, will return positions for logged in person.
term
String. Optional. Search term for role name.
competence_id
Integer. Optional. Return a list of roles that this competence is defined as either mandatory or optional for. This attribute will override user_name if defined. Please not: The APIRole object will be tagged with an attribute called mandatory, which is True if competence is required for role, else False if optional
state
String. Optional. When competence_id is specified, it is possible to specify whenter to fetch roles for which the competence is either mandatory or optional. Default is to return both mandatory and optional. Allowed values: "mandatory", "optional".
role_meta_types
String. Optional. Specify one or more role meta types to list, can be one of or combination of: role, specialrole or position. Example: role_meta_type=role fetches roles only, role_meta_type=role,specialrole fetches both roles and specialroles.
organisation_ids
List of ints. Optional. If present, limits the result to only roles available for these organisation units. Both extern_organisation_ids and organisation_ids can be sent in the same request.
extern_organisation_ids
List of ints. Optional. If present, limits the result to only roles available for these organisation units. Both extern_organisation_ids and organisation_ids can be sent in the same request.
limit
Int. Optional. Default: 20. Maximum: 100. Limit the size of the result set.
offset
Int. Optional. Default: 0. Offset the result set, starting at this index. For batching/paging.
fields
String. Optional. See Field customization.
Return
Array of Role objects.
Security
Superuser, person’s manager and self
Examples:
https://servername/api/roles?role_meta_types=role
Return list of roles of meta type 'role' for currently logged in user
https://servername/api/roles?role_meta_types=role&user_name=pe@snapper.no
Return list of roles of meta type 'role' for user with user name 'pe@snapper.no'.
GET /api/roles/[role_id]
Description
Get single role object.
Parameters
role_id
Int. Mandatory. The ID of the role to return.
fields
String. Optional. See Field customization.
Return
Array of one Role object.
Security
Superuser, superadmin and admin for the role
Search
GET /api/search
Description
Performs a search for various (specified) object types, based on parameters.
Parameters
items
String. Mandatory. Defines what the search looks for, and as an extension what the return value is. Allowed values: person or persons, organisation or organisations, event or events.
mode
String. Mandatory. Defines whether the search should find an exact match or a more fuzzy search. Default: exact. Allowed values: exact, partial.
query
String. Mandatory. The search term/query/string. Must be at least 3 characters.
key
String(s). Optional. Applies to person search only. Defines which keys we try to find a match for. Allowed values: mobile, phone, email, email2, firstname, lastname, fullname. Can be multiple keys in the same search: "key=email&key=fullname".
firstname
String. Optional. Applies to person search only. Search query for first name, specifically.
lastname
String. Optional. Applies to person search only. Search query for last name, specifically.
organisation_ids
List of ints. Optional. Applies to person search only. Defines which organisational units we look for persons in. Depending on user type, this may be mandatory, and security checks are performed to ensure that the user is allowed to search in all organisational units.
limit
Int. Optional. Default: 20. Maximum: 100. Limit the size of the result set.
offset
Int. Optional. Default: 0. Offset the result set, starting at this index. For batching/paging.
view
String. Optional. Accepts "simple" and "full". Controls whether to return the full object or a simple representation.
fields
String. Optional. See Field customization.
Return
Array of Person objects, Organisation objects or Event objects.
Security
Logged in user, but what the user actually can search for depends on its permissions.
SurveyAnswer
GET /api/surveyanswer/[surveyanswer_id]
Description
Get a single survey answer (or, single set of survey answers, as they are usually nested).
Parameters
surveyanswer_id
Int. Mandatory. ID to the SurveyAnswer object. Given in the URL (surveyanswer_id=2): "/api/surveyanswer/2"
limit
Int. Optional. Default: 20. Maximum: 100. Limit the size of the result set.
offset
Int. Optional. Default: 0. Offset the result set, starting at this index. For batching/paging.
view
String. Optional. "full" or "simple". Which type of object view to return.
fields
String. Optional. See Field customization.
Security
Superuser, manager or self
Return
Array of single SurveyAnswer object.
GET /api/surveyanswers
Description
Returns a list of survey answers, belonging to sruvey, organisation or person, depending on parameters.
Parameters
user_name
String. Optional. Get answers for person with this user name. Unlike many other places in the API, we will not return survey answers for the logged in user if user_name isn't present. user_name must be given if we want to get for a specific user.
organisation_id
Int. Optional. Get answers given for the organisation given.
survey_id
Int. Optional. Get all answers belonging to this survey.
view
String. Optional. "full" or "simple". Which type of object view to return.
start
Int. Optional. Offset result list to this point. For batching.
limit
Int. Optional. Limit result list to this. For batching.
fields
String. Optional. See Field customization.
Return
Array of SurveyAnswer objects
Security
Superuser, manager or self
POST /api/surveyanswer
Description
Create a new answer set for survey. This answer can be updated later, using the PUT function.
Parameters
user_name
String. Optional. User name for person answering survey.
organisation_id
Int. Optional. ID for organisation answering survey.
data
JSON. Mandatory. JSON structure containing the answers. Corresponds to the parent/child structure of the survey.
{ "items":[ { "competence_id": ID for Competence, "value": The answer, "file_data": Base64 encoded file contents, "file_name": File name for file ("document.pdf"), "file_title": Display title for file ("My document"), "children": [nested items] }, ... ] }
fields
String. Optional. See Field customization.
Security
Superuser, manager, self
Return
Array of single SurveyAnswer object.
PUT /api/surveyanswers/[surveyanswer_id]
Description
Store a new answer set for an existing survey answer. Technically, the underlying events will be kept from the previous answer, but the actual answers will be replaced.
Parameters
surveyanswer_id
Int. Mandatory. ID for the answer to update.
data
JSON. Mandatory. JSON structure containing the answers. Corresponds to the parent/child structure of the survey.
{ "items":[ { "competence_id": ID for Competence, "value": The answer, "children": [nested items] }, ... ] }
fields
String. Optional. See Field customization.
Security
Superuser, manager or self
Return
Array of single SurveyAnswer object
PUT /api/surveyanswers/[surveyanswer_id]/lock
Description
Lock the survey answer for further editing/updating answers. As a result, a following PUT request to the same answer will be denied, with a prompt to perform a POST in stead.
Parameters
surveyanswer_id
Int. Mandatory. ID for the answer to lock.
fields
String. Optional. See Field customization.
Security
Superuser, manager or admin for event or competence.
Return
Array of single SurveyAnswer object
PUT /api/surveyanswers/[surveyanswer_id]/unlock
Description
Unlock survey answer for further updates.
Parameters
surveyanswer_id
Int. Mandatory. ID for the answer to unlock.
fields
String. Optional. See Field customization.
Security
Superuser, manager or admin for event or competence.
Return
Array of single SurveyAnswer object