&frankly organization API API Reference

This API endpoint provides means to automatically update users and groups in &frankly, and can be used to e.g. set up an automated synchronization between your HR system and &frankly. When using this API, we consider what you send to it as "master" and i.e. will make sure that the current state in &frankly reflects the state that you send. This is done by considering users and groups that are provided through this API as managed. For managed users and groups, we can restrict manual changes in the application (if desired), and we will also perform corrections to all managed users and groups automatically via updates through this API. This means for example if you send a list of users A,B and C through this API, and in the next update you send users A,b and D, then user B will be renamed to b, C will be removed and user D will be added, and similarly for groups. User E that was created manually/outside of this API will be left alone, as will manually created groups.

The inteded use of this API is to allow companies to send a set of users and groups that should always exist in &frankly (removing users that have left the company, and creating new users that have joined) and maintaining an up to date org-structure - but still allow users to create own groups outside of the structured outside of the org-structure.

It is possible to use this API in three manners:
a) Send a full list of users and org structure that is kept up to date in &frankly,
b) Send only a list of users and org units, allowing an administrator to build the tree based on these units, or
c) Send only users, allowing an administrator to build & maintain their own org structure.

When using this API it is important to take care that any users AND org units that are sent are sent with correct unique identifiers, as it is what is used to base changes on. For example, if a org unit with identifier 0000A and name 'Sales Department' is sent to us and later it is removed because there is a new org unit with identifer 0000B that is named 'Sales Department', we will remove the old org unit in &frankly and create a new one (because it has a new unique identifier), which also means all historic results for the previous org unit will be removed/no longer possible to see.

The OpenAPI/Swagger definition of this API is avalable here.

API Endpoint

https://org.api.andfrankly.com/v1/organization

Contact: help@andfrankly.com

Schemes: https

Version: 0.1

Authentication

api_key

type

apiKey

name

Authorization

header

Paths

Organization

POST /organization

Organization

See Organization object for definition

Request Content-Types: application/json

Request Example

{
  "settings": {
    "validateOnly": true,
    "forceSetLanguage": false,
    "maxUsersCreated": 500,
    "maxUsersUpdated": 500,
    "maxUsersDeleted": 500,
    "maxGroupsCreated": 500,
    "maxGroupsUpdated": 500,
    "maxGroupsDeleted": 500
  },
  "data": {
    "users": [
      {
        "externalId": "E001084",
        "firstName": "John",
        "lastName": "Doe",
        "email": "john.doe@company.co",
        "phone": "+461234567",
        "active": true,
        "timezone": "Europe/Stockholm",
        "language": "sv",
        "accessInfo": {
          "memberOf": [
            "0000897"
          ],
          "adminOf": [
            "0000689"
          ],
          "inheritedAdminOf": [
            "0000689"
          ],
          "interestOf": [
            "0000754"
          ],
          "role": "Manager"
        },
        "externalProperties": {
          "gender": "Male"
        }
      }
    ],
    "groups": [
      {
        "externalId": "0000897",
        "name": "Sales Department",
        "description": "Everyone in Sales",
        "parent": "0000689"
      }
    ]
  }
}

200 OK

Successful operation

400 Bad Request

Invalid token

Response Content-Types: application/json

Schema Definitions

Organization: object

Org object

settings: Settings
data: Data

Example

{
  "settings": {
    "validateOnly": true,
    "forceSetLanguage": false,
    "maxUsersCreated": 500,
    "maxUsersUpdated": 500,
    "maxUsersDeleted": 500,
    "maxGroupsCreated": 500,
    "maxGroupsUpdated": 500,
    "maxGroupsDeleted": 500
  },
  "data": {
    "users": [
      {
        "externalId": "E001084",
        "firstName": "John",
        "lastName": "Doe",
        "email": "john.doe@company.co",
        "phone": "+461234567",
        "active": true,
        "timezone": "Europe/Stockholm",
        "language": "sv",
        "accessInfo": {
          "memberOf": [
            "0000897"
          ],
          "adminOf": [
            "0000689"
          ],
          "inheritedAdminOf": [
            "0000689"
          ],
          "interestOf": [
            "0000754"
          ],
          "role": "Manager"
        },
        "externalProperties": {
          "gender": "Male"
        }
      }
    ],
    "groups": [
      {
        "externalId": "0000897",
        "name": "Sales Department",
        "description": "Everyone in Sales",
        "parent": "0000689"
      }
    ]
  }
}

Settings: object

validateOnly: boolean true: Wether to just validate the input (returning the results of this request, without processing), or to fully process the request and enacting the changes in it.
forceSetLanguage: boolean false: If language is provided on users, it is typically only set on creation of the user - not updated for existing users, since language settings is something users change themselves as a preference. By setting this flag to true, you force setting language even on all existing users, effectively forcing language to be set to what is desired in the integration. Note that this may be confusing for users if set to true, as their preferences will be reset periodically.
maxUsersCreated: integer 200: Maximum number of users to allow creation of in this request. Used as a self-control to ensure that a potentially invalid requests do not create an unexpected number of users. Max is 20 000.
maxUsersUpdated: integer 200: Maximum number of users to allow update of in this request. Used as a self-control to ensure that a potentially invalid requests do not change an unexpected number of users. Max is 20 000.
maxUsersDeleted: integer 200: Maximum number of users to allow deletion of in this request. Used as a self-control to ensure that a potentially invalid requests do not delete an unexpected number of users. Max is 20 000.
maxGroupsCreated: integer 200: Maximum number of groups to allow creation of in this request. Used as a self-control to ensure that a potentially invalid requests do not create an unexpected number of groups. Max is 20 000.
maxGroupsUpdated: integer 200: Maximum number of groups to allow update of in this request. Used as a self-control to ensure that a potentially invalid requests do not change an unexpected number of groups. Max is 20 000.
maxGroupsDeleted: integer 200: Maximum number of groups to allow deletion of in this request. Used as a self-control to ensure that a potentially invalid requests do not delete an unexpected number of groups. Max is 20 000.

