Users - Update a user with PATCH | Webex for Developers

Update a user with PATCH

Authorization

OAuth token rendered by Identity Broker.

One of the following OAuth scopes is required:

identity:people_rw

The following administrators can use this API:

id_full_admin
id_user_admin

Usage:

The PATCH API replaces individual attributes of the user's data in the request body. The PATCH API supports add, remove, and replace operations on any individual attribute allowing only specific attributes of the user's object to be modified.
Each operation against an attribute must be compatible with the attribute's mutability.
Each PATCH operation represents a single action to be applied to the same SCIM resource specified by the request URI. Operations are applied sequentially in the order they appear in the array. Each operation in the sequence is applied to the target resource; the resulting resource becomes the target of the next operation. Evaluation continues until all operations are successfully applied or until an error condition is encountered.

Add operations:

The add operation adds a new attribute value to an existing resource. The operation must contain a value member whose content specifies the value to be added. The value may be a quoted value, or it may be a JSON object containing the sub-attributes of the complex attribute specified in the operation's path. The result of the add operation depends upon the target path reference locations:

If omitted, the target location is assumed to be the resource itself. The value parameter contains a set of attributes to be added to the resource.
If the target location does not exist, the attribute and value are added.
If the target location specifies a complex attribute, a set of sub-attributes shall be specified in the value parameter.
If the target location specifies a multi-valued attribute, a new value is added to the attribute.
If the target location specifies a single-valued attribute, the existing value is replaced.
If the target location specifies an attribute that does not exist (has no value), the attribute is added with the new value.
If the target location exists, the value is replaced.
If the target location already contains the value specified, no changes should be made to the resource.

Replace operations:

The replace operation replaces the value at the target location specified by the path. The operation performs the following functions, depending on the target location specified by path:

If the path parameter is omitted, the target is assumed to be the resource itself. In this case, the value attribute shall contain a list of one or more attributes to be replaced.
If the target location is a single-value attribute, the value of the attribute is replaced.
If the target location is a multi-valued attribute and no filter is specified, the attribute and all values are replaced.
If the target location path specifies an attribute that does not exist, the service provider shall treat the operation as an "add".
If the target location specifies a complex attribute, a set of sub-attributes SHALL be specified in the value parameter, which replaces any existing values or adds where an attribute did not previously exist. Sub-attributes not specified in the value parameters are left unchanged.
If the target location is a multi-valued attribute and a value selection ("valuePath") filter is specified that matches one or more values of the multi-valued attribute, then all matching record values will be replaced.
If the target location is a complex multi-valued attribute with a value selection filter ("valuePath") and a specific sub-attribute (e.g., "addresses[type eq "work"].streetAddress"), the matching sub-attribute of all matching records is replaced.
If the target location is a multi-valued attribute for which a value selection filter ("valuePath") has been supplied and no record match was made, the service provider will return failure as HTTP status code 400 and a scimType error code of "noTarget".

Remove operations:

The remove operation removes the value at the target location specified by the required attribute path. The operation performs the following functions, depending on the target location specified by path:

If path is unspecified, the operation fails with HTTP status code 400 and a "scimType" error code of "noTarget".
If the target location is a single-value attribute, the attribute and its associated value is removed, and the attribute will be considered unassigned.
If the target location is a multi-valued attribute and no filter is specified, the attribute and all values are removed, and the attribute SHALL be considered unassigned.
If the target location is a multi-valued attribute and a complex filter is specified comparing a value, the values matched by the filter are removed. If no other values remain after the removal of the selected values, the multi-valued attribute will be considered unassigned.
If the target location is a complex multi-valued attribute and a complex filter is specified based on the attribute's sub-attributes, the matching records are removed. Sub-attributes whose values have been removed will be considered unassigned. If the complex multi-valued attribute has no remaining records, the attribute will be considered unassigned.

PATCH/identity/scim/{orgId}/v2/Users/{userId}

URI Parameters

orgId

stringrequired

Webex Identity assigned organization identifier for user's organization.

userId

stringrequired

Webex Identity assigned user identifier.

Body Parameters

schemas

array[string]required

Input JSON schemas.

