Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers.novala.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

StatusMeaning
openDeal is active and in progress.
wonDeal was won. Set automatically when moved to a closed-won stage.
lostDeal 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

​
stageId
string
Filter by pipeline stage UUID.
​
status
string
Filter by deal status. One of: open, won, lost.
​
companyId
string
Filter by company UUID.
​
ownerId
string
Filter by owner (user) UUID.
​
page
integer
default:"1"
1-based page index.
​
limit
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"

​
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

​
name
string
required
Deal name. Maximum 200 characters.
​
companyId
string
required
UUID of the company this deal is with. Must belong to your tenant.
​
stageId
string
required
UUID of the pipeline stage to place the deal in. Must belong to your tenant.
​
contactId
string
UUID of the primary contact for this deal.
​
siteId
string
UUID of the site associated with this deal.
​
ownerId
string
UUID of the user who owns this deal. Defaults to the authenticated user when using session auth.
​
value
string
Expected deal value as a decimal string (for example, "45000.00").
​
expectedCloseDate
string
Expected close date in YYYY-MM-DD format.
​
products
array
Array of product objects associated with the deal.
​
notes
string
Internal notes about the deal.
​
customFields
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"
  }'

​
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

​
id
string
required
UUID of the deal.

​
Response fields

​
data
object

​
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

​
id
string
required
UUID of the deal.

​
Request body

All fields are optional.
​
name
string
Updated deal name.
​
stageId
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.
​
companyId
string
Updated company UUID.
​
contactId
string | null
Updated contact UUID. Pass null to remove.
​
siteId
string | null
Updated site UUID. Pass null to remove.
​
ownerId
string | null
Updated owner UUID. Pass null to unassign.
​
value
string | null
Updated deal value.
​
expectedCloseDate
string | null
Updated expected close date (YYYY-MM-DD). Pass null to clear.
​
notes
string | null
Updated internal notes.
​
customFields
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"
  }'