All of our customers the ability to use our API regardless of the 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 ensures 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 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 highly recommend getting help from someone from your IT department as they could best understand the information described on 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, then you can share this token with the person helping you do it, because only users granted the role "Administrator" on &frankly are capable of generating API tokens.
Once you have generated the token, you simply need to follow the request parameters.
- API Documentation
- API Endpoint: https://org.api.andfrankly.com/v1/organization
- OpenAPI/Swagger definition
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 only associated with one record.
When using this API, we consider what you send to it 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 associated to that identifiers. For the syncs after that, 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 not longer exist in our records either, therefore it would delete them if they are missing on 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 ensuring all of them are included. After 30 days, the records of the user are deleted to comply with GDPR policies.
- For groups, they are simply archived in our records, which means you can restore them any 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, 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 settings.
- Unique Identifiers cannot be updated via our API: since this is the property we use to base the rest of 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 on &frankly but previous results will not be associated to it.
- If you do 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 update via backend in our records. Please note that we can assist on 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 thirds 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.