Skip to main content
POST
Create a pipeline record

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 record to create, 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 created.

Required string length: 1 - 255
Example:

"erp-opp-981-create"

Path Parameters

workspaceId
string<uuid>
required

Unique identifier of the workspace (UUID v4).

Example:

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

Body

application/json

Request body to create a pipeline record.

contact
Contact · object
required

The contact the record belongs to, given by exactly one of id, phone or email.

pipelineId
string | null

Pipeline to create the record in. Defaults to the workspace's default pipeline.

Required string length: 1 - 255
Example:

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

stageId
string | null

Stage to start the record in. Defaults to the pipeline's initial stage; a final stage is refused. The requirements of the stage apply, such as a complete contact.

Required string length: 1 - 255
Example:

"stage-new"

name
string | null

Name of the record, up to 200 characters. When missing or blank, the contact's full name, then its cellphone, then its email.

Example:

"Acme renewal 2027"

externalId
string | null

Your system's id for the record, unique per pipeline. A second record with the same externalId in the same pipeline is refused with 409 and the id of the existing record.

Required string length: 1 - 255
Example:

"ERP-OPP-981"

values
Values · object

Values of the record's attributes, keyed by attribute id. Only RECORD-scope attributes of the pipeline's current version are accepted, each checked against its type (TEXT up to 2000 characters); a null value, a blank text and an empty list are left out.

Example:

Response

The record was created, or a previous request with the same key created it.

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