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
andreplace
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 is used to add 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 location indicated by path
references:
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, thevalue
attribute shall contain a list of one or more attributes that are 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 that are not specified in thevalue
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 indicate the failure by returning 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.
URI Parameters
Webex Identity assigned organization identifier for user's organization.
Webex Identity assigned user identifier.
Body Parameters
Input JSON schemas.
A list of patch operations.
The operation to perform.
A string containing an attribute path describing the target of the operation.
New value.
Response Properties
Input JSON schemas.
Webex Identity assigned user identifier.
A unique identifier for the user and is used to authenticate the user in Webex. This attribute 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.
A boolean value of "true" or "false" indicating whether the user is active in Webex.
The components of the user's real name.
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").
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").
The middle name(s) of the user (e.g., "Jane" given the full name "Ms. Sarah J Henderson, III").
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").
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").
The value to display or show the user's name in Webex.
A casual name of the user. The value Bob when the user's formal name is Robert.
A list of the user's email addresses with an indicator of the user's primary email address. The primary email address must be the same value as the user's userName.
The email address.
The type of the email.
A human-readable description, primarily used for display purposes.
A Boolean value indicating the email status. If the type is work and primary is true, the value must equal "userName".
The type of the user.
A fully qualified URL pointing to a page representing the user's online profile.
The user's business title. Examples of a title is "Business Manager". "Senior Accountant", "Engineer" etc.
The user's locale which is used to represent 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 English spoken in the United States or fr_FR: for French spoken in France.
External identity.
The user's time zone specified in the IANA timezone timezone format, for example, "America/Los_Angeles".
A list of user's phone numbers with an indicator of primary to specify the user's main number.
phone number.
We support the following types of phone numbers: 'mobile', 'work', 'fax', 'work_extension', 'alternate1', 'alternate2'. Alternate 1 and Alternate 2 are types inherited from Webex meeting sites.
A human-readable name, primarily used for display purposes.
A Boolean value indicating the phone number primary status.
A list of photos for the user that represent a thing the user has.
photo link.
The type of the photo
A human-readable description, primarily used for display purposes.
A Boolean value indicating the photo usage status.
User's physical mailing address.
The type of the address.
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.
The city or locality component.
The state or region component.
The zip code or postal code component.
The country name component.
SCIM2 enterprise extension
Identifies the name of a cost center.
Identifies the name of an organization.
Identifies the name of a division.
Identifies the name of a department.
Numeric or alphanumeric identifier assigned to a person, typically based on order of hire or association with an organization.
The user's manager.
Webex Identity assigned user identifier of the user's manager. The manager must be in the same org as the user.
The value to display or show the manager's name in Webex.
The URI corresponding to a SCIM user that is the manager.
The Cisco extension of SCIM 2.
Account status of the user.
sipAddress values for the user.
The sip address value.
The type of the sipAddress.
A human-readable description, primarily used for display purposes.
Designate the primary sipAddress.
Organizations that the user can manage.
Webex Identity assigned organization identifier.
Role in the target organization for the user.
Groups that the user can manage.
Webex Identity assigned organization identifier.
Webex Identity assigned group identifier.
Role in the target group for the user.
The extension attributes of the user. Postfix support from 1 to 15, for example, "extensionAttribute1","extensionAttribute2"..."extensionAttribute15".
The external attributes of the user. Postfix support from 1 to 15, for example, "externalAttribute1","externalAttribute2"..."externalAttribute15".
Source of external attribute.
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. |
Header
Body
- schemasarrayRequiredInput JSON schemas.
- OperationsarrayRequiredA list of patch operations.
{ "schemas": [ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ], "Operations": [ { "op": "add", "path": "displayName", "value": "new displayName value" } ] }
{ "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" } }