swagger: "2.0"
info:
  description: "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  <i>managed</i>. For <i>managed</i> 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.<br><br>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.<br><br>It is possible to use this API in three manners:<br>a) Send a full list of users and org structure that is kept up to date in &frankly,<br>b) Send only a list of users and org units, allowing an administrator to build the tree based on these units, or <br>c) Send only users, allowing an administrator to build & maintain their own org structure.<br><br>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.<br><br>The OpenAPI/Swagger definition of this API is avalable <a href='../swagger.yml'>here</a>."
  version: "0.1"
  title: "&frankly organization API"
  contact:
    email: "help@andfrankly.com"
host: "org.api.andfrankly.com"
basePath: "/v1/organization"
tags:
- name: "Organization"
schemes:
- "https"
paths:
  /organization:
    post:
      tags:
      - "Organization"
      description: ""
      produces:
      - "application/json"
      consumes:
       - "application/json"
      parameters:
      - name: "body"
        in: "body"
        required: true
        description: "See Organization object for definition"
        schema:
          $ref: "#/definitions/Organization"     
      responses:
        200:
          description: "Successful operation"
        400:
          description: "Invalid token"
securityDefinitions:
  api_key:
    type: "apiKey"
    name: "Authorization"
    in: "header"
definitions:    
  Organization:
    type: "object"
    description: "Org object"
    properties:
      settings:
        $ref: "#/definitions/Settings"
      data:
        $ref: "#/definitions/Data"   
  Settings:
    type: "object"
    properties:     
      validateOnly:
        type: "boolean"
        example: true
        default: true 
        description: "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:
        type: "boolean"
        example: false
        default: false
        description: "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:
        type: "integer"
        example: 500
        default: 200 
        description: "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:
        type: "integer"
        example: 500
        default: 200 
        description: "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:
        type: "integer"
        example: 500
        default: 200 
        description: "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:
        type: "integer"
        example: 500
        default: 200 
        description: "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:
        type: "integer"
        example: 500
        default: 200 
        description: "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:
        type: "integer"
        example: 500
        default: 200 
        description: "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."  
  Data:
    type: "object"
    description: "Organizational data, containing users and groups to supply"  
    properties:
      users:
        $ref: "#/definitions/Users"        
      groups:
        $ref: "#/definitions/Groups"   
  Users:
    type: "array"
    description: "If provided, the list of managed users that should exist in &frankly (any managed user not included should be removed)"          
    items:
      $ref: "#/definitions/User"     
  User:
    type: "object"
    required:
    - externalId
    - firstName
    - lastName
    properties:
      externalId:
        type: "string"
        example: "E001084"       
        description: "Customer unique identifier for the user. Must be unique across all users and must not change over time."
      firstName:
        type: "string"
        example: "John"       
        description: "First/given name of user"        
      lastName:
        type: "string"
        example: "Doe"       
        description: "Last/family name of user"  
      email:
        type: "string"
        example: "john.doe@company.co"       
        description: "Email address of user"          
      phone:
        type: "string"
        example: "+461234567"       
        description: "Phone number of user, should include country prefix e.g. +46xxxx"          
      active:
        type: "boolean"
        example: true
        default: true
        description: "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:
        type: "string"
        example: "Europe/Stockholm"       
        description: "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:
        type: "string"
        example: "sv"       
        description: "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:
        type: "object"
        properties:
          memberOf:
            type: "array"
            description: "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."
            items:
              type: "string"
              example: "0000897"
          adminOf:
            type: "array"
            description: "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."
            items:
              type: "string"    
              example: "0000689"
          inheritedAdminOf:
            type: "array"
            description: "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."
            items:
              type: "string"    
              example: "0000689"              
          interestOf:
            type: "array"
            description: "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."
            items:
              type: "string"    
              example: "0000754"              
          role:
            type: "string"
            enum: [Administrator, Manager, User]
            example: "Manager"
            default: "User"             
            description: "Role that this user should have in &frankly. If omitted will leave user with current role. Note: case sensitive"    
      externalProperties:
        type: "object"    
        description: "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" 
        properties:
          gender:
            type: "string"
            enum: [Male, Female]
            example: "Male"
  Groups:
    type: "array"
    description: "If provied, the list of managed groups that should exist in &frankly (any managed group not included should be removed)"     
    items:
      $ref: "#/definitions/Group"     
  Group:
    type: "object"
    required:
    - externalId
    - name
    properties:
      externalId:
        type: "string"
        example: "0000897"       
        description: "Customer chosen unique identifier for the group. Must be unique across all groups and must not change over time."     
      name:
        type: "string"
        example: "Sales Department"       
        description: "Name of group/org. unit"        
      description:
        type: "string"
        example: "Everyone in Sales"       
        description: "Description of the group/org.unit"  
      parent:
        type: "string"
        example: "0000689"
        description: "externalId of the group/org.unit that this is a child to in an org. structure/hierarchy"