Leapsome SCIM API

openapi: 3.0.1
info:
  version: 1.1.3
  title: Leapsome SCIM API
  contact:
    name: Support
    url: https://leapsome.zendesk.com
  description: 'The SCIM API lets you manage users in your organization. You can then automate the provisioning of product
    licenses for these users, and they can use your companys Single Sign-On solution through an Identity Provider.


    If your company uses Active Directory, OneLogin, Okta or any other identity provider supporting the SCIM protocol, you
    can automatically provision users, groups and reporting lines to Leapsome. New employees will automatically be added to
    Leapsome, and leaving employees will automatically be off-boarded.


    Usage is restricted to a maximum of 30 requests per second when making requests in parallel. If you exceed this limit,
    you will receive a 429 status code.'
servers:
- url: https://api.leapsome.com/scim/v1
tags:
- description: Operations on users belonging to an organization
  name: Users
- description: Operations on groups belonging to an organization
  name: Groups
- description: Operations on schemas
  name: Schemas
paths:
  /Groups:
    get:
      description: Queries multiple group identities in the organization domain. Filtering is available and we return all
        results if none is given.
      operationId: scimGetGroups
      parameters:
      - description: The filter parameter must be a properly formed SCIM filter using the operator "eq" (equals). The filter
          works for the "displayName".
        in: query
        name: filter
        schema:
          type: string
      - schema:
          type: integer
          minimum: 0
          maximum: 1000
        in: query
        name: count
        description: The amount of elements you would like to get returned.
      - schema:
          type: integer
          minimum: 1
        in: query
        name: startIndex
        description: The offset (starts from 1, not 0) used to lookup elements. If you need to paginate, your next startIndex
          value would be "startIndex + count".
      responses:
        '200':
          description: The request has succeeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupCollection'
        '401':
          description: Client is not sufficiently authorized
        '403':
          description: Invalid token passed
      summary: Get Groups
      tags:
      - Groups
    post:
      description: 'Creates a new organization group and adds it to the user domain.

        Member groups and member users must be in the organization.

        '
      operationId: createGroup
      requestBody:
        description: The details of the group to create
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupDefinition'
      responses:
        '201':
          description: The group has been created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '400':
          description: 'Possible reasons are:

            - The displayName field is not set

            - The displayName field is malformed

            '
        '401':
          description: Client is not sufficiently authorized
        '403':
          description: Invalid token passed
        '409':
          description: The displayName is already in use within the organization
      summary: Create Group
      tags:
      - Groups
  /Groups/{groupId}:
    get:
      description: Queries group details in the organization domain. If the provided id does not match a leapsome group's
        id in your organization, we try if we find a group with an externalId like that as fallback.
      operationId: getGroup
      parameters:
      - $ref: '#/components/parameters/groupId'
      responses:
        '200':
          description: Return the group's details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '400':
          description: No groupId provided
        '401':
          description: Client is not sufficiently authorized or group does not exist in organization
        '403':
          description: Invalid token passed
        '404':
          description: Not Found
      summary: Get Group
      tags:
      - Groups
    patch:
      description: 'Updates one or more values of an existing group without sending the full definition. For members you need
        to send the complete list of all members. Member groups and member users must be in the organization.

        '
      operationId: updateGroup
      parameters:
      - $ref: '#/components/parameters/groupId'
      requestBody:
        description: The group data to update. It is allowed to update one or more values of the group definition
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                displayName:
                  type: string
                  description: The name of the group
                externalId:
                  type: string
                  description: The id of the group in an external system
                replaceMembers:
                  type: boolean
                  default: false
                  description: By default, only new members are added. If this value is set to true, all existing team members
                    will be REMOVED from the group and only the newly provided members are added again.
                members:
                  type: array
                  items:
                    $ref: '#/components/schemas/Member'
      responses:
        '200':
          description: The group has been updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '400':
          description: 'Possible reasons are:

            - The displayName field is not set

            - The displayName field is malformed

            - The displayName field exceeds 128 characters

            - The members array exceeds 100 elements

            - No groupId provided'
        '401':
          description: Client is not sufficiently authorized or group does not exist in organization
        '403':
          description: Invalid token passed
        '409':
          description: The displayName is already in use within the organization
      summary: Update Group
      tags:
      - Groups
  /ServiceProviderConfig:
    get:
      description: 'Queries service provider configurations.

        The service provider configurations are defined in SCIM Core Schema (http://www.simplecloud.info/specs/draft-scim-core-schema-01.html#anchor6).

        This call returns a description, a documentationURL, name, and specURL.

        '
      operationId: getServiceProviderConfig
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceProviderConfig'
        '403':
          description: Invalid token passed
      summary: Get Service Provider Configurations
      tags:
      - Schemas
  /Users:
    get:
      description: Queries multiple user identities in the organization domain. Filtering is available and we return a maximum
        of 5000 users if no smaller value is provided.
      operationId: getUsers
      parameters:
      - example: userName eq Smith
        in: query
        name: filter
        schema:
          type: string
          example: externalId eq 123
        description: The filter parameter must be a properly formed SCIM filter using the operator "eq" (equals). We support
          a "userName" filter only.
      - schema:
          type: integer
          minimum: 0
          maximum: 5000
        in: query
        name: count
        description: The amount of elements you would like to get returned.
      - schema:
          type: integer
          minimum: 1
        in: query
        name: startIndex
        description: The offset (starts from 1, not 0) used to lookup elements. If you need to paginate, your next startIndex
          value would be "startIndex + count".
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserCollection'
        '401':
          description: Client is not sufficiently authorized
        '403':
          description: Invalid token passed
      summary: Get Users
      tags:
      - Users
    post:
      description: 'Creates a new organization user and adds them to the user domain. The user email domain must match an
        existing organization email domain.


        Note: All user need to get created before you start assigning managers or groups using the other PATCH and PUT endpoints.'
      operationId: createUsers
      requestBody:
        description: The details of the user to create
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userName:
                  type: string
                  format: email
                  description: A user's email
                name:
                  type: object
                  properties:
                    givenName:
                      type: string
                      example: Jane
                    familyName:
                      type: string
                      example: Doe
                displayName:
                  type: string
                  example: Jane von Doe
                title:
                  type: string
                  description: A user's job title
                  example: Software Engineer
                photos:
                  type: array
                  items:
                    type: object
                    maxProperties: 1
                    properties:
                      value:
                        type: string
                        format: uri
                        description: The uri to the user's profile picture
                        example: https://eu.ui-avatars.com/api/?name=Jane+Doe
                externalId:
                  type: string
                  description: A user's id within an external system
                  example: id::1234
              required:
              - userName
      responses:
        '201':
          description: The user has been created.
          content:
            application/json:
              schema:
                type: object
                description: Returned object for a newly created user. Empty object {} if the user already exists.
                properties:
                  id:
                    type: string
                    description: A user's id generated by Leapsome
                  userName:
                    type: string
                    description: A user's email
                  name:
                    type: object
                    properties:
                      givenName:
                        type: string
                      familyName:
                        type: string
                  displayName:
                    type: string
                  title:
                    type: string
                    description: A user's job title
                  photos:
                    type: array
                    items:
                      type: object
                      maxProperties: 1
                      properties:
                        value:
                          type: string
                          description: The uri to the user's profile picture
                          format: uri
                  externalId:
                    type: string
                    description: A user's id within an external system
                  groups:
                    type: array
                    maxItems: 0
                    items: {}
                  meta:
                    type: object
                    properties:
                      created:
                        type: number
                        description: Timestamp of the creation
                      location:
                        type: string
                        description: The URI path to get the user details from the API
                        format: uri
        '400':
          description: 'One of the following requirements is not met:

            - The userName field is required.

            - The userName field must be non-empty.

            '
        '401':
          description: Client is not sufficiently authorized.
        '403':
          description: Invalid token passed
        '409':
          description: Username is already in use
      summary: Create User
      tags:
      - Users
  /Users/{userId}:
    get:
      description: Queries a single user identity in the organization domain. If the provided id does not match a leapsome
        user's id in your organization, we try if we find a user with an externalId like that as fallback.
      operationId: getUser
      parameters:
      - $ref: '#/components/parameters/userId'
      responses:
        '200':
          description: A user was found and is returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: No userId provided
        '401':
          description: Client is not sufficiently authorized
        '403':
          description: Invalid token passed
        '404':
          description: User not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  schemas:
                    type: array
                    items:
                      type: string
                  detail:
                    type: string
                    example: Resource not found
                  status:
                    type: string
                    example: '404'
      summary: Get User
      tags:
      - Users
    patch:
      description: Changes a limited set (or all if you choose) of the user's data. The updated user email domain must be
        an existing organization email domain.
      operationId: updateUser
      parameters:
      - $ref: '#/components/parameters/userId'
      requestBody:
        description: The new user data
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserDefinition'
      responses:
        '200':
          description: The user has been updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: 'One of the following requirements is not met:

            - The userName field is required.

            - The userName field must be non-empty.

            - No userId provided

            '
        '401':
          description: Client is not sufficiently authorized
        '403':
          description: Invalid token passed
        '404':
          description: User not found
        '409':
          description: Email address conflict
      summary: Update User
      tags:
      - Users
    put:
      description: 'Changes an existing user''s data. The request must include the full user definition (to modify one or
        more values without sending the full definition, use the `PATCH` request).



        The replaced user email domain must be an existing organization email domain.

        '
      operationId: replaceUser
      parameters:
      - $ref: '#/components/parameters/userId'
      requestBody:
        description: The new user data
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserDefinition'
      responses:
        '200':
          description: The user has been replaced.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: 'One of the following requirements is not met:

            - The userName field is required.

            - The userName field must be non-empty.

            - No userId provided'
        '401':
          description: Client is not sufficiently authorized
        '403':
          description: Invalid token passed
        '404':
          description: User not found
        '409':
          description: Email address conflict
      summary: Replace User
      tags:
      - Users
