# User Managing

Manage and edit existing users.

## Before You Start

Adding, replacing or removing existing users and user groups requires **SCIM patching**. [Look here](/usermanagementapi/scim-patch-operations) for guidance and examples of how this works within our platform before attempting to edit users.

## Identifying Users With User_Id

For user management endpoints that call `/{user_id}`, the `{user_id}` path parameter is flexible and supports multiple forms of identification:

| Identifier Type | Source Field | Description |
|  --- | --- | --- |
| SCIM ID | `id` | Firstup-generated SCIM ID (immutable and unique to each user). |
| SCIM userName | `userName` | The user's login ID; also known as `universal_identifier` in Firstup Studio. Must be unique. |
| Email address | `emails.value` | A primary or secondary email associated with the user. Must be valid and exact. |
| External ID | `externalId` | An optional identifier linked to external systems such as HRIS or IdPs. |


### Matching User ID Priority

The lookup process follows this order:

1. `id`
2. `userName`
3. `email`
4. `externalId`


This means if a match is found using `userName`, the system won't continue to check for email or externalId matches.

## Get Users

Get users to manage and make changes to their profiles, such as new job roles, name changes, phone number changes, etc.

**Before you start**

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

**Endpoint**

GET /scim/v2/users/{user_id}
### Get a List of Users

Return a user record for each user in the program. Implements SCIM 2.0 specification.

Filter the list of users with the SCIM filter expression. The supported operator is 'equals to' `eq.`. Supported fields are:

* `userName`: internally maps to universal ID.
* `role`: either legacy or advanced roles.


Examples:

* `userName` eq "`user123`", "`Joebloggs`" - filter returned user list by exact usernames (if known)
* `role` eq "`publisher`" - filter returned user list to only return users with the publisher role.


**Request examples**

All users and no parameters:


```
`HTTP Method: GET
URL: {{apiBaseUrl}}/scim/v2/Users
Headers: 
  Authorization: Bearer {{bearerToken}}
  Accept: application/json
  Content-Type: application/json`
```

A specified user with the filter:


```
`HTTP Method: GET 
URL: {{apiBaseUrl}}/scim/v2/Users?filter=userName eq "{{userName}}" 
Headers: 
 Authorization: Bearer {{bearerToken}} 
 Accept: application/json 
 Content-Type: application/json`
```

A specified user with one user identifier:

Supported user identifiers (`user_id`): `id`, `userName`, `email`, `externalId`


```
`HTTP Method: GET 
URL: {{apiBaseUrl}}/scim/v2/Users/{{user_id}} 
Headers: 
 Authorization: Bearer {{bearerToken}} 
 Accept: application/json 
 Content-Type: application/json`
```

### Get a Specific User

If you know the `user_id` of a user, add it as a path parameter.

Example:

`GET /v2/scim/users/{user_id}`

`user_id` example is `81237405`

## Updating Users

When updating users, we recommend using a patch request. This allows you to edit specific attributes without affecting the entire user profile.
PUT requests can cause modified data that may lead to data loss.

* **Update User**: Make a `PUT` request to change the entire profile of a user, to update big changes that affect multiple attributes, or to add attributes to existing users. Before making this request, make a `GET` request and copy the exact data into the `PUT` body.
* **Update Single Fields**: Use a `PATCH` request to update/change single attributes to existing users using a replace operation.


**Before you start**

Adding, replacing or removing existing users and user groups requires **SCIM patching**. [Look here](/usermanagementapi/scim-patch-operations) for guidance and examples of how this works within our platform before attempting to edit users.

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

### Update User Profile

To update multiple user attributes and big changes to a user, or to add new attributes to a user, make a `PUT` request.

Utilize PUT endpoints carefully. Modified data models caused by new features or user-defined fields may lead to data loss. Any existing attributes not included in a PUT overwrite as blank.

**Endpoint**

PUT /scim/v2/users/{user_id}
1. `GET` the user record using `GET /scim/v2/Users/{user_id}` to retrieve all current attributes and objects associated with the user.
2. Copy the body into the PUT body request to ensure you've captured the entire user profile.
3. Replace whichever values are required.
4. Execute the `PUT` request.


Any attributes left blank or not passed overwrite any existing attributes.

