Cisco Webex People API

openapi: 3.1.0
info:
  title: Cisco Webex Admin Audit Events People API
  description: Access admin audit events for tracking administrative actions performed in Webex Control Hub. Available to full administrators for compliance monitoring and security auditing purposes.
  version: 1.0.0
  contact:
    name: Cisco Webex Developer Support
    url: https://developer.webex.com/support
  license:
    name: Cisco Webex API Terms of Service
    url: https://developer.webex.com/terms-of-service
servers:
- url: https://webexapis.com/v1
  description: Webex Production API
security:
- bearerAuth: []
tags:
- name: People
  description: Operations for managing people and user profiles
paths:
  /people:
    get:
      operationId: listPeople
      summary: Cisco Webex List People
      description: Lists people in the organization. Supports filtering by email, display name, ID, and organization. Results are paginated. Admin users can list people across the organization.
      tags:
      - People
      parameters:
      - name: email
        in: query
        description: Filter by email address. Only exact matches are returned.
        schema:
          type: string
          format: email
      - name: displayName
        in: query
        description: Filter by display name. Supports partial matching.
        schema:
          type: string
      - name: id
        in: query
        description: Filter by person ID. Supports up to 85 IDs, comma-separated.
        schema:
          type: string
      - name: orgId
        in: query
        description: Filter by organization ID.
        schema:
          type: string
      - name: callingData
        in: query
        description: Include Webex Calling user details in the response.
        schema:
          type: boolean
          default: false
      - name: locationId
        in: query
        description: Filter by location ID for Webex Calling users.
        schema:
          type: string
      - name: max
        in: query
        description: Maximum number of people to return (default 100, max 1000).
        schema:
          type: integer
          default: 100
          maximum: 1000
      responses:
        '200':
          description: Successful response with list of people.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Person'
        '401':
          description: Unauthorized - invalid or missing access token.
    post:
      operationId: createPerson
      summary: Cisco Webex Create a Person
      description: Creates a new user account for the organization. Only admins can create people. Newly created accounts require valid email addresses and can be assigned licenses and roles.
      tags:
      - People
      parameters:
      - name: callingData
        in: query
        description: Include Webex Calling user details in the response.
        schema:
          type: boolean
          default: false
      - name: minResponse
        in: query
        description: Only return the person ID on success.
        schema:
          type: boolean
          default: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePersonRequest'
      responses:
        '200':
          description: Person created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Person'
        '400':
          description: Bad request - invalid input parameters.
        '401':
          description: Unauthorized - invalid or missing access token.
  /people/me:
    get:
      operationId: getMyOwnDetails
      summary: Cisco Webex Get My Own Details
      description: Shows the profile for the authenticated user. Use this to confirm identity and retrieve your own person details.
      tags:
      - People
      parameters:
      - name: callingData
        in: query
        description: Include Webex Calling user details in the response.
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Successful response with the authenticated user profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Person'
  /people/{personId}:
    get:
      operationId: getPersonDetails
      summary: Cisco Webex Get Person Details
      description: Shows details for a person by ID. Certain fields may not be available depending on the caller's relationship to the person and admin status.
      tags:
      - People
      parameters:
      - name: personId
        in: path
        required: true
        description: Unique identifier for the person.
        schema:
          type: string
      - name: callingData
        in: query
        description: Include Webex Calling user details in the response.
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Successful response with person details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Person'
        '404':
          description: Person not found.
    put:
      operationId: updatePerson
      summary: Cisco Webex Update a Person
      description: Updates details for a person by ID. Only admins can update people. Include all desired fields in the request body as the update replaces the existing record.
      tags:
      - People
      parameters:
      - name: personId
        in: path
        required: true
        description: Unique identifier for the person.
        schema:
          type: string
      - name: callingData
        in: query
        description: Include Webex Calling user details in the response.
        schema:
          type: boolean
          default: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePersonRequest'
      responses:
        '200':
          description: Person updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Person'
        '400':
          description: Bad request - invalid input parameters.
        '404':
          description: Person not found.
    delete:
      operationId: deletePerson
      summary: Cisco Webex Delete a Person
      description: Removes a person from the system. Only admins can delete people. The deleted person will lose access to Webex services.
      tags:
      - People
      parameters:
      - name: personId
        in: path
        required: true
        description: Unique identifier for the person.
        schema:
          type: string
      responses:
        '204':
          description: Person deleted successfully.
        '404':
          description: Person not found.
