Replace a user (full-resource PUT).

put

https://bonus.ly/api/scim20/Users/{id}

Replaces the user's mutable attributes with the supplied body.
Attributes the IdP omits are not cleared — Bonusly preserves
existing values that the IdP doesn't manage. This matches what
most IdPs (including Microsoft Entra) expect from a SCIM 2.0
target and prevents an IdP-side schema gap from wiping
Bonusly-only fields.

If the payload sets active: false, the user is deactivated
after the attribute replacement is persisted. Activation /
deactivation that violates a Bonusly policy (last admin, aliased
user, integration-managed company) is rejected with 422.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

string

required

Bonusly's internal user ID. Returned as id in every read
response. Stable for the life of the user record.

Body Params

A SCIM 2.0 User resource. Combines RFC 7643 core attributes with
Bonusly's URN extension. Each attribute below documents any
normalization Bonusly applies on write and any constraint on the
accepted value.

schemas

array of strings

required

Always includes the core User URN. When using extension
attributes, also include the Bonusly URN.

schemas*

externalId

string

The IdP's stable identifier for the user (Entra objectId,
Okta id, etc.). Used by Bonusly for cross-IdP matching,
including manager resolution.

userName

string

required

The user's primary email — required, unique per company. The
authoritative lookup key for matching when an IdP creates
users.

active

Whether the user is active. Accepts JSON booleans AND string
booleans (Entra sends strings). State transitions apply
Bonusly's activation policy checks (last admin, aliased user,
integration-managed company); a refused transition returns
422.

name

object

nickName

string

Preferred first name. Shown in the Bonusly UI when set;
otherwise the UI falls back to name.givenName.

title

string

Job title. Stored as a Bonusly custom property
(job_title); custom-property values are lowercased on write.

userType

string

Employment type (e.g., full-time, part-time, contractor).
Stored as a Bonusly custom property (employment_type);
lowercased on write.

timezone

string

IANA timezone identifier (e.g., America/Los_Angeles).
Unrecognized identifiers are silently dropped — Bonusly
never rejects a provisioning request over a bad timezone.

locale

string

Language code (BCP-47 region variants accepted but region is
stripped — en-US is stored as en). Must be one of
Bonusly's supported locales; unsupported codes are silently
dropped.

emails

array of objects

Multi-valued. Bonusly reads ONLY the entry where type = "work".
The value MUST match userName. Personal/home emails are
silently ignored.

emails

addresses

array of objects

Multi-valued. Bonusly reads ONLY the entry where type = "work"
and only its country field. Country is normalized to its
ISO-3166 alpha-2 code ("United States" → US, "France" → FR,
etc.). Unrecognized country names leave the existing value
intact.

addresses

urn:ietf:params:scim:schemas:extension:bonusly:2.0:User

object

Bonusly-specific extension attributes. Every non-core attribute we
accept lives under this URN. IdPs must include the URN in the
schemas array AND nest these fields inside an object keyed by
the URN.

Responses

200User replaced.

400Malformed JSON, unparseable SCIM filter, count above maximum, etc.

401Missing, invalid, expired, or revoked Bearer token; or the token's purpose is not scim; or the token's resource owner no longer exists.

403Token is valid but the resource owner is no longer a company admin (writes only — reads succeed with a non-admin SCIM token).

404The user ID does not exist OR belongs to a different company than the one the SCIM token authenticates. Both cases return 404 — the API never distinguishes "no such record" from "wrong tenant".

422Body parsed but a validation refused (e.g., last-admin deactivation, missing required attribute, invalid email format).