Before you start
- Get a server-side API Key from Authentication and send it in
x-api-key, as with every other operation. TheworkspaceIdin the path must be the workspace of that key. Any other workspace is refused with403BRIDGE_CORE_0301, and nothing is read or written. - Pipelines must be enabled for the workspace. Otherwise every operation answers
403BRIDGE_PIPELINE_0301. - Retrieve the pipeline you write to. It lists the
stageIdvalues, the attribute ids you use asvalueskeys 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 ofcontact.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.
201 with a Location header and the record. Keep its id and its revision:
201
404 BRIDGE_EXTERNAL_0001
Link the record to your own id
SendexternalId 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 with409 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.
Avoid overwriting changes with expectedRevision
Every record has arevision 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 thestageId 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.
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
The actions run after the API answers; the response does not wait for them. Their results arrive aspipeline_action.* webhook events.
Errors and limits
- Every error answers a
Problembody. Branch oncode, not ontitle. 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.

