# Replace a user in the program

To update or replace user information, ensure that your request includes a comprehensive set of user attributes.
⚠ Utilize  endpoints carefully. Modified data models caused by new features or user-defined fields may lead to data loss.
For a seamless process, consider the following:
1.  the user record using 🔗 /scim/v2/Users/{user_id} to retrieve all current attributes and objects associated with the user.
2. Modify the values you wish to change within the retrieved user record.
3. Execute the PUT call with the modified user record to ensure no inadvertent data removal from the application.
Alternatively, you can opt for a 🔗 PATCH call to selectively modify specific attributes without affecting others.
📝 Keep in mind that when updating a user's role using oath2_as_a_user, the acting user must have a role that's the same as or higher than both the starting and ending roles of the user being updated.


Endpoint: PUT /scim/v2/Users/{user_id}
Version: v2
Security: oauth2_as_a_server, oauth2_as_a_user

## Path parameters:

  - `user_id` (string, required)
    ID of the user to update

## Request fields (application/json):

  - `userName` (string)
    uniquely identifies a user in the scope of your organization. It can be updated by the client, but must remain unique.

In Firstup Studio it is referred to as .
    Example: "janeDoe123"

  - `active` (boolean)
    Whether the user is active or blocked in the program.
    Example: true

  - `name` (object)
    An object containing multiple parts that make up a user's name.

  - `name.givenName` (string, required)
    User's first name
    Example: "Jane"

  - `name.familyName` (string, required)
    User's last name
    Example: "Doe"

  - `displayName` (string,null)
    Please refrain from using this attribute without prior consultation with our support staff.


  This attribute serves a distinct purpose within the Firstup system, requires a specific format
  and inappropriate use may introduce unintended side effects.

  - `nickName` (string,null)
    The casual way to address the user in real life.
    Example: "Jane"

  - `roles` (any)
    Defines a user's permissions and access privileges within a system or application.

The provided array extends support for Advanced Permissions, while supporting legacy Roles from Classic Studio. It accommodates a list of objects, each detailing the user's role, record permissions (scope), and legacy role if applicable.



To explore available roles, make use of the  request at .


- administrator
- program_manager
- analyst
- publisher
- channel_contributor
- member



For comprehensive insights into roles, scopes, and legacy roles refer to the following Knowledge Base Articles:

- [Roles-Standard](https://support.firstup.io/hc/en-us/articles/6278321908503)
- [Roles-Custom](https://support.firstup.io/hc/en-us/articles/6744088254359)
- [Scopes or Restrictions](https://support.firstup.io/hc/en-us/articles/6278321908503#h_01HBV399TW5WN1ZZABQF845H4E)
- [Legacy Roles](https://howto.socialchorus.com/hc/en-us/articles/115006356588#h_23542235341518566935216)


- Support the original single-string legacy role format [""]
- Legacy roles include "administrator",  "program_manager", "analyst", "publisher", "channel_contributor", or "member".
- GET /scim/v2/users and /scim/v2/users/{user_id} return this field based on a program configuration. Please contact
 if you need to switch the syntax.

Note: Firstup users have a single role and legacy_role but can have multiple scopes applied.

---

> ### Limitation Notice: Scope
> In addition to role and legacy_role the array supports the setting of record restrictions via scope objects. This includes the ability to define Topic, Audience, Template, and Email Aliases Permissions.
>
> 
> Currently the API does not validate the scope data against existing restriction records. While this does not compromise system security, it may result in users experiencing unexpected access limitations.
>
> 
> Users will still be able to access the application, but their access may not align with expectations due to permissions for records that are not valid. It's crucial to recognize that topic, audience, template, and email scopes play a pivotal role in limiting users to only seeing records defined within those specified scopes.
>
> 
> To ensure accurate access and visibility, we recommend using the Bulk Permissions UI. This ensures that restrictions align with the intended access for users, providing a proactive approach to managing and validating restriction data effectively.

---

  - `emails` (array)
    A list of the user's emails.
If a user has no emails this will be an empty list.

  - `emails.value` (string)
    A valid email address
    Example: "janedoe@email.com"

  - `emails.primary` (boolean)
    Indicates if the value is the user's primary email address
    Example: true

  - `emails.type` (string,null)
    An email type. Should be one of "work", "home", "other" or null
    Enum: "work", "home", "other", null

  - `addresses` (array)
    The user's addresses in the program.
A Firstup user has only one address. The user's address will be set to either:
 The first address marked .
Sending anything other than an array (which may be empty) is an error.

  - `addresses.streetAddress` (string,null)
    A street address, e.g., house number and street name.
    Example: "123 Mission St"

  - `addresses.locality` (string,null)
    Address's locality, e.g, in the US, the city.
    Example: "San Francisco"

  - `addresses.region` (string,null)
    Address's region, e.g., in the US, the state.
    Example: "CA"

  - `addresses.postalCode` (string,null)
    Address's postal code, e.g., in the US, the zip code.
    Example: "94105"

  - `addresses.country` (string,null)
    Address's country.
    Example: "US"

  - `addresses.primary` (boolean)
    Is address primary

  - `addresses.formatted` (string,null)
    Complete address as formatted string.
    Example: "123 Mission St, San Francisco, CA, 94105"

  - `addresses.type` (string,null)
    Address type. This field is ignored by Firstup.
    Example: "work"

  - `title` (string)
    A string containing the user's job title.
    Example: "Vice President"

  - `photos` (array)
    The user's photo (avatar).

* Firstup users have a single avatar photo.
* The single photo must be contained within an array.
* Sending multiple photos is ok but only the first photo is used.
* Only the first photo is validated for correctness.

  - `photos.type` (string)
    The type of photo.

Only  is supported—any other value is an error.
    Example: "photo"

  - `photos.value` (string)
    The URI of the photo (avatar).

URIs may be HTTP, HTTPS, or DATA. DATA URIs must contain a complete data URI including the MIME type, encoding, and data, e.g., 

All photos are downloaded by Firstup and self-hosted: the resulting photo URL will not be the same as the incoming URI.
    Example: "http://an.image/url"

  - `preferredLanguage` (string)
    A string containing the user's preferred language.
    Example: "en-US"

  - `userType` (string)
    The user's employee type
    Example: "Associate"

  - `locale` (string)
    The user's locale.
    Example: "en-US"

  - `timezone` (string)
    The user's timezone.
    Example: "US/Chicago"

  - `urn:SocialChorus:1.0:User` (object)

  - `urn:SocialChorus:1.0:User.businessUnit` (string,null)
    The user's business unit.
    Example: "Accounts Receivable"

  - `urn:SocialChorus:1.0:User.gender` (string,null)
    The user's gender.
    Example: "Female"

  - `urn:SocialChorus:1.0:User.managerName` (string,null)
    The user's manager's name.
    Example: "Jimmy Dean"

  - `urn:SocialChorus:1.0:User.workLocation` (string,null)
    The user's work location.
    Example: "Kabukicho"

  - `urn:SocialChorus:1.0:User.birthDate` (string,null)
    The user's birth date.
    Example: "2000-01-01T00:00:00.000Z"

  - `urn:SocialChorus:1.0:User.hireDate` (string,null)
    The user's start of employment date.
    Example: "2000-01-01T00:00:00.000Z"

  - `urn:SocialChorus:1.0:User.promotionDate` (string,null)
    The user's promotion date.
    Example: "2000-01-01T00:00:00.000Z"

  - `urn:SocialChorus:1.0:User.requisitionApprovalDate` (string,null)
    The Requisition Approval date.
    Example: "2000-01-01T00:00:00.000Z"

  - `urn:SocialChorus:1.0:User.lastAccessedAt` (string,null)
    Please contact your Firstup representative for more information.
    Example: "2000-01-01T00:00:00.000Z"

  - `urn:SocialChorus:1.0:User.customAttributes` (array)
    An array of objects including a name and value. These are stored as an arbitrary additional list of attributes associated to the user and can be used to create Groups and audiences in the Firstup platform. Currently, Custom Attributes can only be string values.
    Example: [{"name":"favorite_food","value":"pizza"},{"name":"favorite_sport","value":"soccer"},{"name":"hair_color","value":"brown"}]

  - `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User` (object)

  - `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.employeeNumber` (string,null)
    An employee id or identifier used in external systems.
    Example: "abc123"

  - `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.organization` (string,null)
    The employee organization name
    Example: "Firstup"

  - `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.department` (string,null)
    The employee's department name
    Example: "HR"

  - `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.costCenter` (string,null)
    The user's cost center
    Example: "NY"

  - `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.division` (string,null)
    The user's division
    Example: "THCI"

## Response 200 fields (application/scim+json):

  - `meta` (object)

  - `meta.resourceType` (string)
    Example: "User"

  - `id` (string)
    An immutable string identifier for the user. This value will never change once a user is created.
    Example: "8675309"

  - `userName` (string)
    uniquely identifies a user in the scope of your organization. It can be updated by the client, but must remain unique.

In Firstup Studio it is referred to as .
    Example: "janeDoe123"

  - `programMembershipId` (string)
    An immutable string identifier for the user's program membership.
    Example: "262574"

  - `externalId` (any)
    ID from provisioning system. This is the resource ID on the client system, not Firstup's ID.
    Example: "ext_123489"

  - `name` (object)
    An object containing multiple parts that make up a user's name.

  - `name.givenName` (string, required)
    User's first name
    Example: "Jane"

  - `name.familyName` (string, required)
    User's last name
    Example: "Doe"

  - `displayName` (string,null)
    Please refrain from using this attribute without prior consultation with our support staff.


  This attribute serves a distinct purpose within the Firstup system, requires a specific format
  and inappropriate use may introduce unintended side effects.

  - `nickName` (string,null)
    The casual way to address the user in real life.
    Example: "Jane"

  - `roles` (any)
    Defines a user's permissions and access privileges within a system or application.

The provided array extends support for Advanced Permissions, while supporting legacy Roles from Classic Studio. It accommodates a list of objects, each detailing the user's role, record permissions (scope), and legacy role if applicable.



To explore available roles, make use of the  request at .


- administrator
- program_manager
- analyst
- publisher
- channel_contributor
- member



For comprehensive insights into roles, scopes, and legacy roles refer to the following Knowledge Base Articles:

- [Roles-Standard](https://support.firstup.io/hc/en-us/articles/6278321908503)
- [Roles-Custom](https://support.firstup.io/hc/en-us/articles/6744088254359)
- [Scopes or Restrictions](https://support.firstup.io/hc/en-us/articles/6278321908503#h_01HBV399TW5WN1ZZABQF845H4E)
- [Legacy Roles](https://howto.socialchorus.com/hc/en-us/articles/115006356588#h_23542235341518566935216)


- Support the original single-string legacy role format [""]
- Legacy roles include "administrator",  "program_manager", "analyst", "publisher", "channel_contributor", or "member".
- GET /scim/v2/users and /scim/v2/users/{user_id} return this field based on a program configuration. Please contact
 if you need to switch the syntax.

Note: Firstup users have a single role and legacy_role but can have multiple scopes applied.

---

> ### Limitation Notice: Scope
> In addition to role and legacy_role the array supports the setting of record restrictions via scope objects. This includes the ability to define Topic, Audience, Template, and Email Aliases Permissions.
>
> 
> Currently the API does not validate the scope data against existing restriction records. While this does not compromise system security, it may result in users experiencing unexpected access limitations.
>
> 
> Users will still be able to access the application, but their access may not align with expectations due to permissions for records that are not valid. It's crucial to recognize that topic, audience, template, and email scopes play a pivotal role in limiting users to only seeing records defined within those specified scopes.
>
> 
> To ensure accurate access and visibility, we recommend using the Bulk Permissions UI. This ensures that restrictions align with the intended access for users, providing a proactive approach to managing and validating restriction data effectively.

---

  - `emails` (array)
    A list of the user's emails.
If a user has no emails this will be an empty list.

  - `emails.value` (string)
    A valid email address
    Example: "janedoe@email.com"

  - `emails.primary` (boolean)
    Indicates if the value is the user's primary email address
    Example: true

  - `emails.type` (string,null)
    An email type. Should be one of "work", "home", "other" or null
    Enum: "work", "home", "other", null

  - `photos` (array)
    A list containing at most a single element, the user's avatar photo URL.
If a user has no avatar photo URL this will be an empty list.

  - `photos.value` (string)
    Direct link to photo image resource
    Example: "http://some.url/photo.png"

  - `photos.type` (string)
    The type of photo; only "photo" is supported.
    Enum: "photo"

  - `phoneNumbers` (array)
    A list of the user's phone numbers.

If a user has no phone numbers this will be an empty list.

Firstup only saves and returns phone numbers with a  of  and .

  - `phoneNumbers.value` (string)
    A phone number
    Example: "555-1212"

  - `phoneNumbers.type` (string)
    The type of phone number. Only  and  are saved or returned by Firstup.

  DO NOT use  as the phone number type because it will be ignored. It's listed for third-party compatibility only.
    Enum: "main", "mobile", "work"

  - `phoneNumbers.primary` (boolean)
    This optional attribute is for compatibility purposes only and is ignored by Firstup.
    Example: true

  - `addresses` (array)
    The user's addresses in the program.
A Firstup user has only one address. The user's address will be set to either:
 The first address marked .
Sending anything other than an array (which may be empty) is an error.

  - `addresses.streetAddress` (string,null)
    A street address, e.g., house number and street name.
    Example: "123 Mission St"

  - `addresses.locality` (string,null)
    Address's locality, e.g, in the US, the city.
    Example: "San Francisco"

  - `addresses.region` (string,null)
    Address's region, e.g., in the US, the state.
    Example: "CA"

  - `addresses.postalCode` (string,null)
    Address's postal code, e.g., in the US, the zip code.
    Example: "94105"

  - `addresses.country` (string,null)
    Address's country.
    Example: "US"

  - `addresses.primary` (boolean)
    Is address primary

  - `addresses.formatted` (string,null)
    Complete address as formatted string.
    Example: "123 Mission St, San Francisco, CA, 94105"

  - `addresses.type` (string,null)
    Address type. This field is ignored by Firstup.
    Example: "work"

  - `title` (string)
    A string containing the user's job title.
    Example: "Vice President"

  - `userType` (string)
    The user's employee type
    Example: "Associate"

  - `locale` (string)
    The user's locale.
    Example: "en-US"

  - `timezone` (string)
    The user's timezone.
    Example: "US/Chicago"

  - `preferredLanguage` (string)
    A string containing the user's preferred language.
    Example: "en-US"

  - `active` (any)
    Whether or not the user is currently marked "active" in the program.
    Example: true

  - `urn:SocialChorus:1.0:User` (object)

  - `urn:SocialChorus:1.0:User.businessUnit` (string,null)
    The user's business unit.
    Example: "Accounts Receivable"

  - `urn:SocialChorus:1.0:User.gender` (string,null)
    The user's gender.
    Example: "Female"

  - `urn:SocialChorus:1.0:User.managerName` (string,null)
    The user's manager's name.
    Example: "Jimmy Dean"

  - `urn:SocialChorus:1.0:User.workLocation` (string,null)
    The user's work location.
    Example: "Kabukicho"

  - `urn:SocialChorus:1.0:User.birthDate` (string,null)
    The user's birth date.
    Example: "2000-01-01T00:00:00.000Z"

  - `urn:SocialChorus:1.0:User.hireDate` (string,null)
    The user's start of employment date.
    Example: "2000-01-01T00:00:00.000Z"

  - `urn:SocialChorus:1.0:User.promotionDate` (string,null)
    The user's promotion date.
    Example: "2000-01-01T00:00:00.000Z"

  - `urn:SocialChorus:1.0:User.requisitionApprovalDate` (string,null)
    The Requisition Approval date.
    Example: "2000-01-01T00:00:00.000Z"

  - `urn:SocialChorus:1.0:User.lastAccessedAt` (string,null)
    Please contact your Firstup representative for more information.
    Example: "2000-01-01T00:00:00.000Z"

  - `urn:SocialChorus:1.0:User.customAttributes` (array)
    An array of objects including a name and value. These are stored as an arbitrary additional list of attributes associated to the user and can be used to create Groups and audiences in the Firstup platform. Currently, Custom Attributes can only be string values.
    Example: [{"name":"favorite_food","value":"pizza"},{"name":"favorite_sport","value":"soccer"},{"name":"hair_color","value":"brown"}]

  - `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User` (object)

  - `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.employeeNumber` (string,null)
    An employee id or identifier used in external systems.
    Example: "abc123"

  - `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.organization` (string,null)
    The employee organization name
    Example: "Firstup"

  - `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.department` (string,null)
    The employee's department name
    Example: "HR"

  - `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.costCenter` (string,null)
    The user's cost center
    Example: "NY"

  - `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.division` (string,null)
    The user's division
    Example: "THCI"

  - `schemas` (array)
    Example: ["urn:ietf:params:scim:schemas:core:2.0:User"]

## Response 400 fields (*/*):

  - `schemas` (array)
    Example: ["urn:ietf:params:scim:api:messages:2.0:Error"]

  - `detail` (string)
    Example: "Reason for bad request"

  - `status` (integer)
    Example: 400

## Response 401 fields (*/*):

  - `schemas` (array)
    Example: ["urn:ietf:params:scim:api:messages:2.0:Error"]

  - `detail` (string)
    Example: "Authentication failure"

  - `status` (integer)
    Example: 401

## Response 403 fields (*/*):

  - `schemas` (array)
    Example: ["urn:ietf:params:scim:api:messages:2.0:Error"]

  - `detail` (string)
    Example: "Operation is not permitted"

  - `status` (integer)
    Example: 403