Contacts and groups

Contacts

Endpoints

Method	Endpoint
`GET`	`/api/v1/contacts`
`POST`	`/api/v1/contacts`
`GET`	`/api/v1/contacts/{id}`
`PUT`	`/api/v1/contacts/{id}`
`DELETE`	`/api/v1/contacts/{id}`
`POST`	`/api/v1/contacts/bulk-delete`
`GET`	`/api/v1/contacts/bulk-jobs`
`GET`	`/api/v1/contacts/bulk-jobs/{jobId}`
`GET`	`/api/v1/contacts/bulk-jobs/{jobId}/progress`
`POST`	`/api/v1/contacts/bulk-jobs/{jobId}/cancel`

Parameters

`POST /api/v1/contacts`

Field	Type	Required	Location	Description
`name`	string	yes	body	Full name
`phone`	string	yes	body	E.164 number
`tags`	string[]	no	body	Contact tags
`meta`	object	no	body	Free-form metadata

`PUT /api/v1/contacts/{id}`

Field	Type	Required	Location	Description
`id`	UUID	yes	path	Contact ID
`name`	string	no	body	New name
`phone`	string	no	body	New number
`tags`	string[]	no	body	Replaces tags
`meta`	object	no	body	Replaces metadata

`POST /api/v1/contacts/bulk-delete`

Field	Type	Required	Location	Description
`contactIds`	UUID[]	yes	body	1 to 10000 IDs

Create a contact

curl -X POST https://srv.msgflash.com/api/v1/contacts \
  -H "x-api-key: msgf_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Awa Doe",
    "phone": "+33612345000",
    "tags": ["vip", "newsletter"],
    "meta": {
      "city": "Cotonou"
    }
  }'

Bulk delete contacts

curl -X POST https://srv.msgflash.com/api/v1/contacts/bulk-delete \
  -H "x-api-key: msgf_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "contactIds": ["CONTACT_UUID_1", "CONTACT_UUID_2"]
  }'

Response example:

{
  "data": {
    "requested": 2,
    "deleted": 1,
    "notFound": ["CONTACT_UUID_2"]
  }
}

Async response example (>= 100 contacts):

{
  "data": {
    "mode": "async",
    "jobId": "job_abc123",
    "status": "pending",
    "operation": "bulk_delete_contacts",
    "requestedCount": 900,
    "progress": 0
  }
}

Common errors

Code	HTTP	When
`VALIDATION_ERROR`	400	Invalid body
`NOT_FOUND`	404	Requested contact not found

Contact groups

Endpoints

Method	Endpoint
`GET`	`/api/v1/contacts/groups`
`POST`	`/api/v1/contacts/groups`
`GET`	`/api/v1/contacts/groups/{groupId}`
`PUT`	`/api/v1/contacts/groups/{groupId}`
`DELETE`	`/api/v1/contacts/groups/{groupId}`
`POST`	`/api/v1/contacts/groups/{groupId}/members`
`DELETE`	`/api/v1/contacts/groups/{groupId}/members`
`GET`	`/api/v1/contacts/groups/{groupId}/members`
`GET`	`/api/v1/contacts/{id}/groups`

Parameters

`POST /api/v1/contacts/groups`

Field	Type	Required	Location	Description
`name`	string	yes	body	Group name
`description`	string	no	body	Description
`color`	string	no	body	Hex color code

`POST /api/v1/contacts/groups/{groupId}/members`

Field	Type	Required	Location	Description
`groupId`	UUID	yes	path	Group ID
`contactIds`	UUID[]	yes	body	1 to 10000 members to add

`GET /api/v1/contacts/groups/{groupId}/members`

Parameter	Type	Required	Location	Description
`groupId`	UUID	yes	path	Group ID
`limit`	integer	no	query	Page size
`cursor`	string	no	query	Cursor
`search`	string	no	query	Filter by name or phone

Create a group

curl -X POST https://srv.msgflash.com/api/v1/contacts/groups \
  -H "x-api-key: msgf_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Clients VIP",
    "description": "High-value clients",
    "color": "#F59E0B"
  }'

Add members

curl -X POST https://srv.msgflash.com/api/v1/contacts/groups/GROUP_ID/members \
  -H "x-api-key: msgf_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "contactIds": ["CONTACT_UUID_1", "CONTACT_UUID_2"]
  }'

Async behavior:

< 100 contacts: synchronous response
>= 100 contacts: asynchronous 202 response with a jobId
Poll GET /api/v1/contacts/bulk-jobs/{jobId}/progress every 2s

List members

curl "https://srv.msgflash.com/api/v1/contacts/groups/GROUP_ID/members?limit=20&search=awa" \
  -H "x-api-key: msgf_live_your_api_key_here"

Response:

{
  "data": {
    "members": [],
    "nextCursor": null,
    "hasMore": false
  }
}

The groups exposed here are MsgFlash contact groups, not native WhatsApp groups.

Common errors

Code	HTTP	When
`MAX_CONTACT_GROUPS_REACHED`	403	Group limit reached
`NOT_FOUND`	404	Group or contact not found
`CONFLICT`	409	A group with the same name already exists

Getting Started

Guides

API Reference · Teams

API Reference · Instances

API Reference · Messages

API Reference · Campaigns

API Reference · Templates

API Reference · Contacts

API Reference · Groups

API Reference · Number Lookups

API Reference · Webhooks

API Reference · Billing

Resources

Contacts and groups

Contacts

Endpoints

Parameters

`POST /api/v1/contacts`

`PUT /api/v1/contacts/{id}`

`POST /api/v1/contacts/bulk-delete`

Create a contact

Bulk delete contacts

Common errors

Contact groups

Endpoints

Parameters

`POST /api/v1/contacts/groups`

`POST /api/v1/contacts/groups/{groupId}/members`

`GET /api/v1/contacts/groups/{groupId}/members`

Create a group

Add members

List members

Common errors

​Contacts

​Endpoints

​Parameters

​POST /api/v1/contacts

​PUT /api/v1/contacts/{id}

​POST /api/v1/contacts/bulk-delete

​Create a contact

​Bulk delete contacts

​Common errors

​Contact groups

​Endpoints

​Parameters

​POST /api/v1/contacts/groups

​POST /api/v1/contacts/groups/{groupId}/members

​GET /api/v1/contacts/groups/{groupId}/members

​Create a group

​Add members

​List members

​Common errors

Contacts

Endpoints

Parameters

`POST /api/v1/contacts`

`PUT /api/v1/contacts/{id}`

`POST /api/v1/contacts/bulk-delete`

Create a contact

Bulk delete contacts

Common errors

Contact groups

Endpoints

Parameters

`POST /api/v1/contacts/groups`

`POST /api/v1/contacts/groups/{groupId}/members`

`GET /api/v1/contacts/groups/{groupId}/members`

Create a group

Add members

List members

Common errors