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

Contacts

What made this section unhelpful for you?

Endpoints

What made this section unhelpful for you?

Sections

Contacts

What made this section unhelpful for you?

Endpoints

What made this section unhelpful for you?

Ask an AI

Code with AI