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.

Before you start

Generate a bearer token.

Endpoint

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:

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:

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.

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

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.

Endpoint

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.

Endpoint

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.

Endpoint

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"
    }
  ]
}