openapi: 3.0.3 info: title: RingCentral Adaptive Cards Internal Contacts API description: RingCentral API specification version: 1.0.58-20240529-47eda8bd contact: name: RingCentral Developers Support url: https://developers.ringcentral.com/support termsOfService: https://www.ringcentral.com/legal/apilitos.html license: name: RingCentral API License Agreement url: https://www.ringcentral.com/legal/apilitos.html servers: - url: https://platform.ringcentral.com description: Production API entry point - url: https://media.ringcentral.com description: Production Media entry point - url: https://platform.devtest.ringcentral.com description: Developer sandbox API entry point - url: https://platform.devtest.ringcentral.com description: Developer sandbox Media entry point security: - OAuth2: [] tags: - name: Internal Contacts paths: /restapi/v1.0/account/{accountId}/directory/entries: get: tags: - Internal Contacts summary: Get Company Directory Entries description: 'Returns contact information on corporate users of federated accounts. Please note: 1. `User`, `DigitalUser`, `VirtualUser` and `FaxUser` types are returned as `User` type. 2. `ApplicationExtension` type is not returned. 3. Only extensions in `Enabled`, `Disabled` and `NotActivated` state are returned.' operationId: listDirectoryEntries parameters: - $ref: '#/components/parameters/AccountId' - name: showFederated in: query description: If `true` then contacts of all accounts in federation are returned. If `false` then only contacts of the current account are returned, and account section is eliminated in this case schema: type: boolean default: true - name: type in: query description: Type of an extension. Please note that legacy 'Department' extension type corresponds to 'Call Queue' extensions in modern RingCentral product terminology schema: type: string enum: - User - Department - Announcement - Voicemail - SharedLinesGroup - PagingOnly - IvrMenu - ParkLocation - Limited - External - name: typeGroup in: query description: Type of extension group schema: type: string enum: - User - NonUser - name: page in: query description: Page number schema: type: integer format: int32 default: 1 - name: perPage in: query description: 'Records count to be returned per one page. It can be either integer or string with the specific keyword values: - `all` - all records are returned in one page - `max` - maximum count of records that can be returned in one page ' schema: oneOf: - type: integer format: int32 default: 1000 maximum: 2000 - type: string enum: - max - all - name: siteId in: query description: Internal identifier of the business site to which extensions belong schema: type: string - $ref: '#/components/parameters/IfNoneMatch' responses: '200': description: Paged collection of all contacts information for a given account. Records can be empty if no data found. content: application/json: schema: $ref: '#/components/schemas/DirectoryResource' '400': description: Current request cannot be processed due to error in its body and/or url. content: application/json: schema: $ref: '#/components/schemas/ADGErrorResponse' '500': description: Some unexpected error during current request processing. content: application/json: schema: $ref: '#/components/schemas/ADGErrorResponse' '503': description: Network error during request content: application/json: schema: $ref: '#/components/schemas/ADGErrorResponse' x-throttling-group: Medium x-app-permission: ReadAccounts /restapi/v1.0/account/{accountId}/directory/entries/{entryId}: get: tags: - Internal Contacts summary: Get Corporate Directory Entry description: Returns contact information on a particular corporate user of a federated account. operationId: readDirectoryEntry parameters: - $ref: '#/components/parameters/AccountId' - name: entryId in: path description: Internal identifier of extension to read information for required: true schema: type: string responses: '200': description: Contact information for given parameters. If value doesn't found then empty body will be returned content: application/json: schema: $ref: '#/components/schemas/ContactResource' '400': description: Current request cannot be processed due to error in its body and/or url content: application/json: schema: $ref: '#/components/schemas/ADGErrorResponse' '500': description: Some unexpected error during current request processing content: application/json: schema: $ref: '#/components/schemas/ADGErrorResponse' '503': description: Network error during request. One should check connection between ADG processing node and ADX data node content: application/json: schema: $ref: '#/components/schemas/ADGErrorResponse' x-throttling-group: Medium x-app-permission: ReadAccounts /restapi/v1.0/account/{accountId}/directory/entries/search: post: tags: - Internal Contacts summary: Search Company Directory Entries description: Returns contact information on corporate users of federated accounts according to the specified filtering and ordering. operationId: searchDirectoryEntries parameters: - $ref: '#/components/parameters/AccountId' - name: accountId in: query description: A list of Account IDs schema: type: string example: '400131426008' - name: department in: query description: A list of department names schema: type: string example: North office - name: siteId in: query description: A list of Site IDs schema: type: string example: '872781797006' - name: extensionStatus in: query description: Extension current state schema: type: string example: Enabled - name: extensionType in: query description: Extension types schema: $ref: '#/components/schemas/SearchDirectoryExtensionType' requestBody: content: application/json: schema: $ref: '#/components/schemas/SearchDirectoryEntriesRequest' required: true responses: '200': description: Paged collection of all contacts information for a given account according to filtering and ordering. Records can be empty if no data found content: application/json: schema: $ref: '#/components/schemas/DirectoryResource' '400': description: Current request cannot be processed due to error in its body and/or url content: application/json: schema: $ref: '#/components/schemas/ADGErrorResponse' '500': description: Some unexpected error during current request processing. content: application/json: schema: $ref: '#/components/schemas/ADGErrorResponse' '503': description: Network error during request content: application/json: schema: $ref: '#/components/schemas/ADGErrorResponse' x-throttling-group: Heavy x-app-permission: ReadAccounts x-user-permission: ReadExtensions /restapi/v1.0/account/{accountId}/directory/federation: get: tags: - Internal Contacts summary: Get Account Federation description: Returns information on a federation and associated accounts. operationId: readDirectoryFederation parameters: - $ref: '#/components/parameters/AccountId' - name: types in: query description: Filter by federation types. Default is Regular schema: $ref: '#/components/schemas/FederationTypes' - name: RCExtensionId in: header description: RingCentral extension id schema: type: string responses: '200': description: List of found federations. Records array can be empty if no data found content: application/json: schema: $ref: '#/components/schemas/FederationResource' '400': description: Current request cannot be processed due to error in its body and/or url content: application/json: schema: $ref: '#/components/schemas/ADGErrorResponse' '500': description: Some unexpected error during current request processing. content: application/json: schema: $ref: '#/components/schemas/ADGErrorResponse' '503': description: Network error during request content: application/json: schema: $ref: '#/components/schemas/ADGErrorResponse' x-feature: ReadCompanyInfo x-throttling-group: Medium x-app-permission: ReadAccounts x-user-permission: ReadCompanyInfo components: schemas: DirectoryRoleResource: required: - id type: object properties: id: type: string name: type: string domain: type: string displayName: type: string FederationType: type: string description: Federation type enum: - Regular - AdminOnly AccountDirectoryProfileImageResource: type: object properties: etag: type: string example: tag uri: type: string format: uri BusinessSiteResource: type: object properties: id: type: string example: '872781820006' name: type: string example: Sales site code: type: string example: '1007' CostCenterResource: type: object properties: id: type: string example: '83266549237542' code: type: string example: Main name: type: string example: Cost Center A ContactResource: required: - id type: object properties: id: type: string description: Contact extension identifier example: '865706371004' type: type: string description: Contact type example: User enum: - User - Department - Announcement - Voicemail - SharedLinesGroup - PagingOnly - ParkLocation - IvrMenu - Limited - ApplicationExtension - Site - Bot - Room - ProxyAdmin - DelegatedLinesGroup - GroupCallPickup - External - RoomConnector - Unknown status: type: string description: Contact status example: Enabled enum: - Enabled - Disabled - Frozen - NotActivated - Unassigned - Unknown account: $ref: '#/components/schemas/AccountResource' department: type: string example: External email: type: string format: email example: john.doe@mycompany.com extensionNumber: type: string example: '103' firstName: type: string description: First name of a contact, for user extensions only example: John lastName: type: string description: Last name of a contact, for user extensions only example: Doe name: type: string description: Name of a contact, for non-user extensions example: Conference room ?5 jobTitle: type: string example: Sales manager phoneNumbers: type: array items: $ref: '#/components/schemas/PhoneNumberResource' profileImage: $ref: '#/components/schemas/AccountDirectoryProfileImageResource' site: $ref: '#/components/schemas/BusinessSiteResource' hidden: type: boolean role: $ref: '#/components/schemas/DirectoryRoleResource' callQueues: type: array items: $ref: '#/components/schemas/CallQueueResource' customFields: type: array items: $ref: '#/components/schemas/CustomFieldResource' groups: type: array items: $ref: '#/components/schemas/GroupResource' costCenter: $ref: '#/components/schemas/CostCenterResource' integration: $ref: '#/components/schemas/ExternalIntegrationResource' subType: $ref: '#/components/schemas/ContactSubTypeEnum' PhoneNumberResource: type: object properties: formattedPhoneNumber: type: string example: +1 (205) 6812029 phoneNumber: type: string example: '+12056812029' type: type: string example: VoiceFax label: type: string description: Custom user name of a phone number, if any example: Boss usageType: type: string description: Usage type of phone number enum: - MobileNumber - ContactNumber - DirectNumber - ForwardedNumber example: DirectNumber hidden: type: boolean description: Specifies if a phone number should be hidden or not primary: type: boolean description: Specifies if the number is primary, i.e. displayed as 'main number' and called by default SearchDirectoryExtensionTypes: type: array description: Types of extension to filter the contacts items: $ref: '#/components/schemas/SearchDirectoryExtensionType' ExternalIntegrationResource: type: object properties: id: type: string example: '9813' typeId: type: string example: '1' type: type: string example: External displayName: type: string example: Integration X routingType: type: string example: Account outboundEdgeId: type: string example: '1726' EnumeratedPagingModel: type: object required: - perPage additionalProperties: false properties: perPage: type: integer format: int32 minimum: 1 maximum: 1000 description: 'Current page size, describes how many items are in each page. Matches "perPage" parameter from the request. ' example: 50 page: type: integer format: int32 minimum: 1 maximum: 1000 description: 'The current page number. 1-indexed, so the first page is 1 by default. May be omitted if result is empty (because non-existent page was specified or perPage=0 was requested) ' example: 5 pageStart: type: integer format: int32 minimum: 0 description: 'The zero-based number of the first element on the current page. Omitted if the page is omitted or result is empty ' example: 0 pageEnd: type: integer format: int32 minimum: 0 description: 'The zero-based index of the last element on the current page. Omitted if the page is omitted or result is empty ' example: 5 totalPages: type: integer format: int32 minimum: 0 description: 'The total number of pages in a dataset. May be omitted for some resources due to performance reasons ' example: 25 totalElements: type: integer format: int32 minimum: 0 description: 'The total number of elements in a dataset. May be omitted for some resource due to performance reasons ' example: 25 CustomFieldResource: type: object properties: id: type: string example: '1032854' name: type: string example: Rank value: type: string example: '5' OrderBy: type: object properties: index: type: integer format: int32 default: 1 description: Sorting priority index, starting from '1'. Optional if only one element in `orderBy` array is specified example: 1 fieldName: type: string description: Field name by which to sort the contacts enum: - firstName - lastName - extensionNumber - phoneNumber - email - jobTitle - department example: department direction: type: string default: Asc description: Sorting direction enum: - Asc - Desc example: Asc CallQueueResource: type: object properties: id: type: string example: '873014540006' name: type: string example: Sales CQ FederationTypes: type: string description: Federation types for search enum: - All - Regular - AdminOnly FederatedAccountResource: type: object required: - id properties: companyName: type: string conflictCount: type: integer format: int32 federatedName: type: string id: type: string linkCreationTime: type: string format: date-time mainNumber: $ref: '#/components/schemas/PhoneNumberResource' GroupResource: type: object properties: id: type: string example: '63723034' name: type: string example: Leaders SearchDirectoryExtensionType: type: string description: Type of extension to filter the contacts enum: - User - Department - Announcement - Voicemail - DigitalUser - VirtualUser - FaxUser - PagingOnly - SharedLinesGroup - IvrMenu - ApplicationExtension - ParkLocation - Limited - Bot - Site - Room - ProxyAdmin - DelegatedLinesGroup - FlexibleUser - GroupCallPickup - RoomConnector example: User ADGErrorResponse: type: object properties: errors: type: array description: Collection of all gathered errors readOnly: true items: $ref: '#/components/schemas/ADGError' description: Format of response in case that any error occurred during request processing ADGError: type: object properties: errorCode: type: string description: Code that characterizes this error. Code uniquely identifies the source of the error. readOnly: true enum: - ErrorCode{code='ADG-000', httpStatus=503, description='Service temporary unavailable.'} - ErrorCode{code='ADG-010', httpStatus=503, description='Federation data temporary unavailable.'} - ErrorCode{code='ADG-001', httpStatus=500, description='Service internal error.'} - ErrorCode{code='ADG-100', httpStatus=403, description='Insufficient permissions.'} - ErrorCode{code='ADG-101', httpStatus=403, description='Unauthorized access.'} - ErrorCode{code='ADG-102', httpStatus=405, description='Method not allowed.'} - ErrorCode{code='ADG-111', httpStatus=400, description='Need Content-Type header.'} - ErrorCode{code='ADG-112', httpStatus=400, description='Request body is invalid.'} - ErrorCode{code='ADG-121', httpStatus=400, description='Parameter [${paramName}] is invalid. ${additionalInfo:-}'} - ErrorCode{code='ADG-115', httpStatus=415, description='Unsupported Media Type.'} - ErrorCode{code='ADG-105', httpStatus=404, description='Current account is not linked to any federation.'} - ErrorCode{code='ADG-107', httpStatus=404, description='Account not found.'} - ErrorCode{code='ADG-122', httpStatus=404, description='Contact not found.'} - ErrorCode{code='ADG-200', httpStatus=404, description='Invalid URI'} message: type: string description: Message that describes the error. This message can be used in UI. readOnly: true description: Description of an error occurred during request processing. This data type can be used only in readonly mode, no writing is allowed ContactSubTypeEnum: type: string description: Extension subtype example: Unknown enum: - Unknown - VideoPro - VideoProPlus - DigitalSignage - Emergency AccountResource: required: - id type: object properties: companyName: type: string example: My lovely company federatedName: type: string example: Lovely Holding id: type: string example: '400131426008' mainNumber: $ref: '#/components/schemas/PhoneNumberResource' SearchDirectoryContactType: type: string description: Type of directory contact to filter enum: - User - Department - Announcement - Voicemail - SharedLinesGroup - PagingOnly - ParkLocation - IvrMenu - Limited - ApplicationExtension - Site - Bot - Room - DelegatedLinesGroup - GroupCallPickup - External example: User FederationResource: type: object properties: accounts: type: array items: $ref: '#/components/schemas/FederatedAccountResource' creationTime: type: string format: date-time displayName: type: string id: type: string lastModifiedTime: type: string format: date-time type: $ref: '#/components/schemas/FederationType' DirectoryResource: required: - records - paging type: object properties: paging: $ref: '#/components/schemas/EnumeratedPagingModel' records: type: array items: $ref: '#/components/schemas/ContactResource' SearchDirectoryEntriesRequest: type: object properties: searchString: type: string description: 'String value to filter the contacts. The value specified is searched through the following fields: `firstName`, `lastName`, `extensionNumber`, `phoneNumber`, `email`, `jobTitle`, `department`, `customFieldValue` ' searchFields: type: array description: The list of field to be searched for items: type: string enum: - firstName - lastName - extensionNumber - phoneNumber - email - jobTitle - department - customFieldValue showFederated: type: boolean description: If `true` then contacts of all accounts in federation are returned, if it is in federation, account section will be returned. If `false` then only contacts of the current account are returned, and account section is eliminated in this case showAdminOnlyContacts: type: boolean description: Should show AdminOnly Contacts default: false extensionType: $ref: '#/components/schemas/SearchDirectoryContactType' siteId: type: string description: Internal identifier of the business site to which extensions belong example: '872781797006' showExternalContacts: type: boolean default: false description: Allows to control whether External (Hybrid) contacts should be returned in the response or not example: true accountIds: type: array description: The list of Internal identifiers of an accounts items: type: string example: - '854874047006' - '422456828004' - '854874151006' department: type: string description: Department siteIds: type: array description: The list of Internal identifiers of the business sites to which extensions belong items: type: string extensionStatuses: type: array description: Extension current state. items: type: string enum: - Enabled - Disabled - NotActivated extensionTypes: $ref: '#/components/schemas/SearchDirectoryExtensionTypes' orderBy: type: array description: Sorting settings items: $ref: '#/components/schemas/OrderBy' page: type: integer format: int32 perPage: type: integer format: int32 example: searchString: John Doe searchFields: - lastName - email showFederated: true siteIds: - '872781797006' - '872781820006' extensionStatuses: - Enabled department: R&D department page: 1 perPage: 30 parameters: IfNoneMatch: name: If-None-Match in: header required: false description: 'User in GET requests to skip retrieving the data if the provided value matches current `ETag` associated with this resource. The server checks the current resource ETag and returns the data only if mismatches the `If-None-Match` value, otherwise `HTTP 304 Not Modified` status is returned. ' schema: type: string AccountId: name: accountId in: path description: 'Internal identifier of the RingCentral account (can be set to "~" to indicate that the account associated with current authorization session should be used) ' required: true style: simple explode: false schema: type: string default: '~' example: '~' securitySchemes: OAuth2: type: oauth2 flows: authorizationCode: authorizationUrl: https://platform.ringcentral.com/restapi/oauth/authorize tokenUrl: https://platform.ringcentral.com/restapi/oauth/token refreshUrl: https://platform.ringcentral.com/restapi/oauth/token scopes: {} x-tagGroups: - name: Voice popular: true tags: - Business Hours - Call Blocking - Call Control - Call Forwarding - Call Handling Rules - Interaction Rules - State-based Rules - Call Flip - Call Log - Call History - Call Log Export - Call Monitoring Groups - Call Queues - Call Recordings - Call Recording Settings - Device SIP Registration - Greetings - IVR - RingOut - Verification Calls - name: SMS and Fax popular: true tags: - Fax - Message Exports - Message Store - Pager Messages - SMS - High Volume SMS - SMS Log Export - SMS Templates - Voicemail Broadcasting - name: Social Messaging popular: true tags: - Identities - Contents - name: Team Messaging popular: true tags: - Adaptive Cards - Bots - Calendar Events - Chats - Conversations - Compliance Exports - Contacts - Incoming Webhooks - Notes - Posts - Profile - Tasks - Teams - name: Video popular: true tags: - Bridge Management - Delegation Management - Meetings History - Meeting Recordings - RCM Meetings (Legacy) - RCM Webinars (Legacy) - name: Webinar popular: true tags: - Webinars and Sessions - Invitees - Historical Webinars - Historical Recordings - Registration Management - Registrants - Webinar Analytics - Webinar Subscriptions - name: Analytics popular: true tags: - Business Analytics - name: Artificial Intelligence popular: true tags: - Insights - Audio - Text - Status - name: Authentication tags: - OAuth 2.0 / OpenID Connect - Interoperability - name: Account tags: - Company - Custom Fields - Features - Licenses - Tax Locations - Cost Centers - Multi-Site - Phone Numbers - Presence - Regional Settings - User Permissions - User Settings - Audit Trail - Calling Rates - Appearance Customization - Account Integrations - name: Provisioning tags: - Automatic Location Updates - Devices - Extensions - Paging Only Groups - Park Locations - Phone Lines - SCIM - Shared Lines - Group Call Pickup - Delegated Lines Groups - Directed Call Pickup - IVR Apps - Video Configuration - Number Porting - SMB - Account Federation - Integrations - Enterprise Portal API - Push to Talk Provisioning - BYOC - name: Address Book tags: - External Contacts - Internal Contacts - Hybrid Directory Contacts - Overlay Contacts - External Shared Directory - name: Roles and Permissions tags: - Permissions - Role Management - Site Administration - User Groups - name: Events & Notifications tags: - Subscriptions - name: User Integrations tags: - Token Management - Calendar Management - Calendar Event Management - Calendar Presence Link - Cloud Personal Contacts - Cloud Shared Contacts - Cloud Directory - Deprecated Calendar API - name: Rooms tags: - Rooms Client API - Rooms Management API - name: App Management tags: - App Gallery - App Rating Review - Bot Provisioning - name: Workflow Builder tags: - Flows - Flow Editor - Flow Log - Flow Templates - name: Utilities tags: - API Info - Application Settings - Async Tasks - User Notifications - Client Versions - End-to-End Encryption