Integrations - API's

The VOLAGIC API allows other applications to retrieve information from VOLAGIC. This includes information about Helpers, Events, Shifts and Tasks. Data cannot be edited via the API.

The VOLAGIC APIs allow IT professionals and developers to retrieve data from VOLAGIC and process it according to their own requirements. The API is available from the Pro subscription onwards in the administration under "Organisation" – "Integration APIs". All content on this page is intended for professionals and should be handled accordingly. VOLAGIC cannot accept liability for incorrect data analysis resulting from improper use.

API-Key

First, you need to create the API key. To do this, click the "API key" button and then "Add". Enter a name and save it. The key will then be displayed and you can copy it directly.

IMPORTANT: The API key is ONLY displayed immediately after it has been created. Store it in a secure location. The API key provides access to the personal data of Helpers and must therefore be treated as confidential!

The API key must be included as X-API-KEY in the request header when making requests. To test the API, we recommend using a tool such as Postman.

 

Available API-Calls

Helpers

The first service allows you to retrieve all Helpers:

https://api.helfereinsatz.ch/v1/[your-organisation-path]/helpers/[page-no]

You will receive a JSON file containing three entries at the top level:

  • pageNo: current page (see page-no)
  • pagesNum: total number of pages → you need this to retrieve all Helpers via the API
  • entries: an array containing all Helpers

entries (Helper) properties

The Helpers array contains the following values:

  • id: unique identifier of the Helper
  • firstName: first name
  • lastName: surname
  • email: email
  • phone: phone
  • additionalEmail1: additional email 1
  • additionalEmail2: additional email 2
  • adminRemarks: comments about the Helper
  • birthDate: date of birth (format YYYY-MM-DD)
  • infoFill: array for each custom field you have created
  • groups: array containing all Groups
  • stateCache: array containing the Helper’s values

infoFill properties

Each infoFill item contains the following values:

  • label: field name
  • value: variable or array containing the Helper’s values for this field

groups properties

Each groups item contains the following values:

  • id: unique identifier of the Group
  • name: name of the Group

stateCache properties

The stateCache array contains the following values:

  • okAssignmentsNum: number of successfully completed Tasks
  • nokAssignmentsNum: number of missed Tasks (accepted but did not attend)
  • confirmedAssignmentsNum: number of confirmed Tasks (i.e. Tasks that are still in the future)
  • reservedAssignmentsNum: with double opt-in, the number of Tasks that the Helper has reserved but not yet confirmed
  • requestedValue: Target value
  • plannedValue: okAssignmentsNum + confirmedAssignmentsNum
  • unconfirmedAssignmentsNum: with double opt-in, the number of Tasks that the Helper reserved but failed to confirm within the time limit

Important: Where Num appears, the value represents a quantity. Where Value appears, it represents the Task value. If Helper A completes a Task on behalf of Helper B, the quantities are recorded for Helper A, while the Task values are credited to Helper B.

Events

This service allows you to retrieve Events and their Shifts. Tasks are not included in this service, as this would make the response too extensive.

https://api.helfereinsatz.ch/v1/[your-organisation-path]/events/[page-no]

This service returns JSON with the following properties at the top level:

  • id: unique identifier of the Event (required for the Tasks service)
  • name: name of the Event
  • date: Event date in YYYY-MM-DD HH-MM-SS format → no longer relevant (deprecated)
  • timeStart: Event start date and time in YYYY-MM-DD HH-MM-SS format
  • timeEnd: Event end date and time in YYYY-MM-DD HH-MM-SS format
  • remarks: Event comments
  • online: online status of the Event
  • done: indicates whether the Event has been processed. When processed, all Tasks are set to status OK.
  • stateCache: cached Event values (see below)
  • category: Section of the Event (if available)
  • shifts: Shifts of the Event

Event stateCache properties

  • confirmedHelperAssignmentsNum: number of confirmed Tasks (for future Events)
  • okHelperAssignmentsNum: number of successfully completed Tasks (for past Events)
  • totalHelperAssignmentsNum: total number of Tasks

category (Sections) properties

  • id: unique identifier of the Section
  • name: name of the Section

shifts (Shifts) properties

  • id: unique identifier of the Shift
  • name: name of the Shift
  • startDateTime: Shift start date and time in YYYY-MM-DD HH-MM-SS format
  • endDateTime: Shift end date and time in YYYY-MM-DD HH-MM-SS format
  • remarks: Shift comments
  • stateCache: cached Shift values

Shift stateCache properties

  • confirmedHelperAssignmentsNum: number of confirmed Tasks for the Shift (for future Events)
  • okHelperAssignmentsNum: number of successfully completed Tasks for the Shift (for past Events)
  • totalHelperAssignmentsNum: total number of Tasks
  • misfit: true if there are Helpers who have taken on Tasks that did not match their Groups

HelperAssignments: Tasks for an Event

This service allows you to retrieve the Tasks for an Event. You need the ID of the Event you want to retrieve. You can obtain the ID via the Events endpoint.

https://api.helfereinsatz.ch/v1/[your-organisation-path]/helperassignments/[event-id]/[page-no]

This service returns JSON with the following properties:

  • pageNo: current page
  • pagesNum: total number of pages for this service
  • entries: Tasks

entries (Tasks)

  • id: unique identifier of the Task
  • responsible: true if this Helper is responsible for the Task
  • remarks: comments for the person taking on this Task
  • value: Task value
  • plannedValue: takes the value from value if the Task has the status confirmed, reserved or ok
  • status: status of the Task → the possible values are listed below
  • startDateTime: Task start time
  • endDateTime: Task end time
  • hours: number of hours for the Task
  • role: Job for the Task
  • shift: Shift properties
  • helper: if a person has already taken on the Task, their properties are listed here
  • helpAsHelper: if the person taking on the Task is doing it on behalf of someone else, the person who receives credit for the Task is listed here
  • stateCache: cached values for the Task

status values

The status of a Task can have the following values:

  • open: open Task
  • confirmed: a Helper has taken on the Task
  • reserved: with double opt-in, the Task is considered reserved once someone has taken it on but has not yet confirmed it
  • unconfirmed: with double opt-in, a Task is considered unconfirmed once the reservation period (24 hours) has expired
  • ok: the Task was completed
  • nok: the Task was not completed

role properties

  • id: unique identifier of the Job
  • name: name of the Job

shift properties

The Shift properties are the same as those in the Event service, so they are not repeated here. You can find them described above.

IMPORTANT: The Shift properties are included with every Task. If you have an Event with 30 Tasks distributed across 3 Shifts with 10 Tasks each, all 10 Tasks in the same Shift will have the same shift properties!

helper and helpAsHelper properties

  • id: unique identifier of the Helper
  • firstName: Helper’s first name
  • lastName: Helper’s surname
  • email: Helper’s email
  • phone: Helper’s phone number

Important: If you need more information about the Helper, you must retrieve it via the Helper service!

Task stateCache properties

  • misfit: true if the Helper takes on a Task that does NOT match their Groups.