openapi: 3.0.0
info:
title: Webex Admin Address Book Subscriptions API
version: 1.0.0
description: The Webex Admin APIs provide comprehensive programmatic access to administrative functions for managing Webex organizations, users, licenses, and settings. These APIs enable automation of user provisioning, license assignment, compliance management, and audit event retrieval. Administrators can integrate with enterprise identity systems, enforce security policies, monitor usage, and streamline onboarding/offboarding processes. The APIs support granular control over organizational resources, making them ideal for large-scale deployments and custom admin tooling.
tags:
- name: Subscriptions
paths:
/v1/subscriptions:
get:
tags:
- Subscriptions
summary: List Subscriptions
description: "Retrieve all subscriptions for a given organization. Requires `cjp:config_read` scope.\n\n\n Note: In the response JSON, the 'data' field only contains V1 based subscriptions, while the field 'meta.subscriptionCount' provides the total count encompassing all the created subscriptions in the organization."
operationId: getSubscriptionByOrgId
parameters:
- name: orgId
in: query
description: Organization ID to be used for this operation. If unspecified, the Organization ID is inferred from the token. The token must have permissions to interact with the organization.
required: false
schema:
type: string
example: 97cdbf45-ebe2-4687-8341-44d5c7abf101
- name: TrackingId
in: header
description: Tracking ID to use for this operation, for traceability, debugging, and error reporting purposes. If not provided, we will generate one for you.
required: false
schema:
type: string
example: NOTIFS_9bcdc696-57fa-4e91-b5aa-57a66a347c23
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SubscriptionApiListResponse'
'400':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
'401':
description: Unauthorized Operation
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
'403':
description: Forbidden Operation
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
'500':
description: An Unexpected Error Occurred
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
post:
tags:
- Subscriptions
summary: Register Subscription
description: Create a subscription which would allow consumers to listen to events. If creating a subscription causes the org-level limit to be exceeded, the subscription registration will be denied. Requires `cjp:config_write` scope.
operationId: createSubscription
parameters:
- name: TrackingId
in: header
description: Tracking ID to use for this operation, for traceability, debugging, and error reporting purposes. If not provided, we will generate one for you.
required: false
schema:
type: string
example: NOTIFS_9bcdc696-57fa-4e91-b5aa-57a66a347c23
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SubscriptionRequest'
required: true
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/SubscriptionCreateApiResponse'
'400':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
'401':
description: Unauthorized Operation
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
'403':
description: Forbidden Operation
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
'500':
description: An Unexpected Error Occurred
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
/v1/subscriptions/{id}:
get:
tags:
- Subscriptions
summary: Get Subscription
description: Retrieve a subscription for a given subscription ID. Requires `cjp:config_read` scope.
operationId: getSubscriptionById
parameters:
- name: id
in: path
required: true
schema:
type: string
description: ID by which to retrieve the subscription.
format: uuid
example: 10b4079b-5162-4526-b6a4-4472734fb69b
- name: orgId
in: query
description: Organization ID to be used for this operation. If unspecified, the Organization ID is inferred from the token. The token must have permissions to interact with the organization.
required: false
schema:
type: string
example: 97cdbf45-ebe2-4687-8341-44d5c7abf101
- name: TrackingId
in: header
description: Tracking ID to use for this operation, for traceability, debugging, and error reporting purposes. If not provided, we will generate one for you.
required: false
schema:
type: string
example: NOTIFS_9bcdc696-57fa-4e91-b5aa-57a66a347c23
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SubscriptionApiResponse'
'400':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
'401':
description: Unauthorized Operation
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
'403':
description: Forbidden Operation
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
'500':
description: An Unexpected Error Occurred
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
delete:
tags:
- Subscriptions
summary: Delete Subscription
description: Deletes a subscription for a given subscription ID. Requires `cjp:config_write` scope.
operationId: deleteSubscriptionById
parameters:
- name: id
in: path
required: true
schema:
type: string
description: ID of the subscription to be deleted.
format: uuid
example: 10b4079b-5162-4526-b6a4-4472734fb69b
- name: orgId
in: query
description: Organization ID to be used for this operation. If unspecified, the Organization ID is inferred from the token. The token must have permissions to interact with the organization.
required: false
schema:
type: string
example: 97cdbf45-ebe2-4687-8341-44d5c7abf101
- name: TrackingId
in: header
description: Tracking ID to use for this operation, for traceability, debugging, and error reporting purposes. If not provided, we will generate one for you.
required: false
schema:
type: string
example: NOTIFS_9bcdc696-57fa-4e91-b5aa-57a66a347c23
responses:
'204':
description: No Content
'400':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
'401':
description: Unauthorized Operation
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
'403':
description: Forbidden Operation
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
'500':
description: An Unexpected Error Occurred
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
patch:
tags:
- Subscriptions
summary: Update Subscription
description: Updates some of the properties in a subscription, for a given subscription ID. Requires `cjp:config_write` scope.
operationId: updateSubscriptionById
parameters:
- name: id
in: path
required: true
schema:
type: string
description: ID of the subscription to be updated.
format: uuid
example: 10b4079b-5162-4526-b6a4-4472734fb69b
- name: TrackingId
in: header
description: Tracking ID to use for this operation, for traceability, debugging, and error reporting purposes. If not provided, we will generate one for you.
required: false
schema:
type: string
example: NOTIFS_9bcdc696-57fa-4e91-b5aa-57a66a347c23
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SubscriptionRequestUpdate'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SubscriptionApiResponse'
'400':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
'401':
description: Unauthorized Operation
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
'403':
description: Forbidden Operation
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
'500':
description: An Unexpected Error Occurred
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
/v1/event-types:
get:
tags:
- Subscriptions
summary: List Event Types
description: Retrieve all available event types for an organization. Requires `cjp:config_read` scope.
operationId: getAllEventTypes
parameters:
- name: orgId
in: query
description: Organization ID to be used for this operation. If unspecified, the Organization ID is inferred from the token. The token must have permissions to interact with the organization.
required: false
schema:
type: string
example: 97cdbf45-ebe2-4687-8341-44d5c7abf101
- name: TrackingId
in: header
description: Tracking ID to use for this operation, for traceability, debugging, and error reporting purposes. If not provided, we will generate one for you.
required: false
schema:
type: string
example: NOTIFS_9bcdc696-57fa-4e91-b5aa-57a66a347c23
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EventTypesApiListResponse'
'400':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
'401':
description: Unauthorized Operation
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
'403':
description: Forbidden Operation
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
'500':
description: An Unexpected Error Occurred
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
/v2/subscriptions:
get:
tags:
- Subscriptions
summary: List Subscriptions
description: "Retrieve all subscriptions for a given organization. Requires `cjp:config_read` scope.\n\n\n Note: In the response JSON, the 'data' field only contains V2 based subscriptions, while the field 'meta.subscriptionCount' provides the total count encompassing all the created subscriptions in the organization."
operationId: getSubscriptionByOrgIdV2
parameters:
- name: orgId
in: query
description: Organization ID to be used for this operation. If unspecified, the Organization ID is inferred from the token. The token must have permissions to interact with the organization.
required: false
schema:
type: string
example: 97cdbf45-ebe2-4687-8341-44d5c7abf101
- name: TrackingId
in: header
description: Tracking ID to use for this operation, for traceability, debugging, and error reporting purposes. If not provided, we will generate one for you.
required: false
schema:
type: string
example: NOTIFS_9bcdc696-57fa-4e91-b5aa-57a66a347c23
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SubscriptionApiListResponseEnhanced'
'400':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
'401':
description: Unauthorized Operation
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
'403':
description: Forbidden Operation
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
'500':
description: An Unexpected Error Occurred
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
post:
tags:
- Subscriptions
summary: Register Subscription
description: Create a subscription which would allow consumers to listen to events. If creating a subscription causes the org-level limit to be exceeded, the subscription registration will be denied. Requires `cjp:config_write` scope.
operationId: createSubscriptionWithV2
parameters:
- name: TrackingId
in: header
description: Tracking ID to use for this operation, for traceability, debugging, and error reporting purposes. If not provided, we will generate one for you.
required: false
schema:
type: string
example: NOTIFS_9bcdc696-57fa-4e91-b5aa-57a66a347c23
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SubscriptionRequestEnhanced'
required: true
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/SubscriptionCreateApiResponseEnhanced'
'400':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
'401':
description: Unauthorized Operation
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
'403':
description: Forbidden Operation
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
'500':
description: An Unexpected Error Occurred
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
/v2/subscriptions/{id}:
get:
tags:
- Subscriptions
summary: Get Subscription
description: Retrieve a subscription for a given subscription ID. Requires `cjp:config_read` scope.
operationId: getSubscriptionByIdV2
parameters:
- name: id
in: path
required: true
schema:
type: string
description: ID by which to retrieve the subscription.
format: uuid
example: 10b4079b-5162-4526-b6a4-4472734fb69b
- name: orgId
in: query
description: Organization ID to be used for this operation. If unspecified, the Organization ID is inferred from the token. The token must have permissions to interact with the organization.
required: false
schema:
type: string
example: 97cdbf45-ebe2-4687-8341-44d5c7abf101
- name: TrackingId
in: header
description: Tracking ID to use for this operation, for traceability, debugging, and error reporting purposes. If not provided, we will generate one for you.
required: false
schema:
type: string
example: NOTIFS_9bcdc696-57fa-4e91-b5aa-57a66a347c23
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SubscriptionApiResponseEnhanced'
'400':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
'401':
description: Unauthorized Operation
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
'403':
description: Forbidden Operation
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
'500':
description: An Unexpected Error Occurred
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
delete:
tags:
- Subscriptions
summary: Delete Subscription
description: Deletes a subscription for a given subscription ID. Requires `cjp:config_write` scope.
operationId: deleteSubscriptionByIdV2
parameters:
- name: id
in: path
required: true
schema:
type: string
description: ID of the subscription to be deleted.
format: uuid
example: 10b4079b-5162-4526-b6a4-4472734fb69b
- name: orgId
in: query
description: Organization ID to be used for this operation. If unspecified, the Organization ID is inferred from the token. The token must have permissions to interact with the organization.
required: false
schema:
type: string
example: 97cdbf45-ebe2-4687-8341-44d5c7abf101
- name: TrackingId
in: header
description: Tracking ID to use for this operation, for traceability, debugging, and error reporting purposes. If not provided, we will generate one for you.
required: false
schema:
type: string
example: NOTIFS_9bcdc696-57fa-4e91-b5aa-57a66a347c23
responses:
'204':
description: No Content
'400':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
'401':
description: Unauthorized Operation
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
'403':
description: Forbidden Operation
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
'500':
description: An Unexpected Error Occurred
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
patch:
tags:
- Subscriptions
summary: Update Subscription
description: Updates some of the properties in a subscription, for a given subscription ID. Requires `cjp:config_write` scope.
operationId: updateSubscriptionByIdWithV2
parameters:
- name: id
in: path
required: true
schema:
type: string
description: ID of the subscription to be updated.
format: uuid
example: 10b4079b-5162-4526-b6a4-4472734fb69b
- name: TrackingId
in: header
description: Tracking ID to use for this operation, for traceability, debugging, and error reporting purposes. If not provided, we will generate one for you.
required: false
schema:
type: string
example: NOTIFS_9bcdc696-57fa-4e91-b5aa-57a66a347c23
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SubscriptionRequestUpdateEnhanced'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SubscriptionApiResponseEnhanced'
'400':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
'401':
description: Unauthorized Operation
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
'403':
description: Forbidden Operation
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
'500':
description: An Unexpected Error Occurred
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
/v2/event-types:
get:
tags:
- Subscriptions
summary: List Event Types
description: 'Retrieve all available event types for an organization along with information about the currently supported resource versions. Requires `cjp:config_read` scope. '
operationId: getAllEventTypesWithResourceVersionMetadata
parameters:
- name: orgId
in: query
description: Organization ID to be used for this operation. If unspecified, the Organization ID is inferred from the token. The token must have permissions to interact with the organization.
required: false
schema:
type: string
example: 97cdbf45-ebe2-4687-8341-44d5c7abf101
- name: TrackingId
in: header
description: Tracking ID to use for this operation, for traceability, debugging, and error reporting purposes. If not provided, we will generate one for you.
required: false
schema:
type: string
example: NOTIFS_9bcdc696-57fa-4e91-b5aa-57a66a347c23
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EventTypesApiListResponseEnhanced'
'400':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
'401':
description: Unauthorized Operation
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
'403':
description: Forbidden Operation
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
'500':
description: An Unexpected Error Occurred
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
components:
schemas:
MetaResourceVersionInfo:
required:
- resourceVersionList
type: object
properties:
orgId:
type: string
description: Organization ID used for this operation.
format: uuid
example: 97cdbf45-ebe2-4687-8341-44d5c7abf101
resourceVersionList:
type: array
description: List of all resources, and it's supported versions available to subscribe.
items:
$ref: '#/components/schemas/ResourceVersion'
MetaSubInfo:
properties:
orgId:
description: Organization ID used for this operation.
example: 97cdbf45-ebe2-4687-8341-44d5c7abf101
format: uuid
type: string
type: object
SubscriptionResponseEnhanced:
required:
- createdBy
- createdTime
- destinationUrl
- eventTypes
- id
- lastUpdatedBy
- lastUpdatedTime
- name
- resourceVersion
- status
type: object
properties:
id:
type: string
description: Subscription ID.
format: uuid
example: 41e92806-331d-4802-bc12-674f92d4a6f7
name:
maxLength: 64
minLength: 4
type: string
description: Client-defined string naming the subscription.
example: My Integration's Subscription
description:
maxLength: 1024
type: string
description: Client-defined string describing the subscription.
example: The subscription my integration uses to synchronize with WxCC
eventTypes:
maxItems: 32
minItems: 1
type: array
description: Types of events to which the subscription will listen.
example:
- agent:login
- agent:logout
items:
type: string
destinationUrl:
type: string
description: URL to which webhooks will be posted. Must be HTTPS on an IANA-listed top-level domain name (e.g. .com) with a path (at least /). No query parameters, userinfo, non-443 ports, or fragments allowed. We do not treat this field as sensitive data, so do not use secrets in this URL such as tokens or API keys.
format: uri
example: https://www.cisco.com/
createdTime:
type: integer
description: Time when subscription was created (epoch milliseconds).
format: int64
example: 1591702170000
createdBy:
type: string
description: Email address of the user who created the subscription.
format: email
example: example@example.com
status:
type: string
description: Status of the subscription. Can be "active" or "inactive". The system may change the status to "inactive" in error scenarios.
example: active
enum:
- active
- inactive
lastUpdatedTime:
type: integer
description: Time when the subscription was last updated (epoch milliseconds).
format: int64
example: 1591702170000
lastUpdatedBy:
type: string
description: Email address of the user who updated the subscription most recently.
format: email
example: example@example.com
resourceVersion:
maxLength: 50
minLength: 1
type: string
description: Version of the resource.
example: agent:1.0.0
SubscriptionApiListResponseEnhanced:
required:
- data
- meta
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/SubscriptionResponseEnhanced'
meta:
$ref: '#/components/schemas/MetaSubInfo'
Meta:
type: object
properties:
orgId:
type: string
description: Organization ID to which resources belong.
example: 3dae8fdd-06e2-411a-9035-51f3719f5b65
description: Response metadata.
Error:
required:
- key
type: object
properties:
key:
type: integer
description: Status code of error.
format: int32
example: 400
message:
type: array
items:
$ref: '#/components/schemas/FieldValidationError'
SubscriptionApiResponseEnhanced:
type: object
properties:
meta:
$ref: '#/components/schemas/Meta'
data:
$ref: '#/components/schemas/SubscriptionResponseEnhanced'
SubscriptionCreateApiResponseEnhanced:
type: object
properties:
meta:
$ref: '#/components/schemas/MetaSubInfo'
data:
$ref: '#/components/schemas/SubscriptionResponseEnhanced'
SubscriptionApiListResponse:
required:
- data
- meta
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/SubscriptionResponse'
meta:
$ref: '#/components/schemas/MetaSubInfo'
ResourceVersion:
type: object
properties:
resource:
type: string
description: Resource name.
example: agent
version:
type: string
description: Version of the resource.
example: 1.0.0
description: List of all resources, and it's supported versions available to subscribe.
EventTypesApiListResponseEnhanced:
required:
- data
- meta
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/EventTypesResponse'
meta:
$ref: '#/components/schemas/MetaResourceVersionInfo'
SubscriptionRequestUpdateEnhanced:
required:
- resourceVersion
type: object
properties:
description:
maxLength: 1024
minLength: 0
type: string
description: Client-defined string describing the subscription.
example: The subscription my integration uses to synchronize with WxCC
eventTypes:
maxItems: 32
minItems: 1
type: array
description: Types of events to which the subscription will listen.
example:
- agent:login
- agent:logout
items:
type: string
destinationUrl:
pattern: ^(https?)://.*$
type: string
description: URL to which webhooks will be posted. Must be HTTPS on an IANA-listed top-level domain name (e.g. .com) with a path (at least /). No query parameters, userinfo, non-443 ports, or fragments allowed. We do not treat this field as sensitive data, so do not use secrets in this URL such as tokens or API keys.
format: uri
example: https://www.cisco.com/
status:
pattern: (active|inactive)
type: string
description: Status of the subscription. Can be "active" or "inactive". The system may change the status to "inactive" in error scenarios.
example: inactive
enum:
- active
- inactive
secret:
maxLength: 256
minLength: 32
type: string
description: Secret string used to sign payloads sent to the destination URL.
example: my-32-plus-character-long-secret
orgId:
type: string
description: Organization ID to be used for this operation. If unspecified, the Organization ID is inferred from the token. The token must have permission to interact with the organization.
format: uuid
example: 97cdbf45-ebe2-4687-8341-44d5c7abf101
resourceVersion:
maxLength: 50
minLength: 1
type: string
description: Represents vers
# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/webex/refs/heads/main/openapi/webex-subscriptions-api-openapi.yml