Sign in

v1

latestOpenAPI 3.0.3RingCentral API License Agreement2026-08-064871,2921.5 MB
Internal Contacts

Search Company Directory Entries

Returns contact information on corporate users of federated accounts according to the specified filtering and ordering.

post/restapi/v1.0/account/{accountId}/directory/entries/search

Path parameters

accountIdstring required

Internal identifier of the RingCentral account (can be set to "~" to indicate that the account associated with current authorization session should be used)

Query parameters

accountIdstring
Example:400131426008

A list of Account IDs

departmentstring
Example:North office

A list of department names

siteIdstring
Example:872781797006

A list of Site IDs

extensionStatusstring
Example:Enabled

Extension current state

extensionType'User' | 'Department' | 'Announcement' | 'Voicemail' | 'DigitalUser' | 'VirtualUser' | 'FaxUser' | 'PagingOnly' | 'SharedLinesGroup' | 'IvrMenu' | 'ApplicationExtension' | 'ParkLocation' | 'Limited' | 'Bot' | 'Site' | 'Room' | 'ProxyAdmin' | 'DelegatedLinesGroup' | 'FlexibleUser' | 'GroupCallPickup' | 'RoomConnector'

Type of extension to filter the contacts

Example:User

Extension types

Request body

searchStringstring

String value to filter the contacts. The value specified is searched through the following fields: firstName, lastName, extensionNumber, phoneNumber, email, jobTitle, department, customFieldValue

searchFieldsstring[]

The list of field to be searched for

showFederatedboolean

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

showAdminOnlyContactsboolean

Should show AdminOnly Contacts

extensionType'User' | 'Department' | 'Announcement' | 'Voicemail' | 'SharedLinesGroup' | 'PagingOnly' | 'ParkLocation' | 'IvrMenu' | 'Limited' | 'ApplicationExtension' | 'Site' | 'Bot' | 'Room' | 'DelegatedLinesGroup' | 'GroupCallPickup' | 'External'

Type of directory contact to filter

siteIdstring

Internal identifier of the business site to which extensions belong

showExternalContactsboolean

Allows to control whether External (Hybrid) contacts should be returned in the response or not

accountIdsstring[]

The list of Internal identifiers of an accounts

departmentstring

Department

siteIdsstring[]

The list of Internal identifiers of the business sites to which extensions belong

extensionStatusesstring[]

Extension current state.

extensionTypesSearchDirectoryExtensionType[]

Types of extension to filter the contacts

pageinteger
perPageinteger

Example request

{
  "searchString": "John Doe",
  "searchFields": [
    "lastName",
    "email"
  ],
  "showFederated": true,
  "siteIds": [
    "872781797006",
    "872781820006"
  ],
  "extensionStatuses": [
    "Enabled"
  ],
  "department": "R&D department",
  "page": 1,
  "perPage": 30
}

Response

Paged collection of all contacts information for a given account according to filtering and ordering. Records can be empty if no data found

Example response

{
  "paging": {
    "perPage": 50,
    "page": 5,
    "pageEnd": 5,
    "totalPages": 25,
    "totalElements": 25
  },
  "records": [
    {
      "id": "865706371004",
      "type": "User",
      "status": "Enabled",
      "account": {
        "companyName": "My lovely company",
        "federatedName": "Lovely Holding",
        "id": "400131426008",
        "mainNumber": {
          "formattedPhoneNumber": "+1 (205) 6812029",
          "phoneNumber": "+12056812029",
          "type": "VoiceFax",
          "label": "Boss",
          "usageType": "DirectNumber"
        }
      },
      "department": "External",
      "email": "john.doe@mycompany.com",
      "extensionNumber": "103",
      "firstName": "John",
      "lastName": "Doe",
      "name": "Conference room ?5",
      "jobTitle": "Sales manager",
      "phoneNumbers": [
        {
          "formattedPhoneNumber": "+1 (205) 6812029",
          "phoneNumber": "+12056812029",
          "type": "VoiceFax",
          "label": "Boss",
          "usageType": "DirectNumber"
        }
      ],
      "profileImage": {
        "etag": "tag"
      },
      "site": {
        "id": "872781820006",
        "name": "Sales site",
        "code": "1007"
      },
      "callQueues": [
        {
          "id": "873014540006",
          "name": "Sales CQ"
        }
      ],
      "customFields": [
        {
          "id": "1032854",
          "name": "Rank",
          "value": "5"
        }
      ],
      "groups": [
        {
          "id": "63723034",
          "name": "Leaders"
        }
      ],
      "costCenter": {
        "id": "83266549237542",
        "code": "Main",
        "name": "Cost Center A"
      },
      "integration": {
        "id": "9813",
        "typeId": "1",
        "type": "External",
        "displayName": "Integration X",
        "routingType": "Account",
        "outboundEdgeId": "1726"
      },
      "subType": "Unknown"
    }
  ]
}