Contacts API

The Contacts API lets you manage the contact book of the active WhatsApp number: list, search, retrieve, create, update the nickname, block/unblock, and export contacts. With the introduction of the BSUID (Business-Scoped User ID) by Meta, each contact can now carry — in addition to the phone number (wa_id) — the fields user_id (BSUID), parent_user_id (parent BSUID), and username. This allows a contact to exist even without a phone number (for example, when the user has adopted a username). Learn the concept in BSUID and user identifiers.

The BSUID fields (user_id, parent_user_id, username) are returned by every contact endpoint and appear populated when available or as null when absent. The wa_id field (phone) is still returned normally for backward compatibility.

Authentication and base URL

Every endpoint on this page uses the production base URL and Bearer Token authentication: https://api.positus.global/v2

Headers

Name	Type	Description
Authorization	string	Authentication using Bearer Token
Content-Type	string	application/json

The list, retrieve, create, nickname, block, and unblock endpoints operate on the session’s active WhatsApp number (the number currently selected by the authenticated user). They do not take the number code (chave) in the path. Only the export endpoint takes the number UUID in the path.

List contacts

GET https://api.positus.global/v2/messenger/contacts Lists the active number’s contacts, paginated (40 per page), ordered by the date of the last message. Supports text search and filters.

Headers

Name	Type	Description
Authorization	string	Authentication using Bearer Token

Query Parameters

Name	Type	Description
`query`	string	Text search. Matches (via `LIKE`) against `name`, `nickname`, `wa_id` (phone), `user_id` (BSUID) and `username`. See Search by BSUID.
`blocked`	boolean	If true, returns only blocked contacts; otherwise only non-blocked ones.
`follower_id`	string	A follower’s UUID, `own` (followed by you), or `without` (no followers).
`tag_id`	string	A tag UUID; filters contacts that have the tag.
`messages`	string	`unread` (with unread messages) or `read` (all read).

Response

{
  "data": [
    {
      "id": "3f2a1b0c-9d8e-4f7a-a6b5-c4d3e2f1a0b9",
      "name": "Maria Silva",
      "nickname": null,
      "wa_id": "5511999999999",
      "user_id": "BR.1234567890",
      "parent_user_id": "BR.PARENT123456789",
      "username": "maria.silva",
      "messages": [],
      "last_message": null,
      "unread_messages": 0,
      "blocked": false,
      "followers": [],
      "tags": [],
      "window_allowed_until": null,
      "created_at": "2026-07-01T12:00:00.000000Z",
      "updated_at": "2026-07-01T12:00:00.000000Z"
    }
  ],
  "links": { "first": "...", "prev": null, "next": null },
  "meta": { "path": "...", "per_page": 40 }
}

{
  "message": "This action is unauthorized."
}

Returns 403 when there is no active WhatsApp number associated with the session.

Retrieve a contact

GET https://api.positus.global/v2/messenger/contacts/{contact} Returns a specific contact of the active number, identified by its UUID (id).

Path Parameters

Name	Type	Description
`contact`	string	Contact UUID (`id` field from the list)

Headers

Name	Type	Description
Authorization	string	Authentication using Bearer Token

Response

{
  "data": {
    "id": "3f2a1b0c-9d8e-4f7a-a6b5-c4d3e2f1a0b9",
    "name": "Maria Silva",
    "nickname": null,
    "wa_id": "5511999999999",
    "user_id": "BR.1234567890",
    "parent_user_id": "BR.PARENT123456789",
    "username": "maria.silva",
    "messages": [],
    "last_message": null,
    "unread_messages": 0,
    "blocked": false,
    "followers": [],
    "tags": [],
    "window_allowed_until": null,
    "created_at": "2026-07-01T12:00:00.000000Z",
    "updated_at": "2026-07-01T12:00:00.000000Z"
  }
}

{
  "message": "No query results for model [Contact]."
}

Create / update a contact

POST https://api.positus.global/v2/messenger/contacts Creates a contact on the active number. If a contact with the same lookup identifier already exists, it is updated instead of duplicated (update-or-create behavior). The contact can be identified by phone (phone) OR by BSUID (user_id) — you must provide at least one of the two. This allows creating contacts without a phone number, using only the BSUID.

