Deals

Track sales opportunities

Retrieves deals

get/deals

Returns 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}.

Query parameters

  • pageinteger
    Page number for pagination
    Default: 1Example: 1
  • limitinteger
    Number of records per page
    Default: 25Example: 25
  • order_bystring
    Field to order results by
    Default: created_atExample: created_at
  • sortstring
    Sort direction (asc or desc)
    Values:ascdescDefault: desc
  • contact_idstring
    Filter deals by the ID of their contact
    Example: 64a1b2c3d4e5f678901234ab
  • assignee_idstring
    Filter deals by the ID of their assigned user
    Example: 64a1b2c3d5e5f678901234ab
  • statusstring
    Filter deals by status
    Values:openwonlost
  • wonboolean
    Filter deals by whether they are won
    Example: false
  • closedboolean
    Filter deals by whether they are closed
    Example: false
  • amount_minnumber
    Filter deals with an amount greater than or equal to this value
    Example: 1000
  • amount_maxnumber
    Filter deals with an amount less than or equal to this value
    Example: 5000
  • created_at_fromstring (date-time)
    Filter deals created at or after this date
    Example: 2024-01-01T00:00:00Z
  • created_at_tostring (date-time)
    Filter deals created at or before this date
    Example: 2024-12-31T23:59:59Z
  • updated_at_fromstring (date-time)
    Filter deals updated at or after this date
    Example: 2024-01-01T00:00:00Z
  • updated_at_tostring (date-time)
    Filter deals updated at or before this date
    Example: 2024-12-31T23:59:59Z
  • close_date_fromstring (date-time)
    Filter deals with a close date at or after this date
    Example: 2024-01-01T00:00:00Z
  • close_date_tostring (date-time)
    Filter deals with a close date at or before this date
    Example: 2024-12-31T23:59:59Z

Responses

  • 200deals found
  • 400unsupported filter param
  • 401unauthorized
Request
curl -X GET 'https://api.vixiees.com/api/v1/deals' \
  -H 'X-Api-Key: YOUR_API_KEY'
Example response 路 200
{
  "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

post/deals

Creates 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.

Request body 路 application/json

  • titlestring
    Example: Software License Deal
  • descriptionstring
    Example: Annual license renewal for 50 seats
  • amountnumber
    Example: 25000
  • contact_idstringrequired
    Vixiees contact ID or the contact external_reference_id
    Example: 64a1b2c3d4e5f678901234ab
  • assignee_idstring
    Example: 64a1b2c3d5e5f678901234ab
  • external_reference_idstring
    External system reference ID, unique per account
    Example: EXT-12345
  • custom_attributesarray<object>nullable
    Custom attribute values. Each field_name must match a deal custom attribute defined in the account.
  • custom_attributes[].field_namestring
    Example: industry
  • custom_attributes[].valuestring
    Example: Technology

Responses

  • 200deal created
  • 401unauthorized
  • 404contact not found
  • 422unprocessable entity
Request
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"
    }
  ]
}'
Example response 路 200
{
  "id": "string"
}

Retrieves a deal

get/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.

Path parameters

  • idstringrequired
    The ID or external_reference_id of the deal to retrieve
    Example: 64a1b2c3d4e5f678901234ab

Responses

  • 200deal found
  • 401unauthorized
  • 404deal not found
Request
curl -X GET 'https://api.vixiees.com/api/v1/deals/64a1b2c3d4e5f678901234ab' \
  -H 'X-Api-Key: YOUR_API_KEY'
Example response 路 200
{
  "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

put/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.

Path parameters

  • idstringrequired
    The ID or external_reference_id of the deal to update
    Example: 64a1b2c3d4e5f678901234ab

Request body 路 application/json

  • titlestring
    Example: Updated Deal Title
  • descriptionstring
    Example: Annual license renewal for 50 seats
  • statusstring
    Values:openwonlost
  • amountnumber
    Example: 30000
  • close_datestring (date-time)
    Example: 2024-12-31T23:59:59Z
  • assignee_idstring
    Example: 64a1b2c3d5e5f678901234ab
  • external_reference_idstring
    External system reference ID, unique per account
    Example: EXT-12345
  • custom_attributesarray<object>nullable
    Custom attribute values. Each field_name must match a deal custom attribute defined in the account.
  • custom_attributes[].field_namestring
    Example: industry
  • custom_attributes[].valuestring
    Example: Technology

Responses

  • 200deal updated
  • 401unauthorized
  • 404deal not found
  • 422unprocessable entity
Request
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"
    }
  ]
}'
Example response 路 200
{
  "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

DEL/deals/{id}

Deletes a deal. You can use either the internal ID or the external_reference_id to identify the deal.

Path parameters

  • idstringrequired
    The ID or external_reference_id of the deal to delete

Responses

  • 200deal deleted
  • 401unauthorized
  • 404deal not found
Request
curl -X DELETE 'https://api.vixiees.com/api/v1/deals/{id}' \
  -H 'X-Api-Key: YOUR_API_KEY'
Example response 路 200
{}