Deals
Track sales opportunities
Retrieves deals
/dealsReturns a paginated list of deals. Filter by contact, assignee, status, amount range, or creation/update/close date range.
Query params that are not supported filters for this endpoint are rejected with a 400 error.
Use order_by and sort to control result ordering (default: created_at desc).
To read a deal's custom attribute values, use GET /deals/{id}.
Parámetros de consulta
- Page number for pagination
pageintegerPor defecto:1Ejemplo:1 - Number of records per page
limitintegerPor defecto:25Ejemplo:25 - Field to order results by
order_bystringPor defecto:created_atEjemplo:created_at - Sort direction (asc or desc)
sortstringValores:ascdescPor defecto:desc - Filter deals by the ID of their contact
contact_idstringEjemplo:64a1b2c3d4e5f678901234ab - Filter deals by the ID of their assigned user
assignee_idstringEjemplo:64a1b2c3d5e5f678901234ab - Filter deals by status
statusstringValores:openwonlost - Filter deals by whether they are won
wonbooleanEjemplo:false - Filter deals by whether they are closed
closedbooleanEjemplo:false - Filter deals with an amount greater than or equal to this value
amount_minnumberEjemplo:1000 - Filter deals with an amount less than or equal to this value
amount_maxnumberEjemplo:5000 - Filter deals created at or after this date
created_at_fromstring (date-time)Ejemplo:2024-01-01T00:00:00Z - Filter deals created at or before this date
created_at_tostring (date-time)Ejemplo:2024-12-31T23:59:59Z - Filter deals updated at or after this date
updated_at_fromstring (date-time)Ejemplo:2024-01-01T00:00:00Z - Filter deals updated at or before this date
updated_at_tostring (date-time)Ejemplo:2024-12-31T23:59:59Z - Filter deals with a close date at or after this date
close_date_fromstring (date-time)Ejemplo:2024-01-01T00:00:00Z - Filter deals with a close date at or before this date
close_date_tostring (date-time)Ejemplo:2024-12-31T23:59:59Z
Respuestas
200deals found400unsupported filter param401unauthorized
curl -X GET 'https://api.vixiees.com/api/v1/deals' \
-H 'X-Api-Key: YOUR_API_KEY'{
"results": [
{
"id": "string",
"title": "string",
"description": "string",
"status": "open",
"won": true,
"closed": true,
"amount": 0,
"close_date": "2024-01-01T00:00:00Z",
"contact_id": "string",
"assignee_id": "string",
"closer_id": "string",
"external_reference_id": "string",
"closed_won_reason": "string",
"closed_lost_reason": "string",
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z"
}
],
"page_info": {
"current_page": 0,
"limit": 0
}
}Creates a new deal
/dealsCreates a new deal linked to a contact.
A deal tracks a sales opportunity with an optional amount and description.
contact_id accepts either the Vixiees contact ID or the contact's external_reference_id.
Use external_reference_id to link the deal to its record in an external system (e.g. your CRM).
It must be unique per account: creating a second deal with the same external_reference_id
returns a 422 error, and the deal can later be retrieved or updated using that value in place of its ID.
Cuerpo de la petición · application/json
titlestringEjemplo:Software License DealdescriptionstringEjemplo:Annual license renewal for 50 seatsamountnumberEjemplo:25000- Vixiees contact ID or the contact external_reference_id
contact_idstringobligatorioEjemplo:64a1b2c3d4e5f678901234ab assignee_idstringEjemplo:64a1b2c3d5e5f678901234ab- External system reference ID, unique per account
external_reference_idstringEjemplo:EXT-12345 - Custom attribute values. Each field_name must match a deal custom attribute defined in the account.
custom_attributesarray<object>puede ser null custom_attributes[].field_namestringEjemplo:industrycustom_attributes[].valuestringEjemplo:Technology
Respuestas
200deal created401unauthorized404contact not found422unprocessable entity
curl -X POST 'https://api.vixiees.com/api/v1/deals' \
-H 'X-Api-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"title": "Software License Deal",
"description": "Annual license renewal for 50 seats",
"amount": 25000,
"contact_id": "64a1b2c3d4e5f678901234ab",
"assignee_id": "64a1b2c3d5e5f678901234ab",
"external_reference_id": "EXT-12345",
"custom_attributes": [
{
"field_name": "industry",
"value": "Technology"
}
]
}'{
"id": "string"
}Retrieves a deal
/deals/{id}Returns a single deal with all fields, including its custom attributes.
You can use either the internal ID or the external_reference_id to retrieve the deal,
which makes this endpoint suitable for checking whether a deal from an external system already exists.
Parámetros de ruta
- The ID or external_reference_id of the deal to retrieve
idstringobligatorioEjemplo:64a1b2c3d4e5f678901234ab
Respuestas
200deal found401unauthorized404deal not found
curl -X GET 'https://api.vixiees.com/api/v1/deals/64a1b2c3d4e5f678901234ab' \
-H 'X-Api-Key: YOUR_API_KEY'{
"id": "string",
"title": "string",
"description": "string",
"status": "open",
"won": true,
"closed": true,
"amount": 0,
"close_date": "2024-01-01T00:00:00Z",
"contact_id": "string",
"assignee_id": "string",
"closer_id": "string",
"external_reference_id": "string",
"closed_won_reason": "string",
"closed_lost_reason": "string",
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z",
"custom_attributes": [
{
"id": "string",
"field_name": "industry",
"humanized_name": "Industry",
"field_type": "string",
"string_value": "Technology",
"integer_value": 0,
"float_value": 0,
"date_value": "2024-01-01T00:00:00Z",
"boolean_value": true,
"array_value": [
"string"
],
"editable": true,
"nullable": true
}
]
}Updates a deal
/deals/{id}Updates a deal's amount, status, close date, or other fields.
Only provided fields are modified; omitted fields remain unchanged.
You can use either the internal ID or the external_reference_id to identify the deal.
Parámetros de ruta
- The ID or external_reference_id of the deal to update
idstringobligatorioEjemplo:64a1b2c3d4e5f678901234ab
Cuerpo de la petición · application/json
titlestringEjemplo:Updated Deal TitledescriptionstringEjemplo:Annual license renewal for 50 seatsstatusstringValores:openwonlostamountnumberEjemplo:30000close_datestring (date-time)Ejemplo:2024-12-31T23:59:59Zassignee_idstringEjemplo:64a1b2c3d5e5f678901234ab- External system reference ID, unique per account
external_reference_idstringEjemplo:EXT-12345 - Custom attribute values. Each field_name must match a deal custom attribute defined in the account.
custom_attributesarray<object>puede ser null custom_attributes[].field_namestringEjemplo:industrycustom_attributes[].valuestringEjemplo:Technology
Respuestas
200deal updated401unauthorized404deal not found422unprocessable entity
curl -X PUT 'https://api.vixiees.com/api/v1/deals/64a1b2c3d4e5f678901234ab' \
-H 'X-Api-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"title": "Updated Deal Title",
"description": "Annual license renewal for 50 seats",
"status": "won",
"amount": 30000,
"close_date": "2024-12-31T23:59:59Z",
"assignee_id": "64a1b2c3d5e5f678901234ab",
"external_reference_id": "EXT-12345",
"custom_attributes": [
{
"field_name": "industry",
"value": "Technology"
}
]
}'{
"id": "string",
"title": "string",
"description": "string",
"status": "open",
"won": true,
"closed": true,
"amount": 0,
"close_date": "2024-01-01T00:00:00Z",
"contact_id": "string",
"assignee_id": "string",
"closer_id": "string",
"external_reference_id": "string",
"closed_won_reason": "string",
"closed_lost_reason": "string",
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z"
}Deletes a deal
/deals/{id}Deletes a deal. You can use either the internal ID or the external_reference_id to identify the deal.
Parámetros de ruta
- The ID or external_reference_id of the deal to delete
idstringobligatorio
Respuestas
200deal deleted401unauthorized404deal not found
curl -X DELETE 'https://api.vixiees.com/api/v1/deals/{id}' \
-H 'X-Api-Key: YOUR_API_KEY'{}