> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wachat.net/llms.txt
> Use this file to discover all available pages before exploring further.
# List Contacts
> Return saved CRM contacts for a specific WhatsApp instance. Contacts are filtered by the API instance name so contacts from other instances are never mixed into the response.
Return saved CRM contacts for a specific WhatsApp instance.
Every contact is filtered by `instanceName`, so contacts from other instances will not be mixed into the response.
```http theme={null}
GET https://app.wachat.net/api/v1/contacts?instanceName=t1_mq9r2jov_jakarta_store
Authorization: Bearer YOUR_API_KEY
```
```json theme={null}
{
"success": true,
"count": 1,
"total": 1,
"page": 1,
"limit": 50,
"hasMore": false,
"instance": {
"id": 29,
"instanceName": "jakarta_store",
"displayName": "jakarta_store",
"apiInstanceName": "t1_mq9r2jov_jakarta_store",
"internalName": "t1_mq9r2jov_jakarta_store"
},
"contacts": [
{
"id": 101,
"name": "John Customer",
"phone": "628123456789",
"remoteJid": "628123456789@s.whatsapp.net",
"isGroup": false,
"profilePicUrl": "https://...",
"profilePictureUrl": "https://...",
"chat": {
"id": 501,
"name": "John Customer",
"pushName": "John",
"lastMessageText": "Hello",
"lastMessageTimestamp": "2026-06-13T08:00:00.000Z",
"unreadCount": 0
},
"assignedUserId": null,
"assignedDepartmentId": null,
"funnelStageId": null,
"notes": null,
"customData": {},
"showTimeInStage": false,
"createdAt": "2026-06-13T08:00:00.000Z",
"updatedAt": "2026-06-13T08:00:00.000Z"
}
]
}
```
Use `apiInstanceName`, for example `t1_mq9r2jov_jakarta_store`, as the `instanceName` query value.
This endpoint returns saved CRM contacts. If a chat has not been saved as a contact yet, it will not appear here.
## OpenAPI
````yaml GET /contacts
openapi: 3.0.3
info:
title: Wachat Enterprise API
description: >
Welcome to the official Wachat API reference. Wachat provides
developer-friendly, ultra-reliable infrastructure to scale your WhatsApp
communications programmatically.
Easily deploy automated messaging pipelines, orchestrate interactive
customer engagement patterns, verify phone numbers instantly, and control
containerized WhatsApp instances via a secure, production-grade REST
architecture.
version: 1.0.0
servers:
- url: https://app.wachat.net/api/v1
description: Live Production Gateway
security:
- bearerAuth: []
paths:
/contacts:
get:
tags:
- Contacts
summary: List Contacts
description: >-
Return saved CRM contacts for a specific WhatsApp instance. Contacts are
filtered by the API instance name so contacts from other instances are
never mixed into the response.
parameters:
- in: query
name: instanceName
required: true
schema:
type: string
description: Unique API instance name returned by Wachat.
example: t1_mq9r2jov_jakarta_store
- in: query
name: q
required: false
schema:
type: string
description: >-
Optional search text. Matches contact name, phone/JID, chat name, or
push name.
example: John
- in: query
name: page
required: false
schema:
type: integer
default: 1
minimum: 1
description: Page number.
example: 1
- in: query
name: limit
required: false
schema:
type: integer
default: 50
minimum: 1
maximum: 100
description: Number of contacts per page. Maximum 100.
example: 50
- in: query
name: includeGroups
required: false
schema:
type: boolean
default: false
description: Include group chats saved as contacts.
example: false
responses:
'200':
description: Contacts returned successfully.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
count:
type: integer
example: 1
total:
type: integer
example: 1
page:
type: integer
example: 1
limit:
type: integer
example: 50
hasMore:
type: boolean
example: false
instance:
type: object
properties:
id:
type: integer
example: 29
instanceName:
type: string
description: Display name shown in Wachat.
example: jakarta_store
displayName:
type: string
example: jakarta_store
apiInstanceName:
type: string
description: Unique API instance name to use in future API calls.
example: t1_mq9r2jov_jakarta_store
internalName:
type: string
example: t1_mq9r2jov_jakarta_store
contacts:
type: array
items:
type: object
properties:
id:
type: integer
example: 101
name:
type: string
example: John Customer
phone:
type: string
nullable: true
example: '628123456789'
remoteJid:
type: string
example: 628123456789@s.whatsapp.net
isGroup:
type: boolean
example: false
profilePicUrl:
type: string
nullable: true
example: https://pps.whatsapp.net/v/t61.24694-24/example.jpg
profilePictureUrl:
type: string
nullable: true
example: https://pps.whatsapp.net/v/t61.24694-24/example.jpg
chat:
type: object
properties:
id:
type: integer
example: 501
name:
type: string
nullable: true
example: John Customer
pushName:
type: string
nullable: true
example: John
lastMessageText:
type: string
nullable: true
example: Hello
lastMessageTimestamp:
type: string
nullable: true
format: date-time
example: '2026-06-13T08:00:00.000Z'
unreadCount:
type: integer
example: 0
assignedUserId:
type: integer
nullable: true
example: null
assignedDepartmentId:
type: integer
nullable: true
example: null
funnelStageId:
type: integer
nullable: true
example: null
notes:
type: string
nullable: true
example: null
customData:
type: object
example: {}
showTimeInStage:
type: boolean
example: false
createdAt:
type: string
format: date-time
example: '2026-06-13T08:00:00.000Z'
updatedAt:
type: string
format: date-time
example: '2026-06-13T08:00:00.000Z'
'400':
description: Missing instanceName query parameter.
'401':
description: Missing or invalid API key.
'403':
description: Subscription restriction prevented contacts lookup.
'404':
description: Instance not found for this API key.
'500':
description: Internal server error.
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Authenticate your integration payloads by injecting your premium secure
Wachat Account API Private Secret Key inside standard Authorization
Bearer header vectors.
````