wxc_sdk.people package

People types and API

As of January 2024, the Webex APIs have been fully upgraded to support the industry-standard SCIM2.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 can 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.

class wxc_sdk.people.PhoneNumberType(value=<no_arg>, names=None, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: str, SafeEnum

Webex phone number type

work = 'work'

mobile = 'mobile'

fax = 'fax'

work_extension = 'work_extension'

enterprise = 'enterprise'

alternate1 = 'alternate1'

alternate2 = 'alternate2'

class wxc_sdk.people.PhoneNumber(*, type: PhoneNumberType, value: str, primary: bool | None = None)

Bases: ApiModel

Webex phone number: type and Value

number_type: PhoneNumberType

value: str

primary: bool | None

class wxc_sdk.people.SipType(value=<no_arg>, names=None, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: str, SafeEnum

SIP address type

enterprise = 'enterprise'

cloudCalling = 'cloud-calling'

personalRoom = 'personal-room'

unknown = 'unknown'

class wxc_sdk.people.SipAddress(*, type: SipType, value: str, primary: bool)

Bases: ApiModel

SIP address: type, value and primary indication

sip_type: SipType

value: str

primary: bool

class wxc_sdk.people.PeopleStatus(value=<no_arg>, names=None, module=None, qualname=None, type=None, start=1, boundary=None)

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'

last activity occurred more than 10 minutes ago

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(value=<no_arg>, names=None, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: str, SafeEnum

An enumeration.

person = 'person'

account belongs to a person

bot = 'bot'

account is a bot user

app_user = '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)

Bases: ApiModel

type: str | None

The type of address Possible values: work

country: str | None

The user’s country Possible values: US

locality: str | None

the user’s locality, often city Possible values: Milpitas

region: str | None

the user’s region, often state Possible values: California

street_address: str | None

the user’s street Possible values: 1099 Bird Ave.

postal_code: str | None

the user’s postal or zip code Possible values: 99212

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)

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 = None)

Bases: ApiChild

People

As of January 2024, the Webex APIs have been fully upgraded to support the industry-standard SCIM2.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 can 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 = None, display_name: str | None = None, id_list: list[str] | None = None, org_id: str | None = None, roles: str | None = None, calling_data: bool | None = None, location_id: str | None = None, **params) → Generator[Person, None, None]

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.

Returns:

yield Person instances

create(settings: Person, calling_data: bool = False, min_response: bool | None = None) → Person

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.

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

Shows details for a person, by ID.

Response properties associated with a user’s presence status, such as status or last_activity, 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 calling_data 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)

Remove a person from the system. Only an admin can remove a person.

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 = None) → 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.

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

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 siteUrls array. The showAllTypes parameter must be set to true.

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

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'