Skip to main content
GET
/
api
/
v1
/
messaging
/
contacts
Contacts API
curl --request GET \
  --url https://api.vobiz.ai/api/v1/messaging/contacts \
  --header 'Content-Type: application/json' \
  --data '
{
  "phone_number": "<string>"
}
'
{
  "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: 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

MethodEndpointDescription
GET/api/v1/messaging/contactsList contacts (paginated)
GET/api/v1/messaging/contacts/{id}Get a single contact
POST/api/v1/messaging/contactsCreate 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/importBulk import from CSV

​
List contacts

GET https://api.vobiz.ai/api/v1/messaging/contacts
Returns a paginated list of contacts. Filter by name/phone with search, or filter by tag.
​
page
integer
default:"1"
Page number.
​
limit
integer
default:"25"
Records per page.
​
search
string
Search by name or phone number.
​
tag
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}
Returns the full profile for a single contact by 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
Create a single contact. Attach tags and custom_attributes for filtering and campaign targeting. Returns 201 Created.
​
phone_number
string
required
Phone number in E.164 format (e.g. +919876543210).
​
name
string
required
Contact name.
​
tags
string[]
List of tag strings.
​
custom_attributes
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}
Update a contact’s name, tags, or custom attributes. All fields are optional; send only what you want to change. Returns 200 OK.
​
name
string
Updated contact name.
​
tags
string[]
Updated list of tag strings.
​
custom_attributes
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}
Permanently delete a contact from your account. Returns 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
Bulk-import contacts from a CSV file using 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": []
}
When some rows fail, 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

​
id
string
Unique contact identifier (UUID).
​
account_id
string
Your Vobiz account ID (MA_XXXXXXXX).
​
phone_number
string
Phone number in E.164 format.
​
name
string
Contact name.
​
tags
string[]
List of tags assigned to the contact.
​
custom_attributes
object
Arbitrary key/value metadata.
​
last_active_at
string
Timestamp of the contact’s most recent activity (RFC3339 UTC). May be omitted if the contact has had no activity.
​
created_at
string
Creation timestamp (RFC3339 UTC).
​
updated_at
string
Last update timestamp (RFC3339 UTC).