WhatsApp Business API
Contacts API
Create, update, tag, and delete WhatsApp contacts on Vobiz, or import thousands of contacts at once via CSV bulk upload for campaign targeting.
GET
/
api
/
v1
/
messaging
/
contacts
Contacts API
curl --request GET \
--url https://api.vobiz.ai/api/v1/messaging/contacts \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: <api-key>' \
--data '
{
"phone_number": "<string>"
}
'import requests
url = "https://api.vobiz.ai/api/v1/messaging/contacts"
payload = { "phone_number": "<string>" }
headers = {
"X-Auth-Token": "<api-key>",
"Content-Type": "application/json"
}
response = requests.get(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {'X-Auth-Token': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({phone_number: '<string>'})
};
fetch('https://api.vobiz.ai/api/v1/messaging/contacts', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": "<string>",
"account_id": "<string>",
"phone_number": "<string>",
"name": "<string>",
"tags": [
"<string>"
],
"custom_attributes": {},
"last_active_at": "<string>",
"created_at": "<string>",
"updated_at": "<string>"
}Base URL:
Returns a paginated list of contacts. Filter by name/phone with
Returns the full profile for a single contact by ID.
Create a single contact. Attach
Update a contact’s name, tags, or custom attributes. All fields are optional; send only what you want to change. Returns
Permanently delete a contact from your account. Returns
Bulk-import contacts from a CSV file using
When some rows fail,
https://api.vobiz.ai/api/v1/messaging
Authentication: every request requires X-Auth-ID: MA_XXXXXXXX and X-Auth-Token: <token> headers (a Authorization: Bearer <JWT> header is also accepted). Send Content-Type: application/json on requests with a body. Get your credentials from console.vobiz.ai.
Endpoints overview
| Method | Endpoint | Description |
|---|---|---|
GET | /api/v1/messaging/contacts | List contacts (paginated) |
GET | /api/v1/messaging/contacts/{id} | Get a single contact |
POST | /api/v1/messaging/contacts | Create a new contact |
PUT | /api/v1/messaging/contacts/{id} | Update a contact |
DELETE | /api/v1/messaging/contacts/{id} | Delete a contact |
POST | /api/v1/messaging/contacts/import | Bulk import from CSV |
List contacts
GET https://api.vobiz.ai/api/v1/messaging/contacts
search, or filter by tag.
integer
default:"1"
Page number.
integer
default:"25"
Records per page.
string
Search by name or phone number.
string
Filter by tag name.
cURL
curl -X GET \
"https://api.vobiz.ai/api/v1/messaging/contacts?page=1&limit=25&search=Rahul&tag=vip" \
-H "X-Auth-ID: MA_XXXXXXXX" \
-H "X-Auth-Token: {auth_token}"
200 OK
{
"items": [
{
"id": "9b8a7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
"account_id": "MA_XXXXXXXX",
"phone_number": "+919876543210",
"name": "Rahul Sharma",
"tags": ["vip"],
"custom_attributes": { "company": "Acme" },
"last_active_at": "2026-03-17T14:22:00Z",
"created_at": "2026-03-01T10:00:00Z",
"updated_at": "2026-03-01T10:00:00Z"
}
],
"total": 1,
"page": 1,
"limit": 25,
"has_more": false
}
Get contact
GET https://api.vobiz.ai/api/v1/messaging/contacts/{id}
cURL
curl -X GET \
"https://api.vobiz.ai/api/v1/messaging/contacts/9b8a7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d" \
-H "X-Auth-ID: MA_XXXXXXXX" \
-H "X-Auth-Token: {auth_token}"
Create contact
POST https://api.vobiz.ai/api/v1/messaging/contacts
tags and custom_attributes for filtering and campaign targeting. Returns 201 Created.
string
required
Phone number in E.164 format (e.g.
+919876543210).string
required
Contact name.
string[]
List of tag strings.
object
Arbitrary key/value metadata for the contact.
cURL
curl -X POST \
"https://api.vobiz.ai/api/v1/messaging/contacts" \
-H "X-Auth-ID: MA_XXXXXXXX" \
-H "X-Auth-Token: {auth_token}" \
-H "Content-Type: application/json" \
-d '{
"phone_number": "+919876543210",
"name": "Rahul Sharma",
"tags": ["vip"],
"custom_attributes": { "company": "Acme" }
}'
Update contact
PUT https://api.vobiz.ai/api/v1/messaging/contacts/{id}
200 OK.
string
Updated contact name.
string[]
Updated list of tag strings.
object
Updated key/value metadata.
cURL
curl -X PUT \
"https://api.vobiz.ai/api/v1/messaging/contacts/9b8a7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d" \
-H "X-Auth-ID: MA_XXXXXXXX" \
-H "X-Auth-Token: {auth_token}" \
-H "Content-Type: application/json" \
-d '{
"name": "Rahul Kumar",
"tags": ["vip", "premium"]
}'
Delete contact
DELETE https://api.vobiz.ai/api/v1/messaging/contacts/{id}
204 No Content.
cURL
curl -X DELETE \
"https://api.vobiz.ai/api/v1/messaging/contacts/9b8a7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d" \
-H "X-Auth-ID: MA_XXXXXXXX" \
-H "X-Auth-Token: {auth_token}"
Import contacts (CSV)
POST https://api.vobiz.ai/api/v1/messaging/contacts/import
multipart/form-data. Send the file under the form field named file. The CSV must include phone_number and name columns; tags (comma-separated) is optional. Returns 200 OK with a summary.
CSV format:
phone_number,name,tags
+919876543210,Rahul Sharma,"vip,enterprise"
+919123456789,Priya Nair,"new"
cURL
curl -X POST \
"https://api.vobiz.ai/api/v1/messaging/contacts/import" \
-H "X-Auth-ID: MA_XXXXXXXX" \
-H "X-Auth-Token: {auth_token}" \
-F "file=@/path/to/contacts.csv"
200 OK
{
"total": 2,
"created": 1,
"updated": 1,
"failed": 0,
"errors": []
}
errors lists each one:
200 OK (with errors)
{
"total": 3,
"created": 1,
"updated": 1,
"failed": 1,
"errors": [
{
"row": 3,
"phone_number": "98765",
"reason": "invalid phone_number: must be E.164 format"
}
]
}
Do not set
Content-Type manually when using -F - curl sets the correct multipart/form-data boundary automatically.Contact object
string
Unique contact identifier (UUID).
string
Your Vobiz account ID (
MA_XXXXXXXX).string
Phone number in E.164 format.
string
Contact name.
string[]
List of tags assigned to the contact.
object
Arbitrary key/value metadata.
string
Timestamp of the contact’s most recent activity (RFC3339 UTC). May be omitted if the contact has had no activity.
string
Creation timestamp (RFC3339 UTC).
string
Last update timestamp (RFC3339 UTC).
Was this page helpful?
⌘I
Contacts API
curl --request GET \
--url https://api.vobiz.ai/api/v1/messaging/contacts \
--header 'Content-Type: application/json' \
--header 'X-Auth-Token: <api-key>' \
--data '
{
"phone_number": "<string>"
}
'import requests
url = "https://api.vobiz.ai/api/v1/messaging/contacts"
payload = { "phone_number": "<string>" }
headers = {
"X-Auth-Token": "<api-key>",
"Content-Type": "application/json"
}
response = requests.get(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {'X-Auth-Token': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({phone_number: '<string>'})
};
fetch('https://api.vobiz.ai/api/v1/messaging/contacts', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": "<string>",
"account_id": "<string>",
"phone_number": "<string>",
"name": "<string>",
"tags": [
"<string>"
],
"custom_attributes": {},
"last_active_at": "<string>",
"created_at": "<string>",
"updated_at": "<string>"
}