Update a user in the program

Request

Update a user in the program with partial changes using SCIM PatchOp. Add, remove, or replace selected fields of the user. Role updates require the acting user's role to be the same or higher role than the user being updated both before and after the role update.

We advise refering to our SCIM patching documentation before executing. Refer to our error responses documentation for detail on errors.

Security

oauth2_as_a_server(Required scopes: users.write) or oauth2_as_a_user(Required scopes: users.write)

Path

user_idstringrequired

Identifier of the user to patch. It could be used either the user's id, universal identifier, an email address, or external Id. The look up will be done in the above mentioned order.

Bodyapplication/jsonrequired

schemasArray of strings

Example:

[
  "urn:ietf:params:scim:api:messages:2.0:PatchOp"
]

OperationsArray of objects

Example:

[
  {
    "op": "replace",
    "path": "active",
    "value": false
  },
  {
    "op": "replace",
    "path": "emails[type eq \"work\"].value",
    "value": "janedoe@email.com"
  }
]

curl -i -X PATCH \
  'https://partner.socialchorus.com/scim/v2/Users/{user_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "schemas": [
      "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ],
    "Operations": [
      {
        "op": "replace",
        "path": "active",
        "value": false
      },
      {
        "op": "replace",
        "path": "emails[type eq \"work\"].value",
        "value": "janedoe@email.com"
      }
    ]
  }'

Responses

Success

Bodyapplication/scim+json

metaobject

idstring(Scim.User.Core.id)

An immutable string identifier for the user. This value will never change once a user is created.

Example:"8675309"

userNamestring(Scim.User.Core.userName)

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"

programMembershipIdstring(Scim.User.Core.programMembershipId)

An immutable string identifier for the user's program membership.

Example:"262574"

externalId(string or null) or (integer or null)(Scim.User.Core.externalId)

Example:"ext_123489"

One of:

ID from provisioning system. This is the resource ID on the client system, not Firstup's ID.

string or null

nameobject(Scim.User.Core.name)

An object containing multiple parts that make up a user's name.

displayNamestring or null(Scim.User.Core.displayName)

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.

nickNamestring or null(Scim.User.Core.nickName)

The casual way to address the user in real life.

Example:"Jane"

rolesScim.User.Core.roleString (string) or Array of Scim.User.Core.rolesObjectArray (any)(Scim.User.Core.roles)

One of:

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:

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

string(Scim.User.Core.roleString)

Enum:"administrator""program_manager""analyst""publisher""channel_contributor""member"

emailsArray of objects(Scim.User.Core.emails)

A list of the user's emails. If a user has no emails this will be an empty list.

photosArray of objects(Scim.User.Core.photos)

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.

phoneNumbersArray of objects(Scim.User.Core.phoneNumbers)

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 type of main and mobile.

addressesArray of objects(Scim.User.Core.addresses)

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.

titlestring(Scim.User.Core.title)

A string containing the user's job title.

Example:"Vice President"

userTypestring(Scim.User.Core.userType)

The user's employee type

Example:"Associate"

localestring(Scim.User.Core.locale)

The user's locale.

Example:"en-US"

timezonestring(Scim.User.Core.timezone)

The user's geographical timezone (IANA format. Note, this is case sensitive).

Example:"America/Chicago"

preferredLanguagestring(Scim.User.Core.preferredLanguage)

A string containing the user's preferred language.

Example:"en-US"

activeboolean or string(Scim.User.Core.active)

Example:true

One of:

Whether or not the user is currently marked "active" in the program.

boolean

urn:SocialChorus:1.0:Userobject(Scim.User.SocialChorusExtension)

urn:ietf:params:scim:schemas:extension:enterprise:2.0:Userobject(Scim.User.EnterpriseExtension)

schemasArray of strings

Example:

[
  "urn:ietf:params:scim:schemas:core:2.0:User"
]

Response

{
  "meta": {
    "resourceType": "User"
  },
  "id": "8675309",
  "userName": "janeDoe123",
  "programMembershipId": "262574",
  "externalId": "ext_123489",
  "name": {
    "givenName": "Jane",
    "familyName": "Doe"
  },
  "displayName": "string",
  "nickName": "Jane",
  "roles": "publisher",
  "emails": [
    { … }
  ],
  "photos": [
    { … }
  ],
  "phoneNumbers": [
    { … }
  ],
  "addresses": [
    { … }
  ],
  "title": "Vice President",
  "userType": "Associate",
  "locale": "en-US",
  "timezone": "America/Chicago",
  "preferredLanguage": "en-US",
  "active": true,
  "urn:SocialChorus:1.0:User": {
    "businessUnit": "Accounts Receivable",
    "gender": "Female",
    "pronouns": "they/them",
    "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",
    "customAttributes": [ … ]
  },
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "employeeNumber": "abc123",
    "organization": "Firstup",
    "department": "HR",
    "costCenter": "NY",
    "division": "THCI"
  },
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ]
}