RingCentral Extensions API
The Extensions API from RingCentral — 5 operation(s) for extensions.
OpenAPI Specification
openapi: 3.0.3
info:
title: RingCentral Adaptive Cards Extensions 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: Extensions
paths:
/restapi/v1.0/account/{accountId}/extension-bulk-update:
post:
tags:
- Extensions
summary: Update Multiple Extensions
description: 'Updates multiple extensions at once. Maximum 500 extensions can be updated per request.
'
operationId: extensionBulkUpdate
parameters:
- $ref: '#/components/parameters/AccountId'
requestBody:
description: JSON body
content:
application/json:
schema:
$ref: '#/components/schemas/ExtensionBulkUpdateRequest'
required: true
responses:
'200':
description: Updated extensions
content:
application/json:
schema:
$ref: '#/components/schemas/ExtensionBulkUpdateTaskResource'
x-feature: EditExtensionInfo
x-availability: Limited
x-throttling-group: Heavy
x-app-permission: EditExtensions
x-user-permission: EditExtensionInfo
/restapi/v1.0/account/{accountId}/extension-bulk-update/tasks/{taskId}:
get:
tags:
- Extensions
summary: Get Extension Update Task Status
description: 'Returns a status of a task to update multiple extensions.
'
operationId: getExtensionBulkUpdateTask
parameters:
- $ref: '#/components/parameters/AccountId'
- name: taskId
in: path
description: 'Internal identifier of a task
'
required: true
schema:
type: string
responses:
'200':
description: Bulk update task status
content:
application/json:
schema:
$ref: '#/components/schemas/ExtensionBulkUpdateTaskResource'
x-feature: EditExtensionInfo
x-availability: Limited
x-throttling-group: Light
x-app-permission: EditExtensions
x-user-permission: EditExtensionInfo
/restapi/v1.0/account/{accountId}/templates:
get:
tags:
- Extensions
summary: List User Templates
description: 'Returns the list of user templates for the current account.
'
operationId: listUserTemplates
parameters:
- $ref: '#/components/parameters/AccountId'
- name: type
description: Type of template
in: query
schema:
type: string
enum:
- UserSettings
- CallHandling
- name: page
in: query
description: 'Indicates a page number to retrieve. Only positive number values
are allowed. Default value is ''1''
'
schema:
type: integer
format: int32
default: 1
- name: perPage
in: query
description: Indicates a page size (number of items). If not specified, the value is '100' by default
schema:
type: integer
format: int32
default: 100
responses:
'200':
description: User templates information
content:
application/json:
schema:
$ref: '#/components/schemas/UserTemplates'
x-feature: ReadCompanyInfo
x-availability: High
x-throttling-group: Medium
x-app-permission: ReadAccounts
x-user-permission: ReadCompanyInfo
/restapi/v1.0/account/{accountId}/templates/{templateId}:
get:
tags:
- Extensions
summary: Get User Template
description: 'Returns the user template by ID.
'
operationId: readUserTemplate
parameters:
- $ref: '#/components/parameters/AccountId'
- name: templateId
in: path
required: true
description: Internal identifier of a template
schema:
type: string
responses:
'200':
description: User template information
content:
application/json:
schema:
$ref: '#/components/schemas/TemplateInfo'
x-feature: ReadCompanyInfo
x-availability: High
x-throttling-group: Light
x-app-permission: ReadAccounts
x-user-permission: ReadCompanyInfo
/restapi/v1.0/account/{accountId}/extension:
get:
tags:
- Extensions
summary: List Extensions
description: 'Returns the list of extensions created for a particular account.
All types of extensions are included in this list.
'
operationId: listExtensions
parameters:
- $ref: '#/components/parameters/AccountId'
- name: extensionNumber
in: query
description: Extension short number to filter records
schema:
type: string
- name: email
in: query
description: 'Extension email address. Multiple values are accepted
'
example: alice.smith@example.com&email=bob.johnson@example.com
schema:
type: string
- name: page
in: query
description: 'Indicates a page number to retrieve. Only positive number values
are allowed
'
schema:
type: integer
format: int32
default: 1
- name: perPage
in: query
description: Indicates a page size (number of items)
schema:
type: integer
format: int32
default: 100
- name: status
in: query
description: 'Extension current state. Multiple values are supported. If ''Unassigned''
is specified, then extensions without `extensionNumber` attribute are returned.
If not specified, then all extensions are returned
'
allowEmptyValue: true
style: form
explode: true
schema:
type: array
items:
type: string
enum:
- Enabled
- Disabled
- NotActivated
- Unassigned
- name: type
in: query
description: 'Extension type. Multiple values are supported. Please note
that legacy ''Department'' extension type corresponds to ''Call Queue''
extensions in modern RingCentral product terminology
'
allowEmptyValue: true
style: form
explode: true
schema:
type: array
items:
type: string
enum:
- User
- FaxUser
- FlexibleUser
- VirtualUser
- DigitalUser
- Department
- Announcement
- Voicemail
- SharedLinesGroup
- PagingOnly
- IvrMenu
- ApplicationExtension
- ParkLocation
- Limited
- Bot
- ProxyAdmin
- DelegatedLinesGroup
- Site
responses:
'200':
description: Extension list information
content:
application/json:
schema:
$ref: '#/components/schemas/GetExtensionListResponse'
x-feature: ReadExtensions
x-availability: High
x-throttling-group: Medium
x-app-permission: ReadAccounts
x-user-permission: ReadExtensions
x-notifications:
- $ref: '#/components/schemas/ExtensionListEvent'
post:
tags:
- Extensions
summary: Create Extension
description: 'Creates an extension.
'
operationId: createExtension
parameters:
- $ref: '#/components/parameters/AccountId'
requestBody:
description: JSON body
content:
application/json:
schema:
$ref: '#/components/schemas/ExtensionCreationRequest'
required: true
responses:
'200':
description: Created extension information
content:
application/json:
schema:
$ref: '#/components/schemas/ExtensionCreationResponse'
'400':
$ref: '#/components/responses/InvalidRequest'
x-feature: EditUsers
x-availability: Limited
x-throttling-group: Medium
x-app-permission: EditAccounts
x-user-permission: AddRemoveUsers
components:
schemas:
ExtensionServiceFeatureInfo:
type: object
properties:
enabled:
type: boolean
description: Feature status; shows feature availability for an extension
featureName:
type: string
description: Feature name
enum:
- AccountFederation
- Archiver
- AutomaticCallRecordingMute
- AutomaticInboundCallRecording
- AutomaticOutboundCallRecording
- BlockedMessageForwarding
- Calendar
- CallerIdControl
- CallForwarding
- CallPark
- CallParkLocations
- CallSupervision
- CallSwitch
- CallQualitySurvey
- Conferencing
- ConferencingNumber
- ConfigureDelegates
- DeveloperPortal
- DND
- DynamicConference
- EmergencyAddressAutoUpdate
- EmergencyCalling
- EncryptionAtRest
- ExternalDirectoryIntegration
- Fax
- FaxReceiving
- FreeSoftPhoneLines
- HDVoice
- HipaaCompliance
- Intercom
- InternationalCalling
- InternationalSMS
- LinkedSoftphoneLines
- MMS
- MobileVoipEmergencyCalling
- OnDemandCallRecording
- Pager
- PagerReceiving
- Paging
- PasswordAuth
- PromoMessage
- Reports
- Presence
- RCTeams
- RingOut
- SalesForce
- SharedLines
- SingleExtensionUI
- SiteCodes
- SMS
- SMSReceiving
- SoftPhoneUpdate
- TelephonySessions
- UserManagement
- VideoConferencing
- VoipCalling
- VoipCallingOnMobile
- Voicemail
- VoicemailToText
- WebPhone
reason:
type: string
description: 'Reason for limitation of a particular service feature. Returned
only if the enabled parameter value is `false`, see Service Feature
Limitations and Reasons. When retrieving service features for an extension,
the reasons for limitations, if any, are returned in response
'
CustomFieldInfo:
type: object
properties:
id:
type: string
description: Internal identifier of a custom field
value:
type: string
description: Custom field value
displayName:
type: string
SetupWizardStateForUpdateEnum:
type: string
description: Initial configuration wizard state
enum:
- NotStarted
- Incomplete
- Completed
default: NotStarted
ExtensionBulkUpdateRequest:
required:
- records
description: List of extensions to be updated
type: object
properties:
records:
type: array
items:
$ref: '#/components/schemas/ExtensionBulkUpdateInfo'
SiteInfo:
type: object
properties:
id:
type: string
description: Internal identifier of a site extension
uri:
type: string
format: uri
description: Link to a site resource
name:
type: string
description: Extension user first name
extensionNumber:
type: string
description: Extension number
callerIdName:
type: string
description: 'Custom name of a caller. Max number of characters is 15 (only
alphabetical symbols, numbers and commas are supported)
'
email:
type: string
format: email
description: Site extension contact email
businessAddress:
$ref: '#/components/schemas/ContactBusinessAddressInfo'
regionalSettings:
$ref: '#/components/schemas/RegionalSettings'
operator:
$ref: '#/components/schemas/OperatorInfo'
code:
type: string
description: 'Site code value. Returned only if specified
'
ProfileImageInfoURI:
type: object
properties:
uri:
type: string
format: uri
RegionalSettings:
type: object
properties:
homeCountry:
$ref: '#/components/schemas/CountryInfoShortModel'
timezone:
$ref: '#/components/schemas/TimezoneInfo'
language:
$ref: '#/components/schemas/RegionalLanguageInfo'
greetingLanguage:
$ref: '#/components/schemas/GreetingLanguageInfo'
formattingLocale:
$ref: '#/components/schemas/FormattingLocaleInfo'
timeFormat:
type: string
description: Time format setting. The default value is '12h' = ['12h', '24h']
enum:
- 12h
- 24h
description: 'Regional data (timezone, home country, language) of an extension/account.
The default is Company (Auto-Receptionist) settings
'
GetExtensionListResponse:
required:
- records
type: object
properties:
uri:
type: string
format: uri
description: Link to an extension list resource
records:
type: array
description: List of extensions with extension information
items:
$ref: '#/components/schemas/GetExtensionListInfoResponse'
navigation:
$ref: '#/components/schemas/PageNavigationModel'
paging:
$ref: '#/components/schemas/EnumeratedPagingModel'
ExtensionUpdateShortResult:
type: object
properties:
extensionId:
type: string
description: Internal identifier of an extension
status:
type: string
description: Extension update status
enum:
- Fail
- Success
errors:
type: array
items:
$ref: '#/components/schemas/ErrorEntity'
ApiErrorWithParameter:
description: 'The error model with additional attributes which can be used for HTTP 400/409
This is a deprecated model: "ApiError" model can be used instead with arbitrary additional parameters
'
allOf:
- $ref: '#/components/schemas/ApiError'
- type: object
properties:
parameterName:
type: string
description: The name of the API parameter/attribute which caused the error
parameterValue:
type: string
description: The value of the API parameter/attribute which caused the error
ReferenceInfo:
type: object
properties:
ref:
type: string
description: Non-RC identifier of an extension
type:
type: string
description: Type of external identifier
enum:
- PartnerId
- CustomerDirectoryId
refAccId:
type: string
description: Primary federation admin account identifier
ExtensionCreationResponse:
type: object
properties:
id:
type: integer
description: Internal identifier of an extension
format: int64
uri:
type: string
format: uri
description: Canonical URI of an extension
contact:
$ref: '#/components/schemas/ContactInfo'
costCenter:
$ref: '#/components/schemas/CostCenterInfo'
customFields:
type: array
items:
$ref: '#/components/schemas/CustomFieldInfo'
extensionNumber:
type: string
description: Extension number
name:
type: string
description: 'Extension name. For user extension types the value is a combination
of the specified first name and last name
'
partnerId:
type: string
description: 'For Partner Applications Internal identifier of an extension
created by partner. The RingCentral supports the mapping of accounts and
stores the corresponding account ID/extension ID for each partner ID of
a client application. In request URIs partner IDs are accepted instead
of regular RingCentral native IDs as path parameters using `pid=XXX` clause.
Though in response URIs contain the corresponding account IDs and extension
IDs. In all request and response bodies these values are reflected via
partnerId attributes of account and extension
'
permissions:
$ref: '#/components/schemas/ExtensionPermissions'
profileImage:
$ref: '#/components/schemas/ProfileImageInfo'
references:
type: array
description: 'List of non-RC internal identifiers assigned to an extension
'
items:
$ref: '#/components/schemas/ReferenceInfo'
regionalSettings:
$ref: '#/components/schemas/RegionalSettings'
serviceFeatures:
type: array
description: 'Extension service features returned in response only when the
logged-in user requests his/her own extension info, see also Extension
Service Features
'
items:
$ref: '#/components/schemas/ExtensionServiceFeatureInfo'
setupWizardState:
$ref: '#/components/schemas/SetupWizardStateForUpdateEnum'
site:
$ref: '#/components/schemas/ProvisioningSiteInfo'
status:
type: string
description: 'Extension current state. If ''Unassigned'' is specified, then
extensions without `extensionNumber` are returned. If not specified, then
all extensions are returned
'
enum:
- Enabled
- Disabled
- Frozen
- NotActivated
- Unassigned
statusInfo:
$ref: '#/components/schemas/ExtensionStatusInfo'
type:
type: string
description: 'Extension type. Please note that legacy ''Department'' extension type
corresponds to ''Call Queue'' extensions in modern RingCentral product terminology
'
enum:
- User
- VirtualUser
- DigitalUser
- FlexibleUser
- Department
- Announcement
- Voicemail
- SharedLinesGroup
- PagingOnly
- ParkLocation
- Limited
hidden:
type: boolean
description: 'Hides an extension from showing in company directory. Supported
for extensions of ''User'' type only
'
assignedCountry:
$ref: '#/components/schemas/AssignedCountryInfo'
ContactBusinessAddressInfo:
type: object
properties:
country:
type: string
description: Country name of a user's company
state:
type: string
description: 'State/province name of a user''s company. Mandatory
for the USA, UK and Canada
'
city:
type: string
description: City name of a user's company
street:
type: string
description: Street address of a user's company
zip:
type: string
description: Zip code of a user's company
description: 'User''s business address. The default is
Company (Auto-Receptionist) settings
'
CountryInfoMinimalModel:
type: object
properties:
id:
type: string
description: Internal identifier of a country
uri:
type: string
format: uri
description: Canonical URI of a country resource
ApiError:
type: object
description: Generalized API error structure suitable for any error type
required:
- errorCode
- message
properties:
errorCode:
type: string
description: Logical error code (typically, 3 letters followed with number, dash separated)
example: XXX-123
message:
type: string
description: User-friendly error message
example: Something went wrong
additionalProperties: true
ExtensionBulkUpdateTaskResult:
type: object
description: Result record on multiple extension update task
properties:
affectedItems:
type: array
items:
$ref: '#/components/schemas/ExtensionUpdateShortResult'
errors:
type: array
items:
$ref: '#/components/schemas/ErrorEntity'
ExtensionLanguageInfoRequest:
type: object
properties:
id:
type: string
description: Internal identifier of a language
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
PageNavigationUri:
type: object
additionalProperties: false
properties:
uri:
type: string
description: Canonical URI to retrieve the particular page of the result set
format: uri
FormattingLocaleInfo:
type: object
properties:
id:
type: string
description: Internal identifier of a formatting language
localeCode:
type: string
description: Localization code of a formatting language
name:
type: string
description: Official name of a formatting language
description: 'Formatting language preferences for numbers, dates and currencies
'
GreetingLanguageInfo:
type: object
properties:
id:
type: string
description: Internal identifier of a greeting language
localeCode:
type: string
description: Localization code of a greeting language
name:
type: string
description: Official name of a greeting language
description: 'Information on language used for telephony greetings
'
CostCenterInfo:
type: object
description: Cost center information. Applicable if Cost Center feature is enabled. The default is `root` cost center value
properties:
id:
type: string
description: Internal identifier of a cost center
name:
type: string
description: Name of a cost center
ExtensionGreetingLanguageInfoRequest:
type: object
properties:
id:
type: string
description: Internal identifier of a greeting language
UserTransitionInfo:
type: object
properties:
sendWelcomeEmailsToUsers:
type: boolean
description: 'Specifies if a welcome/activation email is sent to the existing
users during account confirmation
'
sendWelcomeEmail:
type: boolean
description: 'Specifies if a welcome/activation email is sent to the new users (within extension status changing from
''Unassigned'' to ''NotActivated/Disabled'')
'
description: 'For NotActivated extensions only. Welcome email settings
'
OperatorInfo:
type: object
properties:
id:
type: string
description: Internal identifier of an operator
uri:
type: string
format: uri
description: Link to an operator resource
extensionNumber:
type: string
description: Extension number (pin)
name:
type: string
description: Operator extension user full name
description: 'Site Fax/SMS recipient (operator) reference. Multi-level IVR should
be enabled
'
PageNavigationModel:
type: object
description: Links to other pages of the current result set
additionalProperties: false
properties:
firstPage:
$ref: '#/components/schemas/PageNavigationUri'
nextPage:
$ref: '#/components/schemas/PageNavigationUri'
previousPage:
$ref: '#/components/schemas/PageNavigationUri'
lastPage:
$ref: '#/components/schemas/PageNavigationUri'
TemplateInfo:
type: object
description: Text message template information
required:
- text
properties:
text:
type: string
description: "Text of the message template. Maximum length is 1000 symbols (2-byte UTF-16 encoded). \nIf a character is encoded in 4 bytes in UTF-16 it is treated as 2 characters, \nthus limiting the maximum message length up to 500 symbols\n"
ContactInfo:
type: object
properties:
firstName:
type: string
description: 'User''s first name (for extensions of `User` type only)
'
lastName:
type: string
description: 'For User extension type only. User''s last name (for extensions of `User` type only)
'
name:
type: string
description: 'Extension name (for extensions of `User` type - concatenation of first and last name)
'
company:
type: string
description: User's company name
jobTitle:
type: string
description: User's job title
email:
type: string
format: email
description: User's contact email
businessPhone:
type: string
description: 'User''s contact phone number in [E.164](https://www.itu.int/rec/T-REC-E.164-201011-I)
(with ''+'' sign) format
'
mobilePhone:
type: string
description: 'User''s mobile (**non** Toll Free) phone number in [E.164](https://www.itu.int/rec/T-REC-E.164-201011-I)
(with ''+'' sign) format
'
businessAddress:
$ref: '#/components/schemas/ContactBusinessAddressInfo'
emailAsLoginName:
type: boolean
description: 'Indicates that the contact email is enabled as a login name for this
user. Please note that the email must be unique in this case.
'
default: false
pronouncedName:
$ref: '#/components/schemas/PronouncedNameInfo'
department:
type: string
description: 'User''s department name
'
description: Detailed contact information
ExtensionTimezoneInfoRequest:
type: object
properties:
id:
type: string
description: Internal identifier of a timezone
ExtensionCurrencyInfoRequest:
type: object
properties:
id:
type: string
description: Internal Identifier of a currency
PronouncedNameInfo:
type: object
properties:
type:
type: string
description: 'The method used to pronounce the user''s name:
- `Default` - default extension name; first and last name specified in user''s profile are pronounced using text-to-speech;
- `TextToSpeech` - custom text specified by a user pronounced using text-to-speech;
- `Recorded` - custom audio uploaded by a user, the name recorded in user''s own voice (supported only for extension retrieval).
'
enum:
- Default
- TextToSpeech
- Recorded
text:
type: string
description: Custom text (for `TextToSpeech` type only)
prompt:
$ref: '#/components/schemas/PronouncedNamePromptInfo'
CallQueueExtensionInfo:
type: object
properties:
slaGoal:
type: integer
format: int32
description: 'Target percentage of calls that must be answered by agents
within the service level time threshold
'
slaThresholdSeconds:
type: integer
format: int32
description: 'Period of time in seconds that is considered to be an acceptable
service level
'
includeAbandonedCalls:
type: boolean
description: 'If `true` abandoned calls (hanged up prior to being served)
are included into service level calculation
'
abandonedThresholdSeconds:
type: integer
format: int32
description: 'Period of time in seconds specifying abandoned calls duration
- calls that are shorter will not be included into the calculation of
service level.; zero value means that abandoned calls of any duration
will be included into calculation
'
description: 'For Call Queue extension type only. Please note that legacy
''Department'' extension type corresponds to ''Call Queue'' extensions
in modern RingCentral product terminology
'
ProvisioningSiteInfo:
type: object
properties:
id:
type: string
format: uri
description: Internal identifier of a site
uri:
type: string
format: uri
description: Link to a site resource
name:
type: string
description: Name of a site
code:
type: string
description: Site code value. Returned only if specified
description: 'Site data. If multi-site feature is turned on for an account,
then ID of a site must be specified. In order to assign a wireless
point to the main site (company) the site ID should be set to `main-site`
'
ExtensionStatusInfo:
type: object
properties:
comment:
type: string
# --- truncated at 32 KB (57 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ringcentral/refs/heads/main/openapi/ringcentral-extensions-api-openapi.yml