Users API

1. Overview

The Users API allows you to create, retrieve, list, update, and deactivate users in SpeakUp via the SCIM 2.0 protocol. It is designed for use by enterprise identity providers (IdPs) such as Microsoft Entra ID, Okta, and OneLogin to automate user lifecycle management.

Base Endpoint: {API_BASE_URL}/scim/v2/Users

---

2. Before You Begin

Review the following requirements and behavioral notes before configuring provisioning in your identity provider. Understanding these constraints upfront prevents common provisioning failures.

2.1 Supported Provisioning Features 

Three attributes are mandatory for every user creation request. Your identity provider must be configured to send all three.

2.3 Key Behavioral Constraints

Before provisioning users at scale, be aware of how SpeakUp handles data that your IdP may send in different formats.

One identity per user. SpeakUp enforces a single email address and a single phone number per user account. If your IdP sends arrays with multiple entries, SpeakUp applies the priority rules described in sections 2.5 and 2.6 to determine which value to store.

userName is the unique key. Attempting to create a user with a userName that already exists returns 409 Conflict.

User deletion is not supported. SpeakUp does not support permanent deletion of users via the SCIM API. A DELETErequest will be accepted but the user will be deactivated rather than removed. For all offboarding scenarios, set active: false via a PATCH request. This preserves the account for audit and historical data purposes and allows reactivation if needed.

externalId is sourced from your identity provider. SpeakUp stores the externalId value as received from the provisioning request and uses it to correlate accounts with your external identity provider. It is not used as a lookup key internally — SpeakUp identifies users by its own system-generated id returned at creation time.

2.4 Name Resolution Priority

SpeakUp stores a single name field internally. When a provisioning request includes multiple name-related attributes, SpeakUp resolves the display name using the following priority order:

1. displayName (highest priority — always send this)

2. name.formatted

3. name.givenName + name.familyName (concatenated)

Most identity providers send displayName by default. If your IdP attribute mapping omits displayName, verify that name.formatted or the given/family name combination is present, or the user may be created with a blank display name.

2.5 Email Resolution Priority

When the provisioning request includes both userName and an emails array, SpeakUp determines the stored email as follows:

1. userName (highest priority)

2. emails[].value where primary: true

3. emails[0].value

Because userName takes precedence, ensure your IdP maps the user's primary email to userName. Sending a different address in the emails array does not override the userName value.

2.6 Phone Number Resolution Priority

When multiple phone numbers are provided:

1. phoneNumbers[].value where primary: true

2. phoneNumbers[0].value

If no phone number is included, SpeakUp returns an empty array [] in API responses.

---

3. Authentication

All SCIM API requests must include a bearer token in the Authorization header. Refer to the SpeakUp SCIM Overview for token generation instructions.

---

4. Response Structure

4.1 Core User Attributes

4.2 Enterprise Extension Attributes

To provision organizational attributes such as department or manager, include the enterprise extension schema (urn:ietf:params:scim:schemas:extension:enterprise:2.0:User) in the schemas array.

---

5. Create a User

Method: POST
Endpoint: /scim/v2/Users

5.1 Minimal Request

 

5.2 Request with Name and Email

 

5.3 Request with Enterprise Extension

 

5.4 Response — 201 Created

 

5.5 Error Responses

400 Bad Request — Missing or invalid required fields:

409 Conflict — A user with the same userName already exists:

---

6. Retrieve a User

Method: GET
Endpoint: /scim/v2/Users/{id}

6.1 Query Parameters

6.2 Request

 

6.3 Request (with excludedAttributes)

 

6.4 Response — 200 OK

 

6.5 Error — 404 Not Found

---

7. List Users

Method: GET
Endpoint: /scim/v2/Users

7.1 Query Parameters

7.2 Supported Filter Expressions

All users (default pagination):

 

With pagination 

 

With filter: 

---

8. Update a User (Full Replacement — PUT)

Use PUT to fully replace a user's attributes. Attributes omitted from the request body may be cleared per SCIM semantics. Use PATCH if you only want to update specific fields.

Method: PUT
Endpoint: /scim/v2/Users/{id}

8.1 Request

 

8.2 Response — 200 OK

Returns the full updated user in SCIM format, including updated meta.lastModified.

8.3 Error Responses

---

9. Update a User (Partial Update — PATCH)

Use PATCH to update one or more attributes without affecting others. This is the recommended method for lifecycle operations such as deactivation, reactivation, and attribute updates.

Method: PATCH
Endpoint: /scim/v2/Users/{id}

9.1 Update a Single Attribute 

 

9.2 Update Multiple Attributes

 

9.3 Deactivate a User

 

9.4 Response — 200 OK

Returns the full user in SCIM format with updated attributes and meta.lastModified.

---

10. Status Code Reference

11. Attribute Mapping Reference

11.1 Core Schema (urn:ietf:params:scim:schemas:core:2.0:User)

11.2 Enterprise Extension (urn:ietf:params:scim:schemas:extension:enterprise:2.0:User)

---