Example

{
  "validateOnly": true,
  "forceSetLanguage": false,
  "maxUsersCreated": 500,
  "maxUsersUpdated": 500,
  "maxUsersDeleted": 500,
  "maxGroupsCreated": 500,
  "maxGroupsUpdated": 500,
  "maxGroupsDeleted": 500
}

Data: object

Organizational data, containing users and groups to supply

users: Users
groups: Groups

Example

{
  "users": [
    {
      "externalId": "E001084",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@company.co",
      "phone": "+461234567",
      "active": true,
      "timezone": "Europe/Stockholm",
      "language": "sv",
      "accessInfo": {
        "memberOf": [
          "0000897"
        ],
        "adminOf": [
          "0000689"
        ],
        "inheritedAdminOf": [
          "0000689"
        ],
        "interestOf": [
          "0000754"
        ],
        "role": "Manager"
      },
      "externalProperties": {
        "gender": "Male"
      }
    }
  ],
  "groups": [
    {
      "externalId": "0000897",
      "name": "Sales Department",
      "description": "Everyone in Sales",
      "parent": "0000689"
    }
  ]
}

Users: array

If provided, the list of managed users that should exist in &frankly (any managed user not included should be removed)

User

Example

[
  {
    "externalId": "E001084",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@company.co",
    "phone": "+461234567",
    "active": true,
    "timezone": "Europe/Stockholm",
    "language": "sv",
    "accessInfo": {
      "memberOf": [
        "0000897"
      ],
      "adminOf": [
        "0000689"
      ],
      "inheritedAdminOf": [
        "0000689"
      ],
      "interestOf": [
        "0000754"
      ],
      "role": "Manager"
    },
    "externalProperties": {
      "gender": "Male"
    }
  }
]

User: object

externalId: string: Customer unique identifier for the user. Must be unique across all users and must not change over time.
firstName: string: First/given name of user
lastName: string: Last/family name of user
email: string: Email address of user
phone: string: Phone number of user, should include country prefix e.g. +46xxxx
active: boolean true: Active/inactive state of user. Inactive users (e.g. on leave) still retains an account but cannot login/does not get questions in &frankly
timezone: string: Timezone user is in, so as to notify for questions the correct time - should be valid TZ from e.g. https://en.wikipedia.org/wiki/List_of_tz_database_time_zones, for example 'Europe/Stockholm'. If omitted,the company default timezone will be used.
language: string: Language user prefers to receive questions and/or communication in. Should be a valid ISO-639-1 code (two letters) from e.g. https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes. If omitted, the company default language will be used.
accessInfo: object
memberOf: string[] List of Group externalIds that this user should be member of. If provided, will clear all other memberships of managed groups not set here. If omitted will leave current memberships in managed groups as is. string adminOf: string[] List of Group externalIds that this user should be owner of. If provided, will clear all other ownerships of managed groups not set here. If omitted will leave current ownerships in managed groups as is. string inheritedAdminOf: string[] List of Group externalIds that this user should be administrator of. If provided, will clear all other administrator rights of managed groups not set here. If omitted will leave current administrator in managed groups as is. string interestOf: string[] List of Group externalIds that this user should get read-rights to. If provided, will clear all other read rights of managed groups not set here. If omitted will leave current read rights in managed groups as is. string role: string Administrator, Manager, User User Role that this user should have in &frankly. If omitted will leave user with current role. Note: case sensitive
externalProperties: object: Custom attributes defined for the account, as added on the Account => User management settings page. Below is an example of such an attribute called 'Gender', however any number of attributes for a user can be provided as long as they are defined on the account in settings. If an attribute is provided, the value is set accordingly. If an attribute is omitted then it is left as-is
gender: string Male, Female

Example

{
  "externalId": "E001084",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@company.co",
  "phone": "+461234567",
  "active": true,
  "timezone": "Europe/Stockholm",
  "language": "sv",
  "accessInfo": {
    "memberOf": [
      "0000897"
    ],
    "adminOf": [
      "0000689"
    ],
    "inheritedAdminOf": [
      "0000689"
    ],
    "interestOf": [
      "0000754"
    ],
    "role": "Manager"
  },
  "externalProperties": {
    "gender": "Male"
  }
}

Groups: array

If provied, the list of managed groups that should exist in &frankly (any managed group not included should be removed)

Group

Example

[
  {
    "externalId": "0000897",
    "name": "Sales Department",
    "description": "Everyone in Sales",
    "parent": "0000689"
  }
]

Group: object

externalId: string: Customer chosen unique identifier for the group. Must be unique across all groups and must not change over time.
name: string: Name of group/org. unit
description: string: Description of the group/org.unit
parent: string: externalId of the group/org.unit that this is a child to in an org. structure/hierarchy

Example

{
  "externalId": "0000897",
  "name": "Sales Department",
  "description": "Everyone in Sales",
  "parent": "0000689"
}

Documentation by Spectacle