Contacts API
List, add, update, tag, import and delete a workspace's contacts over the REST API, authenticated with a personal access token.
The contact routes of the REST API manage a workspace's contacts from your own servers, under the same rules as the Contacts page. They use the same tokens and errors as the campaign routes.
curl "https://app.verticalai.com.au/api/v1/workspaces/acme/contacts?tags=vip" \
-H "Authorization: Bearer vai_pat_…"| Method and path | Does |
|---|---|
GET /contacts | List and search |
POST /contacts | Add one |
GET /contacts/{contact} | Read one |
PATCH /contacts/{contact} | Change one |
DELETE /contacts/{contact} | Delete one |
POST /contacts/import | Add or update up to 5,000 |
GET /contacts/tags | The tags in use, with counts |
POST /contacts/tags | Tag and untag many |
GET /contacts/fields | The workspace's fields |
POST /contacts/fields | Add or change a field |
DELETE /contacts/fields/{key} | Delete a field |
Paths are relative to https://app.verticalai.com.au/api/v1/workspaces/{workspace},
where {workspace} is the workspace's slug. {contact} is the contact's id or
their phone number, + written as %2B.
Access
Contacts come with outbound campaigns,
so a workspace without campaigns is refused as not_available. Owners, admins,
editors and members can change contacts; a viewer can read them. A member
limited to some agents, or a client, is refused as workspace_scope_required,
because contacts belong to the whole workspace. A token with View only
access is refused every change as insufficient_scope. Edit access covers
every change here except deleting: deleting a contact or a field also needs
Delete (agent:delete) ticked on the token, or it is refused as
insufficient_scope.
| Status | Codes |
|---|---|
| 400 | invalid_input, bad_phone, bad_field, consent_required, nothing_to_change, too_many, too_many_fields |
| 401 | unauthorized, invalid_token |
| 403 | insufficient_scope, workspace_read_only, workspace_scope_required, workspace_out_of_scope, not_available, staff_token_not_accepted |
| 404 | workspace_not_found, contact_not_found, field_not_found |
| 409 | confirmation_required (a delete without ?confirm=true), contact_exists, field_exists, kind_locked |
| 429 | rate_limited |
| 500 | tool_threw: check, then try again |
List and read
GET /contacts lists 50 a page, most recently changed first, and answers
{ "data": [...], "has_more", "next_cursor" }.
| Parameter | Keeps |
|---|---|
search | Contacts whose name or number contains it |
tags | Contacts with that tag. Repeat it to need several: ?tags=vip&tags=renewal%20due |
fields | Contacts whose fields equal the values, as JSON: ?fields={"plan":"Premium"}, URL-encoded |
limit, cursor | Up to 200 a page, and the next_cursor of the page before |
{
"id": "7a1c4e2b-…",
"phoneNumber": "+61412345678",
"name": "Sam Lee",
"tags": ["renewal due", "vip"],
"fields": { "suburb": "Fremantle", "plan": "Premium", "seats": 3 },
"source": "import",
"doNotCall": false,
"createdAt": "2026-11-08T01:20:00Z",
"updatedAt": "2026-11-08T03:05:00Z"
}doNotCall is true when the number is on the workspace's
do-not-call list. source is how the contact
was first added: import, api or manual.
Add and change
POST /contacts adds one and answers 201 with { "contact": {...} }. A
number that is already a contact is refused as contact_exists.
{ "phone": "0412 345 678", "name": "Sam Lee", "tags": ["vip"], "fields": { "suburb": "Fremantle" } }A number that has called one of your agents is refused as consent_required
unless the body has "consentConfirmed": true: you confirm the person agreed
to hear from you. Callers are never added automatically.
PATCH /contacts/{contact} takes any of name, tags (replaces them all),
addTags and removeTags (send these or tags, not both) and fields (only
the keys given; null clears one), and answers { "contact": {...} }.
DELETE /contacts/{contact}?confirm=true answers { "deleted": "<id>" }. Campaign
recipients made from the contact stay on their campaigns.
Import
POST /contacts/import adds or updates up to 5,000 contacts by number and
answers { "inserted", "updated", "duplicates", "invalid", "createdFields" }.
{
"contacts": [
{ "phone": "0412 345 678", "name": "Sam Lee", "tags": ["vip"], "fields": { "suburb": "Fremantle" } },
{ "phone": "+61298765432", "fields": { "plan": "Basic" } }
],
"tags": ["spring promo"],
"createMissingFields": false
}A number that is already a contact keeps its name unless one is sent, gains
the new tags and has the given fields set. tags at the top level is added to
every contact. Each row is checked: a missing or undialable number, a field
that doesn't exist or a value that doesn't fit its field skips that row and
appears in invalid as { "row": 2, "reason": "Plan must be one of: Basic, Premium" }.
With "createMissingFields": true, an unknown field key adds a text field
instead.
Tags
GET /contacts/tags answers the tags in use as
{ "data": [{ "tag": "vip", "count": 42 }], "has_more": false, "next_cursor": null }.
POST /contacts/tags changes up to 1,000 contacts, each named by id or number,
and answers { "updated" }, the number of contacts found. A reference that
matches no contact is skipped.
{ "contacts": ["+61412345678", "7a1c4e2b-…"], "add": ["renewal due"], "remove": ["lead"] }Tags are stored in lower case, without commas, at most 40 characters each and 50 on a contact.
Fields
GET /contacts/fields answers the fields in data, each with its key,
label, kind (text, number, boolean or choice) and, for a choice,
options.
POST /contacts/fields adds a field, or changes the label or options of the
field with that key, and answers { "field": {...}, "created": true }
(created is false when it changed one).
{ "label": "Plan", "kind": "choice", "options": ["Basic", "Premium"] }key is made from the label when left out. A field's kind can't change
(kind_locked). A workspace has at most 50 fields (too_many_fields). DELETE /contacts/fields/{key}?confirm=true deletes the
field and clears its value from every contact.
Audit
Every change is in the workspace's audit log under your email, made through the API.
Related
Campaigns API
Create, fill, launch and run outbound campaigns from your own servers over the REST API, authenticated with a personal access token.
Glossary
Definitions of the 26 terms in the Vertical AI guides, from workspace and agent to version, eval and judge. Each term links to the guide that covers it in full.