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. name: $ref: '#/components/schemas/UserFullName' displayName: description: A user's full displayed name type: string userName: description: The user's username, usually their email address' type: string location: description: User's location value type: string manager: description: User ID of user's manager which can be a LeapsomeId, an email or the externalId type: string urn:ietf:params:scim:schemas:extension:enterprise:2.0:User: type: object properties: manager: description: User ID of user's manager which can be a LeapsomeId, an email or the externalId type: string additionalManagers: type: array items: description: User ID of user's additional manager which can be a LeapsomeId, an email or the externalId type: string 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 location: description: Location of the employee as a string. type: string example: Berlin active: type: boolean description: Activate (true) or deactivate (false) a user if provided. If the user has been active before, the account will be active again while it might be in a "invited" or "created" state if the user never accepted an invitation before. required: - userName UserFullName: description: The individual name parts of a user type: object title: UserName properties: familyName: description: A user's surname type: string givenName: description: A user's first name type: string formatted: description: A user's full legal name type: string required: - familyName - givenName UserMetadata: description: User metadata type: object properties: created: description: The date and time the user was created format: date-time type: string location: description: The URL where the user can be accessed type: string version: type: string lastModified: type: string format: date-time required: - created - location - version - lastModified UserManager: description: User's (additional) Manager type: object properties: managerId: type: string description: A Leapsome userId of the (additional) manager displayName: type: string description: The full name of the defined (additional) manager security: - SCIM-Token: []