Skip to content

Guides

Read people and teams with SCIM 2.0

On this page

Bizisy runs a read-only SCIM 2.0 service (RFC 7643, RFC 7644) so an identity provider can read the company's people and teams straight from HR. Okta does this with a SCIM app set to import users ("Import New Users and Profile Updates").

Connect an identity provider#

  1. In Bizisy, an owner or admin opens Integrations → SCIM and creates a token. It is shown once. Bizisy keeps only a hash, and you can revoke it at any time.
  2. In the identity provider, set:
    • Base URL: https://api.bizisy.com/scim/v2
    • Authentication: HTTP header, Authorization: Bearer <token>
    • Unique identifier: userName (the work email)
  3. Run an import. People and teams change in Bizisy, so the identity provider only reads.

Microsoft Entra does not read SCIM servers for HR data (its inbound provisioning is push only). Use directory sync for Entra and Google Workspace.

What it returns#

PathAnswer
GET /ServiceProviderConfigFiltering on (up to 200 results), patch, bulk, sort and ETags off, Bearer authentication.
GET /ResourceTypes, GET /SchemasUser (with the enterprise extension) and Group.
GET /Users, GET /Users/{id}People.
GET /Groups, GET /Groups/{id}Teams, with the people in them today.
POST, PUT, PATCH, DELETE501: the service is read only.

Who is listed:

  • Everyone who works at the company today.
  • People starting within 14 days, with active: false until their first day.
  • People who left in the last 90 days, with active: false.

What each user carries:

  • id and externalId: Bizisy's id of the person.
  • userName and emails: the work email.
  • name: the legal given and family name.
  • displayName: the name the person goes by.
  • title: today's job title.
  • active: whether they work here today.
  • The enterprise extension's department (today's team) and manager.

Nothing private or about pay is ever included, and no change before the day it takes effect.

HTTP
GET /scim/v2/Users?filter=userName%20eq%20%22bea%40acme.pt%22 HTTP/1.1
Host: api.bizisy.com
Authorization: Bearer bzscim_…
JSON
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 1, "startIndex": 1, "itemsPerPage": 1,
  "Resources": [{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User", "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],
    "id": "01j…", "externalId": "01j…", "userName": "bea@acme.pt",
    "name": { "givenName": "Bea", "familyName": "Silva", "formatted": "Bea Silva" },
    "displayName": "Bea Silva", "emails": [{ "value": "bea@acme.pt", "type": "work", "primary": true }],
    "title": "Engineer", "active": true,
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": { "department": "Engineering", "manager": { "value": "01j…", "displayName": "Ana Costa" } },
    "meta": { "resourceType": "User", "created": "…", "lastModified": "…", "location": "https://api.bizisy.com/scim/v2/Users/01j…" }
  }]
}

Filters and paging#

  • Operators: eq ne co sw ew gt ge lt le pr, joined with and (which binds first) and or. Parentheses are not supported.
  • User attributes: userName, externalId, id, displayName, active, title, emails / emails.value, name.givenName, name.familyName, meta.lastModified, meta.created, plus the enterprise department and manager.value.
  • Group attributes: displayName, externalId, id, members.value.
  • Case: text compares ignoring case; ids compare exactly.
  • Unsupported filters answer 400 with scimType: invalidFilter.
  • Paging: startIndex (1-based) and count (default 100, at most 200; 0 returns only the total). attributes and excludedAttributes select top-level attributes.

Limits and errors#

  • Each token may make 300 requests a minute.
  • The service answers only on api.bizisy.com. A token belongs to the company and keeps working until it is revoked.
  • Errors use the SCIM error shape (urn:ietf:params:scim:api:messages:2.0:Error, with status as a string): 401 for a missing or revoked token, 403 when the company's account is paused or closing, 404 for an unknown id.

Something missing or wrong on this page? Write to hello@bizisy.com.

Developer docs