Skip to main content
GET
List contacts
Base URL: https://api.vobiz.ai/api/v1/Account/{auth_id}/WhatsApp Authentication: every request needs the X-Auth-ID: MA_XXXXXXXX and X-Auth-Token: YOUR_AUTH_TOKEN headers, and the {auth_id} in the path must be the account those credentials belong to. Send Content-Type: application/json on requests with a JSON body. Get your credentials from console.vobiz.ai. Contacts are also created automatically when you message a number or it messages you.

Endpoints overview

List contacts

Returns a paginated list of contacts, newest first. Filter by name or phone number with search, or filter by tag.
cURL
200 OK

Get contact

Returns the full profile for a single contact by ID. An unknown contact returns 404.
cURL

Create contact

Create a single contact. Attach tags and custom_attributes for filtering and campaign targeting. A phone number that already exists on your account returns 400. Returns 201 Created.
string
required
Phone number in E.164 format (e.g. +919876543210). It must be unique on your account.
string
Contact name.
string[]
List of tag strings, used for campaign targeting.
object
Arbitrary key/value metadata for the contact. Defaults to {}.
cURL
201 Created

Update contact

Update a contact’s name, tags, or custom attributes. All fields are optional; send only what you want to change. The phone number can’t be changed. Returns 200 OK with the updated contact, or 404 for an unknown contact.
string
New contact name. An empty string clears it.
string[]
The complete new list of tags. It replaces the current list.
object
The complete new attributes object. It replaces the current one.
cURL

Delete contact

Permanently delete a contact from your account. Returns 204 No Content, or 404 for an unknown contact.
cURL

List contact tags

Returns every tag used on your contacts, most used first, with how many contacts have it, plus your total contact count. Use it to build tag-based campaign audiences.
cURL
200 OK

Import contacts (CSV)

Create or update contacts from a CSV file using multipart/form-data. Send the file under the form field named file, up to 10 MB and 5,000 data rows. The first row is the header. Vobiz recognises these columns, matched case-insensitively:
  • phone_number (required; also phone, phonenumber, or mobile), in E.164 format.
  • name (optional; also full_name, fullname, or contact_name).
  • tags (optional; also tag, labels, or label), separated by semicolons and stored in lowercase.
Rows are matched to existing contacts on phone number; when a number appears twice, the last row wins. Rows with an invalid number are skipped and listed in errors. Returns 200 OK with a summary. CSV format:
cURL
200 OK
When some rows fail, errors lists each one. Row numbers count the header as row 1:
200 OK (with errors)
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. Empty string when not set.
string[]
List of tags assigned to the contact.
object
Arbitrary key/value metadata. {} when not set.
string | null
When the contact last messaged you (RFC3339 UTC). null when they never have.
string
Creation timestamp (RFC3339 UTC).
string
Last update timestamp (RFC3339 UTC).

Authorizations

X-Auth-ID
string
header
required

Your Vobiz account Auth ID (MA_XXXXXXXX).

X-Auth-Token
string
header
required

Your Vobiz account Auth Token.

Path Parameters

auth_id
string
required

Your account Auth ID. It must match the X-Auth-ID header.

Example:

"MA_XXXXXXXX"

Query Parameters

page
integer
default:1

Page number, starting at 1. Defaults to 1.

Required range: x >= 1
limit
integer
default:25

Contacts per page, from 1 to 1000. Defaults to 25; values above 1000 return 1000.

Required range: 1 <= x <= 1000

Return only contacts whose name or phone number contains this text (case-insensitive).

Example:

"priya"

tag
string

Return only contacts with this tag (exact match).

Example:

"vip"

Response

A page of contacts.

items
object[]
required

Contacts, newest first. Empty array when none match.

total
integer
required

Number of contacts that match.

Example:

1

page
integer
required
Example:

1

limit
integer
required
Example:

25

has_more
boolean
required
Example:

false