Pipeline Deals API — Manage Sales Pipeline Deals

Pipeline deals represent opportunities moving through your sales process. Each deal is tied to a company and a pipeline stage, and can optionally link to a contact, site, and owner. Moving a deal to a closed-won or closed-lost stage automatically updates its status.

Required scope

All pipeline endpoints require the pipeline scope on your API key.

Deal statuses

Status	Meaning
`open`	Deal is active and in progress.
`won`	Deal was won. Set automatically when moved to a closed-won stage.
`lost`	Deal was lost. Set automatically when moved to a closed-lost stage.

List deals

GET /api/v1/pipeline/deals Returns a paginated list of deals for the authenticated tenant.

Query parameters

string

Filter by pipeline stage UUID.

string

Filter by deal status. One of: open, won, lost.

string

Filter by company UUID.

string

Filter by owner (user) UUID.

integer

default:"1"

1-based page index.

integer

default:"25"

Results per page. Maximum 100.

Response

{
  "data": [
    {
      "id": "c4a760a8-dbcf-5a0c-8b5d-48f8e2b18d09",
      "name": "Acme Corp — Enterprise Renewal",
      "value": "45000.00",
      "probability": 65,
      "expectedCloseDate": "2024-09-30",
      "actualCloseDate": null,
      "status": "open",
      "lostReason": null,
      "products": [],
      "notes": null,
      "createdAt": "2024-06-10T09:00:00Z",
      "company": {
        "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
        "name": "Acme Corp"
      },
      "contact": {
        "id": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
        "firstName": "Jane",
        "lastName": "Doe"
      },
      "stage": {
        "id": "b5a6f9e0-1234-4abc-9def-000000000001",
        "name": "Proposal Sent",
        "color": "#3B82F6",
        "probability": 65,
        "isClosedWon": false,
        "isClosedLost": false
      },
      "owner": {
        "id": "user-uuid-here",
        "name": "Sam Chen"
      }
    }
  ],
  "total": 38,
  "page": 1,
  "pageSize": 25
}

curl -X GET "https://app.novala.ai/api/v1/pipeline/deals?status=open" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'https://app.novala.ai/api/v1/pipeline/deals?status=open',
  { headers: { 'Authorization': `Bearer ${apiKey}` } }
);
const { data, total } = await response.json();

Create a deal

POST /api/v1/pipeline/deals Creates a new pipeline deal. The deal’s probability is inherited from the stage. Status is set to open at creation.

Request body

string

required

Deal name. Maximum 200 characters.

string

required

UUID of the company this deal is with. Must belong to your tenant.

string

required

UUID of the pipeline stage to place the deal in. Must belong to your tenant.

string

UUID of the primary contact for this deal.

string

UUID of the site associated with this deal.

string

UUID of the user who owns this deal. Defaults to the authenticated user when using session auth.

string

Expected deal value as a decimal string (for example, "45000.00").

string

Expected close date in YYYY-MM-DD format.

array

Array of product objects associated with the deal.

string

Internal notes about the deal.

object

Custom field key-value map.

Response

Returns 201 Created with { "data": { deal object } }. Returns 404 Not Found if companyId or stageId do not belong to your tenant.

curl -X POST https://app.novala.ai/api/v1/pipeline/deals \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp — Enterprise Renewal",
    "companyId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "stageId": "b5a6f9e0-1234-4abc-9def-000000000001",
    "value": "45000.00",
    "expectedCloseDate": "2024-09-30"
  }'

const response = await fetch('https://app.novala.ai/api/v1/pipeline/deals', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Acme Corp — Enterprise Renewal',
    companyId: 'd290f1ee-6c54-4b01-90e6-d701748f0851',
    stageId: 'b5a6f9e0-1234-4abc-9def-000000000001',
    value: '45000.00',
    expectedCloseDate: '2024-09-30',
  }),
});
const { data } = await response.json(); // 201 Created

Get a deal

GET /api/v1/pipeline/deals/{id} Retrieves a deal with its full detail: company, stage, contact, site, owner, and up to 20 recent activities.

Path parameters

string

required

UUID of the deal.

Response fields

object

Show Deal object

string

UUID of the deal.

string

Deal name.

string | null

Deal value as a decimal string.

integer

Close probability percentage (0–100), inherited from the stage.

string | null

Expected close date (YYYY-MM-DD).

string | null

Actual close date, set when the deal is won or lost.

string

One of open, won, lost.

string | null

Reason for losing the deal.

array

Products associated with the deal.

string | null

Internal notes.

object

Custom field key-value pairs.

object

Nested company with id, name, phone, and email.

object

Nested stage with id, name, color, probability, isClosedWon, isClosedLost.

object | null

Nested contact with id, firstName, lastName, email, phone, role.

object | null

Nested site with id, name, address, city, state.

object | null

Nested owner with id, name, email.

array

Up to 20 recent activities with id, type, description, activityDate, and a nested user.

string

ISO 8601 creation timestamp.

string

ISO 8601 last-updated timestamp.

Update a deal

PATCH /api/v1/pipeline/deals/{id} Partially updates a deal. Only include fields you want to change. Moving a deal to a closed-won or closed-lost stage automatically sets the status and actualCloseDate.

Path parameters

string

required

UUID of the deal.

Request body

All fields are optional.

string

Updated deal name.

string

UUID of the new stage. Probability updates automatically from the stage. If the stage is marked isClosedWon, status becomes won; if isClosedLost, status becomes lost.

string

Updated company UUID.

string | null

Updated contact UUID. Pass null to remove.

string | null

Updated site UUID. Pass null to remove.

string | null

Updated owner UUID. Pass null to unassign.

string | null

Updated deal value.

string | null

Updated expected close date (YYYY-MM-DD). Pass null to clear.

string | null

Updated internal notes.

object

Replaces all custom field values.

Response

Returns 200 OK with { "data": { updated deal } }.

curl -X PATCH https://app.novala.ai/api/v1/pipeline/deals/c4a760a8-dbcf-5a0c-8b5d-48f8e2b18d09 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "stageId": "b5a6f9e0-1234-4abc-9def-000000000002",
    "value": "52000.00"
  }'

const response = await fetch(
  'https://app.novala.ai/api/v1/pipeline/deals/c4a760a8-dbcf-5a0c-8b5d-48f8e2b18d09',
  {
    method: 'PATCH',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      stageId: 'b5a6f9e0-1234-4abc-9def-000000000002',
      value: '52000.00',
    }),
  }
);
const { data } = await response.json();

Overview

Endpoints

Pipeline Deals API — Manage Sales Pipeline Deals

Required scope

Deal statuses

List deals

Query parameters

Response

Create a deal

Request body

Response

Get a deal

Path parameters

Response fields

Update a deal

Path parameters

Request body

Response

​Required scope

​Deal statuses

​List deals

​Query parameters

​Response

​Create a deal

​Request body

​Response

​Get a deal

​Path parameters

​Response fields

​Update a deal

​Path parameters

​Request body

​Response

Required scope

Deal statuses

List deals

Query parameters

Response

Create a deal

Request body

Response

Get a deal

Path parameters

Response fields

Update a deal

Path parameters

Request body

Response