2.1 - Medewerker gegevens - Automatische medewerker import 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 acces 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    
tags array no    
employment_start_date date no yyyy-mm-dd
employment_end_date date no yyyy-mm-dd

Identifier

*You can use either email or external_id as the identifier. It is required only to include one of these two.

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: "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"]

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