Deals API

About

Programmatic access to your deal flow: fetch and search deals, spot deals going cold, and create, update, move, or archive deals from your own code. Pipeline structure (creating pipelines, editing stages) and pipeline analytics have their own page — see the Pipelines API. All operations go through the developer API gateway — one endpoint, called by operationId. If you haven’t set up a key yet, start with the Developer API Overview.

Operations

Reading deals (`READ` scope)

operationId	What it does
`getDeal`	Fetch one deal by id — title, value, stage, pipeline, assigned users, linked contacts, derived commission/GCI, team and participant splits, and recorded custom-field values. Use `listDealCustomFields` for definitions with no value.
`findDeals`	Search deals org-wide — optional `titleContains`, `contactId`, `pipelineId`, `stageId`, `isArchived`, `hasAssignedUsers`, and `userIds` filters. `stageId` reads one pipeline column in a single request; `hasAssignedUsers: false` gets the unowned-deal backlog. Returns a capped page plus the unpaged total, with each deal’s assigned users, contacts, and commission figures. Participant splits and custom fields require `getDeal`.
`listStalledDeals`	List deals going cold (no activity for a while), ordered by days inactive, with the linked contact and `inactiveDays`.
`listDealFiles`	Files attached to a deal, most-recent-first — `id`, `fileName`, `fileUrl`, `createdAt`. Capped at 25 per call, so page with `offset` when a page comes back full.
`listDealActivity`	Page a deal’s audit trail, optionally narrowed by `eventTypes` before paging. Covers stage/value/commission/split/assignment/contact/task/file/archive/comment events; title, description, and custom-field edits are not recorded.
`listDealCustomFields`	List a pipeline’s custom-field definitions by `pipelineId` — id, name, type (`TEXT` \| `NUMBER` \| `DOLLAR` \| `DATE` \| `LINK` \| `DROPDOWN`), options, `allowMultiple`, `defaultValue`. Deal custom fields are per-pipeline. Use each id as the `customFieldId` in the `customFieldValues` input on `createDeal` / `updateDeal`.

findDeals and listStalledDeals are paginatedBoth return up to 50 rows per call (a larger limit is clamped) but take an offset and return totalCount + hasMore, so you can page through the full set: send offset: 0, then offset: 50, and so on until hasMore is false. See Result limits & truncation.

Writing deals (`WRITE` scope)

operationId	What it does
`createDeal`	Create a deal in a stage (`title` + `stageId` required; optional price, close date, links, commission/team/participant splits, and per-pipeline custom-field values). Get stage ids from `listPipelineStages`. The response echoes money and custom fields for read-back.
`updateDeal`	Update a deal — title, price, close date, stage, linked sets, commission/team/participant splits, and custom-field values. Optionally pass `expectedUpdatedAt` as an optimistic-concurrency guard. The response echoes the stored money and custom fields.
`archiveDeal`	Archive or restore a deal (`isArchived` true/false).
`createDealCustomField`	Create a custom-field definition on a pipeline you own: `name` + `type`; `options` required and non-empty for `DROPDOWN`, `allowMultiple`/`defaultValue` optional. A shared pipeline cannot be modified. Applied synchronously; returns the pipeline’s field set, so read the new id back by matching the name.
`attachDealFile`	Attach an existing org-owned chat artifact to a deal by `artifactId`. Returns the linked file; raw-byte upload is not exposed.
`removeDealFile`	Detach one file by `fileId` from `listDealFiles`. The stored bytes remain; an absent link is a no-op.

Deal money fieldsCommission and team split each accept one source: a fixed *AmountCents or a *PercentBps, never both. commissionCents is the server-derived GCI to report. Participant splits allocate what remains after the team fee. For deal custom fields, use the value member that matches the definition type; DOLLAR values are plain numbers, not cents, and dropdown values are option labels.

updateDeal replaces linked setsOn updateDeal, the contactIds, propertyIds, and userIds arrays replace the deal’s linked set — they do not append. To add one contact, send the full existing list plus the new id.

Guarding against a concurrent editPass expectedUpdatedAt — the updatedAt you got from getDeal, findDeals, or a previous write — to make the update conditional. The write applies only if the deal hasn’t changed since; otherwise nothing is written and you get CONFLICT. Use it whenever you decided what to write from a copy you read earlier, so a concurrent edit fails loudly instead of being silently overwritten.

Deal file URLs are short-livedfileUrl from listDealFiles or attachDealFile is a time-limited signed HTTPS URL. Fetch it promptly, and don’t persist or share it — re-read listDealFiles rather than caching the URL. attachDealFile accepts an existing artifact id; it is not a raw-byte upload endpoint.

Organization guardDeal operations are org-guarded: the deal (and any destination stage) must belong to a pipeline owned by or shared with your organization, or the call returns 403 forbidden. Pipelines shared with your org through a partnership work normally. See Authorization for the full owned-vs-shared model.

Example

Move a deal to another stage:

# 1. Find the stage id in the deal's pipeline
curl -X POST https://server.goliathdata.com/api/v1/call \
  -H "Authorization: Bearer gsk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "operationId": "listPipelineStages", "variables": { "pipelineId": "PIPELINE_ID" } }'

# 2. Move the deal
curl -X POST https://server.goliathdata.com/api/v1/call \
  -H "Authorization: Bearer gsk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "operationId": "updateDeal", "variables": { "dealId": "DEAL_ID", "input": { "stageId": "STAGE_ID" } } }'

Full variable schemas, response shapes, and worked examples for every operation are available from the discovery endpoint.

Getting Started

TypeScript SDK

Core Resources

Automations

Communication & Tasks

Account & Billing

About

Operations

Reading deals (`READ` scope)

Writing deals (`WRITE` scope)

Example

​About

​Operations

​Reading deals (READ scope)

​Writing deals (WRITE scope)

​Example

About

Operations

Reading deals (`READ` scope)

Writing deals (`WRITE` scope)

Example