one-on-one meeting

SCIM API Documentation

Humbol SCIM (System for Cross-domain Identity Management) API allows for real-time employee provisioning from customer’s identity provider.

SCIM API Version: 2.0

SCIM API has been tested to work with these identity providers:


  • Active contract including SCIM API usage with Humbol Inc
  • At least one admin user in customer’s Humbol organization
  • If you want to assign Humbol users in Azure AD according to your Azure AD groups, it requires Azure AD Premium P1 license for that person who does the integration (so just 1 pc is enough). Otherwise you have to select each person separately or import all (you might have some accounts in AD which you don’t want to import to Humbol).
    • You can purchase “Azure Active Directory Premium P1” license from here (price in 2023 is 5,1€/month): (Marketplace -> Search -> “Azure” -> Details)
    • Or if you have already some more expensive license (for example Microsoft 365 Business Premium or Microsoft 365 E3) for all, it should also cover this.

Application roles

Humbol application contains these organization level roles which can be controlled via SCIM API:


Organization admins can invite and remove users from an organization and create new teams and administer all teams in Humbol. Administrators do not see any details of any interaction or action other than via the normal visibility rules.

External admin

External admins have otherwise same rights as organization admins, but its’s visible from their profile that they are external to the organization.


Members can see the organization structure and all interactions and actions, which have “Organization” visibility and their own teams’ interactions and actions. They can administer those teams which they have a team organizer or team supporter role in.

External member

External members can see only those teams from the organization which they are part of, plus actions and interactions where they have been registered as participants. They can administer those teams which they have a team organizer or team supporter role in. External members do not see any organization level statistics. They don’t see any organization level actions, goals or interactions if they are not part of that team or participate in the specific action, goal or interaction.

SSO: OAuth 2.0

Administration of permissions and assigned users

Azure Portal

Google Workspace

Permissions required by the application

  • User Profile information
    • Read
    • Needed for fetching user’s name and profile picture
    • Used for all users
  • Calendar
    • Read & write
    • Needed for scheduling and creating calendar events
    • Used only by those who book discussions via Humbol
  • Offline access
    • Needed for 2 way integration for calendar so that you can modify meetings in your calendar and it gets also automatically updated to Humbol
    • Used only by those who book discussions via Humbol
    • Kept only active as long there are meetings booked via Humbol

Taking SCIM API into use

As Humbol admin login into your Humbol organization:

Go to organization’s API settings page:

On the page there is visible your organization SCIM API url. Copy it.

Create SCIM API token and copy the value. NOTE! The token value is not saved anywhere on the Humbol service, so if you lose it, you should create a new one and remove old one.

Go to your identity provider and change Humbol applications provisioning settings to automatic and use the scim api url and token you acquired earlier.

Disable group provisioning and do the user field mapping automatically or manually. These SCIM attributes are always required:

  • userName
  • active
  • name.givenName
  • name.familyName
  • emails[type eq ”work”]
    • one and only one

Note roles[primary eq “True”] is not required: if role is not given, it can be administered inside Humbol by admin user. If you do map it in Azure AD every user must have precisely one role.

Just running SCIM provisioning does not activate any new Humbol user licences: after provisioning has been run you can add imported people to Humbol organization and assign them to teams from Humbol:

Supported SCIM API features

Supported Resources: Users with a role

Schema and supported attributes

See description of supported attributes:

/Schemas API

Supported methods: GET

/Users API

Supported methods: POST and GET

Supported filters: “userName eq” and ”emails[type eq “work”].value eq

/Users/<id> API

Supported methods: GET, PATCH and DELETE

Error responses

HTTP error codes are used according to SCIM specification. If error happens there should be a json body telling the reason.