components:
  securitySchemes:
    SCIM-Token:
      type: http
      scheme: bearer
      description: 'The SCIM-Authentication-Token token you generated within the Leapsome admin area (Section: HRIS integrations
        -> SCIM)'
  parameters:
    groupId:
      description: The key of the group to query. The group must be in the organization domain
      in: path
      name: groupId
      required: true
      schema:
        type: string
    userId:
      description: The key of the user to query. The user must be in the organization domain
      in: path
      name: userId
      schema:
        type: string
      required: true
  schemas:
    AuthenticationSchemes:
      description: Specifies supported Authentication Scheme properties
      properties:
        description:
          description: The description of the Authentication Scheme
          type: string
        documentationUrl:
          description: A HTTP addressable URL pointing to the Authentication Scheme's usage documentation
          type: string
        name:
          description: The common authentication scheme name, e.g. HTTP Basic
          type: string
        specUrl:
          description: A HTTP addressable URL pointing to the Authentication Scheme's specification
          type: string
      required:
      - name
      - description
      - specUrl
      - documentationUrl
    Bulk:
      description: Specifies BULK configuration options
      properties:
        supported:
          description: Specifies whether the operation is supported
          type: boolean
      required:
      - supported
    ChangePassword:
      description: Specifies Change Password configuration options
      properties:
        supported:
          description: Specifies whether the operation is supported
          type: boolean
      required:
      - supported
    Etag:
      description: Specifies Etag configuration options
      properties:
        supported:
          description: Specifies whether the operation is supported
          type: boolean
      required:
      - supported
    Filter:
      description: Specifies FILTER options
      properties:
        supported:
          description: Specifies whether the operation is supported
          type: boolean
      required:
      - supported
    Group:
      description: Describes a group belonging to an organization
      type: object
      properties:
        id:
          description: The group's unique id
          type: string
        displayName:
          description: The group's display name
          type: string
        members:
          type: array
          description: An array of members
          maxItems: 0
          items:
            $ref: '#/components/schemas/Member'
        meta:
          $ref: '#/components/schemas/GroupMetadata'
        schemas:
          type: array
          items:
            type: string
        externalId:
          type: string
          description: A groups id in an external system
      required:
      - id
      - displayName
    GroupCollection:
      description: Class describing a collection of groups
      type: object
      properties:
        Resources:
          description: An array of groups
          type: array
          items:
            $ref: '#/components/schemas/Group'
        totalResults:
          description: The number of groups in the collection
          format: int64
          type: integer
        itemsPerPage:
          type: integer
        startIndex:
          type: integer
        schemas:
          type: array
          items:
            type: string
    GroupDefinition:
      description: Describes the group to create
      type: object
      properties:
        displayName:
          description: The group's display name
          type: string
        externalId:
          type: string
          description: The id of the group in an external system
      required:
      - displayName
    GroupMetadata:
      description: Group metadata
      type: object
      properties:
        created:
          description: The date and time the group was created
          format: date-time
          type: string
        location:
          description: A URI to get the group details through this API
          type: string
        lastModified:
          type: string
          format: date-time
          description: Last modification date & time
        version:
          type: string
    Member:
      description: A member of a group. This can be a group or an user
      type: object
      properties:
        value:
          description: The Leapsome ID of a user
          type: string
    Patch:
      description: Specifies PATCH configuration options
      properties:
        supported:
          description: Specifies whether the operation is supported
          type: boolean
      required:
      - supported
    ResourceSchema:
      description: Describes the attributes and metadata constituting a resource such as a user.
      properties:
        attributes:
          description: The resource's attributes
          items:
            $ref: '#/components/schemas/SchemaAttribute'
          type: array
        description:
          description: The resource's description
          type: string
        endpoint:
          description: The resource's HTTP addressable endpoint relative to the base URL, e.g. /Users.
          type: string
        id:
          description: The resource's id, e.g. urn:scim:schemas:core:1.0:User
          type: string
        name:
          description: The resource's name, e.g. "User"
          type: string
        schema:
          description: The resource's associated schema, e.g. urn:scim:schemas:core:1.0
          type: string
      required:
      - id
      - name
      - description
      - schema
      - endpoint
      - attributes
    SchemaAttribute:
      description: Describes a resource attribute
      properties:
        caseExact:
          description: Indicates whether the attribute is case sensitive
          type: boolean
        description:
          description: The attribute's description
          type: string
        multiValued:
          description: Indicates whether the attribute can have multiple values
          type: boolean
        name:
          description: The attribute's name
          type: string
        readOnly:
          description: Indicates whether the attribute is mutable
          type: boolean
        required:
          description: Indicates whether the attribute is required
          type: boolean
        schema:
          description: The attribute's associated scheme, e.g. urn:scim:schemas:core:1.0
          type: string
        subAttributes:
          description: The attribute's potential sub-attributes
          items:
            $ref: '#/components/schemas/SchemaSubAttribute'
          type: array
        type:
          description: The attribute's data type, e.g. String
          type: string
      required:
      - name
      - type
      - multiValued
      - description
      - schema
      - readOnly
      - required
      - caseExact
    SchemaSubAttribute:
      description: Describes the sub-attribute of a resource attribute
      properties:
        caseExact:
          description: Indicates whether the attribute is case sensitive
          type: boolean
        description:
          description: The attribute's description
          type: string
        name:
          description: The attribute's name
          type: string
        readOnly:
          description: Indicates whether the attribute is mutable
          type: boolean
        required:
          description: Indicates whether the attribute is required
          type: boolean
        type:
          description: The attribute's data type, e.g. String
          type: string
      required:
      - name
      - type
      - description
      - readOnly
      - required
      - caseExact
    ServiceProviderConfig:
      description: Represents the Service Provider's configuration
      properties:
        authenticationSchemes:
          $ref: '#/components/schemas/AuthenticationSchemes'
        bulk:
          $ref: '#/components/schemas/Bulk'
        changePassword:
          $ref: '#/components/schemas/ChangePassword'
        documentationUrl:
          description: An HTTP addressable URL pointing to the Service Provider's help documentation
          type: string
        etag:
          $ref: '#/components/schemas/Etag'
        filter:
          $ref: '#/components/schemas/Filter'
        patch:
          $ref: '#/components/schemas/Patch'
        sort:
          $ref: '#/components/schemas/Sort'
      required:
      - documentationUrl
      - patch
      - bulk
      - filter
      - changePassword
      - sort
      - etag
      - authenticationSchemes
    Sort:
      description: Specifies Sort configuration options
      properties:
        supported:
          description: Specifies whether the operation is supported
          type: boolean
      required:
      - supported
    User:
      description: Describes a user belonging to an organization
      type: object
      properties:
        id:
          description: A user's unique id (generated by Leapsome)
          type: string
        externalId:
          description: A user's ID within an external system
          type: string
          nullable: true
        title:
          description: A user's job title
          default: Colleague
          type: string
        photos:
          description: ''
          type: array
          items:
            type: object
            properties:
              value:
                type: string
                format: uri
                description: A URI to the avatar of the user
              type:
                type: string
                example: photo
                description: Always set to "photo"
        meta:
          $ref: '#/components/schemas/UserMetadata'
        name:
          $ref: '#/components/schemas/UserFullName'
        displayName:
          description: A user's full displayed name
          type: string
        userName:
          description: A user's username, usually their email address
          type: string
        urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:
          type: object
          properties:
            manager:
              $ref: '#/components/schemas/UserManager'
            additionalManagers:
              type: array
              items:
                $ref: '#/components/schemas/UserManager'
            attachments:
              description: All attachments to a user's profile
              type: array
              items:
                type: object
                properties:
                  fileName:
                    type: string
                    description: Name of the file
                    example: Performance-Review-2022.pdf
                  access:
                    type: array
                    description: All roles that have access
                    items:
                      type: string
                      description: Role
                      example: MANAGER
            department:
              type: string
              description: The team name of the user's department
            costCenter:
              type: string
              description: The team name of the user's cost center
            division:
              type: string
            level:
              description: Current level of the employee as a string.
              type: string
              example: Junior Engineer
            startDate:
              description: Employment start Date as a string in ISO-8601 format (YYYY-MM-DD).
              type: string
              example: '2011-03-25'
            endDate:
              description: Employment end Date as a string in ISO-8601 format (YYYY-MM-DD).
              type: string
              example: '2022-02-25'
            birthday:
              description: Birthday of the employee (used for data segmentation) as a string in ISO-8601 format (YYYY-MM-DD).
              type: string
              example: '1985-07-20'
            6140868326541a4da586db0b:
              description: Value of a given custom attribute identified via its ID. Get the custom attribute ID from the Users
                & Teams tab.
              type: string
              example: Salary Class B
            6140868326541a4da586db0c:
              description: Value of a given custom attribute identified via its ID. Get the custom attribute ID from the Users
                & Teams tab.
              type: string
              example: Freelancer
            gender:
              description: Gender of the employee as a string(male, female, diverse)
              type: string
              example: female
            employmentType:
              description: Employment type of the user as a string(internal, external)
              type: string
              example: internal
            location:
              description: Location of the employee as a string.
              type: string
              example: Berlin
        active:
          description: Indicates if the user is activated in Leapsome
          type: boolean
        emails:
          description: User's email
          type: array
          items:
            type: object
            properties:
              primary:
                type: boolean
                description: Always true
                example: true
              type:
                type: string
                description: Always set to "work"
                example: work
              value:
                type: string
                description: A user's email
        groups:
          description: Represent teams in Leapsome
          type: array
          items:
            type: object
            properties:
              value:
                type: string
                description: A teamId
                example: 5ecba01fb567a5d046582027
        manager:
          description: ''
          type: object
          properties:
            value:
              type: string
              description: A Leapsome userId of the manager
              example: 5ecba01fb567a5d046582027
        schemas:
          type: array
          items:
            type: string
      required:
      - id
      - userName
    UserCollection:
      description: Class describing a collection of users
      type: object
      title: UserCollection
      properties:
        Resources:
          description: The list of users
          type: array
          items:
            $ref: '#/components/schemas/User'
        totalResults:
          description: The number of users in the collection
          format: int64
          type: integer
        itemsPerPage:
          type: integer
        startIndex:
          type: integer
        schemas:
          type: array
          items:
            type: string
    UserDefinition:
      description: Describes a new user
      type: object
      x-examples: {}
      properties:
        externalId:
          description: User's ID in external system
          type: string
        title:
          description: User's job title
          default: Colleague
          type: string
        photos:
          description: Array of profile picture URL's. We take the first one as user avatar.
          type: array
          items:
            type: object
            properties:
              value:
                type: string
                format: uri
                description: Needs to be a complete and valid url.


# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/leapsome/refs/heads/main/openapi/leapsome-scim-api-openapi.yml