Mitarbeiterdaten via API importieren

Gewijzigd op Wo, 18 Okt, 2023 om 12:54 PM

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:

201 Created
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.
400 Bad Request
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

Required parameter: external_id.

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"