Deals API

Learn how to manage deals in AchieveApex using the REST API.

Overview

The Deals API allows you to manage sales deals within your organization. You can list, retrieve, create, update, and delete deals, as well as manage deal products.

Base Endpoint

/deals

Deal Object

The deal object contains information about a deal in your organization's sales pipeline.

Deal Object
{
  "id": 123,
  "name": "Enterprise Software Solution",
  "amount": "25000.00",
  "currency": "USD",
  "status": "open",
  "organization_id": 456,
  "pipeline_id": 789,
  "pipeline_stage_id": 101,
  "contact_id": 202,
  "company_id": 303,
  "created_by_user_id": 789,
  "owned_by_user_id": 789,
  "created_at": "2023-01-01T00:00:00.000Z",
  "updated_at": "2023-01-01T00:00:00.000Z",
  "deleted_at": null,
  "won_date": null,
  "lost_date": null,
  "expected_close_date": "2023-03-01T00:00:00.000Z",
  "pipelineStage": {
    "id": 101,
    "name": "Negotiation",
    "pipeline_id": 789
  },
  "pipeline": {
    "id": 789,
    "name": "Main Sales Pipeline"
  },
  "company": {
    "id": 303,
    "name": "Acme Corporation",
    "organization_id": 456,
    "created_by_user_id": 789,
    "owned_by_user_id": 789
  },
  "contact": {
    "id": 202,
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "1234567890",
    "phone_country_code": "+1",
    "company_id": 303,
    "avatar_url": "/path/to/avatar.jpg"
  },
  "owner": {
    "id": 789,
    "first_name": "Admin",
    "last_name": "User",
    "email": "admin@example.com"
  },
  "dealProducts": [
    {
      "id": 501,
      "quantity": "2",
      "price": "10000.00",
      "description": "Enterprise license",
      "discount_type": "percentage",
      "discount_amount": null,
      "discount_percentage": "10",
      "tax_percentage": "7",
      "total_amount_with_tax": "19260.00",
      "total_amount_without_tax": "18000.00",
      "product_id": 601,
      "name": "Software License",
      "sku": "SL-001"
    }
  ]
}

List Deals

Retrieve a list of deals for your organization with optional filtering and pagination.

Request
GET /deals

curl -X GET https://api.achieveapex.com/deals \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "organization_id": 456,
      "status": "open",
      "pipeline_id": 789,
      "$limit": 25,
      "$skip": 0,
      "$sort": { "created_at": -1 },
      "fastJoinForDealsList": true
    }
  }'
Response
{
  "total": 50,
  "limit": 25,
  "skip": 0,
  "data": [
    {
      "id": 123,
      "name": "Enterprise Software Solution",
      "amount": "25000.00",
      "currency": "USD",
      "status": "open",
      "organization_id": 456,
      "pipeline_id": 789,
      "pipeline_stage_id": 101,
      "contact_id": 202,
      "company_id": 303,
      "created_by_user_id": 789,
      "owned_by_user_id": 789,
      "created_at": "2023-01-01T00:00:00.000Z",
      "updated_at": "2023-01-01T00:00:00.000Z",
      "pipelineStage": {
        "id": 101,
        "name": "Negotiation"
      },
      "company": {
        "id": 303,
        "name": "Acme Corporation"
      },
      "contact": {
        "id": 202,
        "first_name": "John",
        "last_name": "Doe",
        "email": "john.doe@example.com"
      },
      "owner": {
        "id": 789,
        "first_name": "Admin",
        "last_name": "User"
      }
    },
    // Additional deals...
  ]
}

Query Parameters

ParameterTypeDescription
organization_idNumberID of the organization to fetch deals for (required)
statusStringFilter deals by status ('open', 'won', 'lost')
pipeline_idNumberFilter deals by pipeline ID
pipeline_stage_idNumberFilter deals by pipeline stage ID
$limitNumberNumber of deals to return (default: 10)
$skipNumberNumber of deals to skip (for pagination)
$sortObjectSort criteria (e.g., { "created_at": -1 } for newest first)
fastJoinForDealsListBooleanInclude associated data like company, contact, pipeline stage, and owner (recommended)