Example:

Original user record from the GET request:


```
{
  "userName": "janeDoe123",
  "active": true,
  "name": {
    "givenName": "Jane",
    "familyName": "Doe"
  },
  "displayName": "Jane Doe",
  "nickName": "Jane",
  "roles": "member",
  "emails": [
    {
      "value": "janedoe@email.com",
      "primary": true,
      "type": "work"
    }
  ],
  "addresses": [
    {
      "streetAddress": "123 Mission St",
      "locality": "San Francisco",
      "region": "CA",
      "postalCode": "94105",
      "country": "US",
      "primary": false,
      "formatted": "123 Mission St, San Francisco, CA, 94105",
      "type": "work"
    }
  ],
  "title": "Sales Person",
  "photos": [
    {
      "type": "photo",
      "value": "http://an.image/url"
    }
  ],
  "preferredLanguage": "en-US",
  "userType": "Associate",
  "locale": "en-US",
  "timezone": "US/Chicago",
  "urn:SocialChorus:1.0:User": {
    "businessUnit": "Accounts Receivable",
    "gender": "Female",
    "managerName": "Jimmy Dean",
    "workLocation": "Kabukicho",
    "birthDate": "2000-01-01T00:00:00.000Z",
    "hireDate": "2000-01-01T00:00:00.000Z",
    "promotionDate": "2000-01-01T00:00:00.000Z",
    "requisitionApprovalDate": "2000-01-01T00:00:00.000Z",
    "lastAccessedAt": "2000-01-01T00:00:00.000Z",
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "employeeNumber": "abc123",
    "organization": "Firstup",
    "department": "Sales",
    "costCenter": "NY",
    "division": "THCI"
  }
}
```

The user record sent in the PUT request:


```
{
  "userName": "janeDoe123",
  "active": true,
  "name": {
    "givenName": "Jane",
    "familyName": "Doe"
  },
  "displayName": "Jane Doe",
  "nickName": "Jane",
  "roles": "publisher",
  "emails": [
    {
      "value": "janedoe@email.com",
      "primary": true,
      "type": "work"
    }
  ],
  "addresses": [
    {
      "streetAddress": "123 Mission St",
      "locality": "San Francisco",
      "region": "CA",
      "postalCode": "94105",
      "country": "US",
      "primary": false,
      "formatted": "123 Mission St, San Francisco, CA, 94105",
      "type": "work"
    }
  ],
  "title": "Sales Manager",
  "photos": [
    {
      "type": "photo",
      "value": "http://an.image/url"
    }
  ],
  "preferredLanguage": "en-US",
  "userType": "Associate",
  "locale": "en-US",
  "timezone": "US/Chicago",
  "urn:SocialChorus:1.0:User": {
    "businessUnit": "Accounts Receivable",
    "gender": "Female",
    "managerName": "Michael Scott",
    "workLocation": "Chicago",
    "birthDate": "2000-01-01T00:00:00.000Z",
    "hireDate": "2000-01-01T00:00:00.000Z",
    "promotionDate": "2000-01-01T00:00:00.000Z",
    "requisitionApprovalDate": "2000-01-01T00:00:00.000Z",
    "lastAccessedAt": "2000-01-01T00:00:00.000Z",
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "employeeNumber": "abc123",
    "organization": "Firstup",
    "department": "Management",
    "costCenter": "NY",
    "division": "THCI"
  }
}
```

### Add Custom User Attributes

Adding custom user attributes to existing user profiles utilizes a PUT request.

Utilize PUT endpoints carefully. Modified data models caused by new features or user-defined fields may lead to data loss. Any existing attributes not included in a PUT overwrite as blank.

1. `GET` the user record using `GET /scim/v2/Users/{user_id}` to retrieve all current attributes and objects associated with the user.
2. Copy the body into the PUT body request to ensure you've captured the entire user profile.
3. Copy the custom user attributes object from the user schema.
4. Paste this into the PUT body request, then replace each custom attribute with a key and a value.
5. Execute the `PUT` request.


Example custom attribute objects:

This example is the plain text copied from the schema:


```
    "urn:SocialChorus:1.0:User": 
    {
    "customAttributes": [
      {
        "name": "name",
        "value": "value"
      },
      {
        "name": "name",
        "value": "value"
      },
      {
        "name": "name",
        "value": "value"
      }
    ]
    }
```

This example shows that text overwritten with example custom attributes:


```
  "urn:SocialChorus:1.0:User": 
    {
    "customAttributes": [
      {
        "name": "companyCar",
        "value": "Tesla"
      },
      {
        "name": "companyPhone",
        "value": "iPhone12"
      },
      {
        "name": "companyLaptop",
        "value": "mac3"
      }
    ]
    }
```

That custom attribute object added into a user body:


```
{
  "userName": "janeDoe123",
  "active": true,
  "name": {
    "givenName": "Jane",
    "familyName": "Doe"
  },
  "displayName": "Jane Doe",
  "nickName": "Jane",
  "roles": "publisher",
  "emails": [
    {
      "value": "janedoe@email.com",
      "primary": true,
      "type": "work"
    }
  ],
  "addresses": [
    {
      "streetAddress": "123 Mission St",
      "locality": "San Francisco",
      "region": "CA",
      "postalCode": "94105",
      "country": "US",
      "primary": false,
      "formatted": "123 Mission St, San Francisco, CA, 94105",
      "type": "work"
    }
  ],
  "title": "Sales Manager",
  "photos": [
    {
      "type": "photo",
      "value": "http://an.image/url"
    }
  ],
  "preferredLanguage": "en-US",
  "userType": "Associate",
  "locale": "en-US",
  "timezone": "US/Chicago",
  "urn:SocialChorus:1.0:User": {
    "businessUnit": "Accounts Receivable",
    "gender": "Female",
    "managerName": "Michael Scott",
    "workLocation": "Chicago",
    "birthDate": "2000-01-01T00:00:00.000Z",
    "hireDate": "2000-01-01T00:00:00.000Z",
    "promotionDate": "2000-01-01T00:00:00.000Z",
    "requisitionApprovalDate": "2000-01-01T00:00:00.000Z",
    "lastAccessedAt": "2000-01-01T00:00:00.000Z",
    "customAttributes": [
      {
        "name": "companyCar",
        "value": "Tesla"
      },
      {
        "name": "companyPhone",
        "value": "iPhone12"
      },
      {
        "name": "companyLaptop",
        "value": "mac3"
      }
    ]
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "employeeNumber": "abc123",
    "organization": "Firstup",
    "department": "Management",
    "costCenter": "NY",
    "division": "THCI"
  }
}
```

Refer to [Custom Attributes](/usermanagementapi/custom-attributes) for further guidance.

## Update Single User Fields

When updating single user attributes, for example job title change or a phone number change, we recommend using a `PATCH` service.

**Before you start**

Adding, replacing or removing existing users and user groups requires **SCIM patching**. [Look here](/usermanagementapi/scim-patch-operations) for guidance and examples of how this works within our platform before attempting to edit users.

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

**Endpoint**

PATCH /scim/v2/users/{user_id}
### Change User Names

A user has different names associated with their account, so bear this in mind when changing their name.

The best way to change a user's name is to change the `nickName` or `name` attributes. This updates how their name appears in Employee Experience.

This example shows a user's `name` as `givenName` Kenny, `familyName` McGregor. Kenny could also be a `nickName` showing instead of their real `givenName`:

![EEname.png](/assets/eename.514c91f1bc7571aeb402cc3979dcf2296865f7180c9dfec6bb4d3f4349b95ed6.9c1bb791.png)

To change this:

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 for a single attribute:


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

Replace operation request example for an object (in this case the `name` object)


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

A look at what name attributes are available and how changing them affects things:

| 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. |
| `displayName` | The `displayname` attribute is called the display name in Studio. It's 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. |


### Change user's email address

Update a user's email address. This example uses a `PATCH` service to update a single user attribute.

1. `GET` the user record using `GET /scim/v2/Users/{user_id}` to retrieve all current attributes and objects associated with the user.
2. Create an `operations` object to send.
3. Replace the email address the `emails` value.
4. Execute the `PATCH` request.



```
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
    {
      "op": "replace",
      "path": "emails[type eq \"work\"].value",
      "value": "janedoe@email.com"
    }
  ]
}
```