GoliathDevelopersGet an API key
Guides / Deals API

Deals API

Search and filter deals, read open-task counts, edit custom fields, and work deals in bulk through the Goliath developer 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. Edit pipeline custom-field definitions, work deals in bulk, and keep a deal’s comments and links. 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, linked deals (linkedItems), derived commission/GCI, team and participant splits, and recorded custom-field values. Money is in cents; priceFormatted and commissionFormatted carry the price and GCI as dollars. Use listDealCustomFields for definitions with no value.
findDeals Search deals org-wide — optional titleContains, contactId or contactIds, pipelineId, stageId, stageName, isArchived, hasAssignedUsers, and userIds filters, plus outcome, stageChangedAfter/stageChangedBefore and closeDateAfter/closeDateBefore windows. stageId reads one pipeline column; hasAssignedUsers: false gets the unowned-deal backlog. Archived deals are included unless you pass isArchived: false. limit defaults to 20. Returns a capped page plus the unpaged total, with assigned users, contacts, createdAt, updatedAt, priceFormatted beside priceCents, commission figures, and recorded custom-field values (value plus field name). If a page comes back truncated, lower limit. Participant splits still require getDeal.
surveyDeals Read many deals with the core filters of findDeals (including contactIds) and a leaner row: id, title, isArchived, stage name, pipeline name, assigned users by name, taskSummary, and recorded custom-field values. limit defaults to 16 and is capped at 45. Get stage ids from listPipelineStages, user ids from listTeammates, and custom-field ids/types from listDealCustomFields. Use findDeals for money, linked contacts, dates, prices, or related ids; getDeal for one deal in full. Archived deals are included unless isArchived: false is supplied.
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, SCRAPER_HEALTH_MOVED reasoning, and CONTRACT_EVENT signing lifecycle events; title, description, and custom-field edits are not recorded.
listDealComments Page a deal’s comment events by dealId, newest first, with offset (cap 50). The SuperJSON payload holds the text at json.body; actor identifies the commenter.
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.
getDealPipelineLayout One pipeline’s field layout: each custom field’s display order, showOnCard / cardDisplayOrder, and hiddenDetailFieldKeys (native:<key> or custom:<fieldId>). The read behind setDealCardFields and setDealDetailHiddenFields.
getDealDetailTabs One pipeline’s deal-sheet tabs and their fields, with the layout version that setDealDetailTabs takes back.
listStagesOfPipelines Every owned and shared pipeline and its stages, in order. Stage names repeat across pipelines: move a deal only within its own pipeline.

Both findDeals and surveyDeals return taskSummary.openTaskCount and taskSummary.openAppointmentCount. These count open items linked to the deal, not every task on its contacts. An openTaskCount of zero identifies a deal with no open task without reading its whole activity feed.

Saved deal filters (READ scope)

operationId What it does
listPipelineNames Read only id and name for the organization’s own pipelines, oldest first. Use this to pick a pipeline without aggregating its deals.
listDealFilters List shared organization DEAL filters plus the key owner’s private ones, with owner userId and metadata. Read criteria with getFilter; create with saveFilter(type: DEAL) and edit with updateFilter. The app’s Deals board has no saved-filter list.
filterDeals Run a saved filterId over one pipelineId. Page with limit (default 25, max 50) and offset; returns items with id, title, archive state, stage and assignees, plus pagination.total and pagination.hasMore.

A saved deal filter does not fix its pipeline: supply the pipeline on every execution. Inline filterTree is not accepted by filterDeals; save the criteria first. Discover DEAL fields with listFilterFieldNames and listFilterFields, and manage filter folders through the Properties API. Check the owner’s userId before editing or deleting a shared filter.

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).
archiveDeals Archive many deals of one pipelineId by id (restore one with archiveDeal). A background task: follow bulkTaskId with getBulkTask.
bulkUpdateDeals Apply one updateDeal input (stage, close date, owners, contacts) to many dealIds. Every id must be a deal your organization owns or shares, or the whole call is refused. A stage move wakes workflows. Large sets run as a background task (bulkTaskId).
bulkCreateDealsOnContacts A new deal per contact from one deal template (the bulk bar’s Add to pipeline). propertyAttachmentMode: ALL attaches each contact’s properties; skipContactsWithDeal skips contacts that already have one; autoNameDeals titles each from its contact and property. A background task (bulkTaskId); new deals wake stage and contact workflows.
deleteDeal Delete a deal for good — prefer archiveDeal unless the person said delete. Org-owned pipelines only. dependencyResolution comes from getDeletionImpact (targetKind: DEAL). Returns stageItWasOn.
addDealComment Add a comment to a deal by dealId and non-empty body (up to 10,000 characters), attributed to the key owner.
editDealComment Replace the body of your own deal comment (commentId from listDealComments).
deleteDealComment Delete a deal comment you wrote, for good.
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.
updateDealCustomField Edit a definition on a pipeline you own, using customFieldId from listDealCustomFields. Optional name, options, and defaultValue leave omitted values untouched; the type cannot change. Returns the updated definition.
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.
addDealExternalLink Add a titled url to a deal’s Links card (getDeal externalLinks). To change one, remove it and add it again.
removeDealExternalLink Remove a deal link by linkId.
updateDealExternalLink Change a deal link’s title or url in place; an omitted one is kept.
linkPipelineItems Link two deals on your organization’s own pipelines, with an optional label. Each then lists the other in getDeal linkedItems. Both deals are org-guarded.
unlinkPipelineItems Remove a link between two deals by the linkId from getDeal linkedItems.

Deal fields and layout (WRITE scope)

These change how a pipeline’s deals are presented and which custom fields exist. All of them require a pipeline your organization owns; a shared pipeline is refused.

operationId What it does
addDealCustomFieldOption Append one option (label) to a DROPDOWN deal field. Never removes an option; a label that already exists (in any case) is kept as it is.
deleteDealCustomField Permanently delete a deal custom-field definition and every deal’s value for it. Irreversible. Requires pipelineId and a dependencyResolution from getDeletionImpact (targetKind: DEAL_CUSTOM_FIELD).
reorderDealCustomFields Set the display order of one pipeline’s custom fields. Pass every field id, in order. Presentation only.
setDealCardFields Replace the up to five fields (custom or built-in, such as Deal Value or Close Date) the pipeline’s board cards show, for everyone. Org admins only: a key created by a member is refused.
setDealDetailHiddenFields Replace the set of fields hidden from the pipeline’s deal sheet and create/edit form: native:team, native:closeDate, native:dealValue, native:commission, or custom:<fieldId>. Stage can never be hidden. Values are kept.
setDealDetailTabs Replace one pipeline’s deal-sheet tabs. Pass the expectedVersion you read from getDealDetailTabs; a stale version is refused.

Pipeline operations

The Pipelines API covers the rest of the deals domain:

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.