Skip to main content
POST
Move a pipeline record to another stage

Authorizations

x-api-key
string
header
required

Copy the API key as provided by the Bridge Console.

Headers

Idempotency-Key
string
required

A key you choose per change, such as your system's operation id. Send the same key when you retry the request: for 24 hours it answers with the record the first request changed.

Required string length: 1 - 255
Example:

"erp-opp-981-won"

Path Parameters

workspaceId
string<uuid>
required

Unique identifier of the workspace (UUID v4).

Example:

"b6cf1c4a-2b1e-4e63-8f3e-0f9d1a2a1234"

recordId
string
required

Unique identifier of the pipeline record.

Required string length: 1 - 255
Example:

"0d3c7f0e-5a43-5c0e-9f53-1f6a4b2e7d11"

Body

application/json

Request body to move a pipeline record to another stage of its pipeline.

stageId
string
required

Stage to move the record to, of the pipeline version the record follows. A final stage closes the record. The requirements of the stage apply, such as a complete contact.

Required string length: 1 - 255
Example:

"stage-won"

expectedRevision
integer | null

The record's revision you last read. When it is no longer the current one, the change fails with 409 BRIDGE_PIPELINE_0101 and the current record in extra.currentRecord. Without it, the change applies to the record as the request reads it, so another change made at the same moment can still fail it with that 409.

Required range: x >= 1
Example:

3

reasonId
string | null

Active close reason of the pipeline, as listed by GET /pipelines/{pipelineId}. Only for a move to a final stage, and optional there.

Maximum string length: 255
Example:

"reason-price"

reasonNote
string | null

Free text that explains the close reason, up to 500 characters. Requires reasonId.

Example:

"Chose a cheaper provider"

Response

The record as it is after the change, or after a previous request with the same key.

A record of a pipeline, such as a sales opportunity of a contact.

id
string
required

Unique identifier of the record.

Example:

"0d3c7f0e-5a43-5c0e-9f53-1f6a4b2e7d11"

pipelineId
string
required

Pipeline the record belongs to.

Example:

"5d0b8f8e-3c1a-4a4e-9a57-2f6f3e1c9b10"

pipelineVersion
integer
required

Version of the pipeline the record follows.

Example:

3

stageId
string
required

Stage the record is in.

Example:

"stage-new"

state
enum<string>
required

OPEN while the record is in an open stage, FINAL once it is in a final stage.

Available options:
OPEN,
FINAL
Example:

"OPEN"

name
string
required

Name of the record.

Example:

"Acme renewal 2027"

contact
Contact · object
required

The contact the record belongs to.

source
enum<string>
required

How the record was created: API, ADVISOR, INBOUND_SESSION or FROM_PIPELINE.

Available options:
ADVISOR,
API,
INBOUND_SESSION,
FROM_PIPELINE
Example:

"API"

revision
integer
required

Goes up by one every time the record changes.

Example:

1

createdAt
string
required

When the record was created.

Example:

"2026-11-11T15:00:00.000Z"

updatedAt
string
required

When the record last changed.

Example:

"2026-11-11T15:00:00.000Z"

values
Values · object

Values of the record's attributes, keyed by attribute id.

Example:
ownerId
string | null

Id of the Bridge User who owns the record. Resolve it with GET /users/{userId}.

Example:

null

externalId
string | null

Your system's id for the record, when it was created with one.

Example:

"ERP-OPP-981"

closeReason
RecordCloseReasonResponse · object | null

The reason a closed record was closed with.

closedAt
string | null

When the record reached a final stage; null while it is open.

Example:

null