All of our customers have the ability to use &frankly’s API, regardless of the subscription-plan that you have acquired with us. With our Organization API, you are able to keep your organizational structure up-to-date by syncing users and groups directly from your own HR system. This will save you time and ensure you are GDPR compliant when using &frankly.
It is possible to use our Organization API in three ways:
- Send a full list of users, groups and org structure that is kept up to date in &frankly.
- Send only a list of users and groups, allowing an administrator to build the tree through our interface in &frankly.
- Send only users, allowing an administrator to build & maintain their groups and organization tree through our interface.
How do I set it up?
Setting up our API is a very straight-forward process if you are familiar with APIs and how they work. If you are not familiar with it, we suggest getting help from someone from your IT department as they could best understand the information described in our API documentation.
First of all, you would need to generate a token for authentication purposes. This can be found under Account -> API Access. If you are not setting up the API by yourself, you can share this token with the person helping you, because only users granted the role "Administrator" in &frankly are capable of generating API tokens.
Once you have generated the token, you simply need to follow the request parameters as described on the links below:
- API Documentation
- API Endpoint: https://org.api.andfrankly.com/v1/organization
- OpenAPI/Swagger definition
Unique identifiers:
When you sync to &frankly, a Unique Identifier will be required to manage the records you send. The Unique Identifiers are IDs generated in your own system that are associated with one record only.
When using this API, we consider what you send to us as the "Master State" and so we will mirror every latest update you send. It is important to make sure that all users AND groups are sent with the correct Unique Identifiers, because it is what our system will use to track all changes. Every time you sync, our system will perform the following actions:
- For existing unique identifiers: Our system will simply update accordingly (names, status, email address, group membership, etc.)
- For new unique identifiers: Our system will create a new record and add the properties that are associated to that identifier. For the following syncs, it will be considered an existing record, so it will simply update as explained above.
- For missing unique identifiers: Our system will interpret that these users or groups should no longer exist in our records either, therefore it would delete them if they are missing in the sync. This is why it is imperative to include ALL the records for groups and users even if no changes are made.
- For users, you can restore them by running the sync again and ensure all of them are included. After 30 days, the records of the user are deleted to comply with GDPR policies.
- Groups are simply archived in our records, which means you can restore them at any point in time by adding them in the next sync.
Is there a test environment to try out the API?
We do not have a demo environment for APIs, however, you can make a validation request in the API. In order to do this, you need to set the value validateOnly to "true" in the parameters of your request.
Important information:
- Unique Identifiers cannot be updated via our API: since this is the property we use to base the rest of the changes. For instance, if a group is deleted in your HRM system and created again, it is likely that your HRM system will assign a new identifier, same applies for users. This means that the old record (and its history) will be deleted from &frankly and a new record (often with the same name) will be created in &frankly, but previous results will not be associated with it.
- If you really need to sync old history to a new record, you need to contact our Support Team and provide them with the old identifier (that you removed from your system) and the new one, so we can update the records via our backend. Please note that we can assist with updating the identifier for any group, however, when it comes to users, we will only update the identifier if both email addresses match, to avoid third parties from accessing someone else's results.
- Users and Groups created manually outside of the API will not be touched in the syncs, this means they will not be updated or removed from &frankly unless they are manually changed through our interface too. You can lock your organizational tree to keep people from manually adding Users or Groups by going to Account -> User Management -> User Management and change the setting to "Locked for editing", please note that Administrator rights are needed to execute this change.