Contacts

Contacts are social media users who have interacted with your connected accounts. VoxBurst syncs them automatically from inbound interactions. You can also create, update, and tag contacts manually.

Contacts are available on all plans — no feature flag required.

Base URL


https://api.voxburst.io/v1/contacts

Contact Object


{
  "id": "contact_abc123",
  "workspaceId": "ws_01hwxyz",
  "platform": "TWITTER",
  "platformId": "1234567890",
  "displayName": "Alice Example",
  "username": "alice",
  "avatarUrl": "https://cdn.example.com/avatar.jpg",
  "tags": ["vip", "customer"],
  "customFields": { "tier": "gold" },
  "lastSeenAt": "2026-05-10T14:00:00Z",
  "createdAt": "2026-04-01T10:00:00Z",
  "updatedAt": "2026-05-10T14:00:00Z"
}

Contact Fields

Field	Type	Description
`id`	string	Contact ID
`workspaceId`	string	Workspace this contact belongs to
`platform`	string	Platform constant (e.g. `TWITTER`)
`platformId`	string	User ID on the platform
`displayName`	string \| null	Display name on the platform
`username`	string \| null	Handle or username
`avatarUrl`	string \| null	Profile avatar URL
`tags`	string[]	Workspace-defined tags for segmentation
`customFields`	object	Arbitrary key-value metadata
`lastSeenAt`	string \| null	ISO 8601 timestamp of last interaction
`createdAt`	string	ISO 8601 creation timestamp
`updatedAt`	string	ISO 8601 last-updated timestamp

List Contacts

GET /v1/contacts

List contacts with optional search, platform, and tag filtering. Uses page/limit pagination.

Query Parameters

Parameter	Type	Description
`search`	string	Search by display name or username
`platform`	string	Filter by platform constant (e.g. `TWITTER`)
`tags`	string	Comma-separated list of tags to filter by
`page`	integer	Page number (default: 1)
`limit`	integer	Results per page (default: 20, max: 100)


curl "https://api.voxburst.io/v1/contacts?platform=TWITTER&tags=vip&limit=20" \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

Response


{
  "contacts": [
    {
      "id": "contact_abc123",
      "platform": "TWITTER",
      "platformId": "1234567890",
      "displayName": "Alice Example",
      "username": "alice",
      "tags": ["vip"],
      "customFields": {},
      "lastSeenAt": "2026-05-10T14:00:00Z",
      "createdAt": "2026-04-01T10:00:00Z",
      "updatedAt": "2026-05-10T14:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20,
  "pages": 1
}

Get Contact

GET /v1/contacts/:id

Retrieve a single contact by ID.


curl https://api.voxburst.io/v1/contacts/contact_abc123 \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

Response


{
  "contact": { ... }
}

Create Contact

POST /v1/contacts

Manually create a contact. If a contact with the same platform + platformId already exists in the workspace, the record is upserted (updated in place, not duplicated).

Request Body

Field	Type	Required	Description
`platform`	string	Yes	Platform constant (e.g. `TWITTER`)
`platformId`	string	Yes	The user’s ID on the platform
`displayName`	string	No	Display name (max 255 chars)
`username`	string	No	Handle or username (max 255 chars)
`avatarUrl`	string	No	Valid HTTPS URL
`tags`	string[]	No	Tags (each max 100 chars, default: `[]`)
`customFields`	object	No	Key-value metadata (default: `{}`)


curl -X POST https://api.voxburst.io/v1/contacts \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "TWITTER",
    "platformId": "1234567890",
    "displayName": "Alice Example",
    "username": "alice",
    "tags": ["vip"]
  }'

Response (201)


{
  "contact": { ... }
}

Update Contact

PATCH /v1/contacts/:id

Update a contact’s display name, tags, or custom fields. All fields are optional.

Request Body

Field	Type	Description
`displayName`	string \| null	New display name, or `null` to clear
`tags`	string[]	Replacement tag list (replaces all existing tags)
`customFields`	object	Replacement custom fields


curl -X PATCH https://api.voxburst.io/v1/contacts/contact_abc123 \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["vip", "customer"],
    "customFields": { "tier": "gold" }
  }'

Response


{
  "contact": { ... }
}

Delete Contact

DELETE /v1/contacts/:id

Delete a contact from the workspace.


curl -X DELETE https://api.voxburst.io/v1/contacts/contact_abc123 \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

Response


{ "ok": true }

Add Tag

POST /v1/contacts/:id/tags

Add a single tag to a contact without replacing the existing tag list.

Request Body

Field	Type	Required	Description
`tag`	string	Yes	Tag to add (1–100 chars)


curl -X POST https://api.voxburst.io/v1/contacts/contact_abc123/tags \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "tag": "newsletter" }'

Response


{
  "contact": { ... }
}

Remove Tag

DELETE /v1/contacts/:id/tags/:tag

Remove a specific tag from a contact.


curl -X DELETE https://api.voxburst.io/v1/contacts/contact_abc123/tags/newsletter \
  -H "Authorization: Bearer vb_live_xxxxxxxxxxxxx"

Response


{
  "contact": { ... }
}