Contacts
Manage contacts (leads and clients)
Logs a call made outside Vixiees
/contacts/{contact_id}/callsRecords a call that already happened outside Vixiees (another dialer, an AI voice agent, a mobile phone) on the contact.
No call is placed. The call appears in the contact timeline; it does not change the contact's state or tasks. It is not billed and does not count in Vixiees call analytics.
When omitted, to (outgoing) or from (incoming) defaults to the contact phone.
Request body · application/json
directionstringrequiredValues:incomingoutgoing- ISO 8601, not in the future
started_atstring (date-time)requiredExample:2026-10-27T10:00:00Z - Duration in seconds; the call cannot end in the future
durationintegerrequiredExample:95 response_statusstringrequiredValues:completedfailedcanceledno_answerbusyblocked_high_riskclosed_officemachine_answeredanswered_but_busyshort_durationdeclined- Vixiees user who made or took the call. Omit it when no Vixiees user was involved (e.g. an AI agent)
user_idstringExample:64a1b2c3d4e5f678901235fe - Calling number, E.164. Defaults to the contact phone for incoming calls
fromstringExample:+34600000002 - Called number, E.164. Defaults to the contact phone for outgoing calls
tostringExample:+34600000001 - Your id for this call. If a call with this id was already logged for the account, the request is rejected with 422 and an
external_reference_idstringexternal_reference_iderror, meaning the call already existsExample:dialer-call-8812 - What was said on the call, turn by turn, in order. Up to 100000 characters in total; a longer transcript rejects the whole request. Send it with the call: it cannot be added later. It is stored with the call; it is not shown in the app or returned by the API yet
transcriptarray<object> transcript[].speakerstringrequiredagentfor whoever spoke on your behalf (a person or an AI agent),contactfor the contactValues:agentcontact- Turns with an empty or null text are left out
transcript[].textstringrequirednullableExample:Hola, le llamo de Vixiees
Responses
200call logged401unauthorized404contact not found422unprocessable entity
curl -X POST 'https://api.vixiees.com/api/v1/contacts/{contact_id}/calls' \
-H 'X-Api-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"direction": "outgoing",
"started_at": "2026-10-27T10:00:00Z",
"duration": 95,
"response_status": "completed",
"user_id": "64a1b2c3d4e5f678901235fe",
"from": "+34600000002",
"to": "+34600000001",
"external_reference_id": "dialer-call-8812",
"transcript": [
{
"speaker": "agent",
"text": "Hola, le llamo de Vixiees"
}
]
}'{
"id": "string"
}Retrieves documents for a contact
/contacts/{contact_id}/documentsReturns all files attached to the contact (PDFs, images, etc.).
Each document includes a secure url for downloading the file.
Responses
200documents found401unauthorized404contact not found
curl -X GET 'https://api.vixiees.com/api/v1/contacts/{contact_id}/documents' \
-H 'X-Api-Key: YOUR_API_KEY'{
"results": [
{
"id": "string",
"file_name": "string",
"file_size": 0,
"file_content_type": "string",
"tag": "string",
"source": "string",
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z",
"url": "string"
}
]
}Uploads a document to a contact
/contacts/{contact_id}/documentsUploads a file to the contact. Maximum file size is 35MB.
Use the tag parameter to categorize documents (e.g., "contract", "id", "invoice").
Responses
200document created401unauthorized404contact not found422unprocessable entity
curl -X POST 'https://api.vixiees.com/api/v1/contacts/{contact_id}/documents' \
-H 'X-Api-Key: YOUR_API_KEY'{
"id": "507f1f77bcf86cd799439011"
}Retrieves the activity feed for a contact
/contacts/{contact_id}/feedReturns a paginated activity feed for a contact, including calls (regular, WhatsApp and calls logged through the API), comments, tasks, emails, SMS messages, and other events.
Items are ordered by occurrence_at descending (most recent first). Use subject_types[] to filter by event type, and from/to to filter by date range.
Query parameters
- Page number (1-based)
pageintegerDefault:1 - Number of items per page (max 100)
limitintegerDefault:25 - Filter by subject type(s). Valid values: Call, WhatsappCall, ExternalCall, Comment, Task, Sms, Email, PlaybookContactStatus, AssigneeChange, ContactMergeEvent, ContactCreation, DealCreation, Meeting, WorkflowLog, EntityUpdate. Call returns every call type (Call, WhatsappCall, ExternalCall); use WhatsappCall or ExternalCall to narrow it.
subject_typesarray<string> - ISO8601 datetime — return items with occurrence_at >= from
fromstring (date-time) - ISO8601 datetime — return items with occurrence_at <= to
tostring (date-time)
Responses
200feed retrieved401unauthorized404contact not found422invalid date params
curl -X GET 'https://api.vixiees.com/api/v1/contacts/{contact_id}/feed' \
-H 'X-Api-Key: YOUR_API_KEY'{
"results": [
{
"id": "string",
"subject_type": "string",
"subject_id": "string",
"occurrence_at": "2024-01-01T00:00:00Z",
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z",
"subject": {}
}
],
"page_info": {
"current_page": 0,
"limit": 0
}
}Retrieves whatsapp conversations for a contact
/contacts/{contact_id}/whatsapp_conversationsReturns 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.
For template messages, message_template_body returns the full rendered message
(header, body and footer joined by newlines) with the template variables resolved to
their sent values when the corresponding parameters are present, instead of raw
{{1}}/{{2}} placeholders.
Responses
200whatsapp conversations found401unauthorized404contact not found
curl -X GET 'https://api.vixiees.com/api/v1/contacts/{contact_id}/whatsapp_conversations' \
-H 'X-Api-Key: YOUR_API_KEY'{
"messages": [
{
"id": "string",
"body": "string",
"sent": true,
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z",
"from": "string",
"to": "string",
"text": true,
"status": "string",
"message_type": "string",
"message_template_body": "string",
"template": true,
"header_parameters": [
"string"
],
"body_parameters": [
"string"
],
"buttons_parameters": [
"string"
],
"url_parameter": "string",
"wa_id": "string",
"reply": true,
"reply_wa_id": "string",
"attachment": true,
"image": true,
"audio": true,
"video": true,
"application": true,
"filename": "string",
"media_id": "string",
"media_url": "string",
"media_content_type": "string",
"voice": true,
"location": true,
"latitude": 0,
"longitude": 0,
"label": "string",
"address": "string"
}
]
}Retrieves contacts
/contactsReturns a paginated list of contacts. Use filters to narrow results:
words: Full-text search across name, email, phone, companyexact_search: Exact match on email/phone (useful for deduplication)- Date filters:
created_at_from/to,updated_at_from/to playbook_id/flow_step_id: Restrict to contacts currently in that playbook/flow step
Tip: For webhook-driven sync, filter by updated_at to get only changed records.
Query parameters
- Filter by the contact's current playbook ID. A malformed ID returns an empty result set rather than an error.
playbook_idstringExample:507f1f77bcf86cd799439011 - Filter by the contact's current flow step ID. A malformed ID returns an empty result set rather than an error.
flow_step_idstringExample:507f1f77bcf86cd799439012 - Search terms to filter contacts
wordsstringExample:Jon Smith - Whether to perform an exact match search on email and phone
exact_searchboolean - Sort direction (asc or desc)
sortstringValues:ascdesc - Field to order results by
order_bystringExample:created_at - Page number for pagination
pageintegerExample:1 - Number of records per page
limitintegerExample:25 - Filter by creation date from
created_at_fromstring (date-time)Example:2024-01-01T00:00:00Z - Filter by creation date to
created_at_tostring (date-time)Example:2024-12-31T23:59:59Z - Filter by update date from
updated_at_fromstring (date-time)Example:2024-01-01T00:00:00Z - Filter by update date to
updated_at_tostring (date-time)Example:2024-12-31T23:59:59Z
Responses
200contacts found401unauthorized
curl -X GET 'https://api.vixiees.com/api/v1/contacts' \
-H 'X-Api-Key: YOUR_API_KEY'{
"results": [
{
"id": "507f1f77bcf86cd799439011",
"first_name": "John",
"last_name": "Doe",
"second_last_name": "Smith",
"email": "john.doe@example.com",
"phone": "+34627352692",
"company_name": "Acme Corporation",
"additional_phones": [
"+34627352693"
],
"additional_emails": [
"john.doe+work@example.com"
],
"priority": 3,
"source": "api",
"country_code": "ES",
"language": "es",
"whatsapp_transactional_opt_in": true,
"email_transactional_opt_in": true,
"whatsapp_marketing_opt_in": false,
"email_marketing_opt_in": false,
"external_reference_id": "EXT-12345",
"external_reference_url": "https://external-system.com/contacts/12345",
"ignored": false,
"is_client": false,
"last_close_won_reason": "Product demo convinced them",
"last_close_lost_reason": "Budget constraints",
"skills": [
"spanish",
"english"
],
"created_at": "2023-01-15T10:30:00Z",
"updated_at": "2023-01-15T14:30:00Z",
"title": "John Doe",
"closed_won_reason": "Product demo convinced them",
"closed_lost_reason": "Budget constraints",
"custom_attributes": [
{
"field_name": "industry",
"value": "Technology"
}
]
}
],
"page_info": {
"current_page": 0,
"limit": 0
}
}Creates a new contact
/contactsCreates 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.
Request body · application/json
- Contact first name
first_namestringExample:John - Contact last name
last_namestringExample:Doe - Contact second last name
second_last_namestringExample:Smith - Contact email address
emailstringExample:john.doe@example.com - Contact phone number
phonestringExample:+34627352692 - Company name
company_namestringExample:Acme Corporation - Additional phone numbers
additional_phonesarray<string>Example:["+34627352693","+34627352694"] - Additional email addresses
additional_emailsarray<string>Example:["john.doe+work@example.com","j.doe@company.com"] - Contact source
sourcestringValues:manualcsvapicallwhatsappemailcrm - Country code (ISO 3166-1 alpha-2)
country_codestringExample:ES - Language code (ISO 639-1)
languagestringExample:es - WhatsApp transactional messages opt-in
whatsapp_transactional_opt_inbooleanExample:true - Email transactional messages opt-in
email_transactional_opt_inbooleanExample:true - WhatsApp marketing messages opt-in
whatsapp_marketing_opt_inbooleanExample:false - Email marketing messages opt-in
email_marketing_opt_inbooleanExample:false - External system reference ID
external_reference_idstringExample:EXT-12345 - External system reference URL
external_reference_urlstringExample:https://external-system.com/contacts/12345 - Contact skills
skillsarray<string>Example:["spanish","english","sales"] custom_attributesarray<object>nullablecustom_attributes[].field_namestringExample:industrycustom_attributes[].valuestringExample:Technology- ID of playbook to assign
playbook_idstringExample:507f1f77bcf86cd799439011 - ID of flow step to assign
flow_step_idstringExample:507f1f77bcf86cd799439012 - ID of user to assign as contact owner
assignee_idstringExample:507f1f77bcf86cd799439013
Responses
200contact created401unauthorized422unprocessable entity
curl -X POST 'https://api.vixiees.com/api/v1/contacts' \
-H 'X-Api-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"first_name": "John",
"last_name": "Doe",
"second_last_name": "Smith",
"email": "john.doe@example.com",
"phone": "+34627352692",
"company_name": "Acme Corporation",
"additional_phones": [
"+34627352693",
"+34627352694"
],
"additional_emails": [
"john.doe+work@example.com",
"j.doe@company.com"
],
"source": "api",
"country_code": "ES",
"language": "es",
"whatsapp_transactional_opt_in": true,
"email_transactional_opt_in": true,
"whatsapp_marketing_opt_in": false,
"email_marketing_opt_in": false,
"external_reference_id": "EXT-12345",
"external_reference_url": "https://external-system.com/contacts/12345",
"skills": [
"spanish",
"english",
"sales"
],
"custom_attributes": [
{
"field_name": "industry",
"value": "Technology"
}
],
"playbook_id": "507f1f77bcf86cd799439011",
"flow_step_id": "507f1f77bcf86cd799439012",
"assignee_id": "507f1f77bcf86cd799439013"
}'{
"id": "string"
}Retrieves a specific contact
/contacts/{id}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.
Path parameters
- The ID or external reference ID of the contact to retrieve
idstringrequiredExample:64a1b2c3d4e5f678901234ab
Responses
200contact found401unauthorized404contact not found
curl -X GET 'https://api.vixiees.com/api/v1/contacts/64a1b2c3d4e5f678901234ab' \
-H 'X-Api-Key: YOUR_API_KEY'{
"id": "507f1f77bcf86cd799439011",
"first_name": "John",
"last_name": "Doe",
"second_last_name": "Smith",
"email": "john.doe@example.com",
"phone": "+34627352692",
"company_name": "Acme Corporation",
"additional_phones": [
"+34627352693"
],
"additional_emails": [
"john.doe+work@example.com"
],
"source": "api",
"country_code": "ES",
"language": "es",
"whatsapp_transactional_opt_in": true,
"email_transactional_opt_in": true,
"whatsapp_marketing_opt_in": false,
"email_marketing_opt_in": false,
"external_reference_id": "EXT-12345",
"external_reference_url": "https://external-system.com/contacts/12345",
"skills": [
"spanish",
"english"
],
"custom_attributes": [
{
"field_name": "industry",
"value": "Technology"
}
]
}Deletes a contact
/contacts/{id}Deletes a contact. All associated tasks and deals will be preserved but no longer visible in the app.
Path parameters
- The ID or external reference ID of the contact to delete
idstringrequired
Responses
200contact deleted401unauthorized404contact not found
curl -X DELETE 'https://api.vixiees.com/api/v1/contacts/{id}' \
-H 'X-Api-Key: YOUR_API_KEY'{
"status": "ok"
}Updates a contact
/contacts/{id}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.
Path parameters
- The ID or external reference ID of the contact to update
idstringrequiredExample:64a1b2c3d4e5f678901234ab
Request body · application/json
- Contact first name
first_namestringExample:John - Contact last name
last_namestringExample:Doe - Contact second last name
second_last_namestringExample:Smith - Contact email address
emailstringExample:john.doe@example.com - Contact phone number
phonestringExample:+34627352692 - Company name
company_namestringExample:Acme Corporation - Additional phone numbers
additional_phonesarray<string>Example:["+34627352693","+34627352694"] - Additional email addresses
additional_emailsarray<string>Example:["john.doe+work@example.com","j.doe@company.com"] - Contact priority (1-5)
priorityintegerValues:12345 - Contact source
sourcestringValues:manualcsvapicallwhatsappemailcrm - Country code (ISO 3166-1 alpha-2)
country_codestringExample:ES - Language code (ISO 639-1)
languagestringExample:es - WhatsApp transactional messages opt-in
whatsapp_transactional_opt_inbooleanExample:true - Email transactional messages opt-in
email_transactional_opt_inbooleanExample:true - WhatsApp marketing messages opt-in
whatsapp_marketing_opt_inbooleanExample:false - Email marketing messages opt-in
email_marketing_opt_inbooleanExample:false - External system reference ID
external_reference_idstringExample:EXT-12345 - External system reference URL
external_reference_urlstringExample:https://external-system.com/contacts/12345 - Contact skills
skillsarray<string>Example:["spanish","english","sales"] custom_attributesarray<object>nullablecustom_attributes[].field_namestringExample:industrycustom_attributes[].valuestringExample:Technology
Responses
200contact updated401unauthorized404contact not found
curl -X PUT 'https://api.vixiees.com/api/v1/contacts/64a1b2c3d4e5f678901234ab' \
-H 'X-Api-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"first_name": "John",
"last_name": "Doe",
"second_last_name": "Smith",
"email": "john.doe@example.com",
"phone": "+34627352692",
"company_name": "Acme Corporation",
"additional_phones": [
"+34627352693",
"+34627352694"
],
"additional_emails": [
"john.doe+work@example.com",
"j.doe@company.com"
],
"priority": 3,
"source": "api",
"country_code": "ES",
"language": "es",
"whatsapp_transactional_opt_in": true,
"email_transactional_opt_in": true,
"whatsapp_marketing_opt_in": false,
"email_marketing_opt_in": false,
"external_reference_id": "EXT-12345",
"external_reference_url": "https://external-system.com/contacts/12345",
"skills": [
"spanish",
"english",
"sales"
],
"custom_attributes": [
{
"field_name": "industry",
"value": "Technology"
}
]
}'{
"id": "507f1f77bcf86cd799439011",
"first_name": "John",
"last_name": "Doe",
"second_last_name": "Smith",
"email": "john.doe@example.com",
"phone": "+34627352692",
"company_name": "Acme Corporation",
"additional_phones": [
"+34627352693"
],
"additional_emails": [
"john.doe+work@example.com"
],
"priority": 3,
"source": "api",
"country_code": "ES",
"language": "es",
"whatsapp_transactional_opt_in": true,
"email_transactional_opt_in": true,
"whatsapp_marketing_opt_in": false,
"email_marketing_opt_in": false,
"external_reference_id": "EXT-12345",
"external_reference_url": "https://external-system.com/contacts/12345",
"ignored": false,
"is_client": false,
"last_close_won_reason": "Product demo convinced them",
"last_close_lost_reason": "Budget constraints",
"skills": [
"spanish",
"english"
],
"created_at": "2023-01-15T10:30:00Z",
"updated_at": "2023-01-15T14:30:00Z",
"title": "John Doe",
"closed_won_reason": "Product demo convinced them",
"closed_lost_reason": "Budget constraints",
"custom_attributes": [
{
"field_name": "industry",
"value": "Technology"
}
]
}Updates a contact's current playbook
/contacts/{id}/update_current_playbookMoves 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.
Path parameters
- The ID or external reference ID of the contact
idstringrequiredExample:64a1b2c3d4e5f678901234ab
Request body · application/json
playbook_idstringrequiredExample:64a1b2c3d4e5f678901234cdflow_step_idstringExample:64a1b2c3d4e5f678901234ef- Optional array of contact fields to update along with the playbook change
contact_required_fieldsarray<object>Example:[{"key":"custom_field_name","value":"custom_value"}] - Field name (can be a contact attribute or custom attribute)
contact_required_fields[].keystringrequiredExample:custom_field_name - Field value
contact_required_fields[].valuestringrequiredExample:custom_value
Responses
200playbook updated with contact required fields401unauthorized404contact not found
curl -X POST 'https://api.vixiees.com/api/v1/contacts/64a1b2c3d4e5f678901234ab/update_current_playbook' \
-H 'X-Api-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"playbook_id": "64a1b2c3d4e5f678901234cd",
"flow_step_id": "64a1b2c3d4e5f678901234ef",
"contact_required_fields": [
{
"key": "custom_field_name",
"value": "custom_value"
}
]
}'{
"id": "507f1f77bcf86cd799439011",
"first_name": "John",
"last_name": "Doe",
"second_last_name": "Smith",
"email": "john.doe@example.com",
"phone": "+34627352692",
"company_name": "Acme Corporation",
"additional_phones": [
"+34627352693"
],
"additional_emails": [
"john.doe+work@example.com"
],
"priority": 3,
"source": "api",
"country_code": "ES",
"language": "es",
"whatsapp_transactional_opt_in": true,
"email_transactional_opt_in": true,
"whatsapp_marketing_opt_in": false,
"email_marketing_opt_in": false,
"external_reference_id": "EXT-12345",
"external_reference_url": "https://external-system.com/contacts/12345",
"ignored": false,
"is_client": false,
"last_close_won_reason": "Product demo convinced them",
"last_close_lost_reason": "Budget constraints",
"skills": [
"spanish",
"english"
],
"created_at": "2023-01-15T10:30:00Z",
"updated_at": "2023-01-15T14:30:00Z",
"title": "John Doe",
"closed_won_reason": "Product demo convinced them",
"closed_lost_reason": "Budget constraints",
"custom_attributes": [
{
"field_name": "industry",
"value": "Technology"
}
]
}Assigns a user to a contact
/contacts/{id}/assign_userAssigns a team member to be the owner of this contact.
The assigned user will see this contact in their task queue and receive notifications.
Path parameters
- The ID or external reference ID of the contact
idstringrequiredExample:64a1b2c3d4e5f678901234ab
Request body · application/json
assignee_idstringrequiredExample:64a1b2c3d4e5f678901234gh
Responses
200user assigned401unauthorized404contact not found
curl -X POST 'https://api.vixiees.com/api/v1/contacts/64a1b2c3d4e5f678901234ab/assign_user' \
-H 'X-Api-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"assignee_id": "64a1b2c3d4e5f678901234gh"
}'{
"status": "string"
}Adds a comment to a contact
/contacts/{id}/add_commentAdds a comment to a contact's activity feed.
Comments are visible in the contact timeline and can be synced to integrated CRMs (Hubspot, Pipedrive).
Path parameters
- The ID or external reference ID of the contact
idstringrequiredExample:64a1b2c3d4e5f678901234ab
Request body · application/json
- The comment text
contentstringrequiredExample:Called the contact, left voicemail.
Responses
200comment added401unauthorized404contact not found422validation failed
curl -X POST 'https://api.vixiees.com/api/v1/contacts/64a1b2c3d4e5f678901234ab/add_comment' \
-H 'X-Api-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"content": "Called the contact, left voicemail."
}'{
"id": "string"
}