# User Provisioning

Provision (and de-provison) new users for your Firstup Community. Create users from our API manually, or automatically from external HRIS or IDP applications via SCIM servicing.

Once a user has been created using this method, they require the same onboarding steps as if being created in Creator Studio. This includes activating the users, and if necessary sending them an invite to join the community.

When creating new user records, their role is `member` and status is `created` by default. Change `roles` to assign different user roles.
Setting a user's role requires that the acting user have a role the same or less than the role of the user being created.
The role property is also formatted as an array to comply with SCIM protocol though it only accepts a single value. Providing more than one value will result in a 400 response.

Look at [User Role Assigning](/usermanagementapi/user-role-provisioning) for further guidance.

**Before you start**

[Generate a bearer token](/usermanagementapi/user-management-overview#before-you-start).

**Endpoint**

POST /scim/v2/users
Note: A user's role is set to **member** by default. A member role will enable your users access to your community (web or mobile experience). To create users with other supported roles, for example access to Creator Studio (such as **Content Creator**, **Publisher**, etc.) send the role value to the appropriate role type.

## Create Users

When creating users with the API, it is possible to create them using only the `username` attribute. Users then exist in Creator Studio, where you can continue with the onboarding process. Or, you can create users with every user attribute available for a full profile. Then they exist in Studio for you to continue the onboarding process and invite users.

We recommend including these standard user attributes and the required attributes:

| Firstup Attribute | Requirement | Format | SCIM Attribute | Description |
|  --- | --- | --- | --- | --- |
| `universal_identifier` | Required | String | `username` | The user's community login. This is the same for web and mobile experience. |
| `first_name` | Recommended | String | `givenname` | The user's name. This is recommended especially if you're bulk provisioning users. |
| `last_name` | Recommended | String | `familyname` | The user's name. This is recommended especially if you're bulk provisioning users. |
| `emails.value` | Recommended | String | `emails.value` | The user's email address (external to Firstup). This is recommended so the user receives their community invitation. |


This allows the Creator Studio user to continue the onboarding process and invite the created user to join the employee experience. This is what they will see in Creator Studio:

![userprofilecreated.png](/assets/userprofilecreated.8b098d27400dd9984345ce4ea41862be3c56c7f0254086de56b12666891ac749.9c1bb791.png)

A user's role is member and their status is created by default

### User Attributes

User attributes are pieces of information that belong to each member. This information is used for multiple reasons, such as: reporting, audience building, insights and reporting, profile building.

A user can have up to 80 attributes, that consist of X standard and X potential custom.

Refer to [SCIM user attributes](/usermanagementapi/user-scim-attributes) for the full table of SCIM-compliant user attributes.

Refer to [custom user attributes](/usermanagementapi/custom-attributes) for custom Firstup attributes.

### User's names

A look at the different names in Firstup:

| API Name Attribute | Description |
|  --- | --- |
| `userName` | This is more of a backend function and relates to the universal identifier in our API and in Studio. It doesn't show in Employee Experience. Users with the appropriate roles can change this field in Studio, and the API can also change it, but it must be unique and is not recommended. |
| `displayName` | The `displayname` attribute is called the display name in Studio. Its auto-generated by the application and changing this is not advisable. It serves a distinct purpose within Firstup, requires a specific format and inappropriate use may introduce unintended side effects. It's main purpose in the employee experience is the name that appears when users @ comment in the comments section. Users can change this attribute themselves in their Employee Experience profile, but this cannot be changed in Studio. ![displayname.png](/assets/displayname.2bb71a64b5f32e0becfa94e0b1b3c71c901628304abacd6ee3e438f4d91fa4fe.9c1bb791.png) |
| `nickName` | This is the preferred name (and short name) in Studio, and can be changed in Studio, by the user in Employee Experience and using the API. It replaces the user's given name (their first name) in the Employee Experience UI and in Studio. It does not override their given name, it only displays instead of. |
| `name` | This object has the `givenName` and `familyName` attributes. Shown as the First name and Last name in Studio. Users in Employee Experience cannot change this, but the API and Creator Studio users with relevant access can. |


### Manually

Create one or multiple members for your community by making a `post` request.

### Automate

Set up an automated system to continuously sync user data from your HRIS to Firstup. This ensures the HRIS (source of truth) will be properly reflected on the Firstup side. This can offer:

* Complete user management automation
* Offer different options to the manual user provision process
* Bulk user management
* Integration with HRIS


### Creating a User Example


```
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:SocialChorus:1.0:User"
],
"userName": "alex.smith@example.com",
"name": {
"givenName": "Alex",
"familyName": "Smith"
},
"displayName": "Alex Smith",
"nickName": "Al",
"emails": [
{
"value": "alex.smith@example.com",
"primary": true,
"type": "work"
}
],
"phoneNumbers": [
{
"value": "555-123-4567",
"type": "mobile"
},
{
"value": "555-987-6543",
"type": "main"
}
],
"addresses": [
{
"streetAddress": "456 Elm Street",
"locality": "Boston",
"region": "MA",
"postalCode": "02110",
"country": "US"
}
],
"preferredLanguage": "en-US",
"locale": "en-US",
"timezone": "America/New_York",
"roles": [
{
"type": "role",
"value": "member"
}
],
"active": true,
"urn:SocialChorus:1.0:User": {
"birthDate": "1985-06-15T00:00:00.000Z",
"hireDate": "2022-02-01T00:00:00.000Z",
"promotionDate": "2024-03-01T00:00:00.000Z",
"requisitionApprovalDate": "2022-01-15T00:00:00.000Z",
"gender": "Female",
"managerName": "Morgan Taylor",
"workLocation": "New York HQ",
"businessUnit": "Marketing"
}
}
```

## Response Expectations

When creating a user via `POST /scim/v2/Users`, the API returns a structured SCIM-compliant response.

### Success Response – 201 Created

- The user is created and provisioned successfully.
- The response includes the complete SCIM user resource.
- The `Location` header may contain the URI of the newly created user.


**Example Response:**


```
HTTP/1.1 201 Created
Content-Type: application/scim+json

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:SocialChorus:1.0:User"
  ],
  "id": "8675309",
  "userName": "alex.smith@example.com",
  "name": {
    "givenName": "Alex",
    "familyName": "Smith"
  },
  "emails": [
    {
      "value": "alex.smith@example.com",
      "primary": true
    }
  ],
  "active": true,
  "roles": [
    {
      "type": "role",
      "value": "member"
    }
  ],
  "urn:SocialChorus:1.0:User": {
    "hireDate": "2022-02-01T00:00:00.000Z"
  },
  "meta": {
    "resourceType": "User"
  }
}
```

### Error Responses

The API may return one of the following error codes if the request is invalid or unauthorized:

| Status | Meaning | Likely Cause |
|  --- | --- | --- |
| 400 | Bad Request | Malformed JSON, missing required fields such as `userName`, or use of unsupported field values. |
| 401 | Unauthorized | The OAuth token is missing, expired, or invalid. |
| 403 | Forbidden | The caller does not have sufficient permissions to create users (e.g., role mismatch). |
| 422 | Unprocessable Entity | Schema validation failed. Common causes include invalid date formats or supplying more than one role. |


**Example 422 Error Response:**


```
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": 422,
  "detail": [
    {
      "instancePath": "/roles",
      "message": "Only one role may be provided"
    }
  ]
}
```

## Deprovision Users

Deprovision (or archive) a user from your community. This action means the user no longer has access to Firstup.

Get the user's ID by making a `GET` request. Pass this ID to deprovision that specific user. This ID can be:

* `userId` (`federated_identifier` in classic Studio)
* email address
* `externalId`


### Permanently

To completely delete the user permanently from the Firstup platform perform a delete request.

**Before you start**

[Generate a bearer token](/user-management-api/user-management-overview#before-you-start).

**Endpoint**

DELETE /scim/v2/users/{user_id}
### Forget

To completely forget the user and all user details from the Firstup platform, for example GDPR purposes, perform a `POST` request to forget the user. The user must currently exist before making this call, therefore use this call instead of `DELETE` when forgetting a user and their data.

**Before you start**

[Generate a bearer token](/user-management-api/user-management-overview#before-you-start).

**Endpoint**

POST /scim/v2/users/{user_id}/forget
### Deactivate Status

To change the user's status to deactive, but keep their user profile in your community, perform a `PUT` or `PATCH` call to update the user's status. To change their active status:

Change `active` to `false`.

We recommend using the `PATCH` service for this operation, as you are only updating a single field.

**Before you start**

[Generate a bearer token](/user-management-api/user-management-overview#before-you-start).

**Endpoint**

PATCH /scim/v2/users/{user_id}
1. `GET` the user record using `GET /scim/v2/Users/{user_id}` to retrieve the user.
2. Create a replace operation (see example below).
3. Execute the `PATCH` request.


Replace operation request example:


```
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "active",
      "value": "false"
    }
  ]
}
```