Possible values: urn:ietf:params:scim:api:messages:2.0:PatchOp

Operations

array[object]required

A list of patch operations.

enum

The operation to perform.

add

string

replace

string

remove

string

path

string

A string containing an attribute path describing the target of the operation.

Possible values: displayName

value

string

New value.

Possible values: new displayName value

Response Properties

schemas

array[string]

Input JSON schemas.

string

Webex Identity assigned user identifier.

userName

string

A unique identifier for the user and authenticates the user in Webex. This must be set to the user's primary email address. No other user in Webex may have the same userName value and thus this value is required to be unique within Webex.

active

boolean

A boolean value of "true" or "false" indicating whether the user is allowed to login in Webex.

name

NameObject

The components of the user's real name.

givenName

string

The given name of the user, or first name in most Western languages (e.g., "Sarah" given the full name "Ms. Sarah J Henderson, III").

familyName

string

The family name of the user, or last name in most Western languages (e.g., "Henderson" given the full name "Ms. Sarah J Henderson, III").

middleName

string

The middle name(s) of the user (e.g., "Jane" given the full name "Ms. Sarah J Henderson, III").

honorificPrefix

string

The honorific prefix(es) of the user, or title in most Western languages (e.g., "Ms." given the full name "Ms. Sarah J Henderson, III").

honorificSuffix

string

The honorific suffix(es) of the user, or suffix in most Western languages (e.g., "III" given the full name "Ms. Sarah J Henderson, III").

displayName

string

The name displayed for the user in Webex.

nickName

string

A casual name of the user. For example, Bob when the user's formal name is Robert.

emails

array[EmailObject]

A list of the user's email addresses, including primary and alternative emails. The primary work email address must match the value of the user's username.

value

string

The email address.

type

enum

The type of the email.

work

string

home

string

room

string

other

string

display

string

A human-readable description, primarily used for display purposes.

primary

boolean

Email status boolean value. If the type is work and primary is true, the value must equal userName.

userType

UserTypeObject

User type.

user

string

room

string

external_calling

string

calling_service

string

profileUrl

string

A fully qualified URL pointing to a page representing the user's online profile.

title

string

The user's business title. Examples of a title is "Business Manager". "Senior Accountant", "Engineer" etc.

preferredLanguage

string

User's preferred language. Acceptable values for this field are based on the ISO-696 and ISO-3166 with the 2 letter language code followed by an _ and then the 2 letter country code. Examples are:

                                en_US : for United States English or fr_FR for Parisian French.

locale

string

The user's locale which represents the user's currency, time format, and numerical representations. Acceptable values for this field are based on the ISO-696 and ISO-3166 with the 2 letter language code followed by an _ and then the 2 letter country code. Examples are:

                     en_US : for United States English or fr_FR for Parisian French.

externalId

string

User identifier provided by an external provisioning source.

timezone

string

The user's time zone specified in the IANA timezone timezone format, for example, "America/Los_Angeles".

phoneNumbers

array[PhoneNumberObject]

A list of user's phone numbers.

value

string

phone number.

type

enum

We support the following phone number types: 'mobile', 'work', 'fax', 'work_extension', 'alternate1', 'alternate2'. Alternate 1 and Alternate 2 are types inherited from Webex meeting sites.

work

string

home

string

mobile

string

work_extension

string

fax

string

pager

string

other

string

display

string

A human-readable name, primarily used for display purposes.

primary

boolean

A Boolean value for phone number's primary status.

photos

array[PhotoObject]

A list of photo objects for the user.

value

string

photo link.

type

enum

The type of the photo

photo

string

thumbnail

string

resizable

string

display

string

A human-readable description, primarily used for display purposes.

primary

boolean

A Boolean value for the photo usage status.

addresses

array[AddressObject]

User's physical mailing address.

type

string

The type of the address.

streetAddress

string

The full street address component, which may include house number, street name, P.O. box, and multi-line extended street address information. This attribute MAY contain newlines.

locality

string

The city or locality component.

region

string

The state or region component.

postalCode

string

The zip code or postal code component.

country

string

The country name component.

urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

object

SCIM2 enterprise extension

costCenter

string

Name of a cost center.

organization

string