Get a Deal

Retrieve a single deal by ID.

Request
GET /deals/:id

curl -X GET https://api.achieveapex.com/deals/123 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "fastJoinForDealsList": true
    }
  }'
Response
{
  "id": 123,
  "name": "Enterprise Software Solution",
  "amount": "25000.00",
  "currency": "USD",
  "status": "open",
  "organization_id": 456,
  "pipeline_id": 789,
  "pipeline_stage_id": 101,
  "contact_id": 202,
  "company_id": 303,
  "created_by_user_id": 789,
  "owned_by_user_id": 789,
  "created_at": "2023-01-01T00:00:00.000Z",
  "updated_at": "2023-01-01T00:00:00.000Z",
  "deleted_at": null,
  "won_date": null,
  "lost_date": null,
  "expected_close_date": "2023-03-01T00:00:00.000Z",
  "pipelineStage": {
    "id": 101,
    "name": "Negotiation",
    "pipeline_id": 789
  },
  "pipeline": {
    "id": 789,
    "name": "Main Sales Pipeline"
  },
  "company": {
    "id": 303,
    "name": "Acme Corporation",
    "organization_id": 456,
    "created_by_user_id": 789,
    "owned_by_user_id": 789
  },
  "contact": {
    "id": 202,
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "1234567890",
    "phone_country_code": "+1",
    "company_id": 303,
    "avatar_url": "/path/to/avatar.jpg"
  },
  "owner": {
    "id": 789,
    "first_name": "Admin",
    "last_name": "User",
    "email": "admin@example.com"
  },
  "dealProducts": [
    {
      "id": 501,
      "quantity": "2",
      "price": "10000.00",
      "description": "Enterprise license",
      "discount_type": "percentage",
      "discount_amount": null,
      "discount_percentage": "10",
      "tax_percentage": "7",
      "total_amount_with_tax": "19260.00",
      "total_amount_without_tax": "18000.00",
      "product_id": 601,
      "name": "Software License",
      "sku": "SL-001"
    }
  ]
}

Create a Deal

Create a new deal in your organization.

Request
POST /deals

curl -X POST https://api.achieveapex.com/deals \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "name": "New Software Implementation",
    "amount": 15000,
    "currency": "USD",
    "status": "open",
    "pipeline_id": 789,
    "pipeline_stage_id": 100,
    "contact_id": 202,
    "company_id": 303,
    "owned_by_user_id": 789,
    "expected_close_date": "2023-04-15T00:00:00.000Z"
  }'
Response
{
  "id": 124,
  "name": "New Software Implementation",
  "amount": "15000.00",
  "currency": "USD",
  "status": "open",
  "organization_id": 456,
  "pipeline_id": 789,
  "pipeline_stage_id": 100,
  "contact_id": 202,
  "company_id": 303,
  "created_by_user_id": 789,
  "owned_by_user_id": 789,
  "created_at": "2023-01-02T00:00:00.000Z",
  "updated_at": "2023-01-02T00:00:00.000Z",
  "deleted_at": null,
  "won_date": null,
  "lost_date": null,
  "expected_close_date": "2023-04-15T00:00:00.000Z"
}

Request Parameters

ParameterTypeRequiredDescription
organization_idNumberYesID of the organization to create the deal in
nameStringYesName of the deal
amountNumberYesThe monetary value of the deal
currencyStringYesThe currency code (e.g., "USD", "EUR")
statusStringYesDeal status ('open', 'won', 'lost')
pipeline_idNumberYesID of the pipeline this deal belongs to
pipeline_stage_idNumberYesID of the pipeline stage this deal is currently in
contact_idNumberNoID of the contact associated with this deal
company_idNumberNoID of the company associated with this deal
owned_by_user_idNumberNoID of the user who owns this deal (defaults to creator)
expected_close_dateStringNoExpected date of deal closure (ISO 8601 format)

Update a Deal

Update an existing deal's information.

