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.

Sections

Completes a task

Header Parameters

Path Parameters

Response

Response Attributes

What made this section unhelpful for you?

Response

What made this section unhelpful for you?

Sections

Completes a task

Header Parameters

Path Parameters

Response

Response Attributes

What made this section unhelpful for you?

Response

What made this section unhelpful for you?

Ask an AI

Code with AI