> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hypersender.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Check Contact Exists
> Verify if a phone number is registered on WhatsApp and retrieve its chatId for messaging purposes.
Check if a phone number is registered on WhatsApp before attempting to send messages.
This endpoint allows you to:
* Verify if a phone number exists on WhatsApp
* Get the correct chatId format for messaging
* Prevent errors when sending messages to non-existent numbers
This is useful for validating contacts before sending messaging operations or when integrating with external systems.
## Use Cases
### Contact Validation
Before sending messages to a list of contacts, verify which numbers are actually registered on WhatsApp.
### CRM Integration
When syncing contacts from your CRM, check their WhatsApp availability to enable messaging features.
### User Onboarding
Verify if a user's phone number is on WhatsApp during registration or account setup.
This endpoint is very useful to avoid getting blocked by WhatsApp, As it prevent you from sending messages to non-existing numbers.
## Response Examples
### Existing Contact
When the phone number is registered on WhatsApp:
```json theme={null}
{
"numberExists": true,
"chatId": "201553730661@c.us"
}
```
### Non-existing Contact
When the phone number is not registered on WhatsApp:
```json theme={null}
{
"numberExists": false,
"chatId": null
}
```
The `chatId` can be in any format `+20123456789`, `20123456789`, `0123456789`, or `123456789`
## OpenAPI
````yaml v1/api-reference/whatsapp/whatsapp-collection.json GET /{instance}/contacts/check-exists
openapi: 3.1.0
info:
version: v1.0
title: Hypersender WhatsApp API Docs
description: >
The Hypersender WhatsApp API is a powerful api to send and recieve messages
using your own whatsapp number.
Without the high costs of Meta's Whatsapp business API.
In this Docs you'll learn how to use and integrate Hypersnder Whatsapp API
into your existing system/service or application using simple API endpoints.
**What you can Do?**
- Send Text and basic Url messages.
- Send Media through Link or uploaded file.
- Send Audio through Link or uploaded file.
- Send Contact Card
- Send Location
- Send Poll votes
**You can also**
- React to a message
- Forward messages to other chats
- Acknowledge messages (mark as read)
- Star and unstar messages
**Quick Demo**
**Learn how to use Hypersender whatsapp API to send a message using Postman:**
[Demo Link](https://app.hypersender.com/send-whatsapp-message-in-postman) **to easily interact with our API.**
**postman collection**
You can download our [Postman
Collection](https://docs.hypersender.com/whatsapp-postman-collection.json)
to easily interact with our API.
## Servers (Endpoints)
- Production (activated):
[https://app.hypersender.com/api/whatsapp/v1](https://app.hypersender.com/api/whatsapp/v1)
servers:
- url: https://app.hypersender.com/api/whatsapp/v1
description: Production
security:
- Authorization: []
paths:
/{instance}/contacts/check-exists:
get:
tags:
- Contacts
summary: Check if contact exists on WhatsApp
description: Verify if a phone number is registered on WhatsApp and get its chatId
parameters:
- name: Accept
in: header
description: application/json
schema:
type: string
example: application/json
- name: Content-Type
in: header
description: application/json
schema:
type: string
example: application/json
- name: instance
in: path
description: Instance UUID copied from hypersender dashboard
required: true
schema:
type: string
example: '{{ instance_id }}'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CheckContactExistsRequest'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
numberExists:
type: boolean
description: Whether the phone number exists on WhatsApp
chatId:
type:
- string
- 'null'
description: The WhatsApp chat ID if number exists, null otherwise
examples:
Existing Contact:
value:
numberExists: true
chatId: 201553730661@c.us
Non-existing Contact:
value:
numberExists: false
chatId: null
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ServerError'
security:
- Authorization: []
components:
schemas:
CheckContactExistsRequest:
type: object
properties:
phone:
type: string
description: Phone number to check (with country code, without + or spaces)
example: '201553730661'
required:
- phone
NotFoundError:
type: object
title: NotFoundError
example:
message: Resource not found.
properties:
message:
type: string
x-examples:
Example 1:
message: Resource not found.
x-stoplight:
id: ar3vz55asbxme
ValidationError:
type: object
title: ValidationError
properties:
message:
type: string
errors:
type: object
description: Invalid or missing feilds will be shown here
statusCode:
type: number
example:
message: The given data was invalid.
errors: {}
statusCode: 422
required:
- errors
- statusCode
x-examples:
Multiple fields Error:
message: The given data was invalid.
errors:
messages:
- The number you want to send the message to is not on whatsapp.
jid: 20121323124131@s.whatsapp.net
exists: false
statusCode: 422
'Single Field error ':
message: The given data was invalid.
errors:
messages:
- textMessage.text should not be empty
statusCode: 422
x-stoplight:
id: 90x3wfxw7gqcb
ServerError:
type: object
title: ServerError
properties:
message:
type: string
example:
message: Internal Server Error
x-stoplight:
id: 2fhq2gihsfreh
securitySchemes:
Authorization:
type: http
scheme: bearer
````