Name of an organization.

division

string

Name of a division.

department

string

Name of a department.

employeeNumber

string

Numeric or alphanumeric identifier assigned to a person, typically based on the order of hire or association with an organization.

manager

ManagerResponseObject

The user's manager.

value

string

Webex Identity assigned user identifier of the user's manager. The manager must belong to the same org as the user.

displayName

string

The name displayed for the manager in Webex.

$ref

string

The URI corresponding to a SCIM user that is the manager.

urn:scim:schemas:extension:cisco:webexidentity:2.0:User

object

The Cisco extension of SCIM 2.

accountStatus

AccountStatusObject

An array of additional information about a user's status.

active

string

pending

string

transient

string

disabled

string

fraud

string

fraud_transient

string

compliance_transient

string

pending_transient

string

sipAddresses

array[SipAddressObject]

sipAddress values for the user.

value

string

The sipAddress value.

type

enum

sipAddress type.

enterprise

string

display

string

A human-readable description, primarily used for display purposes.

primary

boolean

Designate the primary sipAddress.

managedOrgs

array[ManagedOrgsObject]

Organizations that the user can manage.

orgId

string

Webex Identity assigned organization identifier.

role

string

Role in the target organization for the user.

managedGroups

array[ManagedGroupsObject]

Groups that the user can manage.

orgId

string

Webex Identity assigned organization identifier.

groupId

string

Webex Identity assigned group identifier.

role

string

Role in the target group for the user.

extensionAttribute*

array[string]

The extension attributes of the user. Postfix support from 1 to 15, for example: "extensionAttribute1", "extensionAttribute2", ..., "extensionAttribute15".

externalAttribute*

array[ExternalAttributeObject]

The external attributes of the user. Postfix support from 1 to 15, for example: "externalAttribute1", "externalAttribute2", ..., "externalAttribute15".

source

string

Source of external attribute.

value

string

Value of external attribute.

Response Codes

The list below describes the common success and error responses you should expect from the API.

Code	Status	Description
200	OK	Successful request with body content.
201	Created	The request has succeeded and has led to the creation of a resource.
202	Accepted	The request has been accepted for processing.
204	No Content	Successful request without body content.
400	Bad Request	The request was invalid or cannot be otherwise served. An accompanying error message will explain further.
401	Unauthorized	Authentication credentials were missing or incorrect.
403	Forbidden	The request is understood, but it has been refused or access is not allowed.
404	Not Found	The URI requested is invalid or the resource requested, such as a user, does not exist. Also returned when the requested format is not supported by the requested method.
405	Method Not Allowed	The request was made to a resource using an HTTP request method that is not supported.
409	Conflict	The request could not be processed because it conflicts with some established rule of the system. For example, a person may not be added to a room more than once.
410	Gone	The requested resource is no longer available.
415	Unsupported Media Type	The request was made to a resource without specifying a media type or used a media type that is not supported.
423	Locked	The requested resource is temporarily unavailable. A `Retry-After` header may be present that specifies how many seconds you need to wait before attempting the request again.
428	Precondition Required	File(s) cannot be scanned for malware and need to be force downloaded.
429	Too Many Requests	Too many requests have been sent in a given amount of time and the request has been rate limited. A `Retry-After` header should be present that specifies how many seconds you need to wait before a successful request can be made.
500	Internal Server Error	Something went wrong on the server. If the issue persists, feel free to contact the Webex Developer Support team.
502	Bad Gateway	The server received an invalid response from an upstream server while processing the request. Try again later.
503	Service Unavailable	Server is overloaded with requests. Try again later.
504	Gateway Timeout	An upstream server failed to respond on time. If your query uses `max` parameter, please try to reduce it.

PATCH

/identity/scim//v2/Users/

Header

Content-Type
Authorization
Use personal access token
Bearer
This limited-duration personal access token is hidden for your security.

Body

schemas
arrayRequired
Input JSON schemas.
Operations
arrayRequired
A list of patch operations.

https://webexapis.com/identity/scim/0ae87ade-8c8a-4952-af08-318798958d0c/v2/Users/3426a8e3-d414-4bf0-a493-4f6787632a13

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "add",
      "path": "displayName",
      "value": "new displayName value"
    }
  ]
}

