--- title: "Search Telegram contacts and the public directory" method: GET path: "/v1/contacts/search" tags: ["Identity"] --- # Search Telegram contacts and the public directory `GET /v1/contacts/search` ## Request - Base URL: `https://telegram155.p.rapidapi.com` - URL: `https://telegram155.p.rapidapi.com/v1/contacts/search` - Auth: none declared Returns matching peers from the public directory. `q` must be at least 4 characters: Telegram's directory search ignores shorter queries and answers with an empty result rather than an error, so this API rejects them up front (400 `INVALID_REQUEST`, `query too short`) instead of returning an empty page you would have to interpret. A shorter term still works if you pad it to four characters with spaces: `?q=gta%20` searches for `gta` and returns GTA-prefixed peers. Telegram measures the query as sent but trims it before matching, and `q` is forwarded to it byte-for-byte. ## Query parameters - `q` string, required - `limit` integer ## Response `200` Matching peers. - ContactsSearch: Hybrid contact + global directory search. `results[]` are public directory matches; `my_results[]` is reserved for future use and is currently null. - `chats` Chat[] - `autotranslation` boolean: True if auto-translation is enabled. - `broadcast` boolean: True if this is a broadcast channel. - `date` integer: Unix timestamp the chat was created. - `fake` boolean: True if Telegram has flagged this chat as fake. - `forum` boolean: True if this is a forum (channel with topics). - `gigagroup` boolean: True if this is a gigagroup (broadcast-only supergroup). - `id` integer: Chat peer id. Pass this as `peer_id` to channel/peer endpoints. - `join_request` boolean: True if join requires admin approval. - `join_to_send` boolean: True if posting requires joining. - `left` boolean: True if the viewer has left this chat. - `level` integer: Boost level. - `linked_monoforum_id` integer: Linked monoforum id (if any). - `megagroup` boolean: True if this is a supergroup. - `min` boolean: True if the record is a stripped (min) representation. - `noforwards` boolean: True if content protection (no forwards) is enabled. - `participants_count` integer: Approximate participant count (may be 0 if not exposed). - `photo` Photo: Photo metadata. The image bytes are not returned; clients fetch them out-of-band. - `dcid` integer: Telegram data-center id where the photo lives. - `flags` integer: Bitfield flags. - `has_video` boolean: True if the photo has a video preview. - `photo_id` integer: Photo id. - `stripped_thumb` string: Base64-ish stripped JPEG thumbnail; can be expanded client-side. - `restricted` boolean: True if this chat is restricted (see `restriction_reason`). - `restriction_reason` object[], nullable: Reasons for any restriction. - `scam` boolean: True if Telegram has flagged this chat as a scam. - `signatures` boolean: True if posts show their author. - `slowmode_enabled` boolean: True if slow mode is on. - `title` string: Public display title of the chat. - `username` string: Primary public @username (empty if private). - `usernames` UsernameAlias[], nullable: All public usernames bound to this chat. - `active` boolean: True if the alias is currently active. - `editable` boolean: True if the alias can be edited (only true for the primary one). - `flags` integer: Bitfield of optional Telegram fields. - `username` string: The alias text (no leading @). - `verified` boolean: True if Telegram has verified this chat. - `my_results` Peer[], nullable: Reserved; currently null. - `channel_id` integer: Set when this peer is a channel or supergroup. - `chat_id` integer: Set when this peer is a legacy basic group chat. - `user_id` integer: Set when this peer is a user (1:1 chat partner or contact). - `results` Peer[]: Matches from the public directory. - `channel_id` integer: Set when this peer is a channel or supergroup. - `chat_id` integer: Set when this peer is a legacy basic group chat. - `user_id` integer: Set when this peer is a user (1:1 chat partner or contact). - `users` User[] - `bot` boolean: True if this account is a bot. - `close_friend` boolean: Close-friend flag. - `contact` boolean: Contact-relationship flag. - `deleted` boolean: True if the account has been deleted. - `fake` boolean: True if Telegram has flagged this account as fake. - `first_name` string: First name (may be empty for deleted accounts). - `id` integer: User peer id. Pass this as `peer_id` to `/v1/users/{peer_id}`. - `lang_code` string: BCP-47-ish locale code reported by the client (e.g. "en", "ru"). - `last_name` string: Last name (may be empty). - `mutual_contact` boolean: True if the contact relationship is mutual. - `phone` string: Phone number in international format. Empty unless the caller has visibility. - `photo` Photo: Photo metadata. The image bytes are not returned; clients fetch them out-of-band. - `dcid` integer: Telegram data-center id where the photo lives. - `flags` integer: Bitfield flags. - `has_video` boolean: True if the photo has a video preview. - `photo_id` integer: Photo id. - `stripped_thumb` string: Base64-ish stripped JPEG thumbnail; can be expanded client-side. - `premium` boolean: True if this account has Telegram Premium. - `restricted` boolean: True if this user is restricted (see `restriction_reason`). - `restriction_reason` object[], nullable: Reasons for any restriction. Null when not restricted. - `scam` boolean: True if Telegram has flagged this account as a scam. - `status` object, nullable: Online status object (varies by privacy settings). - `username` string: Primary public @username (empty if the user has none). - `usernames` UsernameAlias[], nullable: All public usernames bound to this user (some accounts collect multiple). - `active` boolean: True if the alias is currently active. - `editable` boolean: True if the alias can be edited (only true for the primary one). - `flags` integer: Bitfield of optional Telegram fields. - `username` string: The alias text (no leading @). - `verified` boolean: True if Telegram has verified this user. ## Other responses - `400`: Invalid request — bad path or query parameter. - `404`: Not found. - `409`: The peer id could not be found, so no access hash exists for it. Not transient: seed the id via GET /v1/usernames/{username}, GET /v1/phones/{phone}, or by encountering it in a chat, then retry. Raw MTProto ids only: a Bot-API id like -1001234567890 must be sent as 1234567890 (strip the leading -100), and -123456789 as 123456789. When the request carries such an id, the hint names the exact id to retry with. - `429`: Rate limit exceeded. - `503`: Service temporarily unavailable. - `504`: Request timed out. --- [API](https://skmtc.dev/tgatlas/apis/tgatlas-telegram-channel-data-api.md) · [All operations](https://skmtc.dev/tgatlas/apis/tgatlas-telegram-channel-data-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tgatlas/apis/tgatlas-telegram-channel-data-api/revisions/875ce0155fe9?raw)