Request
PATCH /deals/:id

curl -X PATCH https://api.achieveapex.com/deals/123 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Enterprise Software Solution - Extended",
    "amount": 30000,
    "owned_by_user_id": 790,
    "status": "won",
    "pipeline_stage_id": 102
  }'
Response
{
  "id": 123,
  "name": "Enterprise Software Solution - Extended",
  "amount": "30000.00",
  "currency": "USD",
  "status": "won",
  "organization_id": 456,
  "pipeline_id": 789,
  "pipeline_stage_id": 102,
  "contact_id": 202,
  "company_id": 303,
  "created_by_user_id": 789,
  "owned_by_user_id": 790,
  "created_at": "2023-01-01T00:00:00.000Z",
  "updated_at": "2023-01-03T00:00:00.000Z",
  "deleted_at": null,
  "won_date": "2023-01-03T00:00:00.000Z",
  "lost_date": null,
  "expected_close_date": "2023-03-01T00:00:00.000Z"
}

Delete a Deal

Mark a deal as deleted (soft delete).

Request
DELETE /deals/:id

curl -X DELETE https://api.achieveapex.com/deals/123 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"
Response
{
  "id": 123,
  "name": "Enterprise Software Solution - Extended",
  "amount": "30000.00",
  "currency": "USD",
  "status": "won",
  "organization_id": 456,
  "pipeline_id": 789,
  "pipeline_stage_id": 102,
  "contact_id": 202,
  "company_id": 303,
  "created_by_user_id": 789,
  "owned_by_user_id": 790,
  "created_at": "2023-01-01T00:00:00.000Z",
  "updated_at": "2023-01-03T12:00:00.000Z",
  "deleted_at": "2023-01-03T12:00:00.000Z",
  "won_date": "2023-01-03T00:00:00.000Z",
  "lost_date": null,
  "expected_close_date": "2023-03-01T00:00:00.000Z"
}

Deal Products

Manage products associated with a deal.

Deal Product Object

Deal Product Object
{
  "id": 501,
  "quantity": "2",
  "price": "10000.00",
  "description": "Enterprise license",
  "discount_type": "percentage",
  "discount_amount": null,
  "discount_percentage": "10",
  "tax_percentage": "7",
  "total_amount_with_tax": "19260.00",
  "total_amount_without_tax": "18000.00",
  "product_id": 601,
  "deal_id": 123,
  "organization_id": 456,
  "name": "Software License",
  "sku": "SL-001",
  "created_at": "2023-01-01T00:00:00.000Z",
  "updated_at": "2023-01-01T00:00:00.000Z",
  "deleted_at": null
}

Add a Product to a Deal

Request
POST /deal-products

curl -X POST https://api.achieveapex.com/deal-products \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "deal_id": 123,
    "organization_id": 456,
    "product_id": 601,
    "quantity": 2,
    "price": 10000,
    "description": "Enterprise license",
    "discount_type": "percentage",
    "discount_percentage": 10,
    "tax_percentage": 7
  }'

Update a Deal Product

Request
PATCH /deal-products/:id

curl -X PATCH https://api.achieveapex.com/deal-products/501 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "quantity": 3,
    "discount_type": "fixed",
    "discount_amount": 5000,
    "discount_percentage": null
  }'

Remove a Product from a Deal

Request
DELETE /deal-products/:id

curl -X DELETE https://api.achieveapex.com/deal-products/501 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"

Error Handling

The Deals API returns standard HTTP status codes and error messages.

Error Response
{
  "name": "NotFound",
  "message": "No record found for id '999'",
  "code": 404,
  "className": "not-found"
}
Status CodeDescription
400 Bad RequestInvalid parameters or request
401 UnauthorizedMissing or invalid authentication
403 ForbiddenNot authorized to access this organization's deals
404 Not FoundDeal not found
500 Internal Server ErrorServer error

Related Documentation

For information on managing companies and contacts associated with deals, see the Companies API and Contacts API documentation.

Report an issue with this documentation

Please log in to report issues with our documentation.