RingCentral

RingCentral Identities API

The Identities API from RingCentral — 2 operation(s) for identities.

GitHub OpenAPI

Operations 2

GET /cx/social-messaging/v1/identities List All Identities #
GET /cx/social-messaging/v1/identities/{identityId} Get Identity #

Documentation

📖
Documentation
https://developers.ringcentral.com/voice-api
📖
APIReference
https://developers.ringcentral.com/api-reference/Call-Control

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/ringcentral/refs/heads/main/openapi/ringcentral-identities-api-openapi.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/ringcentral-identities-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

ringcentral-identities-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: RingCentral Adaptive Cards Identities 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: Identities
paths:
  /cx/social-messaging/v1/identities:
    get:
      tags:
      - Identities
      summary: List All Identities
      description: 'List identities by creation date. The default order is descending.


        The account context of this request is determined by the RC Account Id associated with the access token provided

        in the Authorization header.


        The query parameters provided shall be considered an AND operation to filter the list.


        A query parameter not specified or a query parameter provided with no value is treated as not required for

        filtering the list.

        '
      operationId: socMsgListIdentities
      parameters:
      - $ref: '#/components/parameters/SourceId'
      - $ref: '#/components/parameters/IdentityGroupIds'
      - $ref: '#/components/parameters/UserId'
      - $ref: '#/components/parameters/UUID'
      - $ref: '#/components/parameters/SocMsgOrderBy'
      - $ref: '#/components/parameters/PageToken'
      - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          $ref: '#/components/responses/SocMsgListIdentitiesResponse200'
        '400':
          $ref: '#/components/responses/SocMsgListIdentitiesResponse400'
      x-throttling-group: Light
      x-app-permission: SocialMessaging
  /cx/social-messaging/v1/identities/{identityId}:
    get:
      tags:
      - Identities
      summary: Get Identity
      description: 'Renders an identity from given id.

        '
      operationId: socMsgGetIdentity
      parameters:
      - $ref: '#/components/parameters/IdentityId'
      responses:
        '200':
          $ref: '#/components/responses/SocMsgGetIdentityResponse200'
        '404':
          $ref: '#/components/responses/SocMsgResponse404'
      x-throttling-group: Light
      x-app-permission: SocialMessaging
