---
title: "Find chats by recipient"
method: GET
path: "/api/v2/chats/search/recipients"
tags: ["Chats"]
---

# Find chats by recipient

`GET /api/v2/chats/search/recipients`

<a class="try-sandbox-link" href="https://sandbox.textmagic.com/#/Chats/searchChatsByReceipent" target="_blank">Try in sandbox</a><br>Find chats by recipient (contact, list name or phone number).

## Query parameters

- `page` integer
- `limit` integer
- `query` string
- `orderBy` 'id' | 'unread' | 'messageTime'

## Response `200`

Returned when successful.

- SearchChatsByReceipentPaginatedResponse
  - `page` integer, required
  - `pageCount` integer, required — The total number of pages.
  - `limit` integer, required — The number of results per page.
  - `resources` Chat[], required
    - `id` integer, required — Chat ID.
    - `originalId` integer, nullable, required
    - `phone` string, required — Chat partner's phone number.
    - `contact` Contact, nullable, required
      - `id` integer, required — Contact ID.
      - `favorited` boolean, required — Is the Contact favorite? [Favorite list](https://docs.textmagic.com/#operation/getFavorites).
      - `blocked` boolean, required — Is the Contact blocked? [Blocked contacts](https://docs.textmagic.com/#operation/getBlockedContacts).
      - `firstName` string, nullable, required — Contact first name.
      - `lastName` string, nullable, required — Contact last name.
      - `companyName` string, nullable, required — Company name.
      - `phone` string, nullable, required — Phone number in [E.164 format](https://en.wikipedia.org/wiki/E.164).
      - `email` string, email, nullable, required — Contact email address.
      - `country` Country, nullable, required
        - `id` string, required — The 2-letter ISO country ID.
        - `name` string, required — Full country name.
      - `customFields` CustomFieldListItem[], required
        - `id` integer, required — Custom Field ID.
        - `userCustomFieldId` integer, required — Old property custom Field ID.
        - `name` string, required — Custom Field name.
        - `value` string, required — Custom Field value.
        - `createdAt` string, date-time, required — Custom field creation time.
      - `customFieldValues` CustomFieldValues[], required
        - `fieldId` integer
        - `fieldTitle` string
        - `fieldType` string
        - `value` object
      - `user` User, nullable, required
        - `id` integer, required — User ID.
        - `displayTimeFormat` '12h' | '24h' — User's preferred format of time display: * *12h* - AM/PM format; * *24h* - 24-hour clock format.
        - `username` string, required — Username.
        - `firstName` string, required — Account first name.
        - `lastName` string, required — Account last name.
        - `email` string, required — User email address.
        - `status` 'A' | 'T', required — Current account status: * **A** for Active; * **T** for Trial.
        - `balance` number, required — Account balance (in account currency).
        - `phone` string, nullable, required — User's phone number.
        - `company` string, nullable, required — Account company name.
        - `currency` Currency, required
          - `id` string, required — The 3-letter ISO currency ID.
          - `unicodeSymbol` string, required — Unicode-compatible currency symbol.
          - `htmlSymbol` string, required — HTML-compatible currency symbol.
        - `country` Country, nullable, required
          - `id` string, required — The 2-letter ISO country ID.
          - `name` string, required — Full country name.
        - `timezone` Timezone, required
          - `id` integer, required — Internal timezone ID.
          - `area` string, required — Timezone area.
          - `dst` integer, required — Is daylight saving time used in this timezone?
          - `offset` integer, required — Offset from UTC time in seconds. In this example, it is 21600/60/60=6 hours.
          - `timezone` string, required — User-friendly timezone name (with spaces replaced by underscores).
        - `subaccountType` 'P' | 'A' | 'U', required — Type of account: * **P** for Parent User; * **A** for Administrator Sub-Account; * **U** for Regular User.
        - `emailAccepted` boolean, required — Does the account have a confirmed email?
        - `phoneAccepted` boolean, required — Does the account have a confirmed phone number?
        - `avatar` UserImage, nullable, required
          - `href` string, required — The URI of a user avatar.
      - `lists` List[], required
        - `id` integer, required — List ID.
        - `name` string, required — List name.
        - `description` string, nullable, required — Description of the list.
        - `favorited` boolean, required — Is the List favorited? See [Favorites list](https://docs.textmagic.com/#operation/getFavourites).
        - `membersCount` integer, required — List members count.
        - `user` User, nullable, required
          - `id` integer, required — User ID.
          - `displayTimeFormat` '12h' | '24h' — User's preferred format of time display: * *12h* - AM/PM format; * *24h* - 24-hour clock format.
          - `username` string, required — Username.
          - `firstName` string, required — Account first name.
          - `lastName` string, required — Account last name.
          - `email` string, required — User email address.
          - `status` 'A' | 'T', required — Current account status: * **A** for Active; * **T** for Trial.
          - `balance` number, required — Account balance (in account currency).
          - `phone` string, nullable, required — User's phone number.
          - `company` string, nullable, required — Account company name.
          - `currency` Currency, required
            - `id` string, required — The 3-letter ISO currency ID.
            - `unicodeSymbol` string, required — Unicode-compatible currency symbol.
            - `htmlSymbol` string, required — HTML-compatible currency symbol.
          - `country` Country, nullable, required
            - `id` string, required — The 2-letter ISO country ID.
            - `name` string, required — Full country name.
          - `timezone` Timezone, required
            - `id` integer, required — Internal timezone ID.
            - `area` string, required — Timezone area.
            - `dst` integer, required — Is daylight saving time used in this timezone?
            - `offset` integer, required — Offset from UTC time in seconds. In this example, it is 21600/60/60=6 hours.
            - `timezone` string, required — User-friendly timezone name (with spaces replaced by underscores).
          - `subaccountType` 'P' | 'A' | 'U', required — Type of account: * **P** for Parent User; * **A** for Administrator Sub-Account; * **U** for Regular User.
          - `emailAccepted` boolean, required — Does the account have a confirmed email?
          - `phoneAccepted` boolean, required — Does the account have a confirmed phone number?
          - `avatar` UserImage, nullable, required
            - `href` string, required — The URI of a user avatar.
        - `service` boolean, required — Internal service field.
        - `shared` boolean, nullable, required — Is the list **shared** among all sub-accounts?
        - `avatar` ListImage, nullable, required
          - `href` string, required — The URI of a list avatar.
        - `isDefault` boolean, nullable, required — Indicates that List is used as a default. All new contacts added via the Web-app will be added in this List by default.
      - `owner` User, nullable
        - `id` integer, required — User ID.
        - `displayTimeFormat` '12h' | '24h' — User's preferred format of time display: * *12h* - AM/PM format; * *24h* - 24-hour clock format.
        - `username` string, required — Username.
        - `firstName` string, required — Account first name.
        - `lastName` string, required — Account last name.
        - `email` string, required — User email address.
        - `status` 'A' | 'T', required — Current account status: * **A** for Active; * **T** for Trial.
        - `balance` number, required — Account balance (in account currency).
        - `phone` string, nullable, required — User's phone number.
        - `company` string, nullable, required — Account company name.
        - `currency` Currency, required
          - `id` string, required — The 3-letter ISO currency ID.
          - `unicodeSymbol` string, required — Unicode-compatible currency symbol.
          - `htmlSymbol` string, required — HTML-compatible currency symbol.
        - `country` Country, nullable, required
          - `id` string, required — The 2-letter ISO country ID.
          - `name` string, required — Full country name.
        - `timezone` Timezone, required
          - `id` integer, required — Internal timezone ID.
          - `area` string, required — Timezone area.
          - `dst` integer, required — Is daylight saving time used in this timezone?
          - `offset` integer, required — Offset from UTC time in seconds. In this example, it is 21600/60/60=6 hours.
          - `timezone` string, required — User-friendly timezone name (with spaces replaced by underscores).
        - `subaccountType` 'P' | 'A' | 'U', required — Type of account: * **P** for Parent User; * **A** for Administrator Sub-Account; * **U** for Regular User.
        - `emailAccepted` boolean, required — Does the account have a confirmed email?
        - `phoneAccepted` boolean, required — Does the account have a confirmed phone number?
        - `avatar` UserImage, nullable, required
          - `href` string, required — The URI of a user avatar.
      - `tags` Tag[]
        - `id` integer, required — Tag ID.
        - `title` string, required — Tag title.
      - `phoneType` string, nullable, required — Phone number type: * **0** if it is fixed-line; * **1** if it is mobile; * **2** if it is mobile or fixed-line (in case we cannot distingush between fixed-line or mobile); * **3** if it is toll-free; * **4** if it is a premium rate phone; * **5** if it is a shared cost phone; * **6** if it is a VoIP; * **7** if it is a [Personal Number](); * **8** if it is a pager; * **9** if it is a Universal Access Number; * **10** if the phone type is unknown; * **-1** if the phone type is not yet processed or cannot be determined.
      - `avatar` ContactImage, nullable, required
        - `href` string, required — The URI of a contact avatar.
      - `notes` ContactNote[], required
        - `id` integer, required — Contact note ID.
        - `createdAt` string, date-time, required — Contact note creation time.
        - `note` string, required — Contact note text.
        - `user` User, nullable, required
          - `id` integer, required — User ID.
          - `displayTimeFormat` '12h' | '24h' — User's preferred format of time display: * *12h* - AM/PM format; * *24h* - 24-hour clock format.
          - `username` string, required — Username.
          - `firstName` string, required — Account first name.
          - `lastName` string, required — Account last name.
          - `email` string, required — User email address.
          - `status` 'A' | 'T', required — Current account status: * **A** for Active; * **T** for Trial.
          - `balance` number, required — Account balance (in account currency).
          - `phone` string, nullable, required — User's phone number.
          - `company` string, nullable, required — Account company name.
          - `currency` Currency, required
            - `id` string, required — The 3-letter ISO currency ID.
            - `unicodeSymbol` string, required — Unicode-compatible currency symbol.
            - `htmlSymbol` string, required — HTML-compatible currency symbol.
          - `country` Country, nullable, required
            - `id` string, required — The 2-letter ISO country ID.
            - `name` string, required — Full country name.
          - `timezone` Timezone, required
            - `id` integer, required — Internal timezone ID.
            - `area` string, required — Timezone area.
            - `dst` integer, required — Is daylight saving time used in this timezone?
            - `offset` integer, required — Offset from UTC time in seconds. In this example, it is 21600/60/60=6 hours.
            - `timezone` string, required — User-friendly timezone name (with spaces replaced by underscores).
          - `subaccountType` 'P' | 'A' | 'U', required — Type of account: * **P** for Parent User; * **A** for Administrator Sub-Account; * **U** for Regular User.
          - `emailAccepted` boolean, required — Does the account have a confirmed email?
          - `phoneAccepted` boolean, required — Does the account have a confirmed phone number?
          - `avatar` UserImage, nullable, required
            - `href` string, required — The URI of a user avatar.
      - `whatsappPhone` string, nullable — Whatsapp phone number in [E.164 format](https://en.wikipedia.org/wiki/E.164).
    - `unsubscribedContactId` integer, nullable, required — If this field has a value, it means that the chat phone number has been unsubscribed from you and this value is an ID of an Unsubscribed contact entity. See [Get all unsubscribed contacts](https://docs.textmagic.com/#operation/getUnsubscribers).
    - `unread` integer, required — Total unread incoming messages.
    - `updatedAt` string, date-time, required — Time when the last incoming message arrived at this chat.
    - `status` 'a' | 'c' | 'd', required — Chat status: * **a** - Active; * **c** - Closed; * **d** - Deleted.
    - `mute` 0 | 1, required — Indicates when the chat is muted.
    - `lastMessage` string, nullable, required — The last message content of a chat.
    - `direction` 'ci' | 'co' | 'i' | 'o', nullable, required — Last message type: * **ci** - incoming call; * **co** - outgoing call; * **i** - incoming message; * **o** - outgoing message.
    - `replyOptionsType` string, nullable, required — Used for chats prices.
    - `from` string, nullable, required — If filled, the value will be used as a sender number for all outgoing messages of a chat.
    - `mutedUntil` string, date-time, nullable, required — Date and time until the chat will be muted.
    - `timeLeftMute` integer, required — Time left untill the chat will be unmuted (seconds).
    - `country` Country, nullable, required
      - `id` string, required — The 2-letter ISO country ID.
      - `name` string, required — Full country name.
    - `pinned` boolean, nullable, required — Indicates when the chat is pinned.
    - `type` string, required — Chat type.
    - `smsPrice` number, required
    - `mmsPrice` number, required
    - `tags` Tag[]
      - `id` integer, required — Tag ID.
      - `title` string, required — Tag title.
    - `assigneeId` integer, nullable, required
    - `updatedBy` NullableUserPersonalInfo, nullable
      - `id` integer — User ID.
      - `firstName` string, nullable — User's first name.
      - `lastName` string, nullable — User's last name.
      - `avatarUrl` string, nullable — URL to user's avatar image.
      - `email` string, email, nullable — User's email address.
    - `createdAt` string, date-time, required — Chat creation date and time.
    - `messageTime` string, date-time, required — Chat last message date and time.
    - `conversationEnded` boolean, nullable — Indicates whether the live chat conversation has ended. Null for non-live chats.
    - `rating` object, nullable — Live chat satisfaction survey result. Null when the chat has no rating.
      - `rate` 'good' | 'poor' | 'no-rate' — Satisfaction survey reaction.
      - `comment` string, nullable — Optional survey comment left by a contact.

## Other responses

- `401` — Unauthorized request.

---

[API](https://skmtc.net/textmagic/apis/textmagic-api.md) · [All operations](https://skmtc.net/textmagic/apis/textmagic-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/textmagic/textmagic-api/revisions/3e4029d19684/schema)