Search users
Authorization
OAuth token rendered by Identity Broker.
One of the following OAuth scopes is required:
identity:people_rwidentity:people_read
The following administrators can use this API:
id_full_adminid_user_adminid_readonly_adminid_device_admin
URI Parameters
Webex Identity assigned organization identifier for user's organization.
Query Parameters
The URL encoded filter. If the value is empty, the API will return all users under the organization.
The examples below show some search filters:
userNameeq "user1@example.com"userNamesw "user1@example"userNameew "example"phoneNumbers[ type eq "mobile" and value eq "14170120"]urn:scim:schemas:extension:cisco:webexidentity:2.0:User:meta.organizationIdeq "0ae87ade-8c8a-4952-af08-318798958d0c"For more filter patterns, please check filtering.
| Attributes | Operators |
|---|---|
| SCIM Core | ---- |
id | eq |
userName | eq sw ew |
name.familyName | eq sw ew |
name.givenName | eq sw |
name.middleName | eq sw |
name.formatted | eq sw |
displayName | eq sw ew |
nickName | eq sw ew |
emails.display | eq sw ew |
emails.value | eq sw ew |
phoneNumbers.value | eq sw ew |
phoneNumbers.display | eq sw ew |
| Enterprise Extensions | ---- |
employeeNumber | eq sw ew |
costCenter | eq sw ew |
organization | eq sw ew |
division | eq sw ew |
department | eq sw ew |
manager.value | eq |
manager.displayName | eq sw ew |
A multi-valued list of string names for resource attributes to return in the response, like 'userName,department,emails'. It supports the SCIM id 'urn:ietf:params:scim:schemas:extension:enterprise:2.0:User,userName'. The default is empty, all attributes will be returned
A multi-valued list of strings names for resource attributes to be removed from the default set of attributes to return. The default is empty, all attributes will be returned
A string for the attribute whose value can be used to order the returned responses. Now we only allow userName, id, meta.lastModified to sort.
A string for the order in which the 'sortBy' parameter is applied. Allowed values are 'ascending' and 'descending'.
An integer for the 1-based index of the first query result. The default is 1.
An integer for the maximum number of query results per page. The default is 100.
Define whether the group information needs to be returned. The default is false.
Define whether the group information with details needs to be returned. The default is false.
Returns groups with details of the specified group type.
Response Properties
Input JSON schemas.
Total number of users in search results.
The total number of items in a paged result.
Start at the one-based offset in the list of matching users.
A list of users with details.
Input JSON schemas.
Webex Identity assigned user identifier.
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 is required to be unique within Webex.
A boolean value of "true" or "false" indicating whether the user is allowed to login 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 name displayed for the user in Webex.
A casual name of the user. For example, Bob when the user's formal name is Robert.
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.
The email address.
The type of the email.
A human-readable description, primarily used for display purposes.
Email status boolean value. If the type is work and primary is true, the value must equal userName.
User type.
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 represents the user's currency, time format, and numerical representations. Acceptable values 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.
User identifier provided by an external provisioning source.
The user's time zone specified in the IANA timezone timezone format, for example, "America/Los_Angeles".
A list of user's phone numbers.
phone number.
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.
A human-readable name, primarily used for display purposes.
A Boolean value for phone number's primary status.
A list of group details returned only when includeGroupDetails or returnGroups request parameters are set to true.
A unique identifier for the group.
Display name of the group.
The URI corresponding to a group.
A list of photo objects for the user.
photo link.
The type of the photo
A human-readable description, primarily used for display purposes.
A Boolean value for 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
Name of a cost center.
Name of an organization.
Name of a division.
Name of a department.
Numeric or alphanumeric identifier assigned to a person, typically based on the 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 belong to the same org as the user.
The name displayed for the manager in Webex.
The URI corresponding to a SCIM user that is the manager.
The Cisco extension of SCIM 2.
An array of additional information about a user's status.
sipAddress values for the user.
The sipAddress value.
sipAddress type.
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 metadata.
The date and time the group was created.
The date and time the group was last changed.
The version of the user.
The resource itself.
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
Query Parameters
- The URL encoded filter. If the value is empty, the API will return all users under the organization. The examples below show some search filters: - `userName` eq "user1@example.com" - `userName` sw "user1@example" - `userName` ew "example" - `phoneNumbers` [ type eq "mobile" and value eq "14170120"] - `urn:scim:schemas:extension:cisco:webexidentity:2.0:User:meta.organizationId` eq "0ae87ade-8c8a-4952-af08-318798958d0c" - For more filter patterns, please check [filtering](https://datatracker.ietf.org/doc/html/rfc7644#section-3.4.2.2). | **Attributes** | **Operators** | |-----|-----| | **SCIM Core** | ---- | | `id` | eq | | `userName` | eq sw ew | | `name.familyName` | eq sw ew | | `name.givenName` | eq sw | | `name.middleName` | eq sw | | `name.formatted` | eq sw | | `displayName` | eq sw ew | | `nickName` | eq sw ew | | `emails.display` | eq sw ew | | `emails.value` | eq sw ew | | `phoneNumbers.value` | eq sw ew | | `phoneNumbers.display` | eq sw ew | | **Enterprise Extensions** | ---- | | `employeeNumber` | eq sw ew | | `costCenter` | eq sw ew | | `organization` | eq sw ew | | `division` | eq sw ew | | `department` | eq sw ew | | `manager.value` | eq | | `manager.displayName` | eq sw ew |
- A multi-valued list of string names for resource attributes to return in the response, like 'userName,department,emails'. It supports the SCIM id 'urn:ietf:params:scim:schemas:extension:enterprise:2.0:User,userName'. The default is empty, all attributes will be returned
- A multi-valued list of strings names for resource attributes to be removed from the default set of attributes to return. The default is empty, all attributes will be returned
- A string for the attribute whose value can be used to order the returned responses. Now we only allow `userName`, `id`, `meta.lastModified` to sort.
- A string for the order in which the 'sortBy' parameter is applied. Allowed values are 'ascending' and 'descending'.
- An integer for the 1-based index of the first query result. The default is 1.
- An integer for the maximum number of query results per page. The default is 100.
- Define whether the group information needs to be returned. The default is false.
- Define whether the group information with details needs to be returned. The default is false.
- Returns groups with details of the specified group type.
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"totalResults": 2,
"itemsPerPage": 2,
"startIndex": 1,
"Resources": [
{
"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": "user1@example.com",
"active": true,
"name": {
"familyName": "Joestar",
"givenName": "Jonathan",
"middleName": "Jane",
"honorificPrefix": "Mr.",
"honorificSuffix": "III"
},
"displayName": "Mr. Jonathan Jane Joestar, III",
"nickName": "JoJo",
"emails": [
{
"value": "user1@example.home.com",
"type": "home",
"display": "home email description"
},
{
"value": "user1@example.com",
"type": "work",
"primary": true
}
],
"userType": "user",
"profileUrl": "https://jojowiki.com/Jonathan_Joestar",
"title": "Sales manager",
"preferredLanguage": "en_US",
"locale": "en_US",
"externalId": "externalIdValue",
"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": "3936af3e-15ff-43d1-9ef5-66c569ef34f5",
"role": "location_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/\"76678575420\"",
"created": "2023-01-11T17:38:31.605Z",
"lastModified": "2023-01-11T17:38:31.605Z"
}
},
{
"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": "f3e35265-40df-4865-812a-66e62e79c9dc",
"userName": "user2@example.com",
"active": true,
"name": {
"familyName": "Joestar",
"givenName": "Jonathan",
"middleName": "Jane",
"honorificPrefix": "Mr.",
"honorificSuffix": "III"
},
"displayName": "Mr. Jonathan Jane Joestar, III",
"nickName": "JoJo",
"emails": [
{
"value": "user2@example.home.com",
"type": "home",
"display": "home email description"
},
{
"value": "user2@example.com",
"type": "work",
"primary": true
}
],
"userType": "user",
"profileUrl": "https://jojowiki.com/Jonathan_Joestar",
"title": "Sales manager",
"preferredLanguage": "en_US",
"locale": "en_US",
"externalId": "externalIdValue",
"timezone": "America/Los_Angeles",
"phoneNumbers": [
{
"value": "400 123 1234",
"type": "work",
"primary": true,
"display": "work phone number"
}
],
"groups": [
{
"value": "11d0ec88-04b9-4ece-9f28-06e1d7673ee3",
"display": "Darmstadt",
"$ref": "https://webexapis.com/identity/scim/36818b6f-ef07-43d1-b76f-ced79ab2e3e7/v2/Groups/11d0ec88-04b9-4ece-9f28-06e1d7673ee3"
},
],
"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": "0ae87ade-8c8a-4952-af08-318798958d0c",
"groupId": "d178e396-aa06-42cd-ab98-5124eb3b1926",
"role": "id_full_admin"
},
{
"orgId": "0ae87ade-8c8a-4952-af08-318798958d0c",
"groupId": "e0bdf530-f3e2-4ada-bbce-c5725acafc11",
"role": "id_full_admin"
}
],
"meta": {
"organizationId": "0ae87ade-8c8a-4952-af08-318798958d0c"
}
},
"meta": {
"resourceType": "User",
"location": "http://integration.webexapis.com/identity/scim/0ae87ade-8c8a-4952-af08-318798958d0c/v2/Users/f3e35265-40df-4865-812a-66e62e79c9dc",
"version": "W/\"76678575420\"",
"created": "2023-01-11T17:38:31.605Z",
"lastModified": "2023-01-11T17:38:31.605Z"
}
}
]
}