# Contact operations

Exact methods, permissions, request bodies and query fields for contact operations.

## Get all contacts for a session

GET /api/v1/channels/{channel_id}/contacts

Token scope: read. Paid access and a ready, customer-owned session are required. List responses are bounded; use documented pagination parameters.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.





Query parameter | Required | Schema
--- | --- | ---
limit | No | {"type":"integer","minimum":1,"maximum":100}
offset | No | {"type":"integer","minimum":0,"maximum":10000}

```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "required": []
}
```





## Batch-resolve profile picture URLs for up to 50 contacts

GET /api/v1/channels/{channel_id}/contacts/profile-pictures

Token scope: read. Paid access and a ready, customer-owned session are required. List responses are bounded; use documented pagination parameters.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.





Query parameter | Required | Schema
--- | --- | ---
ids | No | {"type":"string","maxLength":4096}

```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "required": []
}
```





## List the contacts this account has blocked

GET /api/v1/channels/{channel_id}/contacts/blocked

Token scope: read. Paid access and a ready, customer-owned session are required. List responses are bounded; use documented pagination parameters.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.







```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "required": []
}
```





## Get a specific contact by ID

GET /api/v1/channels/{channel_id}/contacts/{contactId}

Token scope: read. Paid access and a ready, customer-owned session are required. List responses are bounded; use documented pagination parameters.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.







```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "required": []
}
```





## Save a contact to the account's addressbook, or edit an existing entry

PUT /api/v1/channels/{channel_id}/contacts/{contactId}

Token scope: manage. Paid access and a ready, customer-owned session are required. Supply an Idempotency-Key. Returns an operation ID; inspect /api/v1/operations/{id}. A completed result is recorded; an unconfirmed result is uncertain and never automatically retried.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.



- `firstName` (string, required): Maximum 100 characters. See JSON schema for all validation constraints.
- `lastName` (string): Maximum 100 characters. See JSON schema for all validation constraints.



```json
{
  "type": "object",
  "properties": {
    "firstName": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "lastName": {
      "type": "string",
      "maxLength": 100
    }
  },
  "required": [
    "firstName"
  ],
  "additionalProperties": false
}
```





## Remove a contact from the account's addressbook

DELETE /api/v1/channels/{channel_id}/contacts/{contactId}

Token scope: manage. Paid access and a ready, customer-owned session are required. Supply an Idempotency-Key. Returns an operation ID; inspect /api/v1/operations/{id}. A completed result is recorded; an unconfirmed result is uncertain and never automatically retried.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.







```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "required": []
}
```





## Check if a phone number exists on WhatsApp

GET /api/v1/channels/{channel_id}/contacts/check/{number}

Token scope: read. Paid access and a ready, customer-owned session are required. List responses are bounded; use documented pagination parameters.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.







```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "required": []
}
```





## Look up the LID of a phone number

GET /api/v1/channels/{channel_id}/contacts/{number}/lid

Token scope: read. Paid access and a ready, customer-owned session are required. List responses are bounded; use documented pagination parameters.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.







```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "required": []
}
```





## Get profile picture URL for a contact

GET /api/v1/channels/{channel_id}/contacts/{contactId}/profile-picture

Token scope: read. Paid access and a ready, customer-owned session are required. List responses are bounded; use documented pagination parameters.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.







```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "required": []
}
```





## Resolve a contact id (e.g. an @lid) to a phone number — best-effort

GET /api/v1/channels/{channel_id}/contacts/{contactId}/phone

Token scope: read. Paid access and a ready, customer-owned session are required. List responses are bounded; use documented pagination parameters.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.







```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "required": []
}
```





## Block a contact

POST /api/v1/channels/{channel_id}/contacts/{contactId}/block

Token scope: manage. Paid access and a ready, customer-owned session are required. Supply an Idempotency-Key. Returns an operation ID; inspect /api/v1/operations/{id}. A completed result is recorded; an unconfirmed result is uncertain and never automatically retried.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.







```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "required": []
}
```





## Unblock a contact

DELETE /api/v1/channels/{channel_id}/contacts/{contactId}/block

Token scope: manage. Paid access and a ready, customer-owned session are required. Supply an Idempotency-Key. Returns an operation ID; inspect /api/v1/operations/{id}. A completed result is recorded; an unconfirmed result is uncertain and never automatically retried.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.







```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "required": []
}
```