200 / OK

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:scim:schemas:extension:cisco:webexidentity:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
    ],
    "id": "3426a8e3-d414-4bf0-a493-4f6787632a13",
    "userName": "user1Changed@example.com",
    "active": true,
    "name": {
        "familyName": "Joestar",
        "givenName": "Jonathan",
        "middleName": "Jane",
        "honorificPrefix": "Mr.",
        "honorificSuffix": "III"
    },
    "displayName": "new displayName value",
    "nickName": "JoJo",
    "emails": [
        {
            "value": "user1@example.home.com",
            "type": "home",
            "display": "home email description"
        },
        {
            "value": "user1Changed@example.com",
            "type": "work",
            "primary": true
        }
    ],
    "userType": "user",
    "profileUrl": "https://jojowiki.com/Jonathan_Joestar",
    "title": "Sales manager",
    "preferredLanguage": "en_US",
    "locale": "en_US",
    "externalId": "externalIdNewValue",
    "timezone": "America/Los_Angeles",
    "phoneNumbers": [
        {
            "value": "400 123 1234",
            "type": "work",
            "primary": true,
            "display": "work phone number"
        }
    ],
    "photos": [
        {
            "value": "https://photos.example.com/profilephoto/72930000000Ccne/F",
            "type": "photo",
            "primary": true,
            "display": "photo description"
        }
    ],
    "addresses": [
        {
            "type": "work",
            "streetAddress": "100 Universal City Plaza",
            "locality": "Hollywood",
            "region": "CA",
            "postalCode": "91608",
            "country": "US"
        }
    ],
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
        "employeeNumber": "518-8888-888",
        "costCenter": "costCenter 123",
        "organization": "Cisco webexidentity",
        "division": "division 456",
        "department": "department 789",
        "manager": {
            "value": "b5717a4a-0169-43b2-ac3c-db20ba4e72cd",
            "displayName": "Identity Administrator",
            "$ref": "http://integration.webexapis.com/identity/scim/0ae87ade-8c8a-4952-af08-318798958d0c/v2/Users/b5717a4a-0169-43b2-ac3c-db20ba4e72cd"
        }
    },
    "urn:scim:schemas:extension:cisco:webexidentity:2.0:User": {
        "accountStatus": [
            "active"
        ],
        "sipAddresses": [
            {
                "value": "sipAddress value1",
                "type": "enterprise",
                "primary": true,
                "display": "sipAddress1 description"
            }
        ],
        "managedOrgs": [
            {
                "orgId": "75fe2995-24f5-4831-8d2c-1c2f8255912e",
                "role": "id_full_admin"
            }
        ],
        "managedGroups": [
            {
                "orgId": "75fe2995-24f5-4831-8d2c-1c2f8255912e",
                "groupId": "d178e396-aa06-42cd-ab98-5124eb3b1926",
                "role": "id_full_admin"
            }
        ],
        "externalAttribute1": [
            {
                "source": "Source.1_7ddf1f2c-2985-4c37-a450-d58bbc201750",
                "value": "externalAttribute1_value"
            }
        ],
        "externalAttribute2": [
            {
                "source": "Source.2_7ddf1f2c-2985-4c37-a450-d58bbc201750",
                "value": "externalAttribute2_value"
            }
        ],
        "extensionAttribute1": [
            "extensionAttribute1_Item1",
            "extensionAttribute1_Item2"
        ],
        "extensionAttribute2": [
            "extensionAttribute2_Item1",
            "extensionAttribute2_Item2",
            "extensionAttribute2_Item3"
        ],
        "meta": {
            "organizationId": "0ae87ade-8c8a-4952-af08-318798958d0c"
        }
    },
    "meta": {
        "resourceType": "User",
        "location": "http://integration.webexapis.com/identity/scim/0ae87ade-8c8a-4952-af08-318798958d0c/v2/Users/3426a8e3-d414-4bf0-a493-4f6787632a13",
        "version": "W/\"88678579986\"",
        "created": "2023-01-11T17:38:31.605Z",
        "lastModified": "2023-02-02T11:38:31.009Z"
    }
}