&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
in
header

Paths

POST /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"
          ],
          "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"
          ],
          "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"
        ],
        "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"
      ],
      "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
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"
    ],
    "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"
}