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.
Cuerpo de la petición · application/json
directionstringobligatorioValores:incomingoutgoing- ISO 8601, not in the future
started_atstring (date-time)obligatorioEjemplo:2026-10-27T10:00:00Z - Duration in seconds; the call cannot end in the future
durationintegerobligatorioEjemplo:95 response_statusstringobligatorioValores: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_idstringEjemplo:64a1b2c3d4e5f678901235fe - Calling number, E.164. Defaults to the contact phone for incoming calls
fromstringEjemplo:+34600000002 - Called number, E.164. Defaults to the contact phone for outgoing calls
tostringEjemplo:+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 existsEjemplo: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[].speakerstringobligatorioagentfor whoever spoke on your behalf (a person or an AI agent),contactfor the contactValores:agentcontact- Turns with an empty or null text are left out
transcript[].textstringobligatoriopuede ser nullEjemplo:Hola, le llamo de Vixiees
Respuestas
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.
Respuestas
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").
Respuestas
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.
Parámetros de consulta
- Page number (1-based)
pageintegerPor defecto:1 - Number of items per page (max 100)
limitintegerPor defecto: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)
Respuestas
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.
Respuestas
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.
Parámetros de consulta
- Filter by the contact's current playbook ID. A malformed ID returns an empty result set rather than an error.
playbook_idstringEjemplo:507f1f77bcf86cd799439011 - Filter by the contact's current flow step ID. A malformed ID returns an empty result set rather than an error.
flow_step_idstringEjemplo:507f1f77bcf86cd799439012 - Search terms to filter contacts
wordsstringEjemplo:Jon Smith - Whether to perform an exact match search on email and phone
exact_searchboolean - Sort direction (asc or desc)
sortstringValores:ascdesc - Field to order results by
order_bystringEjemplo:created_at - Page number for pagination
pageintegerEjemplo:1 - Number of records per page
limitintegerEjemplo:25 - Filter by creation date from
created_at_fromstring (date-time)Ejemplo:2024-01-01T00:00:00Z - Filter by creation date to
created_at_tostring (date-time)Ejemplo:2024-12-31T23:59:59Z - Filter by update date from
updated_at_fromstring (date-time)Ejemplo:2024-01-01T00:00:00Z - Filter by update date to
updated_at_tostring (date-time)Ejemplo:2024-12-31T23:59:59Z
Respuestas
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.
Cuerpo de la petición · application/json
- Contact first name
first_namestringEjemplo:John - Contact last name
last_namestringEjemplo:Doe - Contact second last name
second_last_namestringEjemplo:Smith - Contact email address
emailstringEjemplo:john.doe@example.com - Contact phone number
phonestringEjemplo:+34627352692 - Company name
company_namestringEjemplo:Acme Corporation - Additional phone numbers
additional_phonesarray<string>Ejemplo:["+34627352693","+34627352694"] - Additional email addresses
additional_emailsarray<string>Ejemplo:["john.doe+work@example.com","j.doe@company.com"] - Contact source
sourcestringValores:manualcsvapicallwhatsappemailcrm - Country code (ISO 3166-1 alpha-2)
country_codestringEjemplo:ES - Language code (ISO 639-1)
languagestringEjemplo:es - WhatsApp transactional messages opt-in
whatsapp_transactional_opt_inbooleanEjemplo:true - Email transactional messages opt-in
email_transactional_opt_inbooleanEjemplo:true - WhatsApp marketing messages opt-in
whatsapp_marketing_opt_inbooleanEjemplo:false - Email marketing messages opt-in
email_marketing_opt_inbooleanEjemplo:false - External system reference ID
external_reference_idstringEjemplo:EXT-12345 - External system reference URL
external_reference_urlstringEjemplo:https://external-system.com/contacts/12345 - Contact skills
skillsarray<string>Ejemplo:["spanish","english","sales"] custom_attributesarray<object>puede ser nullcustom_attributes[].field_namestringEjemplo:industrycustom_attributes[].valuestringEjemplo:Technology- ID of playbook to assign
playbook_idstringEjemplo:507f1f77bcf86cd799439011 - ID of flow step to assign
flow_step_idstringEjemplo:507f1f77bcf86cd799439012 - ID of user to assign as contact owner
assignee_idstringEjemplo:507f1f77bcf86cd799439013
Respuestas
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.
Parámetros de ruta
- The ID or external reference ID of the contact to retrieve
idstringobligatorioEjemplo:64a1b2c3d4e5f678901234ab
Respuestas
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.
Parámetros de ruta
- The ID or external reference ID of the contact to delete
idstringobligatorio
Respuestas
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.
Parámetros de ruta
- The ID or external reference ID of the contact to update
idstringobligatorioEjemplo:64a1b2c3d4e5f678901234ab
Cuerpo de la petición · application/json
- Contact first name
first_namestringEjemplo:John - Contact last name
last_namestringEjemplo:Doe - Contact second last name
second_last_namestringEjemplo:Smith - Contact email address
emailstringEjemplo:john.doe@example.com - Contact phone number
phonestringEjemplo:+34627352692 - Company name
company_namestringEjemplo:Acme Corporation - Additional phone numbers
additional_phonesarray<string>Ejemplo:["+34627352693","+34627352694"] - Additional email addresses
additional_emailsarray<string>Ejemplo:["john.doe+work@example.com","j.doe@company.com"] - Contact priority (1-5)
priorityintegerValores:12345 - Contact source
sourcestringValores:manualcsvapicallwhatsappemailcrm - Country code (ISO 3166-1 alpha-2)
country_codestringEjemplo:ES - Language code (ISO 639-1)
languagestringEjemplo:es - WhatsApp transactional messages opt-in
whatsapp_transactional_opt_inbooleanEjemplo:true - Email transactional messages opt-in
email_transactional_opt_inbooleanEjemplo:true - WhatsApp marketing messages opt-in
whatsapp_marketing_opt_inbooleanEjemplo:false - Email marketing messages opt-in
email_marketing_opt_inbooleanEjemplo:false - External system reference ID
external_reference_idstringEjemplo:EXT-12345 - External system reference URL
external_reference_urlstringEjemplo:https://external-system.com/contacts/12345 - Contact skills
skillsarray<string>Ejemplo:["spanish","english","sales"] custom_attributesarray<object>puede ser nullcustom_attributes[].field_namestringEjemplo:industrycustom_attributes[].valuestringEjemplo:Technology
Respuestas
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.
Parámetros de ruta
- The ID or external reference ID of the contact
idstringobligatorioEjemplo:64a1b2c3d4e5f678901234ab
Cuerpo de la petición · application/json
playbook_idstringobligatorioEjemplo:64a1b2c3d4e5f678901234cdflow_step_idstringEjemplo:64a1b2c3d4e5f678901234ef- Optional array of contact fields to update along with the playbook change
contact_required_fieldsarray<object>Ejemplo:[{"key":"custom_field_name","value":"custom_value"}] - Field name (can be a contact attribute or custom attribute)
contact_required_fields[].keystringobligatorioEjemplo:custom_field_name - Field value
contact_required_fields[].valuestringobligatorioEjemplo:custom_value
Respuestas
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.
Parámetros de ruta
- The ID or external reference ID of the contact
idstringobligatorioEjemplo:64a1b2c3d4e5f678901234ab
Cuerpo de la petición · application/json
assignee_idstringobligatorioEjemplo:64a1b2c3d4e5f678901234gh
Respuestas
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).
Parámetros de ruta
- The ID or external reference ID of the contact
idstringobligatorioEjemplo:64a1b2c3d4e5f678901234ab
Cuerpo de la petición · application/json
- The comment text
contentstringobligatorioEjemplo:Called the contact, left voicemail.
Respuestas
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"
}