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:

• Microsoft Entra ID (formerly Azure Active Directory)
  • https://learn.microsoft.com/en-us/entra/identity/saas-apps/humbol-provisioning-tutorial

Prerequisites

• Active contract including SCIM API usage with Humbol Inc
  • Pricing
• Provisioning Light Members via SCIM requires the Light Members agreement
• SMS-based notifications for Light Members are a separately billed extension of the Light Members agreement — required if your Light Members are contacted by phone number
• At least one admin user in customer’s Humbol organization
• If you want to assign Humbol users in Entra ID according to your Entra ID groups, it requires MS Entra ID 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 Entra ID which you don’t want to import to Humbol).
  • You can purchase “Microsoft Entra ID P1” license from here (price in 2026 is 5,60€/month): https://admin.microsoft.com/ (Marketplace -> All Products-> Search all product categories-> “Entra” -> Details)
    • Microsoft Entra ID P1 pricing: https://www.microsoft.com/security/business/microsoft-entra-pricing
  • 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:

Admin

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 it’s visible from their profile that they are external to the organization.

Member

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.

Light Member

Light members mainly use the system only via pre-authenticated links to access those interactions where they are participants or feedback givers. Pre-authenticated links are delivered by email or SMS and are person specific and valid only until the discussion has been marked ready. Light members can be team members (but not organizer or supporter) and can participate into actions, but can’t have goals or be action owners. They can also login to Humbol application if they have MS or Google account which corresponds to their email address. Light members do not see any organization level statistics. They don’t see any organization level actions or interactions if they are not part of that team or participate in the specific action or interaction.

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

Microsoft Entra ID

https://entra.microsoft.com/#view/Microsoft_AAD_IAM/StartboardApplicationsMenuBlade/~/AppAppsPreview

Your tenant has a Humbol application for sign-in, calendar access and, unless Light Members are notified by SMS, user provisioning. It appears in the list once someone in your organization has tried to sign in to Humbol, even if your organization’s settings stopped them. A second one, Humbol Service, Humbol’s backend, appears once admin consent is given and needs no action.

Without admin consent, each employee is asked to approve calendar access the first time they book a discussion. An administrator can grant it once for the whole organization:

1. Sign in to the Microsoft Entra admin center above as at least a Cloud Application Administrator.
2. Go to Entra ID › Enterprise apps › All applications and search for Humbol.
3. Open the Humbol application and go to Security › Permissions.
4. Select Grant admin consent and accept the listed permissions.

Google Workspace

https://admin.google.com/u/0/ac/owl/list?tab=apps

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: https://my.humbol.app/login.

Go to organization’s API settings page: https://my.humbol.app/settings#apis

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
• at least one of:
  • emails[type eq ”work”] — one and only one
  • phoneNumbers[type eq ”mobile”] — one and only one, Finnish number in E.164 format (+358…)

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 Entra ID every user must have precisely one role. Light Members (see User classification below) get the lightMember role automatically.

Without automatic team management, running SCIM provisioning does not activate any new Humbol user licences — after provisioning, you can add imported people to Humbol organization and assign them to teams from Humbol: https://my.humbol.app/organization/members/invite.

When automatic team management is enabled for the organization, role assignment and licence activation happen automatically as part of provisioning (subject to available licences), and the manager mapping is used to add each user to teams their manager owns.

User classification

When a user is provisioned, Humbol classifies them based on their email and phone number:

Email	Phone	Classified as
Domain matches the organization’s configured domains	any	Full user
Domain does not match	any	Light Member
None	Valid Finnish number	Light Member
None	None	Rejected

Light Members notified by SMS

Provisioning Light Members who are notified by SMS needs a custom (non-gallery) Entra ID application, named for example “Humbol Provisioning”, instead of the Humbol gallery application: their mobile number has to be mapped, and their email left unmapped so that a company mailbox does not make them full users. Use one application for all users, so that each person’s manager is provisioned along with them.

Mobile numbers must be Finnish, in international format (+358123456789).

Contact Humbol support and we will set up the provisioning together with your IT.

Supported SCIM API features

Supported Resources: Users with a role

Schema and supported attributes

See description of supported attributes: https://my.humbol.app/api/scim/Schemas

/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

Errors

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

Common error responses:

• HTTP 400 — the payload is missing required fields, has neither email nor phone, or refers to an unknown manager.value.
• HTTP 403 — the organization’s contract does not include the requested capability (SCIM, Light Members, or SMS), or the token does not belong to the organization being addressed.
• HTTP 409 — a user with the same identifier already exists in an active state.

Support

Contact: support@humbol.app