Skip to main content
A pipeline record follows one piece of work for a Contact, such as a sales opportunity, through the stages of a pipeline. Use this recipe to keep the records of your system in a Bridge pipeline: create them, change their values, move them between stages, close them with a reason and reopen them. To receive the changes made in Bridge, subscribe to pipeline record events.

Before you start

  • Get a server-side API Key from Authentication and send it in x-api-key, as with every other operation. The workspaceId in the path must be the workspace of that key. Any other workspace is refused with 403 BRIDGE_CORE_0301, and nothing is read or written.
  • Pipelines must be enabled for the workspace. Otherwise every operation answers 403 BRIDGE_PIPELINE_0301.
  • Retrieve the pipeline you write to. It lists the stageId values, the attribute ids you use as values keys and the active close reasons. List the pipelines to find its id.
403 BRIDGE_CORE_0301

The operations

... stands for /bridge/api/v1/workspaces/{workspaceId}, on the REST API host https://api-connect-us.bridge.new.

Create a record

Name the Contact with exactly one of contact.id, contact.phone or contact.email. Bridge finds the Contact the same way as contact lookup; a Contact merged into another one resolves to the Contact that replaced it. The Contact is never created: when it does not exist the request fails with 404 BRIDGE_EXTERNAL_0001, so create the Contact first and retry. Without pipelineId the record goes to the workspace’s default pipeline, and without stageId to the pipeline’s initial stage. A final stage is refused at creation. A pipeline set not to accept records from the API refuses the creation with 403 BRIDGE_PIPELINE_0317.
A created record answers 201 with a Location header and the record. Keep its id and its revision:
201
404 BRIDGE_EXTERNAL_0001
Send externalId with the id the record has in your system. A pipeline holds one record per externalId: a second creation with the same externalId in the same pipeline fails with 409 BRIDGE_PIPELINE_0003, and extra.recordId is the record that already has it. Read that record instead of creating another one. To find it later, list records with externalId (and pipelineId when it is not the default pipeline). The record id is chosen by Bridge; the request body has no field to set it.
409 BRIDGE_PIPELINE_0003

One open record per Contact

A pipeline can be set in Bridge to allow a Contact only one open record at a time. In such a pipeline, creating a record for a Contact that already has an open one fails with 409 BRIDGE_PIPELINE_0318, and extra.openRecordId is that open record: work on it instead. Closed records do not count, so a Contact can start a new record once the previous one is closed. Reopening a record fails the same way when the Contact has another open record in the pipeline.
409 BRIDGE_PIPELINE_0318

Retry safely with Idempotency-Key

POST .../records, POST .../move and POST .../reopen require an Idempotency-Key header of 1 to 255 characters. Use one key per change you want to make, and send the same key when you retry that change. A key is kept for 24 hours; after that the same key runs as a new request. Keys are shared by every operation of the workspace, so do not reuse one across records.
If a request is cut off before it finishes, its key can keep answering 409 BRIDGE_PIPELINE_0401 for up to 24 hours. Retry with a new key. Send externalId when you create records, so that a retry with a new key can never create a second record.

Avoid overwriting changes with expectedRevision

Every record has a revision that goes up by one each time the record changes. Send the revision you last read as expectedRevision in the body of PATCH, move or reopen. If someone changed the record in the meantime, the request fails with 409 BRIDGE_PIPELINE_0101 and changes nothing. extra.currentRecord is the record as it is now: decide again from it and retry with its revision. expectedRevision is optional. Without it, the change applies to the record as Bridge reads it, and a change made at the same moment can still fail it with the same 409.
PATCH
409 BRIDGE_PIPELINE_0101
extra.currentRecord holds the whole record, with the same fields as the 201 response above; the example shows only three of them.

Move, close and reopen

Move the record with the stageId of a stage of the pipeline version it follows. Moving it to a final stage closes it. A move to a final stage can carry reasonId, one of the active close reasons of the pipeline, and a reasonNote of up to 500 characters, which needs reasonId. The close reason is optional: without one, the record closes with closeReason: null.
The answer is 200 with the record. A closed record has state: "FINAL", closedAt and, when the move carried one, closeReason with the id, label and note of the reason. Reopen a closed record to take it back to the open stage it was in before it was closed; its close reason is cleared. When its history names no open stage of its version, the record goes to the pipeline’s initial stage. The body is optional and only takes expectedRevision. Reopening an open record fails with 409 BRIDGE_PIPELINE_0307.

Stage actions run on every entry

A stage can have actions, such as creating a task or creating a record in another pipeline. They run every time a record enters the stage: when it is created in the stage, when it is moved to it and when it is reopened into it. That includes every record you create through the API, so a bulk import into a stage with actions runs them once per record. Check the actions of the stage before an import.
The actions run after the API answers; the response does not wait for them. Their results arrive as pipeline_action.* webhook events.

Errors and limits

  • Every error answers a Problem body. Branch on code, not on title. See Pipeline error codes for each code and what to do.
  • The pipelines operations draw from the same budget as the rest of the API: 50 requests every 5 seconds per workspace. See Rate limits.