components:
  schemas:
    UpdatePersonRequest:
      type: object
      properties:
        emails:
          type: array
          items:
            type: string
            format: email
        displayName:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        avatar:
          type: string
          format: uri
        orgId:
          type: string
        roles:
          type: array
          items:
            type: string
        licenses:
          type: array
          items:
            type: string
        department:
          type: string
        manager:
          type: string
        managerId:
          type: string
        title:
          type: string
        addresses:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              streetAddress:
                type: string
              locality:
                type: string
              region:
                type: string
              postalCode:
                type: string
              country:
                type: string
        phoneNumbers:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              value:
                type: string
        extension:
          type: string
        locationId:
          type: string
        loginEnabled:
          type: boolean
    Person:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the person.
        emails:
          type: array
          description: Email addresses of the person.
          items:
            type: string
            format: email
        phoneNumbers:
          type: array
          description: Phone numbers of the person.
          items:
            type: object
            properties:
              type:
                type: string
                description: Phone number type.
              value:
                type: string
                description: Phone number value.
        sipAddresses:
          type: array
          description: SIP addresses of the person.
          items:
            type: object
            properties:
              type:
                type: string
              value:
                type: string
              primary:
                type: boolean
        extension:
          type: string
          description: Webex Calling extension number.
        locationId:
          type: string
          description: Location ID for Webex Calling.
        displayName:
          type: string
          description: Full name of the person.
        nickName:
          type: string
          description: Nickname of the person.
        firstName:
          type: string
          description: First name of the person.
        lastName:
          type: string
          description: Last name of the person.
        avatar:
          type: string
          format: uri
          description: URL to the person's avatar image.
        orgId:
          type: string
          description: Organization ID the person belongs to.
        roles:
          type: array
          description: Roles assigned to the person.
          items:
            type: string
        licenses:
          type: array
          description: Licenses assigned to the person.
          items:
            type: string
        department:
          type: string
          description: Department of the person.
        manager:
          type: string
          description: Manager name of the person.
        managerId:
          type: string
          description: Person ID of the manager.
        title:
          type: string
          description: Job title of the person.
        addresses:
          type: array
          description: Physical addresses of the person.
          items:
            type: object
            properties:
              type:
                type: string
              streetAddress:
                type: string
              locality:
                type: string
              region:
                type: string
              postalCode:
                type: string
              country:
                type: string
        created:
          type: string
          format: date-time
          description: Date and time the person was created.
        lastModified:
          type: string
          format: date-time
          description: Date and time the person was last modified.
        timezone:
          type: string
          description: Time zone of the person.
        lastActivity:
          type: string
          format: date-time
          description: Date and time of the person's last activity.
        siteUrls:
          type: array
          description: Webex site URLs associated with the person.
          items:
            type: string
        status:
          type: string
          description: Current presence status.
          enum:
          - active
          - call
          - DoNotDisturb
          - inactive
          - meeting
          - OutOfOffice
          - pending
          - presenting
          - unknown
        type:
          type: string
          description: Person type.
          enum:
          - person
          - bot
          - appuser
        invitePending:
          type: boolean
          description: Whether the invite is pending acceptance.
        loginEnabled:
          type: boolean
          description: Whether the person's login is enabled.
    CreatePersonRequest:
      type: object
      required:
      - emails
      properties:
        emails:
          type: array
          description: Email addresses for the person.
          items:
            type: string
            format: email
        phoneNumbers:
          type: array
          description: Phone numbers for the person.
          items:
            type: object
            properties:
              type:
                type: string
              value:
                type: string
        extension:
          type: string
          description: Webex Calling extension.
        locationId:
          type: string
          description: Location ID for Webex Calling.
        displayName:
          type: string
          description: Full name of the person.
        firstName:
          type: string
          description: First name.
        lastName:
          type: string
          description: Last name.
        avatar:
          type: string
          format: uri
          description: URL to the avatar image.
        orgId:
          type: string
          description: Organization ID.
        roles:
          type: array
          description: Roles to assign.
          items:
            type: string
        licenses:
          type: array
          description: Licenses to assign.
          items:
            type: string
        department:
          type: string
          description: Department.
        manager:
          type: string
          description: Manager name.
        managerId:
          type: string
          description: Person ID of the manager.
        title:
          type: string
          description: Job title.
        addresses:
          type: array
          description: Physical addresses.
          items:
            type: object
            properties:
              type:
                type: string
              streetAddress:
                type: string
              locality:
                type: string
              region:
                type: string
              postalCode:
                type: string
              country:
                type: string
        siteUrls:
          type: array
          description: Webex site URLs.
          items:
            type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Webex API access token. Obtain via OAuth 2.0 authorization flow. Requires audit:events_read scope.