Guides / Pipeline items API

Pipeline items API

Search and filter pipeline items, read open-task counts, edit custom fields, and work pipeline items in bulk through the Goliath developer API

About

Programmatic access to your pipeline item flow: fetch and search pipeline items, spot pipeline items going cold, and create, update, move, or archive pipeline items from your own code. Edit pipeline custom-field definitions, work pipeline items in bulk, and keep a pipeline item’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 pipeline items (`READ` scope)

operationId	What it does
`getPipelineItem`	Fetch one pipeline item by id — title, value, stage, pipeline, assigned users, linked contacts, linked pipeline items (`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 `listPipelineItemCustomFields` for definitions with no value.
`findPipelineItems`	Search pipeline items 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-pipeline item backlog. Archived pipeline items 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 `getPipelineItem`.
`surveyPipelineItems`	Read many pipeline items with the core filters of `findPipelineItems` (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 `listPipelineItemCustomFields`. Use `findPipelineItems` for money, linked contacts, dates, prices, or related ids; `getPipelineItem` for one pipeline item in full. Archived pipeline items are included unless `isArchived: false` is supplied.
`listStalledPipelineItems`	List pipeline items going cold (no activity for a while), ordered by days inactive, with the linked contact and `inactiveDays`.
`listPipelineItemFiles`	Files attached to a pipeline item, most-recent-first — `id`, `fileName`, `fileUrl`, `createdAt`. Capped at 25 per call, so page with `offset` when a page comes back full.
`listPipelineItemActivity`	Page a pipeline item’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.
`listPipelineItemComments`	Page a pipeline item’s comment events by `pipelineItemId`, newest first, with `offset` (cap 50). The SuperJSON payload holds the text at `json.body`; `actor` identifies the commenter.
`listPipelineItemCustomFields`	List a pipeline’s custom-field definitions by `pipelineId` — id, name, type (`TEXT` \| `NUMBER` \| `DOLLAR` \| `DATE` \| `LINK` \| `DROPDOWN`), options, `allowMultiple`, `defaultValue`. Pipeline item custom fields are per-pipeline. Use each id as the `customFieldId` in the `customFieldValues` input on `createPipelineItem` / `updatePipelineItem`.
`getPipelineLayout`	One pipeline’s field layout: each custom field’s display order, `showOnCard` / `cardDisplayOrder`, and `hiddenDetailFieldKeys` (`native:<key>` or `custom:<fieldId>`). The read behind `setPipelineItemCardFields` and `setPipelineItemDetailHiddenFields`.
`getPipelineDetailTabs`	One pipeline’s pipeline item-sheet tabs and their fields, with the layout `version` that `setPipelineDetailTabs` takes back.
`listStagesOfPipelines`	Every owned and shared pipeline and its stages, in order. Stage names repeat across pipelines: move a pipeline item only within its own pipeline.

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

Saved pipeline item 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 pipeline items.
`listPipelineItemFilters`	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 Pipeline items board has no saved-filter list.
`filterPipelineItems`	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 pipeline item filter does not fix its pipeline: supply the pipeline on every execution. Inline filterTree is not accepted by filterPipelineItems; 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 pipeline items (`WRITE` scope)

operationId	What it does
`createPipelineItem`	Create a pipeline item 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.
`updatePipelineItem`	Update a pipeline item — 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.
`archivePipelineItem`	Archive or restore a pipeline item (`isArchived` true/false).
`archivePipelineItems`	Archive many pipeline items of one `pipelineId` by id (restore one with `archivePipelineItem`). A background task: follow `bulkTaskId` with `getBulkTask`.
`bulkUpdatePipelineItems`	Apply one `updatePipelineItem` input (stage, close date, owners, contacts) to many `pipelineItemIds`. Every id must be a pipeline item your organization owns or shares, or the whole call is refused. A stage move wakes workflows. Large sets run as a background task (`bulkTaskId`).
`bulkCreatePipelineItemsOnContacts`	A new pipeline item per contact from one `pipelineItem` template (the bulk bar’s Add to pipeline). `propertyAttachmentMode: ALL` attaches each contact’s properties; `skipContactsWithPipelineItem` skips contacts that already have one; `autoNamePipelineItems` titles each from its contact and property. A background task (`bulkTaskId`); new pipeline items wake stage and contact workflows.
`deletePipelineItem`	Delete a pipeline item for good — prefer `archivePipelineItem` unless the person said delete. Org-owned pipelines only. `dependencyResolution` comes from `getDeletionImpact` (`targetKind: DEAL`). Returns `stageItWasOn`.
`addPipelineItemComment`	Add a comment to a pipeline item by `pipelineItemId` and non-empty `body` (up to 10,000 characters), attributed to the key owner.
`editPipelineItemComment`	Replace the body of your own pipeline item comment (`commentId` from `listPipelineItemComments`).
`deletePipelineItemComment`	Delete a pipeline item comment you wrote, for good.
`createPipelineItemCustomField`	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.
`updatePipelineItemCustomField`	Edit a definition on a pipeline you own, using `customFieldId` from `listPipelineItemCustomFields`. Optional `name`, `options`, and `defaultValue` leave omitted values untouched; the type cannot change. Returns the updated definition.
`attachPipelineItemFile`	Attach an existing org-owned chat artifact to a pipeline item by `artifactId`. Returns the linked file; raw-byte upload is not exposed.
`removePipelineItemFile`	Detach one file by `fileId` from `listPipelineItemFiles`. The stored bytes remain; an absent link is a no-op.
`addPipelineItemExternalLink`	Add a titled `url` to a pipeline item’s Links card (`getPipelineItem` `externalLinks`). To change one, remove it and add it again.
`removePipelineItemExternalLink`	Remove a pipeline item link by `linkId`.
`updatePipelineItemExternalLink`	Change a pipeline item link’s `title` or `url` in place; an omitted one is kept.
`linkPipelineItems`	Link two pipeline items on your organization’s own pipelines, with an optional `label`. Each then lists the other in `getPipelineItem` `linkedItems`. Both pipeline items are org-guarded.
`unlinkPipelineItems`	Remove a link between two pipeline items by the `linkId` from `getPipelineItem` `linkedItems`.

Pipeline item fields and layout (`WRITE` scope)

These change how a pipeline’s pipeline items 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
`addPipelineItemCustomFieldOption`	Append one option (`label`) to a `DROPDOWN` pipeline item field. Never removes an option; a label that already exists (in any case) is kept as it is.
`deletePipelineItemCustomField`	Permanently delete a pipeline item custom-field definition and every pipeline item’s value for it. Irreversible. Requires `pipelineId` and a `dependencyResolution` from `getDeletionImpact` (`targetKind: DEAL_CUSTOM_FIELD`).
`reorderPipelineItemCustomFields`	Set the display order of one pipeline’s custom fields. Pass every field id, in order. Presentation only. Org admins only.
`setPipelineItemCardFields`	Replace the up to five fields (custom or built-in, such as Pipeline item Value or Close Date) the pipeline’s board cards show, for everyone. Org admins only: a key created by a member is refused.
`setPipelineItemDetailHiddenFields`	Replace the set of fields hidden from the pipeline’s pipeline item sheet and create/edit form: `native:team`, `native:closeDate`, `native:dealValue`, `native:commission`, or `custom:<fieldId>`. Stage can never be hidden. Values are kept.
`setPipelineDetailTabs`	Replace one pipeline’s pipeline item-sheet tabs. Pass the `expectedVersion` you read from `getPipelineDetailTabs`; a stale version is refused.

Guarding against a concurrent edit

Pass expectedUpdatedAt — the updatedAt you got from getPipelineItem, findPipelineItems, or a previous write — to make the update conditional. The write applies only if the pipeline item 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.

A guarded update is all-or-nothing: userIds, participantSplits, and customFieldValues are part of the same transaction as the core pipeline item fields. A rejected value rolls back the whole edit, including title and stage changes. A successful write advances updatedAt, so re-read before using another concurrency guard.

Without expectedUpdatedAt, the core write commits before the custom fields: a later custom-field failure can leave the title or stage changed. A deleted pipeline item returns NOT_FOUND; an unparseable token returns BAD_USER_INPUT.

Pipeline operations

The Pipelines API covers the rest of the pipelineItems domain:

Read structure with listPipelineNames, listPipelines, and listPipelineStages (READ).
Create and edit it with createPipeline (returns the created pipeline with its stages in order), updatePipeline, addPipelineStages, updatePipelineStage, and reorderPipelineStages (WRITE).
Preview dependencies with getDeletionImpact (READ) before deletePipeline or deletePipelineStage (WRITE). Review the replacement options carefully: one permanently deletes the stage’s pipeline items.
Read reporting with getPipelineAnalytics and listPipelineTransitions (ADMIN, rate-limited).

Example

Move a pipeline item to another stage:

# 1. Find the stage id in the pipeline item'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 pipeline item
curl -X POST https://server.goliathdata.com/api/v1/call \
  -H "Authorization: Bearer gsk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "operationId": "updatePipelineItem", "variables": { "pipelineItemId": "PIPELINE_ITEM_ID", "input": { "stageId": "STAGE_ID" } } }'

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

Pipeline items API

About

Operations

Reading pipeline items (READ scope)

Saved pipeline item filters (READ scope)

Writing pipeline items (WRITE scope)

Pipeline item fields and layout (WRITE scope)