curl --request POST \
--url https://api-connect-us.bridge.new/bridge/api/v1/workspaces/{workspaceId}/records/{recordId}/move \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--header 'x-api-key: <api-key>' \
--data '
{
"stageId": "stage-won",
"expectedRevision": 3,
"reasonId": "reason-price",
"reasonNote": "Chose a cheaper provider"
}
'import requests
url = "https://api-connect-us.bridge.new/bridge/api/v1/workspaces/{workspaceId}/records/{recordId}/move"
payload = {
"stageId": "stage-won",
"expectedRevision": 3,
"reasonId": "reason-price",
"reasonNote": "Chose a cheaper provider"
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
'x-api-key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
stageId: 'stage-won',
expectedRevision: 3,
reasonId: 'reason-price',
reasonNote: 'Chose a cheaper provider'
})
};
fetch('https://api-connect-us.bridge.new/bridge/api/v1/workspaces/{workspaceId}/records/{recordId}/move', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-connect-us.bridge.new/bridge/api/v1/workspaces/{workspaceId}/records/{recordId}/move",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'stageId' => 'stage-won',
'expectedRevision' => 3,
'reasonId' => 'reason-price',
'reasonNote' => 'Chose a cheaper provider'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api-connect-us.bridge.new/bridge/api/v1/workspaces/{workspaceId}/records/{recordId}/move"
payload := strings.NewReader("{\n \"stageId\": \"stage-won\",\n \"expectedRevision\": 3,\n \"reasonId\": \"reason-price\",\n \"reasonNote\": \"Chose a cheaper provider\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api-connect-us.bridge.new/bridge/api/v1/workspaces/{workspaceId}/records/{recordId}/move")
.header("Idempotency-Key", "<idempotency-key>")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"stageId\": \"stage-won\",\n \"expectedRevision\": 3,\n \"reasonId\": \"reason-price\",\n \"reasonNote\": \"Chose a cheaper provider\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-connect-us.bridge.new/bridge/api/v1/workspaces/{workspaceId}/records/{recordId}/move")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"stageId\": \"stage-won\",\n \"expectedRevision\": 3,\n \"reasonId\": \"reason-price\",\n \"reasonNote\": \"Chose a cheaper provider\"\n}"
response = http.request(request)
puts response.read_body{
"id": "0d3c7f0e-5a43-5c0e-9f53-1f6a4b2e7d11",
"pipelineId": "5d0b8f8e-3c1a-4a4e-9a57-2f6f3e1c9b10",
"pipelineVersion": 3,
"stageId": "stage-new",
"state": "OPEN",
"name": "Acme renewal 2027",
"contact": {
"id": "4e362e2b-67b2-4a7e-a9df-e9ecf9141be8"
},
"source": "API",
"revision": 1,
"createdAt": "2026-11-11T15:00:00.000Z",
"updatedAt": "2026-11-11T15:00:00.000Z",
"values": {
"budget": 15000000,
"closeDate": "2026-12-15"
},
"ownerId": null,
"externalId": "ERP-OPP-981",
"closeReason": {
"id": "reason-price",
"label": "Price too high",
"note": null
},
"closedAt": null
}Move a pipeline record to another stage
Move an open record to another stage of the pipeline version it follows; a final stage closes it.
A stage that is not in that version, such as one of another pipeline, fails with 422 BRIDGE_PIPELINE_0311
(errRecordStage), and the stage the record is already in with 409 BRIDGE_PIPELINE_0004. A closed record
fails with 409 BRIDGE_PIPELINE_0306: reopen it first. When the stage requires a complete contact, an
incomplete one fails with 422 BRIDGE_PIPELINE_0305. A move to a final stage may carry an active reasonId
of the pipeline (422 BRIDGE_PIPELINE_0315 when it does not exist, BRIDGE_PIPELINE_0314 when it is retired)
and a reasonNote; without one the record closes with no reason. A reason or a note on a move to an open
stage fails with 422 BRIDGE_PIPELINE_0311. With expectedRevision, a record changed since you read it fails
with 409 BRIDGE_PIPELINE_0101, whose extra.currentRecord is the record as it is now.
Idempotency-Key is required and works like on POST /records: a retry with the same key and body answers the
record with Idempotent-Replayed: true, as it is now. The same key on another record or operation fails with
422 BRIDGE_PIPELINE_0402.
curl --request POST \
--url https://api-connect-us.bridge.new/bridge/api/v1/workspaces/{workspaceId}/records/{recordId}/move \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--header 'x-api-key: <api-key>' \
--data '
{
"stageId": "stage-won",
"expectedRevision": 3,
"reasonId": "reason-price",
"reasonNote": "Chose a cheaper provider"
}
'import requests
url = "https://api-connect-us.bridge.new/bridge/api/v1/workspaces/{workspaceId}/records/{recordId}/move"
payload = {
"stageId": "stage-won",
"expectedRevision": 3,
"reasonId": "reason-price",
"reasonNote": "Chose a cheaper provider"
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
'x-api-key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
stageId: 'stage-won',
expectedRevision: 3,
reasonId: 'reason-price',
reasonNote: 'Chose a cheaper provider'
})
};
fetch('https://api-connect-us.bridge.new/bridge/api/v1/workspaces/{workspaceId}/records/{recordId}/move', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-connect-us.bridge.new/bridge/api/v1/workspaces/{workspaceId}/records/{recordId}/move",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'stageId' => 'stage-won',
'expectedRevision' => 3,
'reasonId' => 'reason-price',
'reasonNote' => 'Chose a cheaper provider'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api-connect-us.bridge.new/bridge/api/v1/workspaces/{workspaceId}/records/{recordId}/move"
payload := strings.NewReader("{\n \"stageId\": \"stage-won\",\n \"expectedRevision\": 3,\n \"reasonId\": \"reason-price\",\n \"reasonNote\": \"Chose a cheaper provider\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api-connect-us.bridge.new/bridge/api/v1/workspaces/{workspaceId}/records/{recordId}/move")
.header("Idempotency-Key", "<idempotency-key>")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"stageId\": \"stage-won\",\n \"expectedRevision\": 3,\n \"reasonId\": \"reason-price\",\n \"reasonNote\": \"Chose a cheaper provider\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-connect-us.bridge.new/bridge/api/v1/workspaces/{workspaceId}/records/{recordId}/move")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"stageId\": \"stage-won\",\n \"expectedRevision\": 3,\n \"reasonId\": \"reason-price\",\n \"reasonNote\": \"Chose a cheaper provider\"\n}"
response = http.request(request)
puts response.read_body{
"id": "0d3c7f0e-5a43-5c0e-9f53-1f6a4b2e7d11",
"pipelineId": "5d0b8f8e-3c1a-4a4e-9a57-2f6f3e1c9b10",
"pipelineVersion": 3,
"stageId": "stage-new",
"state": "OPEN",
"name": "Acme renewal 2027",
"contact": {
"id": "4e362e2b-67b2-4a7e-a9df-e9ecf9141be8"
},
"source": "API",
"revision": 1,
"createdAt": "2026-11-11T15:00:00.000Z",
"updatedAt": "2026-11-11T15:00:00.000Z",
"values": {
"budget": 15000000,
"closeDate": "2026-12-15"
},
"ownerId": null,
"externalId": "ERP-OPP-981",
"closeReason": {
"id": "reason-price",
"label": "Price too high",
"note": null
},
"closedAt": null
}Headers
Path Parameters
Body
Request body to move a pipeline record to another stage of its pipeline.
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.
x >= 13
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.
Was this page helpful?

