openapi: 3.0.0
info:
title: Webex Admin Address Book Organization Contacts 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: Organization Contacts
paths:
/contacts/organizations/{orgId}/contacts:
post:
responses:
'201':
description: Created
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ContactResponse'
example:
schemas: urn:cisco:codev:identity:contact:core:1.0
meta:
created: '2023-05-10T09:24:44.910Z'
lastModified: '2023-05-10T09:24:44.910Z'
contactId: 933de120-ad46-49b0-91cc-65c3966bb14e
firstName: Simic
lastName: Zhang
companyName: Cisco Systems
title: Product Manager
address: '{"city" : "Milpitas", "country" : "US", "street" : "1099 Bird Ave.", "zipCode" : "99212"}'
avatarURL: https://avatar-prod-us-east-2.webexcontent.com/default_avatar~1600
displayName: Logan
addressInfo:
city: Milpitas
country: US
street: 1099 Bird Ave.
zipCode: '99212'
primaryContactMethod: EMAIL
phoneNumbers:
- type: work
value: '20134319'
emails:
- type: work
value: simizhan@example.com
sipAddresses:
- type: work
value: sip://mysip1231233
ims:
- type: work
value: '87003922'
source: CH
isMigration: false
orgId: 153ced48-d2d1-4369-86fd-9b9fade218ff
groupIds:
- b3e594aa-19ea-488a-9d42-f811e272f4bd
'400':
description: 'Bad Request: The request was invalid or cannot be otherwise served. An accompanying error message will explain further.'
'401':
description: 'Unauthorized: Authentication credentials were missing or incorrect.'
'403':
description: 'Forbidden: The request is understood, but it has been refused or access is not allowed.'
'404':
description: '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':
description: 'Method Not Allowed: The request was made to a resource using an HTTP request method that is not supported.'
'409':
description: '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':
description: 'Gone: The requested resource is no longer available.'
'415':
description: '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':
description: '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':
description: 'Precondition Required: File(s) cannot be scanned for malware and need to be force downloaded.'
'429':
description: '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':
description: 'Internal Server Error: Something went wrong on the server. If the issue persists, feel free to contact the [Webex Developer Support team](/explore/support).'
'502':
description: 'Bad Gateway: The server received an invalid response from an upstream server while processing the request. Try again later.'
'503':
description: 'Service Unavailable: Server is overloaded with requests. Try again later.'
'504':
description: 'Gateway Timeout: An upstream server failed to respond on time. If your query uses max parameter, please try to reduce it.'
summary: Create a Contact
operationId: Create a Contact
description: 'Creating a new contact for a given organization requires an org admin role.
At least one of the following body parameters: `phoneNumbers`, `emails`, `sipAddresses` is required to create a new contact for source "CH",
`displayName` is required to create a new contact for source "Webex4Broadworks".
Use the optional `groupIds` field to add group IDs in an array within the organisation contact. This will become a group contact.'
tags:
- Organization Contacts
parameters:
- name: orgId
in: path
description: Webex Identity assigned organization identifier for the user's organization or the organization he manages.
required: true
example: 0ae87ade-8c8a-4952-af08-318798958d0c
schema:
type: string
requestBody:
content:
application/json:
example:
schemas: urn:cisco:codev:identity:contact:core:1.0
displayName: John Andersen
firstName: John
lastName: Andersen
companyName: Cisco Systems
title: GM
address: '{\"city\" : \"Milpitas\", \"country\" : \"US\", \"street\" : \"1099 Bird Ave.\", \"zipCode\" : \"99212\"}'
avatarURL: https://avatar-prod-us-east-2.webexcontent.com/default_avatar~1600
primaryContactMethod: SIPADDRESS
source: Webex4Broadworks
emails:
- value: user1@example.home.com
type: home
primary: false
phoneNumbers:
- value: 400 123 1234
type: work
primary: true
sipAddresses:
- value: sipAddress value1
type: enterprise
primary: true
ims:
- value: aim_account_ID
type: aim
primary: true
groupIds:
- 9ac175bf-0249-4287-8fb3-e320e525fcf6
schema:
$ref: '#/components/schemas/Contact'
/contacts/organizations/{orgId}/contacts/{contactId}:
get:
responses:
'200':
description: OK
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ContactResponse'
example:
schemas: urn:cisco:codev:identity:contact:core:1.0
meta:
created: '2023-05-11T02:55:25.460Z'
lastModified: '2023-05-11T02:55:25.460Z'
contactId: 6847ee0f-5e9c-4403-9f0e-0aa8552f7829
firstName: Simic
lastName: Zhang
companyName: Cisco Systems
title: Product Manager
address: '{"city" : "Milpitas", "country" : "US", "street" : "1099 Bird Ave.", "zipCode" : "99212"}'
avatarURL: https://avatar-prod-us-east-2.webexcontent.com/default_avatar~1600
displayName: Logan
addressInfo:
city: Milpitas
country: US
street: 1099 Bird Ave.
zipCode: '99212'
primaryContactMethod: EMAIL
phoneNumbers:
- type: work
value: '20134319'
emails:
- type: work
value: simizhan@example.com
sipAddresses:
- type: work
value: sip://mysip1231233
ims:
- type: work
value: '87003922'
source: CH
isMigration: false
orgId: d23736ac-8055-433e-b85a-0fc55c96ead9
groupIds:
- b3e594aa-19ea-488a-9d42-f811e272f4bd
'400':
description: 'Bad Request: The request was invalid or cannot be otherwise served. An accompanying error message will explain further.'
'401':
description: 'Unauthorized: Authentication credentials were missing or incorrect.'
'403':
description: 'Forbidden: The request is understood, but it has been refused or access is not allowed.'
'404':
description: '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':
description: 'Method Not Allowed: The request was made to a resource using an HTTP request method that is not supported.'
'409':
description: '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':
description: 'Gone: The requested resource is no longer available.'
'415':
description: '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':
description: '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':
description: 'Precondition Required: File(s) cannot be scanned for malware and need to be force downloaded.'
'429':
description: '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':
description: 'Internal Server Error: Something went wrong on the server. If the issue persists, feel free to contact the [Webex Developer Support team](/explore/support).'
'502':
description: 'Bad Gateway: The server received an invalid response from an upstream server while processing the request. Try again later.'
'503':
description: 'Service Unavailable: Server is overloaded with requests. Try again later.'
'504':
description: 'Gateway Timeout: An upstream server failed to respond on time. If your query uses max parameter, please try to reduce it.'
summary: Get a Contact
operationId: Get a Contact
description: 'Shows details for an organization contact by ID.
Specify the organization ID in the `orgId` parameter in the URI, and specify the contact ID in the `contactId` parameter in the URI.
**NOTE**:
The `orgId` used in the path for this API are the org UUIDs. They follow a xxxx-xxxx-xxxx-xxxx pattern. If you have an orgId in base64 encoded format (starting with Y2.....) you need to base64 decode the id and extract the UUID from the slug, before you use it in your API call.'
tags:
- Organization Contacts
parameters:
- name: orgId
in: path
description: Webex Identity assigned organization identifier for the user's organization or the organization he manages.
required: true
example: d23736ac-8055-433e-b85a-0fc55c96ead8
schema:
type: string
- name: contactId
in: path
description: The contact ID.
required: true
example: 6847ee0f-5e9c-4403-9f0e-0aa8552f7828
schema:
type: string
patch:
responses:
'200':
description: OK
headers: {}
content:
application/json:
schema:
type: object
properties:
schemas:
type: string
meta:
type: object
properties:
created:
type: string
lastModified:
type: string
contactId:
type: string
firstName:
type: string
lastName:
type: string
companyName:
type: string
title:
type: string
address:
type: string
avatarURL:
type: string
displayName:
type: string
addressInfo:
type: object
properties:
city:
type: string
country:
type: string
street:
type: string
zipCode:
type: string
primaryContactMethod:
type: string
phoneNumbers:
type: array
items:
type: object
properties:
type:
type: string
value:
type: string
emails:
type: array
items:
type: object
properties:
type:
type: string
value:
type: string
sipAddresses:
type: array
items:
type: object
properties:
type:
type: string
value:
type: string
ims:
type: array
items:
type: object
properties:
type:
type: string
value:
type: string
source:
type: string
isMigration:
type: boolean
orgId:
type: string
groupIds:
type: array
items:
type: string
example:
schemas: urn:cisco:codev:identity:contact:core:1.0
meta:
created: '2023-05-11T02:55:25.460Z'
lastModified: '2023-05-11T02:55:25.460Z'
contactId: 6847ee0f-5e9c-4403-9f0e-0aa8552f7829
firstName: Simic
lastName: Zhang
companyName: Cisco Systems
title: Product Manager
address: '{"city" : "Milpitas", "country" : "US", "street" : "1099 Bird Ave.", "zipCode" : "99212"}'
avatarURL: https://avatar-prod-us-east-2.webexcontent.com/default_avatar~1600
displayName: Logan
addressInfo:
city: Milpitas
country: US
street: 1099 Bird Ave.
zipCode: '99212'
primaryContactMethod: EMAIL
phoneNumbers:
- type: work
value: '20134319'
emails:
- type: work
value: simizhan@example.com
sipAddresses:
- type: work
value: sip://mysip1231233
ims:
- type: work
value: '87003922'
source: CH
isMigration: false
orgId: d23736ac-8055-433e-b85a-0fc55c96ead9
groupIds:
- b3e594aa-19ea-488a-9d42-f811e272f4bd
'400':
description: 'Bad Request: The request was invalid or cannot be otherwise served. An accompanying error message will explain further.'
'401':
description: 'Unauthorized: Authentication credentials were missing or incorrect.'
'403':
description: 'Forbidden: The request is understood, but it has been refused or access is not allowed.'
'404':
description: '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':
description: 'Method Not Allowed: The request was made to a resource using an HTTP request method that is not supported.'
'409':
description: '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':
description: 'Gone: The requested resource is no longer available.'
'415':
description: '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':
description: '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':
description: 'Precondition Required: File(s) cannot be scanned for malware and need to be force downloaded.'
'429':
description: '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':
description: 'Internal Server Error: Something went wrong on the server. If the issue persists, feel free to contact the [Webex Developer Support team](/explore/support).'
'502':
description: 'Bad Gateway: The server received an invalid response from an upstream server while processing the request. Try again later.'
'503':
description: 'Service Unavailable: Server is overloaded with requests. Try again later.'
'504':
description: 'Gateway Timeout: An upstream server failed to respond on time. If your query uses max parameter, please try to reduce it.'
summary: Update a Contact
operationId: Update a Contact
description: 'Update details for contact by ID. Only an admin can update a contact.
Specify the organization ID in the `orgId` parameter in the URI, and specify the contact ID in the `contactId` parameter in the URI.
Use the optional `groupIds` field to update the group IDs by changing the existing array. You can add or remove one or all groups. To remove all associated groups, pass an empty array in the `groupIds` field.'
tags:
- Organization Contacts
parameters:
- name: orgId
in: path
description: Webex Identity assigned organization identifier for the user's organization or the organization he manages.
required: true
example: d23736ac-8055-433e-b85a-0fc55c96ead8
schema:
type: string
- name: contactId
in: path
description: The contact ID.
required: true
example: 6847ee0f-5e9c-4403-9f0e-0aa8552f7828
schema:
type: string
requestBody:
content:
application/json:
example:
schemas: urn:cisco:codev:identity:contact:core:1.0
displayName: John Andersen
firstName: John
lastName: Andersen
companyName: Cisco Systems
title: GM
address: '{\"city\" : \"Milpitas\", \"country\" : \"US\", \"street\" : \"1099 Bird Ave.\", \"zipCode\" : \"99212\"}'
avatarURL: https://avatar-prod-us-east-2.webexcontent.com/default_avatar~1600
primaryContactMethod: SIPADDRESS
source: Webex4Broadworks
emails:
- value: user1@example.home.com
type: home
primary: false
phoneNumbers:
- value: 400 123 1234
type: work
primary: true
operation: delete
sipAddresses:
- value: sipAddress value1
type: enterprise
primary: true
ims:
- value: aim_account_ID
type: aim
primary: true
groupIds:
- 9ac175bf-0249-4287-8fb3-e320e525fcf6
schema:
$ref: '#/components/schemas/UpdateContact'
delete:
responses:
'204':
description: No Content
headers: {}
content: {}
'400':
description: 'Bad Request: The request was invalid or cannot be otherwise served. An accompanying error message will explain further.'
'401':
description: 'Unauthorized: Authentication credentials were missing or incorrect.'
'403':
description: 'Forbidden: The request is understood, but it has been refused or access is not allowed.'
'404':
description: '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':
description: 'Method Not Allowed: The request was made to a resource using an HTTP request method that is not supported.'
'409':
description: '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':
description: 'Gone: The requested resource is no longer available.'
'415':
description: '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':
description: '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':
description: 'Precondition Required: File(s) cannot be scanned for malware and need to be force downloaded.'
'429':
description: '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':
description: 'Internal Server Error: Something went wrong on the server. If the issue persists, feel free to contact the [Webex Developer Support team](/explore/support).'
'502':
description: 'Bad Gateway: The server received an invalid response from an upstream server while processing the request. Try again later.'
'503':
description: 'Service Unavailable: Server is overloaded with requests. Try again later.'
'504':
description: 'Gateway Timeout: An upstream server failed to respond on time. If your query uses max parameter, please try to reduce it.'
summary: Delete a Contact
operationId: Delete a Contact
description: 'Remove a contact from the organization. Only an admin can remove a contact.
Specify the organization ID in the `orgId` parameter in the URI, and specify the contact ID in the `contactId` parameter in the URI.'
tags:
- Organization Contacts
parameters:
- name: orgId
in: path
description: Webex Identity assigned organization identifier for the user's organization or the organization he manages.
required: true
example: d23736ac-8055-433e-b85a-0fc55c96ead8
schema:
type: string
- name: contactId
in: path
description: The contact ID.
required: true
example: 6847ee0f-5e9c-4403-9f0e-0aa8552f7828
schema:
type: string
/contacts/organizations/{orgId}/contacts/search:
get:
responses:
'200':
description: OK
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/SearchResponse'
example:
result:
- schemas: urn:cisco:codev:identity:contact:core:1.0
meta:
created: '2023-05-11T01:59:38.398Z'
lastModified: '2023-05-11T01:59:38.398Z'
contactId: 441d0fa5-7fa0-491e-b27a-f017896c0bab
firstName: Simic
lastName: Zhang
companyName: Cisco Systems
title: Product Manager
address: '{"city" : "Milpitas", "country" : "US", "street" : "1099 Bird Ave.", "zipCode" : "99212"}'
avatarURL: https://avatar-prod-us-east-2.webexcontent.com/default_avatar~1600
displayName: Logan
addressInfo:
city: Milpitas
country: US
street: 1099 Bird Ave.
zipCode: '99212'
primaryContactMethod: EMAIL
phoneNumbers:
- type: work
value: '20134319'
emails:
- type: work
value: simizhan@example.com
sipAddresses:
- type: work
value: sip://mysip1231233
ims:
- type: work
value: '87003922'
source: CH
isMigration: false
orgId: d23736ac-8055-433e-b85a-0fc55c96ead9
groupIds:
- b3e594aa-19ea-488a-9d42-f811e272f4bd
start: 0
limit: 1000
total: 1
'400':
description: 'Bad Request: The request was invalid or cannot be otherwise served. An accompanying error message will explain further.'
'401':
description: 'Unauthorized: Authentication credentials were missing or incorrect.'
'403':
description: 'Forbidden: The request is understood, but it has been refused or access is not allowed.'
'404':
description: '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':
description: 'Method Not Allowed: The request was made to a resource using an HTTP request method that is not supported.'
'409':
description: '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':
description: 'Gone: The requested resource is no longer available.'
'415':
description: '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':
description: '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':
description: 'Precondition Required: File(s) cannot be scanned for malware and need to be force downloaded.'
'429':
description: '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':
description: 'Internal Server Error: Something went wrong on the server. If the issue persists, feel free to contact the [Webex Developer Support team](/explore/support).'
'502':
description: 'Bad Gateway: The server received an invalid response from an upstream server while processing the request. Try again later.'
'503':
description: 'Service Unavailable: Server is overloaded with requests. Try again later.'
'504':
description: 'Gateway Timeout: An upstream server failed to respond on time. If your query uses max parameter, please try to reduce it.'
summary: List Contacts
operationId: List Contacts
description: 'List contacts in the organization. The default limit is `100`.
`keyword` can be the value of "displayName", "firstName", "lastName", "email". An empty string of `keyword` means get all contacts.
`groupIds` is a comma separated list group IDs. Results are filtered based on those group IDs.
Long result sets will be split into [pages](/docs/basics#pagination).'
tags:
- Organization Contacts
parameters:
- name: orgId
in: path
description: The organization ID.
required: true
example: d23736ac-8055-433e-b85a-0fc55c96ead8
schema:
type: string
- name: keyword
in: query
description: List contacts with a keyword.
example: john.andersen@example.com
schema:
type: string
- name: source
in: query
description: List contacts with source.
example: CH
schema:
type: string
- name: limit
in: query
description: "Limit the maximum number of contact in the response.\n + Default: 100\n"
example: '100'
schema:
type: number
- name: groupIds
in: query
description: Filter contacts based on groups.
example: 9ac175bf-0249-4287-8fb3-e320e525fcf6,23b95024-7063-404c-9a3c-37532f53a9ce
schema:
type: array
items:
type: string
example: 9ac175bf-0249-4287-8fb3-e320e525fcf6,23b95024-7063-404c-9a3c-37532f53a9ce
description: Filter contacts based on groups.
/contacts/organizations/{orgId}/contacts/bulk:
post:
responses:
'200':
description: OK
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/BulkCreateResponse'
example:
contacts:
- schemas: urn:cisco:codev:identity:contact:core:1.0
meta:
created: '2023-05-12T06:53:12.141Z'
lastModified: '2023-05-12T06:53:12.142Z'
contactId: 5a521987-5407-4824-9389-d4ca82b85752
displayName: simizhan1
emails:
- type: WORK
value: simizhan1@example.com
source: CH
isMigration: false
orgId: d23736ac-8055-433e-b85a-0fc55c96ead9
- null
- null
failedContacts:
- id: '1'
errorCode: external.non.privilege
errorMessage: Caller is not authorized for source null, only sources [CH] are allowed
statusCode: 403
- id: '2'
errorCode: external.non.privilege
errorMessage: Caller is not authorized for source null, only
# --- truncated at 32 KB (64 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/webex/refs/heads/main/openapi/webex-organization-contacts-api-openapi.yml