Connect

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 pathDoes
GET /contactsList and search
POST /contactsAdd one
GET /contacts/{contact}Read one
PATCH /contacts/{contact}Change one
DELETE /contacts/{contact}Delete one
POST /contacts/importAdd or update up to 5,000
GET /contacts/tagsThe tags in use, with counts
POST /contacts/tagsTag and untag many
GET /contacts/fieldsThe workspace's fields
POST /contacts/fieldsAdd 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.

StatusCodes
400invalid_input, bad_phone, bad_field, consent_required, nothing_to_change, too_many, too_many_fields
401unauthorized, invalid_token
403insufficient_scope, workspace_read_only, workspace_scope_required, workspace_out_of_scope, not_available, staff_token_not_accepted
404workspace_not_found, contact_not_found, field_not_found
409confirmation_required (a delete without ?confirm=true), contact_exists, field_exists, kind_locked
429rate_limited
500tool_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" }.

ParameterKeeps
searchContacts whose name or number contains it
tagsContacts with that tag. Repeat it to need several: ?tags=vip&tags=renewal%20due
fieldsContacts whose fields equal the values, as JSON: ?fields={"plan":"Premium"}, URL-encoded
limit, cursorUp 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.

On this page