# Replace a user in the program

To update or replace user information, ensure that your request includes a comprehensive set of user attributes.
Utilize **PUT** endpoints carefully. Modified data models caused by new features or user-defined fields may lead to data loss. Refer to our <a href="https://developers.firstup.io/usermanagementapi/scim-patch-operations"> SCIM patching documentation</a> before executing.
**Quick Guidance**<br>
For a seamless process, consider the following:
1. <a href="https://developers.firstup.io/endpoints/openapi/user-management/detailuser"> **GET** the user record</a> 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 <a href="https://developers.firstup.io/endpoints/openapi/user-management/patchuser"> **PATCH**</a> 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.
 We advise refering to our <a href="https://developers.firstup.io/usermanagementapi/scim-patch-operations"> SCIM patching documentation</a> before executing.
Refer to our <a href="https://developers.firstup.io/gettingstarted/error_responses"> error responses documentation</a> for detail on errors.

Endpoint: PUT /scim/v2/Users/{user_id}
Version: 2026-05-01
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)
    `userName` 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 `universal_identifier`.
    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)
    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)
    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.
Extended documentation explaining how user roles and access works within our API can be found  here. 
**Discover Available Roles**
 GET /scim/v2/roles to explore available roles.
**Available Legacy Roles**
- administrator
- program_manager
- analyst
- publisher
- channel_contributor
- member

**Additional Resources**
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)

**Backward Compatibility:**
- Support the original single-string legacy role format ["`legacy_role`"]
- Legacy roles include "administrator",  "program_manager", "analyst", "publisher", "channel_contributor", or "member".
-  GET /scim/v2/users and GET /scim/v2/users/{user_id} return this field based on a program configuration. Please contact
[Support](https://support.firstup.io/hc/en-us) if you need to switch the syntax.

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.
**Issue:**
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.
**Impact:**
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.
**Recommendation:**
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.



---

  - `roles.type` (string)
    The `type` field specifies the role or access permissions in the Firstup API. It encompasses the following key elements:
The `type` field specifies the role or access permissions in the Firstup API.
It encompasses the following key elements:
- **Role:** Represents the Creator Studio Advanced Permissions Role, defining the user's overarching responsibilities.
- **Scope:** Indicates the restrictions associated with the Advanced Permissions Role, determining the records the user can access within Firstup.
- **Legacy Roles:** Deprecated roles from the past that may still be associated with the user. In most scenarios, these roles are no longer utilized and are not required for current functionality.

Ensure to review and align roles and scopes for effective management of user access and permissions.
    Enum: "role", "scope", "legacy_role"

  - `roles.value` (string)
    The `value` field within the context of the Firstup API represents the identifier or key associated with the corresponding record.
This identifier links to the specific record defined by the user's role, scope, or legacy roles.
For example, if the `type` is role, the `value` would point to the unique identifier for that role.

  - `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)
    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, or... * The first address marked `primary`.
Sending anything other than an array (which may be empty) is an error.

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

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

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

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

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

  - `addresses.primary` (boolean)
    Is address primary
    Example: false

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

  - `addresses.type` (string)
    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 `"photo"` 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., `data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...`
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 geographical timezone (IANA format. Note, this is case sensitive).
    Example: America/Chicago

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

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

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

  - `urn:SocialChorus:1.0:User.pronouns` (string)
    The user's pronouns.
    Example: they/them

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

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

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

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

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

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

  - `urn:SocialChorus:1.0:User.lastAccessedAt` (string)
    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:SocialChorus:1.0:User.customAttributes.name` (string, required)
    The name of the attribute

  - `urn:SocialChorus:1.0:User.customAttributes.value` (string, required)
    The value of the attribute

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

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

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

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

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

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

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

  - `schemas` (array)

## 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