components:
  parameters:
    SourceId:
      name: sourceId
      description: Filter based on the specified sourceId.
      in: query
      required: false
      schema:
        type: string
    UUID:
      name: uuid
      description: Filter based on the specified uuid.
      in: query
      required: false
      schema:
        type: string
    SocMsgOrderBy:
      in: query
      name: orderBy
      required: false
      description: Order results by specified field.
      schema:
        $ref: '#/components/schemas/SocMsgCreationTimeOrder'
    IdentityId:
      in: path
      name: identityId
      required: true
      schema:
        $ref: '#/components/schemas/IdentityId'
    PageToken:
      name: pageToken
      in: query
      description: 'The token indicating the particular page of the result set to be retrieved.

        If omitted the first page will be returned.

        '
      required: false
      explode: false
      schema:
        type: string
    IdentityGroupIds:
      name: identityGroupIds
      description: Filter based on the specified identityGroupIds (separated by commas).
      in: query
      required: false
      style: form
      explode: false
      schema:
        type: array
        items:
          type: string
    PerPage:
      name: perPage
      in: query
      description: 'The number of items per page. If provided value in the request

        is greater than a maximum, the maximum value is applied

        '
      required: false
      explode: false
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 1000
        default: 100
      example: 100
    UserId:
      name: userId
      description: Filter based on the specified userId.
      in: query
      required: false
      schema:
        type: string
  schemas:
    IdentityAvatarURI:
      description: Identity's avatar Uri.
      type: string
      format: uri
      example: https://example.com/assets/avatar/default-79fd530c58c2a6b83a11fcc0e842ed7023ceb69292cfeb857bc2af2c624b90fd.png
    IdentityFbBio:
      description: 'Facebook biography of the identity.


        Applicable to Facebook and Messenger channels only.

        '
      type: string
      example: Painter living in Paris
    IdentityModel:
      type: object
      required:
      - id
      - type
      - creationTime
      - lastModifiedTime
      properties:
        id:
          $ref: '#/components/schemas/IdentityId'
        avatarUri:
          $ref: '#/components/schemas/IdentityAvatarURI'
        company:
          $ref: '#/components/schemas/SocMsgCompany'
        creationTime:
          $ref: '#/components/schemas/SocMsgCreationTime'
        displayName:
          $ref: '#/components/schemas/IdentityDisplayName'
        emailAddress:
          $ref: '#/components/schemas/SocMsgEmailAddress'
        extraValues:
          $ref: '#/components/schemas/IdentityExtraValues'
        firstName:
          $ref: '#/components/schemas/SocMsgFirstName'
        gender:
          $ref: '#/components/schemas/SocMsgGender'
        homePhone:
          $ref: '#/components/schemas/SocMsgPhoneNumber'
        identityGroupId:
          $ref: '#/components/schemas/IdentityGroupId'
        lastName:
          $ref: '#/components/schemas/SocMsgLastName'
        mobilePhone:
          $ref: '#/components/schemas/SocMsgPhoneNumber'
        screenName:
          $ref: '#/components/schemas/IdentityScreenName'
        type:
          $ref: '#/components/schemas/IdentityType'
        lastModifiedTime:
          $ref: '#/components/schemas/SocMsgLastModifiedTime'
        userIds:
          $ref: '#/components/schemas/IdentityUserIds'
        uuid:
          $ref: '#/components/schemas/IdentityUUID'
        mobileDeviceInfo:
          $ref: '#/components/schemas/IdentityMobileDeviceInfo'
        fbBio:
          $ref: '#/components/schemas/IdentityFbBio'
        fbCategory:
          $ref: '#/components/schemas/IdentityFbCategory'
        fbLocale:
          $ref: '#/components/schemas/IdentityFbLocale'
        igFollowersCount:
          $ref: '#/components/schemas/IdentityIgFollowersCount'
        twDescription:
          $ref: '#/components/schemas/IdentityTwDescription'
        twFollowersCount:
          $ref: '#/components/schemas/IdentityTwFollowersCount'
        twFollowingCount:
          $ref: '#/components/schemas/IdentityTwFollowingCount'
        twStatusesCount:
          $ref: '#/components/schemas/IdentityTwStatusesCount'
        twLocation:
          $ref: '#/components/schemas/IdentityTwLocation'
        apiVersion:
          $ref: '#/components/schemas/IdentityApiVersion'
        country:
          $ref: '#/components/schemas/IdentityCountry'
        deviceType:
          $ref: '#/components/schemas/IdentityDeviceType'
        language:
          $ref: '#/components/schemas/IdentityLanguage'
        mcc:
          $ref: '#/components/schemas/IdentityMcc'
        mnc:
          $ref: '#/components/schemas/IdentityMnc'
        primaryDeviceOs:
          $ref: '#/components/schemas/IdentityPrimaryDeviceOs'
        viberVersion:
          $ref: '#/components/schemas/IdentityViberVersion'
    SocMsgPhoneNumber:
      description: Phone number.
      type: string
      example: '+33634231224'
    IdentityGroupId:
      description: 'The identity group id references the identity group that contains

        all information (phone, notes, etc.). Many identities may belong to

        this group. If the identity group id is null, it means that identity

        does not have a group and any extra information.

        '
      type: string
      example: 54085e5b7aa58d8b5d00006c
    IdentityViberVersion:
      description: 'Viber application version of the identity.


        Applicable to Viber channels only.

        '
      type: string
      example: 19.5.0
    SocMsgCompany:
      description: Company.
      type: string
      example: Test Company
    IdentityLanguage:
      description: 'Viber language of the identity.


        Applicable to Viber channels only.

        '
      type: string
      example: fr-FR
    IdentityPrimaryDeviceOs:
      description: 'Viber primary device OS of the identity.


        Applicable to Viber channels only.

        '
      type: string
      example: Android 11
    IdentityTwLocation:
      description: 'Twitter location of the identity.


        Applicable to Twitter channels only.

        '
      type: string
      example: Paris
    IdentityTwDescription:
      description: 'Twitter description of the identity.


        Applicable to Twitter channels only.

        '
      type: string
      example: Software Engineer
    SocMsgCreationTime:
      description: Creation time of the resource.
      format: date-time
      type: string
      example: '2023-02-04T12:43:07Z'
    SocMsgGender:
      description: Gender.
      type:
      - string
      - 'null'
      example: Woman
      enum:
      - Man
      - Woman
    IdentityDeviceType:
      description: 'Viber device type of the identity.


        Applicable to Viber channels only.

        '
      type: string
      example: SM-G970U1
    IdentityDisplayName:
      description: Display name of the identity.
      type: string
      example: John Doe
    SocMsgLastModifiedTime:
      description: The time when the last modification was completed.
      format: date-time
      type: string
      example: '2023-02-04T12:43:07Z'
    IdentityFbCategory:
      description: 'Facebook category of the identity.


        Applicable to Facebook and Messenger channels only.

        '
      type: string
      example: Computers/Internet
    NonEnumeratedPagingModel:
      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
        pageToken:
          type: string
          description: 'Current page token. May be omitted if result is empty (because non-existent page

            was specified or perPage=0 was requested)

            '
        nextPageToken:
          type: string
          description: A page token to be used to fetch the next page of the result set. May be omitted if the current page is the last one.
        previousPageToken:
          type: string
          description: 'A page token to be used to fetch the previous page of the result set.

            May be omitted if the current page is the first one or if the result set does not support backward navigation.

            '
        firstPageToken:
          type: string
          description: A page token to be used to fetch the first page of the result set.
    IdentityMcc:
      description: 'Viber mobile country code of the identity.


        Applicable to Viber channels only.

        '
      type: string
      example: '1'
    SocMsgFirstName:
      description: FirstName.
      type: string
      example: John
    IdentityExtraValues:
      description: Additional data to store along the identity.
      type: object
      additionalProperties:
        type: string
      example:
        key: value
    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
    IdentityMobileDeviceInfo:
      description: 'Device info of the identity.


        Applicable to RingCX Digital Messaging channels only.

        '
      type: string
      example: iPhone (iPhone); iOS 15.0.2
    IdentityUserIds:
      description: List of the associated user identifiers who can use the identity.
      items:
        type: string
        example: 54085e5b7aa58d8b5d00006c
      type: array
      minItems: 0
    IdentityMnc:
      description: 'Viber mobile network code of the identity.


        Applicable to Viber channels only.

        '
      type: string
      example: '220'
    IdentityTwFollowersCount:
      description: 'Twitter followers count of the identity.


        Applicable to Twitter channels only.

        '
      type: integer
      format: int32
      example: 10
    IdentityApiVersion:
      description: 'Viber API version of the identity.


        Applicable to Viber channels only.

        '
      type: string
      example: '10'
    ApiErrorResponseModel:
      type: object
      description: Standard error response model which is returned in case of any unsuccessful operation
      required:
      - errors
      properties:
        errors:
          type: array
          description: The array of errors (there will be just one in the most of the cases)
          minItems: 1
          items:
            $ref: '#/components/schemas/ApiError'
    IdentityCountry:
      description: 'Viber country of the identity.


        Applicable to Viber channels only.

        '
      type: string
      example: FR
    SocMsgLastName:
      description: LastName.
      type: string
      example: Doe
    IdentityIgFollowersCount:
      description: 'Instagram followers count of the identity.


        Applicable to Instagram and InstagramMessaging channels only.

        '
      type: integer
      format: int32
      example: 10
    IdentityId:
      type: string
      description: Identity identifier.
      example: 506d9e817aa58d1259000f12
    SocMsgCreationTimeOrder:
      description: Ordering by creationTime is descending by default.
      type: string
      enum:
      - -creationTime
      - +creationTime
      - creationTime
      default: -creationTime
      example: +creationTime
    IdentityTwStatusesCount:
      description: 'Count of tweets of the identity.


        Applicable to Twitter channels only.

        '
      type: integer
      format: int32
      example: 42
    IdentityUUID:
      description: UUID of the identity.
      type: string
      example: 9680ab94-3b78-495c-bb2c-a969954d8260
    IdentitiesList:
      type: object
      required:
      - records
      - paging
      properties:
        records:
          type: array
          minItems: 0
          items:
            $ref: '#/components/schemas/IdentityModel'
        paging:
          $ref: '#/components/schemas/NonEnumeratedPagingModel'
    IdentityScreenName:
      description: Screen name of the identity.
      type: string
      example: John D.
    IdentityFbLocale:
      description: 'Facebook locale of the identity.


        Applicable to Facebook and Messenger channels only.

        '
      type: string
      example: fr_FR
    IdentityTwFollowingCount:
      description: 'Count of Twitter accounts followed by the identity.


        Applicable to Twitter channels only.

        '
      type: integer
      format: int32
      example: 500
    IdentityType:
      description: Type of the identity.
      type: string
      enum:
      - AppleMessagesForBusiness
      - Email
      - EngageMessaging
      - Facebook
      - GoogleBusinessMessages
      - GoogleMyBusiness
      - Instagram
      - Linkedin
      - Twitter
      - Viber
      - WhatsApp
      - Youtube
    SocMsgEmailAddress:
      description: Email address.
      type: string
      format: email
      example: user@example.com
  examples:
    EDI-032:
      summary: Invalid id
      value:
        errors:
        - errorCode: EDI-032
          message: 'Invalid id: [${invalidId}]'
    EDI-029:
      summary: Resource not found
      value:
        errors:
        - errorCode: EDI-029
          message: Resource not found
    EDI-028:
      summary: Search query is invalid
      value:
        errors:
        - errorCode: EDI-028
          message: Search query is invalid
        - errorCode: EDI-028
          message: Searching identity groups by "firstname" only is disabled, please provide "lastname"
  responses:
    SocMsgListIdentitiesResponse400:
      description: Error 400 on Identity search
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponseModel'
          examples:
            EDI-028:
              $ref: '#/components/examples/EDI-028'
    SocMsgGetIdentityResponse200:
      description: Successful response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IdentityModel'
    SocMsgResponse404:
      description: Error 404
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponseModel'
          examples:
            EDI-029:
              $ref: '#/components/examples/EDI-029'
            EDI-032:
              $ref: '#/components/examples/EDI-032'
    SocMsgListIdentitiesResponse200:
      description: Successful response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/IdentitiesList'
  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