Skip to main content
GET
/
instances
List Instances
curl --request GET \
  --url https://app.hypersender.com/api/whatsapp/v1/instances \
  --header 'Authorization: Bearer <token>'
[
  {
    "id": "fa3d01c4-1234-4c0d-a12f-df319b612f8c",
    "name": "MyInstanceName",
    "phone": "+201234567890",
    "service_type": "whatsapp",
    "status": "WORKING",
    "access_token": "234|3uB2pBST2H6If8twXIeUaeNu23VJ8XassYoOVJuva48388e1",
    "created_at": "2025-05-26T10:12:45"
  },
  {
    "id": "c9a1dd76-5678-4f9d-9012-a5b78de100c3",
    "name": "SecondInstance",
    "phone": "+201234567891",
    "service_type": "whatsapp",
    "status": "SCAN_QR_CODE",
    "access_token": null,
    "created_at": "2025-05-25T15:30:22"
  }
]
List all WhatsApp instances associated with your authenticated account. Use filters to narrow down results by UUID, name, phone number, or status.

​
Filtering Options

You can filter the list of instances using the following query parameters:
  • filter[uuid] - Filter by instance UUID (exact match)
  • filter[name] - Filter by instance name (partial match)
  • filter[phone] - Filter by phone number (exact match)
  • filter[status] - Filter by instance status

​
Response Fields

Each instance in the response includes:
  • id - Instance UUID
  • name - Instance name
  • phone - Phone number in E.164 format
  • service_type - Service type (whatsapp)
  • status - Current instance status
  • access_token - Access token for the instance (null if not yet connected)
  • created_at - Creation timestamp

​
Example Use Cases

  • Display all instances in your application dashboard
  • Filter instances by status to show only active ones
  • Search for a specific instance by name or phone number
  • Monitor all instances created at a specific time
Use the filter[status] parameter with value WORKING to get only active and ready instances.

​
Instance Status Values

  • STOPPED: Instance is stopped
  • STARTING: Instance is starting up
  • WORKING: Instance is running and ready
  • SCAN_QR_CODE: Waiting for QR code scan
  • FAILED: Instance failed to start
  • PENDING: Awaiting server assignment

Authorizations

​
Authorization
string
header
required

Bearer token authentication. Example: Bearer 234|3uB2pBST2H6If8twXIeUaeNu23VJ8XassYoOVJuva48388e1

Headers

​
Accept
string

application/json

Example:

"application/json"

Query Parameters

​
filter[uuid]
string

Filter by instance UUID

​
filter[name]
string

Filter by instance name (partial match)

​
filter[phone]
string

Filter by phone number

​
filter[status]
enum<string>

Filter by instance status

Available options:
STOPPED,
STARTING,
WORKING,
SCAN_QR_CODE,
FAILED,
PENDING

Response

200 - application/json

Successful response

​
id
string

Instance UUID

Example:

"fa3d01c4-1234-4c0d-a12f-df319b612f8c"

​
name
string

Instance name

Example:

"MyInstanceName"

​
phone
string

Phone number in E.164 format

Example:

"+201234567890"

​
service_type
string

Service type

Example:

"whatsapp"

​
status
enum<string>

Instance status

Available options:
STOPPED,
STARTING,
WORKING,
SCAN_QR_CODE,
FAILED,
PENDING
Example:

"WORKING"

​
access_token
string | null

Access token for the instance

Example:

"234|3uB2pBST2H6If8twXIeUaeNu23VJ8XassYoOVJuva48388e1"

​
created_at
string

Creation timestamp

Example:

"2025-05-26T10:12:45"