RingCentral Internal Contacts API
The Internal Contacts API from RingCentral — 4 operation(s) for internal contacts.
The Internal Contacts API from RingCentral — 4 operation(s) for internal contacts.
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