Headers

Name	Type	Description
Authorization	string	Authentication using Bearer Token
Content-Type	string	application/json

Request Body

Name	Type	Description
`name`	string	Required. Contact name.
`nickname`	string	Optional. Contact nickname.
`phone`	string	Required when `user_id` is omitted. Contact phone number.
`user_id`	string	Required when `phone` is omitted. Contact BSUID (e.g. `BR.1234567890`). See BSUID.

Lookup key (avoids duplication):

If user_id is provided, the contact is looked up/updated by user_id (BSUID priority). If phone is also present, the phone is stored in wa_id.
If only phone is provided, the contact is looked up/updated by wa_id.

The username is not used as an identification key — it is populated by Meta’s webhooks.

On-premises numbers: when creating a contact by phone only (no user_id), the API validates the number against the WhatsApp API before storing — if the number does not exist, it returns 404. When creating by user_id only (no phone), this validation is skipped. On Cloud API numbers there is no prior validation.

Request Body (traditional contact — by phone)

{
  "name": "Maria Silva",
  "nickname": "Maria",
  "phone": "+5511999999999"
}

Request Body (contact by BSUID — no phone)

{
  "name": "Maria Silva",
  "user_id": "BR.1234567890"
}

Request Body (BSUID + phone)

{
  "name": "Maria Silva",
  "user_id": "BR.1234567890",
  "phone": "+5511999999999"
}

Response

{
  "data": {
    "contact": {
      "id": "3f2a1b0c-9d8e-4f7a-a6b5-c4d3e2f1a0b9",
      "name": "Maria Silva",
      "nickname": "Maria",
      "wa_id": "5511999999999",
      "user_id": "BR.1234567890",
      "parent_user_id": null,
      "username": null,
      "messages": [],
      "last_message": null,
      "unread_messages": 0,
      "blocked": false,
      "followers": [],
      "tags": [],
      "window_allowed_until": null,
      "created_at": "2026-07-01T12:00:00.000000Z",
      "updated_at": "2026-07-01T12:00:00.000000Z"
    },
    "recently_created": true
  }
}

{
  "errors": {
    "phone": [
      "Este número de WhatsApp não existe"
    ]
  }
}

{
  "message": "The phone field is required when user id is not present. (and 1 more error)",
  "errors": {
    "phone": [
      "The phone field is required when user id is not present."
    ],
    "user_id": [
      "The user id field is required when phone is not present."
    ]
  }
}

The recently_created field indicates whether the contact was created now (true) or an existing contact was updated (false).

Update nickname

PUT https://api.positus.global/v2/messenger/contacts/{contact}/nickname Updates the nickname (nickname) of an existing contact, identified by its UUID.

Path Parameters

Name	Type	Description
`contact`	string	Contact UUID

Request Body

Name	Type	Description
`nickname`	string	New contact nickname.

{
  "nickname": "VIP Customer"
}

Response

{
  "data": {
    "id": "3f2a1b0c-9d8e-4f7a-a6b5-c4d3e2f1a0b9",
    "name": "Maria Silva",
    "nickname": "VIP Customer",
    "wa_id": "5511999999999",
    "user_id": "BR.1234567890",
    "parent_user_id": null,
    "username": null,
    "blocked": false
  }
}

Block a contact

POST https://api.positus.global/v2/messenger/contacts/{contact}/block Blocks an existing contact.

Path Parameters

Name	Type	Description
`contact`	string	Contact UUID

Request Body

Name	Type	Description
`reason`	string	Reason for blocking.

{
  "reason": "Spam"
}

Response

{
  "data": {
    "id": "3f2a1b0c-9d8e-4f7a-a6b5-c4d3e2f1a0b9",
    "name": "Maria Silva",
    "wa_id": "5511999999999",
    "user_id": "BR.1234567890",
    "parent_user_id": null,
    "username": null,
    "blocked": true,
    "block_reason": "Spam"
  }
}

Unblock a contact

POST https://api.positus.global/v2/messenger/contacts/{contact}/unblock Unblocks a blocked contact.

Path Parameters

Name	Type	Description
`contact`	string	Contact UUID

