Documentation
Sign In

Deals

Manage your sales pipeline. Deals move through stages from lead to paid, and can drive invoicing via contract type and rates.

Required scopes:deals:readdeals:write

All endpoints require authentication with an API key via Authorization: Bearer anch_... — see Authentication. A :write scope implicitly includes its :read scope.

Quick example

curl "https://your-domain.com/api/deals?stage=proposal&sortBy=valueCents&sortOrder=desc" \
  -H "Authorization: Bearer anch_your_api_key"

Endpoints

GET/api/deals
POST/api/deals
GET/api/deals/{id}
PATCH/api/deals/{id}
DELETE/api/deals/{id}

GET/api/deals

Query parameters

FieldTypeDescription
searchstringFull-text search across deal titles
stagestringFilter by pipeline stage (see enumeration below)
companyIdstringFilter to deals for a specific company
ownerUserIdstringFilter to deals owned by a specific user
sortBystringtitle, valueCents, closeDate, or createdAt
sortOrderstringasc or desc
limitintegerPage size (default: 50)
offsetintegerPagination offset (default: 0)

Response (200)

{
  "data": [ { "id": "dl_...", "title": "Acme expansion", "stage": "proposal", ... } ],
  "meta": { "total": 17, "limit": 50, "offset": 0 }
}

POST/api/deals

Body fields

FieldTypeDescription
titlerequiredstringDeal title
valueCentsintegerDeal value in cents (default: 0)
currencystringISO currency code (default: USD)
stagestringPipeline stage (default: lead)
closeDateinteger | stringExpected close date — Unix ms or ISO string
ownerUserIdstringUser who owns the deal
companyIdstringAssociated company
contractTypestringfixed, hourly, milestone, or retainer
hourlyRateCentsintegerHourly rate in cents (for hourly contracts)
estimatedHoursnumberEstimated hours (for hourly contracts)

Response (201)

{ "id": "dl_V1StGXR8Z5jdHi6B" }

GET/api/deals/{id}

Response (200)

{
  "data": {
    "id": "dl_V1StGXR8Z5jdHi6B",
    "organizationId": "org_4f90...",
    "title": "Acme expansion",
    "valueCents": 2400000,
    "currency": "USD",
    "stage": "proposal",
    "closeDate": 1739577600000,
    "ownerUserId": "usr_...",
    "companyId": "cmp_...",
    "contractType": "hourly",
    "hourlyRateCents": 15000,
    "estimatedHours": 160,
    "createdAt": 1736899200000,
    "updatedAt": 1736899200000,
    "deletedAt": null
  }
}

PATCH/api/deals/{id}

PUT is also accepted. All fields are optional; only provided fields are updated.

Body fields

FieldTypeDescription
titlestringDeal title
valueCentsintegerDeal value in cents (default: 0)
currencystringISO currency code (default: USD)
stagestringPipeline stage (default: lead)
closeDateinteger | stringExpected close date — Unix ms or ISO string
ownerUserIdstringUser who owns the deal
companyIdstringAssociated company
contractTypestringfixed, hourly, milestone, or retainer
hourlyRateCentsintegerHourly rate in cents (for hourly contracts)
estimatedHoursnumberEstimated hours (for hourly contracts)

Response (200)

{ "ok": true }

DELETE/api/deals/{id}

Deals are soft-deleted and excluded from subsequent list and get requests.

Response (200)

{ "ok": true }

Enumerations

Pipeline stages

  • lead — New, unqualified opportunity
  • qualified — Qualified and actively worked
  • proposal — Proposal sent
  • won — Deal won, contract not yet active
  • contract_active — Work in progress
  • pending_invoice — Work complete, awaiting invoicing
  • paid_complete — Invoiced and paid
  • lost — Deal lost

Contract types

  • fixed
  • hourly
  • milestone
  • retainer

Notes

  • Monetary values are integers in cents.
  • GET/POST/DELETE /api/deals/{id}/recurring manages recurring invoice schedules for a deal.