Create a user.

post

https://bonus.ly/api/scim20/Users

Creates a new user in the authenticated company. Returns the
created user in SCIM form with Location header pointing at
/Users/{id}.

Returns 409 Conflict with scimType: "uniqueness" if a user
with the same userName (email) already exists in the company.
The conflict response does not echo the conflicting email back to
the IdP.

New users automatically receive a Bonusly welcome email. The
invitation flow used for self-signup is bypassed for
SCIM-provisioned users.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

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

201User created.

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).

409A user with the same userName already exists in the company. Returns scimType: "uniqueness".