Vixiees

**Welcome to the Vixiees API**

The Vixiees API allows you to securely and efficiently integrate your systems with our platform,
automate processes and synchronize data in real time. With a single **X-API-Key**, you can create and update
contacts and deals, access recordings, send WhatsApp messages via approved templates and receive
instant notifications through configurable webhooks.

Designed to be **robust, scalable and easy to implement**, the API offers predictable endpoints,
clear limits and intelligent developer support.

---

**What you can do with the API**
- Contacts: create, update and receive changes automatically.
- Deals: create, update and receive changes automatically.
- Recordings: query and retrieve call recordings.
- Messaging: send WhatsApp Business templates.
- Webhooks: receive real-time events for contacts and deals.

---

**Access and authentication**
1. Go to *Settings -> Account -> API*.
2. Enable the API and copy your **secret X-API-Key**.
3. (Optional) Enable webhooks and set the **Webhook URL**.
The API Key is sensitive - do not share it publicly.

---

**Webhooks**
- Enable or disable specific events from the same section.
- Set your receiving URL.
- Receive instant notifications when important changes occur.

---

**Usage limits**
- **License-Based Scaling**
  - Per minute: `licenses x 25 requests`
  - Per hour: x60
  - Per day: x24
- **Hardcore limit:** 40 requests / 2 s (independent of other limits).
- If any limit is exceeded, a `429 TooManyRequests` response is returned with details and a link to [developers.vixiees.com](https://developers.vixiees.com).

---

**Pagination**
- Max **1000 records per page set**.
- Use `limit <= 1000` and `page=1` onwards.
- Filter by `created_at` or `updated_at` to segment results.
  Example: `updated_at>=2025-08-07T00:00:00`
- `422 Unprocessable Entity` indicates the limit has been exceeded or the query is invalid.

---

**Quick summary**

| Element                     | Detail                                                                  |
|-----------------------------|-------------------------------------------------------------------------|
| Authentication              | X-API-Key from Settings -> Account -> API                              |
| Webhooks                    | Configurable from the same section                                     |
| Rate Limits                 | License-Based + Hardcore (40 req/2s)                                   |
| Pagination                  | Max 1000 records per page set                                          |
| Main features               | Contacts, deals, recordings, WhatsApp templates, events                |

---

**Common Use Cases**

**1. Sync contacts to external CRM**
- GET `/contacts` with `updated_at_from` filter for incremental sync
- Configure `contact_updated` webhook for real-time updates

**2. Send WhatsApp after form submission**
- Configure `submitted_form_created` webhook
- POST `/whatsapp_templates/{id}/send_message` to send confirmation

**3. Track deal pipeline**
- Configure `deal_updated` webhook
- GET `/deals` to sync current state to your BI tool

**4. Automate task creation**
- POST `/tasks` to create follow-up tasks via API
- Configure `task_completed` webhook for notifications

---

**Error Responses**

All endpoints return errors in this format:
```json
{
  "error": "Error message",
  "details": { /* field-specific errors */ }
}
```

Common HTTP status codes:
- `400` - Bad request (invalid parameters)
- `401` - Unauthorized (invalid API key)
- `404` - Resource not found
- `422` - Validation failed
- `429` - Rate limit exceeded


Vixiees API

Call Recordings

Returns a paginated list of call recordings with transcription status.

Each recording includes an `encrypted_url` for secure playback access.
Filter by contact, user, playbook, or task to narrow results.


Retrieves call recordings

Contacts

Returns a paginated list of contacts. Use filters to narrow results:
- `words`: Full-text search across name, email, phone, company
- `exact_search`: Exact match on email/phone (useful for deduplication)
- Date filters: `created_at_from/to`, `updated_at_from/to`

**Tip:** For webhook-driven sync, filter by `updated_at` to get only changed records.


Retrieves contacts

Creates a new contact. At least one of `email` or `phone` is required for WhatsApp/email communication.

Optionally assign the contact to a playbook, flow step, and user at creation time.


Creates a new contact

Returns all files attached to the contact (PDFs, images, etc.).

Each document includes a secure `url` for downloading the file.


Retrieves documents for a contact

Uploads a file to the contact. Maximum file size is 35MB.

Use the `tag` parameter to categorize documents (e.g., "contract", "id", "invoice").


Uploads a document to a contact

Returns the WhatsApp conversation history for a contact.

Messages include media URLs for attachments (images, documents, audio, video).
Both sent and received messages are included with timestamps and delivery status.


Retrieves whatsapp conversations for a contact

Returns a single contact with all fields including custom attributes.

You can use either the internal ID or the `external_reference_id` to retrieve the contact.


Retrieves a specific contact

Deletes a contact. All associated tasks and deals will be preserved but no longer visible in the app.


Deletes a contact

Partial update of a contact. Only provided fields are modified; omitted fields remain unchanged.

Custom attributes can be updated by including them in the `custom_attributes` array.


Updates a contact

Adds a comment to a contact's activity feed.

Comments are visible in the contact timeline and can be synced to integrated CRMs (Hubspot, Pipedrive).


Adds a comment to a contact

Assigns a team member to be the owner of this contact.

The assigned user will see this contact in their task queue and receive notifications.


Assigns a user to a contact

Moves a contact to a different playbook and/or flow step.

Use this to progress contacts through your sales pipeline or reassign them to different workflows.
Optionally update contact fields at the same time using `contact_required_fields`.


Updates a contact's current playbook

Contracts

Returns a paginated list of contract documents.

Contracts track agreements with clients including status, start/end dates.


Retrieves contracts

Deals

Returns a paginated list of deals. Filter by contact, status, or date range.

Use `order_by` and `sort` to control result ordering (default: created_at desc).


Retrieves deals

Creates a new deal linked to a contact.

A deal tracks a sales opportunity with an optional amount, close date, and status.


Creates a new deal

Retrieves a deal

Updates a deal's amount, status, close date, or other fields.

Only provided fields are modified; omitted fields remain unchanged.


Updates a deal

Deletes a deal

Playbooks

Returns all playbooks (sales workflows) for the account.

Playbooks define the stages (flow steps) that contacts progress through.
Use the playbook ID when assigning contacts to a workflow.


Retrieves all playbooks

Flow Steps

Returns all stages (flow steps) within a playbook.

Flow steps represent the progression stages for contacts (e.g., "New Lead", "Qualified", "Negotiating").
Use flow step IDs when updating a contact's current position in the sales workflow.


Retrieves flow steps for a playbook

Submitted Forms

Returns a paginated list of submitted lead capture forms.

Forms can come from multiple sources: web forms, Meta (Facebook) lead ads, or Typeform.
Each form includes the raw responses and the associated contact.


Retrieves submitted forms

Returns a single submitted form with all responses and metadata.

Retrieves a submitted form

Task Templates

Returns all task templates defined for the account.

Task templates define the types of follow-up actions (e.g., "First Call", "Demo Meeting").
Use template IDs when creating tasks via the API.


Retrieves task templates

Tasks

Returns a paginated list of tasks. Filter by assignee, contact, or status.

Tasks represent follow-up actions for contacts (calls, meetings, etc.).


Retrieves tasks

Creates a new task for contact follow-up.

Tasks are based on task templates which define the type of follow-up action.
Optionally schedule the task for a specific date using `active_on`.


Creates a new task

Marks a task as cancelled. The task will no longer appear in the task queue.

Cancels a task

Marks a task as completed. Records the completion time and removes it from the task queue.

Completes a task

WhatsApp Templates

Returns all approved WhatsApp Business templates for the account.

Only templates with `status: approved` can be used to send messages.
Templates are required to initiate conversations outside the 24-hour window.


Retrieves WhatsApp templates

Sends a WhatsApp template message to a contact.

Use `parameters` to fill template variables (e.g., {{1}}, {{2}}).
For templates with media headers, use `header_parameters` with document/image/video links.
For templates with URL buttons, use `buttons_parameters` to set the dynamic URL suffix.


Sends a WhatsApp template message

Webhooks

Receive webhook events. All events POST to this single path. See multiple examples below.

Example only. Actual endpoint path is /webhooks. Use YOUR_WEBHOOK_URL; only the body varies.

Webhooks example: contact_comment_created

Webhooks example: contact_created

Webhooks example: contact_deleted

Webhooks example: contact_updated

Webhooks example: deal_updated

Webhooks example: document_created

Webhooks example: incoming_call

Webhooks example: task_completed

Webhooks example: whatsapp_received

Default

Vixiees Client API

v1 English

Vixiees API Server

event

account_id

assignee_id

Current playbook (sales workflow) the contact is in

current_playbook_id

current_flow_step_id

current_flow_step_since

ID of the import batch if contact was imported

contact_import_id

Computed full name (first_name + last_name)

title

Direct URL to view contact in Vixiees app

app_url

first_name

last_name

second_last_name

email

canonical_email

phone

ISO country code derived from phone number

phone_country_code

invalid_phone

invalid_email

company_name

additional_phones

additional_emails

All email addresses (primary + additional)

all_emails

all_phones

Contact priority (1=highest, 5=lowest). Used for task ordering.

priority

How contact was created: api, whatsapp, form, import, facebook, etc.

source

Content of the most recent WhatsApp message

last_message

When the last WhatsApp message was received

last_message_at

unread_messages

True if contact has received at least one response

answered_at_least_once

True if contact was answered via phone call

answered_via_call

answered_via_email

True if contact was answered via WhatsApp

answered_via_whatsapp

Seconds between contact creation and first response

first_answer_time

first_answered_at

When contact received most recent response

last_answered_at

Consent to receive transactional WhatsApp messages

whatsapp_transactional_opt_in

email_transactional_opt_in

Consent to receive marketing WhatsApp messages

whatsapp_marketing_opt_in

email_marketing_opt_in

external_reference_id

external_reference_url

bankflip_user_link

bankflip_documentation_area_id

True if contact has no assignee or pending tasks

unattended

True if contact sent email that has not been replied to

unanswered_email

True if contact sent WhatsApp that has not been replied to

unanswered_whatsapp

True if contact has missed/unreturned calls

unanswered_call

True if contact has an active task assigned

on_task

True if contact has unfinished check tasks (checklist items)

check_tasks_pending

True if contact is marked as ignored/archived

ignored

True if contact has at least one won deal

is_client

True if contact requested data removal (GDPR)

remove_requested

last_close_won_reason

last_close_lost_reason

True if contact was merged into another contact

merged

merged_at

last_closed_office_message_sent_at

last_assignee_at

last_started_task_at

last_completed_task_at

last_successful_call_at

When last unsuccessful call attempt was made

last_unsuccessful_call_at

last_email_sent_at

last_email_received_at

last_window_opened_at

True if AI is currently managing this contact

ai_controlling

ai_disabled

ai_test

ai_suppressed_until_flow_step_change

ai_reply_count_in_state

deals_count

meetings_count

pinned_comment_id

has_skills

skills

created_at

updated_at

deleted_at

locale

country_code

utm_source

utm_medium

utm_campaign

utm_term

utm_content

gclid

URL of the page where contact was captured

Sections

Webhooks example: contact_deleted

Body Parameters

Response

What made this section unhelpful for you?

Response

What made this section unhelpful for you?

Sections

Webhooks example: contact_deleted

Body ParametersExpand all

Response

What made this section unhelpful for you?

Response

What made this section unhelpful for you?

Ask an AI

Code with AI

Body Parameters