wxc_sdk.people package

People types and API

As of January 2024, the Webex APIs have been fully upgraded to support the industry-standard SCIM 2.0 protocol, which is used for user and group management, provisioning, and maintenance. Developers are advised to use this API instead of the people API, due to its higher performance and readily available connectors. Users created via SCIM should be licensed using the /licenses API, even in large quantities, using the new PATCH method.

People are registered users of Webex. Searching and viewing People requires an auth token with a scope of spark:people_read. Viewing the list of all People in your organization requires an administrator auth token with spark-admin:people_read scope. Adding, updating, and removing People requires an administrator auth token with the spark-admin:people_write and spark-admin:people_read scope.

A person’s call settings are for Webex Calling and necessitate Webex Calling licenses.

To learn more about managing people in a room see the Memberships API. For information about how to allocate Hybrid Services licenses to people, see the `Managing Hybrid Services

class wxc_sdk.people.PhoneNumberType(*values)[source]

Bases: str, SafeEnum

Webex phone number type

work = 'work'

Work phone number of the person.

work_extension = 'work_extension'

Work extension of the person. For the Webex Calling person, the value will have a routing prefix along with the extension.

mobile = 'mobile'

Mobile number of the person.

fax = 'fax'

FAX number of the person.

enterprise = 'enterprise'
alternate1 = 'alternate1'
alternate2 = 'alternate2'
class wxc_sdk.people.PhoneNumber(*, type: PhoneNumberType, value: str, primary: bool | None = None, **extra_data: Any)[source]

Bases: ApiModel

Webex phone number: type and Value

number_type: PhoneNumberType
value: str
primary: bool | None
class wxc_sdk.people.SipType(*values)[source]

Bases: str, SafeEnum

SIP address type

personal_room = 'personal-room'

Personal room address.

enterprise = 'enterprise'

Enterprise address.

cloud_calling = 'cloud-calling'

Cloud calling address.

unknown = 'unknown'
class wxc_sdk.people.SipAddress(*, type: SipType, value: str, primary: bool, **extra_data: Any)[source]

Bases: ApiModel

SIP address: type, value and primary indication

sip_type: SipType

The type of SIP address.

value: str

The SIP address.

primary: bool

Primary SIP address of the person.

class wxc_sdk.people.PeopleStatus(*values)[source]

Bases: str, SafeEnum

An enumeration.

active = 'active'

Active within the last 10 minutes.

call = 'call'

The user is in a call.

do_not_disturb = 'DoNotDisturb'

The user has manually set their status to “Do Not Disturb”.

inactive = 'inactive'

Last activity occurred more than 10 minutes ago.

meeting = 'meeting'

The user is in a meeting.

out_of_office = 'OutOfOffice'

The user or a Hybrid Calendar service has indicated that they are “Out of Office”.

pending = 'pending'

The user has never logged in; a status cannot be determined.

presenting = 'presenting'

The user is sharing content.

unknown = 'unknown'

The user’s status could not be determined.

class wxc_sdk.people.PersonType(*values)[source]

Bases: str, SafeEnum

An enumeration.

person = 'person'

Account belongs to a person.

bot = 'bot'

Account is a bot user.

appuser = 'appuser'

Account is a guest user.

class wxc_sdk.people.PersonAddress(*, type: str | None = None, country: str | None = None, locality: str | None = None, region: str | None = None, streetAddress: str | None = None, postalCode: str | None = None, **extra_data: Any)[source]

Bases: ApiModel

type: str | None

The type of address.

country: str | None

The user’s country.

locality: str | None

The user’s locality, often city.

region: str | None

The user’s region, often state.

street_address: str | None

The user’s street.

postal_code: str | None

The user’s postal or zip code.

class wxc_sdk.people.Person(*, errors: dict[str, CodeAndReason] | None = None, id: str | None = None, emails: list[str] | None = None, phoneNumbers: list[PhoneNumber] | None = None, extension: str | None = None, locationId: str | None = None, displayName: str | None = None, nickName: str | None = None, firstName: str | None = None, lastName: str | None = None, avatar: str | None = None, orgId: str | None = None, roles: list[str] | None = None, licenses: list[str] | None = None, department: str | None = None, manager: str | None = None, managerId: str | None = None, title: str | None = None, addresses: list[PersonAddress] | None = None, siteUrls: list[str] | None = None, created: datetime | None = None, lastModified: datetime | None = None, timezone: str | None = None, lastActivity: str | None = None, sipAddresses: list[SipAddress] | None = None, status: PeopleStatus | None = None, invitePending: bool | None = None, loginEnabled: bool | None = None, type: PersonType | None = None, userName: str | None = None, **extra_data: Any)[source]

Bases: ApiModelWithErrors

Webex person

person_id: str | None

A unique identifier for the person.

emails: list[str] | None

The email addresses of the person.

phone_numbers: list[PhoneNumber] | None

Phone numbers for the person.

extension: str | None

The Webex Calling extension for the person. Only applies to a person with a Webex Calling license

location_id: str | None

The ID of the location for this person retrieved from BroadCloud.

display_name: str | None

The full name of the person.

nick_name: str | None

The nickname of the person if configured. If no nickname is configured for the person, this field will not be present.

first_name: str | None

Optional[str]

Type:

first_name

last_name: str | None

The last name of the person.

avatar: str | None

The URL to the person’s avatar in PNG format

org_id: str | None

The ID of the organization to which this person belongs.

roles: list[str] | None

An array of role strings representing the roles to which this person belongs.

licenses: list[str] | None

An array of license strings allocated to this person.

department: str | None

The business department the user belongs to.

manager: str | None

A manager identifier.

manager_id: str | None

Person Id of the manager

title: str | None

the person’s title

addresses: list[PersonAddress] | None

Person’s address

site_urls: list[str] | None

mysite.webex.com#attendee

Type:

Possible values

created: datetime | None

The date and time the person was created.

last_modified: datetime | None

The date and time the person was last changed.

timezone: str | None

The time zone of the person if configured. If no timezone is configured on the account, this field will not be present

last_activity: str | None

The date and time of the person’s last activity within Webex. This will only be returned for people within your organization or an organization you manage. Presence information will not be shown if the authenticated user has disabled status sharing.

sip_addresses: list[SipAddress] | None

The users sip addresses. Read-only.

status: PeopleStatus | None

The current presence status of the person. This will only be returned for people within your organization or an organization you manage. Presence information will not be shown if the authenticated user has disabled status sharing.

invite_pending: bool | None

Whether or not an invite is pending for the user to complete account activation. This property is only returned if the authenticated user is an admin user for the person’s organization.

login_enabled: bool | None

Whether or not the user is allowed to use Webex. This property is only returned if the authenticated user is an admin user for the person’s organization.

person_type: PersonType | None

The type of person account, such as person or bot.

user_name: str | None
property person_id_uuid: str

person id in uuid format

property plus_e164: list[PhoneNumber]

List of +E.164 phone numbers of the user :return:

property tn: PhoneNumber | None

user’s TN (first +E.164 number if any) :return:

class wxc_sdk.people.PeopleApi(*, session: RestSession, base: str = None)[source]

Bases: ApiChild

People

As of January 2024, the Webex APIs have been fully upgraded to support the industry-standard SCIM 2.0 protocol, which is used for user and group management, provisioning, and maintenance. Developers are advised to use this API instead of the people API, due to its higher performance and readily available connectors. Users created via SCIM should be licensed using the /licenses API, even in large quantities, using the new PATCH method.

People are registered users of Webex. Searching and viewing People requires an auth token with a scope of spark:people_read. Viewing the list of all People in your organization requires an administrator auth token with spark-admin:people_read scope. Adding, updating, and removing People requires an administrator auth token with the spark-admin:people_write and spark-admin:people_read scope.

A person’s call settings are for Webex Calling and necessitate Webex Calling licenses.

To learn more about managing people in a room see the Memberships API. For information about how to allocate Hybrid Services licenses to people, see the Managing Hybrid Services guide.

list(email: str = None, display_name: str = None, id_list: list[str] = None, org_id: str = None, roles: str = None, calling_data: bool = None, location_id: str = None, exclude_status: bool = None, **params) → Generator[Person, None, None][source]

List people in your organization. For most users, either the email or displayName parameter is required. Admin users can omit these fields and list all users in their organization.

Response properties associated with a user’s presence status, such as status or lastActivity, will only be returned for people within your organization or an organization you manage. Presence information will not be returned if the authenticated user has disabled status sharing.

Admin users can include Webex Calling (BroadCloud) user details in the response by specifying callingData parameter as true. Admin users can list all users in a location or with a specific phone number. Admin users will receive an enriched payload with additional administrative fields like liceneses,roles etc. These fields are shown when accessing a user via GET /people/{id}, not when doing a GET /people?id=

Lookup by email is only supported for people within the same org or where a partner admin relationship is in place.

Lookup by roles is only supported for Admin users for the people within the same org.

Parameters:

  • email (str) – List people with this email address. For non-admin requests, either this or displayName are required.

  • display_name (str) – List people whose name starts with this string. For non-admin requests, either this or email are required.

  • id_list (list[str]) – List people by ID. Accepts up to 85 person IDs. If this parameter is provided then presence information (such as the last_activity or status properties) will not be included in the response.

  • org_id (str) – List people in this organization. Only admin users of another organization (such as partners) may use this parameter.

  • roles (str) – List of roleIds separated by commas.

  • calling_data (bool) – Include Webex Calling user details in the response. Default: False

  • location_id (str) – List people present in this location.

  • exclude_status (bool) – Omit people status/availability to enhance query performance.

Returns:

yield Person instances

create(settings: Person, calling_data: bool = False, min_response: bool = None) → Person[source]

Create a Person

Create a new user account for a given organization. Only an admin can create a new user account.

At least one of the following body parameters is required to create a new user: displayName, firstName, lastName.

Currently, users may have only one email address associated with their account. The emails parameter is an array, which accepts multiple values to allow for future expansion, but currently only one email address will be used for the new user.

Admin users can include Webex calling (BroadCloud) user details in the response by specifying callingData parameter as true. It may happen that the POST request with calling data returns a 400 status, but the person was created still. One way to get into this state is if an invalid phone number is assigned to a user. The people API aggregates calls to several other microservices, and one may have failed. A best practice is to check if the user exists before retrying. This can be done with the user’s email address and a GET /people.

When doing attendee management, to make the new user an attendee for a site: append #attendee to the siteUrl parameter (eg: mysite.webex.com#attendee).

NOTES:

  • For creating a Webex Calling user, you must provide phoneNumbers or extension, locationId, and licenses string in the same request.

  • SipAddresses are assigned via an asynchronous process. This means that the POST response may not show the SIPAddresses immediately. Instead, you can verify them with a separate GET to /people, after they were newly configured.

  • When assigning multiple licenses in a single request, the system will assign all valid and available licenses. If any requested licenses cannot be assigned, the operation will continue with the remaining licenses. As a result, it is possible that not all requested licenses are assigned to the user.

Parameters:

  • settings (Person) – settings for new user

  • calling_data (bool) – Include Webex Calling user details in the response.

  • min_response (bool) – Set to true to improve performance by omitting person details and returning only the ID in the response when successful. If unsuccessful the response will have optional error details.

Returns:

new user

Return type:

Person

details(person_id: str, calling_data: bool = False) → Person[source]

Get Person Details

Shows details for a person, by ID.

Response properties associated with a user’s presence status, such as status or lastActivity, will only be displayed for people within your organization or an organization you manage. Presence information will not be shown if the authenticated user has disabled status sharing.

Admin users can include Webex Calling (BroadCloud) user details in the response by specifying callingData parameter as true.

Parameters:

  • person_id (str) – A unique identifier for the person.

  • calling_data (bool) – Include Webex Calling user details in the response. Default: false

Returns:

person details

Return type:

Person

delete_person(person_id: str)[source]

Delete a Person

Remove a person from the system.

Required Administrator Roles:

The following administrators have permission to use this API:

Customer Organization:

  • Full administrator

  • User administrator

Partner/External Access:

  • External full administrator

Note: External read-only administrators, provisioning administrators, and device administrators cannot delete users.

Parameters:

person_id – A unique identifier for the person.

Returns:

update(person: Person, calling_data: bool = False, show_all_types: bool = False, min_response: bool = None) → Person[source]

Update a Person

Update details for a person, by ID.

Specify the person ID in the personId parameter in the URI. Only an admin can update a person details.

Include all details for the person. This action expects all user details to be present in the request. A common approach is to first GET the person’s details, make changes, then PUT both the changed and unchanged values.

Admin users can include Webex Calling (BroadCloud) user details in the response by specifying callingData parameter as true.

When doing attendee management, to update a user from host role to an attendee for a site append #attendee to the respective siteUrl and remove the meeting host license for this site from the license array.

To update a person from an attendee role to a host for a site, add the meeting license for this site in the meeting array, and remove that site from the siteurl parameter.

To remove the attendee privilege for a user on a meeting site, remove the sitename#attendee from the siteUrl`s array. The `showAllTypes parameter must be set to true.

NOTE:

  • The locationId can only be set when assigning a calling license to a user. It cannot be changed if a user is already an existing calling user.

  • The extension field should be used to update the Webex Calling extension for a person. The extension value should not include the location routing prefix. The work_extension type in the phoneNumbers object as seen in the response payload of List People or `Get Person Details extension for a person.

  • When updating a user with multiple email addresses using a PUT request, ensure that the primary email address is listed first in the array. Note that the order of email addresses returned by a GET request is not guaranteed..

  • The People API is a combination of several microservices, each responsible for specific attributes of a person. As a result, a PUT request that returns an error response code may still have altered some values of the person’s data. Therefore, it is recommended to perform a GET request after encountering an error to verify the current state of the resource.

  • Some licenses are implicitly assigned by the system and cannot be admin controlled. They are necessary for the baseline function of the Webex system. If you get an error about implicitly assigned licensed that cannot be removed, please ensure you have the corresponding license in your PUT request.

  • When assigning multiple licenses in a single request, the system will assign all valid and available licenses. If any requested licenses cannot be assigned, the operation will continue with the remaining licenses. As a result, it is possible that not all requested licenses are assigned to the user.

Parameters:

  • person (Person) – The person to update

  • calling_data (bool) – Include Webex Calling user details in the response. Default: False

  • show_all_types (bool) – Include additional user data like #attendee role

  • min_response (bool) – Set to true to improve performance by omitting person details in the response. If unsuccessful the response will have optional error details.

Returns:

Person details

Return type:

Person

me(calling_data: bool = False) → Person[source]

Show the profile for the authenticated user. This is the same as GET /people/{personId} using the Person ID associated with your Auth token.

Admin users can include Webex Calling (BroadCloud) user details in the response by specifying callingData parameter as true.

Parameters:

calling_data (bool) – True -> return calling data

Return type:

Person

Returns:

profile of authenticated user

base = 'people'