2.1 - Employee information - Automatic import of data via API

Access to this feature is restricted to authorized API users only. If you feel you need access to this feature, please contact product@springest.com.

This is an optional feature. Are you interested in using this feature? Contact your Customer Success Manager and discuss options and pricing.

You can access the endpoint for Go sites on the following host: https://site-name.api.go.springest.nl (or .de, .co.uk, etc).

Note: Edit "site-name" to the name that is applicable to your site. So, for example with site name exampleorganisation.go.springest.nl, the URL to be used will be: exampleorganisation.api.go.springest.nl.

In order to process a user you need to send a POST request (json) to the following endpoint. 

POST

Endpoint: /users.json?api_key=YOUR_PRIVATE_API_KEY

We support both creating and updating existing users. Users can be matched on either email or external_id. All data you send will override the existing data, even when a value is empty.

We support the following data fields:

Field Type Required Accepted format Note
email string yes*    
external_id string yes*    
gender string no "m" or "f"  
first_name string no    
last_name string no    
phone_number string no    
birthdate string no yyyy-mm-dd  
birthplace string no    
company_name string no      
address string no    
house_number string no    
zip_code string no    
city string no    
country string no    
active boolean no   default: true
job_title string no     
department_name string no    
business_unit string no  
cost_center string no    
cost_center_name string no  
approvers array no    
— email string yes    
— label string yes    
— can_approve boolean no         default: true
tags array no    
employment_start_date date no yyyy-mm-dd
employment_end_date date no yyyy-mm-dd

Identifier

*When updating an existing user, you can use either email or external_id as the identifier. If you include both, precedence will be giving to external_id.

Responses

When you POST your data to our API we run some validations on our end and will only process the conversion when they pass. When they don't, we let you know. As such, there are a couple of possible responses:

  1. 201 Created
  2. When the user has been created successfully. It will return the ID of the user as a response. You can save this id as a reference to how we saved the booking.
  3. 400 Bad Request
  4. We were not able to process this user, the response will contain relevant validation errors.

Multiple sites

What if you need to update user data for multiple sites (for example, if you are a Go customer with sites for multiple countries)?

  • You will receive one API key per site
  • For each user: you should send a POST request for each site to which this user should have access.

Once you have a role with suitable admin rights, you can download an XLS file with an overview of all users. This helps to double-check if importing occurred as expected.

Further details about specific fields

Field: "approvers"

Background information: read more about the "manager approval" feature here.

Possible situations to consider:

  • Approver does not exist yet: when adding approvers to a user, it's important that the approver has an existing, active user account. If you try to add an approver that does not exist, you will get validation errors.

Field: Approvers -Label

For each approver a label can be set. We offer three options:

Manager: This is the direct manager of the employee. The manager can see bookings, compliance status (when Certified is also active), remaining budgets (when these are active) and approve the booking for all their managees.

Non-approving manager: This is a secondary 'manager' of the employee, but can be used for other users as well. The non approving manager can see bookings, compliance status (when Certified is also active) and remaining budgets (when these are active), but can not approve the booking for all their managees..

Higher manager: This is the manager's manager. This higher manager can see bookings, compliance status (when Certified is also active), remaining budgets (when these are active) and approve bookings over a certain price for all their managees.

Field: "tags"

Background: this field is only relevant when your organisation uses the "learning tracks" feature. Based on these tags, any learning tracks with matching tags will be assigned automatically to the user.

Instructions: this field should be an array of strings, separated by comma's. Special characters (including spaces) are allowed. Any uppercase letters will be downcased in our application.

Examples: ["Marketer", "Netherlands", "department-1"]

De-activing users

Should an account be de-activated, for example if an employee has left your organisation? There are two relevant fields:

  • active: when you set this to "false", the account for this user is no longer accessible.
  • employee_end_date: with this field, you can specify the exact date that an employee leaves your organisation. Note: when there is a date specified, it does not mean that the account becomes inaccessible on that date. However, this field is used by our application to automatically remove personal information in a time-frame agreed upon between Springest and your organisation.

Development tips

XLS report for double-checking:

Once you have a role with suitable admin rights, you can download an XLS file with an overview of all users. This helps to double-check if importing occurred as expected.

GET

Endpoint: /users.json?api_key=YOUR_PRIVATE_API_KEY

These fields are present in the output:

Field Type Note
id string  
external_id string  
user_email string  
active string  
learning_track_status string Possible output values: "not_compliant", "expiring_soon", "uncompleted", "completed", "no_tracks_assigned"
Heeft dit je vraag beantwoord? Bedankt voor je feedback. Als je nog vragen hebt: stel ze gerust hieronder. Sorry, je feedback kon niet worden verstuurd. Probeer het later nog eens.

Nog steeds hulp nodig? Neem contact met ons op Neem contact met ons op