# Search Directory Contacts

`ringcentral_search-directory-contacts` · RingCentral MCP tool · Identity

Search the RingCentral account's company directory (and any federated accounts) by text, extension type/status, site, department, and sort order. Read-only.

## RingCentral Frequently Asked Questions

**What does the Search Directory Contacts tool do?**

This page documents the Search Directory Contacts tool (`ringcentral_search-directory-contacts`). Search the RingCentral account's company directory (and any federated accounts) by text, extension type/status, site, department, and sort order. Read-only. It is one of the RingCentral Identity tools, invoked through your firm's Weave MCP connection and available to members whose access level permits it.

**What is the RingCentral integration?**

The RingCentral integration connects your firm's RingCentral account to Weave. RingCentral (RingEX) is a cloud phone/UCaaS platform. This integration exposes read-only call log, call analytics, recordings, directory, extension, and account diagnostics data as governed MCP tools, scoped per member by access level. It groups 17 tools into 5 categories, exposed through your firm's Weave MCP connection and filtered per member by access level.

## Input

- **searchString** `string` — Text to filter contacts by; matched against firstName, lastName, extensionNumber, phoneNumber, email, jobTitle, department, and customFieldValue.
- **searchFields** `array` — Restrict `searchString` matching to these fields only.
  - **[]** `string` (enum: "firstName", "lastName", "extensionNumber", "phoneNumber", "email", "jobTitle", "department", "customFieldValue")
- **showFederated** `boolean` — If true, include contacts of every account in the federation (each carries its `account` section); if false, only the current account's contacts.
- **showAdminOnlyContacts** `boolean` — Whether to include AdminOnly contacts. Defaults to false.
- **extensionType** `string` (enum: "User", "Department", "Announcement", "Voicemail", "SharedLinesGroup", "PagingOnly", "ParkLocation", "IvrMenu", "Limited", "ApplicationExtension", "Site", "Bot", "Room", "DelegatedLinesGroup", "GroupCallPickup", "External") — Restrict results to this single extension type.
- **siteId** `string` — Internal identifier of the business site to which extensions belong.
- **showExternalContacts** `boolean` — Whether to include External (Hybrid) contacts. Defaults to false.
- **accountIds** `array` — Internal identifiers of the accounts to search within.
  - **[]** `string`
- **department** `string` — Restrict results to this department name.
- **siteIds** `array` — Internal identifiers of the business sites to which extensions belong.
  - **[]** `string`
- **extensionStatuses** `array` — Restrict results to extensions in one of these states.
  - **[]** `string` (enum: "Enabled", "Disabled", "NotActivated")
- **extensionTypes** `array` — Restrict results to one of these extension types.
  - **[]** `string` (enum: "User", "Department", "Announcement", "Voicemail", "DigitalUser", "VirtualUser", "FaxUser", "PagingOnly", "SharedLinesGroup", "IvrMenu", "ApplicationExtension", "ParkLocation", "Limited", "Bot", "Site", "Room", "ProxyAdmin", "DelegatedLinesGroup", "FlexibleUser", "GroupCallPickup", "RoomConnector")
- **orderBy** `array` — Sort criteria, applied in `index` priority order.
  - **[]** `object`
    - **index** `integer` — Sort priority, starting from 1; optional when only one `orderBy` entry is given.
    - **fieldName** `string` (enum: "firstName", "lastName", "extensionNumber", "phoneNumber", "email", "jobTitle", "department") — Field to sort by.
    - **direction** `string` (enum: "Asc", "Desc") — Sort direction; defaults to 'Asc'.
- **page** `integer` — Which results page to fetch. Omit for page 1.
- **perPage** `integer` — Records per page. Omit for the RingCentral default.

## Output

- **paging** `object` (required) — Pagination metadata for `records`.
  - **perPage** `integer` (required) — Page size — how many items are in each page.
  - **page** `integer` — 1-based current page number; omitted if the result is empty.
  - **pageStart** `integer` — 0-based index of the first element on the current page.
  - **pageEnd** `integer` — 0-based index of the last element on the current page.
  - **totalPages** `integer` — Total number of pages in the dataset (may be omitted for performance reasons).
  - **totalElements** `integer` — Total number of elements in the dataset (may be omitted for performance reasons).