Response

{
  "data": {
    "id": "3f2a1b0c-9d8e-4f7a-a6b5-c4d3e2f1a0b9",
    "name": "Maria Silva",
    "wa_id": "5511999999999",
    "user_id": "BR.1234567890",
    "parent_user_id": null,
    "username": null,
    "blocked": false
  }
}

Export contacts

POST https://api.positus.global/v2/whatsapp/numbers/{number}/exports/contacts Exports all contacts of a number (identified by its UUID in the path) as CSV or XLSX. The file includes dedicated columns for the BSUID fields (user_id, parent_user_id, username).

Path Parameters

Name	Type	Description
`number`	string	WhatsApp number UUID

Request Body

Name	Type	Description
`extension`	string	Required. File format: `csv` or `xlsx`.

{
  "extension": "xlsx"
}

Response

Returns the binary file for download (CSV or XLSX) with the columns: id, name, nickname, wa_id, user_id, parent_user_id, username, blocked, block_reason, blocked_at, created_at, updated_at.

{
  "message": "The selected extension is invalid.",
  "errors": {
    "extension": [
      "The selected extension is invalid."
    ]
  }
}

Contact object

Fields returned in the contact object (list, retrieve, and create endpoints):

Field	Type	Description
`id`	string	Contact UUID (used as the identifier in the other routes).
`name`	string	Contact name.
`nickname`	string\|null	Contact nickname.
`wa_id`	string\|null	Contact phone (WhatsApp ID). May be `null` for BSUID-only contacts.
`user_id`	string\|null	Contact BSUID (Business-Scoped User ID). See BSUID.
`parent_user_id`	string\|null	Contact parent BSUID.
`username`	string\|null	Contact public username (set by the user on WhatsApp).
`messages`	array	Reserved (returned empty on this route).
`last_message`	object\|null	The contact’s last message.
`unread_messages`	integer\|null	Number of unread messages.
`blocked`	boolean	Whether the contact is blocked.
`block_reason`	string	Reason for the block (present only when `blocked` is `true`).
`followers`	array	Users following the contact.
`tags`	array	Tags associated with the contact.
`window_allowed_until`	string\|null	Date/time until which the 24h service window is open.
`created_at`	string	Creation date.
`updated_at`	string	Update date.
`blocked_at`	string	Block date (present only when `blocked` is `true`).

Search by `user_id` or `username`

The query parameter of the contact list performs a text search (via LIKE, partial match) over the following fields:

name
nickname
wa_id (phone)
user_id (BSUID)
username

This lets you find BSUID-only contacts (without a phone) by searching for the BSUID or the username.

# Search by BSUID
GET https://api.positus.global/v2/messenger/contacts?query=BR.1234567890

# Search by username
GET https://api.positus.global/v2/messenger/contacts?query=maria.silva

The username is only a text search criterion — it is not a unique key. Do not use username to uniquely identify a contact; use the id (UUID) or the user_id (BSUID).

​Contacts API

​Authentication and base URL

​Headers

​List contacts

​Headers

​Query Parameters

​Response

​Retrieve a contact

​Path Parameters

​Headers

​Response

​Create / update a contact

​Headers

​Request Body

​Request Body (traditional contact — by phone)

​Request Body (contact by BSUID — no phone)

​Request Body (BSUID + phone)

​Response

​Update nickname

​Path Parameters

​Request Body

​Response

​Block a contact

​Path Parameters

​Request Body

​Response

​Unblock a contact

​Path Parameters

​Response

​Export contacts

​Path Parameters

​Request Body

​Response

​Contact object

​Search by user_id or username

Contacts API

Authentication and base URL

Headers

List contacts

Headers

Query Parameters

Response

Retrieve a contact

Path Parameters

Headers

Response

Create / update a contact

Headers

Request Body

Request Body (traditional contact — by phone)

Request Body (contact by BSUID — no phone)

Request Body (BSUID + phone)

Response

Update nickname

Path Parameters

Request Body

Response

Block a contact

Path Parameters

Request Body

Response

Unblock a contact

Path Parameters

Response

Export contacts

Path Parameters

Request Body

Response

Contact object

Search by `user_id` or `username`