Contacts API

GET

api

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: 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

Returns a paginated list of contacts. Filter by name/phone with 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}

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.

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}

Update a contact’s name, tags, or custom attributes. All fields are optional; send only what you want to change. Returns 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}

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

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).

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>"
}

​Endpoints overview

​List contacts

​Get contact

​Create contact

​Update contact

​Delete contact

​Import contacts (CSV)

​Contact object

Endpoints overview

List contacts

Get contact

Create contact

Update contact

Delete contact

Import contacts (CSV)

Contact object