- **records** `array` (required) — Matching directory contacts; empty if none found.
  - **[]** `object`
    - **id** `string` (required) — Contact extension identifier.
    - **type** `string` — Contact type (open string — RC directory contact-type taxonomy; may return values beyond the vendored enum).
    - **status** `string` (enum: "Enabled", "Disabled", "Frozen", "NotActivated", "Unassigned", "Unknown") — Contact status.
    - **account** `object` — The account this contact belongs to.
      - **companyName** `string` — Company name of the account.
      - **federatedName** `string` — Federated (holding) company name, if federated.
      - **id** `string` (required) — Internal identifier of the account.
      - **mainNumber** `object` — Account main phone number.
        - **formattedPhoneNumber** `string` — Human-formatted phone number.
        - **phoneNumber** `string` — Phone number in E.164-like form.
        - **type** `string` — Phone number type (documented example 'VoiceFax'; open string, not a closed enum).
        - **label** `string` — Custom user-assigned name of the phone number, if any.
        - **usageType** `string` (enum: "MobileNumber", "ContactNumber", "DirectNumber", "ForwardedNumber") — Usage type of the phone number.
        - **hidden** `boolean` — Whether the phone number should be hidden.
        - **primary** `boolean` — Whether this is the primary number (displayed as 'main number', called by default).
        - **smsAvailabilityStatus** `string` — SMS availability status of the phone number (live-observed, undocumented field).
    - **department** `string` — Department name, when applicable.
    - **email** `string` — Contact email address.
    - **extensionNumber** `string` — Extension short number.
    - **firstName** `string` — First name, for user extensions only.
    - **lastName** `string` — Last name, for user extensions only.
    - **name** `string` — Name, for non-user extensions.
    - **jobTitle** `string` — Job title.
    - **phoneNumbers** `array` — Phone numbers associated with the contact.
      - **[]** `object`
        - **formattedPhoneNumber** `string` — Human-formatted phone number.
        - **phoneNumber** `string` — Phone number in E.164-like form.
        - **type** `string` — Phone number type (documented example 'VoiceFax'; open string, not a closed enum).
        - **label** `string` — Custom user-assigned name of the phone number, if any.
        - **usageType** `string` (enum: "MobileNumber", "ContactNumber", "DirectNumber", "ForwardedNumber") — Usage type of the phone number.
        - **hidden** `boolean` — Whether the phone number should be hidden.
        - **primary** `boolean` — Whether this is the primary number (displayed as 'main number', called by default).
        - **smsAvailabilityStatus** `string` — SMS availability status of the phone number (live-observed, undocumented field).
    - **profileImage** `object` — Contact profile image.
      - **etag** `string` — Identifier of the profile image.
      - **uri** `string` — Link to the profile image resource.
    - **site** `object` — Business site the contact belongs to.
      - **id** `string` — Internal identifier of the business site.
      - **name** `string` — Name of the business site.
      - **code** `string` — Site code value.
    - **hidden** `boolean` — Whether the contact is hidden from the directory.
    - **role** `object` — Directory role assigned to the contact.
      - **id** `string` (required) — Internal identifier of the directory role.
      - **name** `string` — Name of the role.
      - **domain** `string` — Domain the role applies to.
      - **displayName** `string` — Display name of the role.
    - **callQueues** `array` — Call queues the contact belongs to.
      - **[]** `object`
        - **id** `string` — Internal identifier of the call queue.
        - **name** `string` — Name of the call queue.
    - **customFields** `array` — Custom field values on the contact.
      - **[]** `object`
        - **id** `string` — Internal identifier of the custom field.
        - **name** `string` — Name of the custom field.
        - **value** `string` — Value of the custom field.
    - **groups** `array` — Groups the contact belongs to.
      - **[]** `object`
        - **id** `string` — Internal identifier of the group.
        - **name** `string` — Name of the group.
    - **costCenter** `object` — Cost center assigned to the contact.
      - **id** `string` — Internal identifier of the cost center.
      - **code** `string` — Cost center code.
      - **name** `string` — Name of the cost center.
    - **integration** `object` — External integration information, when applicable.
      - **id** `string` — Internal identifier of the external integration.
      - **typeId** `string` — Internal identifier of the integration type.
      - **type** `string` — Integration type.
      - **displayName** `string` — Display name of the integration.
      - **routingType** `string` — Routing type used by the integration.
      - **outboundEdgeId** `string` — Outbound edge identifier used by the integration.
    - **subType** `string` (enum: "Unknown", "VideoPro", "VideoProPlus", "DigitalSignage", "Emergency") — Contact subtype, when applicable.