Initiate a LeadScout outbound conversation with a known lead

curl --request POST \
  --url https://api-connect-us.bridge.new/bridge/api/v1/workspaces/{workspaceId}/leadscout/outbound \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "contact": {
    "identifier": "<string>",
    "providerChannelId": "c4f2a1e0-9b8d-4e7c-a6f5-1d2e3f4a5b6c"
  },
  "template": {
    "name": "<string>",
    "orderedParams": [
      "<string>"
    ]
  },
  "additionalMessages": [
    {
      "messageBody": "<string>",
      "mediaIds": [
        "<string>"
      ]
    }
  ],
  "agentContext": {
    "notes": "Lead asked about pricing tiers last week.",
    "mediaIds": [
      "<string>"
    ]
  },
  "consent": {
    "capturedAt": "2026-04-20T10:00:00.000Z"
  },
  "handoffOverride": {
    "preAssignedUser": {
      "identifier": "<string>"
    }
  },
  "brandId": null,
  "campaignId": null,
  "forceSend": false
}
'

{
  "conversation": {
    "id": "<string>",
    "workspaceId": "<string>",
    "participants": {
      "externals": [
        {
          "identifier": "<string>",
          "joinedAt": "2023-11-07T05:31:56Z",
          "lastSeenAt": null
        }
      ],
      "internals": [
        {
          "identifier": "<string>",
          "joinedAt": "2023-11-07T05:31:56Z",
          "lastSeenAt": null
        }
      ]
    },
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "name": "Bridge Support Team",
    "status": "ACTIVE"
  },
  "contact": {
    "id": "<string>",
    "workspaceId": "<string>",
    "createdAt": "<string>",
    "updatedAt": "<string>",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "cellphone": "+14084029292",
    "customAttributes": [
      {
        "key": "<string>",
        "values": [
          "<string>"
        ]
      }
    ],
    "languageCode": "EN",
    "ownerId": "37673840-6259-40f9-bbe5-a7db40f8e3cf"
  },
  "templateSent": {
    "name": "<string>",
    "messageId": null
  },
  "additionalMessagesPersisted": 0,
  "alreadyInitiated": false
}

LeadScout API

Initiate a LeadScout outbound conversation with a known lead

Start an AI-controlled outbound conversation with a known lead.

Pre-flight checks run before any write: template exists and is APPROVED, contact exists, a WhatsApp channel resolves, a prospection agent owns it, and any handoffOverride user is valid.

If an active conversation is already running on the chosen channel:

forceSend=false (default) → 409 with the blocking conversation id.
forceSend=true → that conversation is reused; the new template and follow-ups are appended to it and the response sets alreadyInitiated=true.

Otherwise a fresh conversation is opened (controlled by the prospection agent) with the template as its first message; additionalMessages are persisted for the agent to send once the lead replies.

POST

bridge

api

workspaces

{workspaceId}

leadscout

outbound

Initiate a LeadScout outbound conversation with a known lead

curl --request POST \
  --url https://api-connect-us.bridge.new/bridge/api/v1/workspaces/{workspaceId}/leadscout/outbound \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "contact": {
    "identifier": "<string>",
    "providerChannelId": "c4f2a1e0-9b8d-4e7c-a6f5-1d2e3f4a5b6c"
  },
  "template": {
    "name": "<string>",
    "orderedParams": [
      "<string>"
    ]
  },
  "additionalMessages": [
    {
      "messageBody": "<string>",
      "mediaIds": [
        "<string>"
      ]
    }
  ],
  "agentContext": {
    "notes": "Lead asked about pricing tiers last week.",
    "mediaIds": [
      "<string>"
    ]
  },
  "consent": {
    "capturedAt": "2026-04-20T10:00:00.000Z"
  },
  "handoffOverride": {
    "preAssignedUser": {
      "identifier": "<string>"
    }
  },
  "brandId": null,
  "campaignId": null,
  "forceSend": false
}
'

{
  "conversation": {
    "id": "<string>",
    "workspaceId": "<string>",
    "participants": {
      "externals": [
        {
          "identifier": "<string>",
          "joinedAt": "2023-11-07T05:31:56Z",
          "lastSeenAt": null
        }
      ],
      "internals": [
        {
          "identifier": "<string>",
          "joinedAt": "2023-11-07T05:31:56Z",
          "lastSeenAt": null
        }
      ]
    },
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "name": "Bridge Support Team",
    "status": "ACTIVE"
  },
  "contact": {
    "id": "<string>",
    "workspaceId": "<string>",
    "createdAt": "<string>",
    "updatedAt": "<string>",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "cellphone": "+14084029292",
    "customAttributes": [
      {
        "key": "<string>",
        "values": [
          "<string>"
        ]
      }
    ],
    "languageCode": "EN",
    "ownerId": "37673840-6259-40f9-bbe5-a7db40f8e3cf"
  },
  "templateSent": {
    "name": "<string>",
    "messageId": null
  },
  "additionalMessagesPersisted": 0,
  "alreadyInitiated": false
}

Authorizations

x-api-key

string

header

required

Copy the API key as provided by the Bridge Console.

Path Parameters

workspaceId

string<uuid>

required

Unique identifier of the workspace (UUID v4).

Example:

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

Body

application/json

Request body for initiating a LeadScout outbound conversation.

contact

Contact · object

required

The lead this outbound conversation targets. Must already exist in the workspace.

Show child attributes

template

Template · object

required

The opening template to send.

Show child attributes

additionalMessages

OutboundFollowUpRequest · object[]

Up to five follow-up messages persisted on the conversation. They are not delivered immediately; the agent decides when to send them once the lead replies.

Maximum array length: 5

Show child attributes

agentContext

OutboundAgentContextRequest · object

Notes and media stored on the conversation as agent context for the AI / human reviewer.

Show child attributes

Tenant-affirmed opt-in evidence recorded verbatim on the conversation.

Show child attributes

handoffOverride

LeadscoutOutboundHandoffOverride · object

Overrides the default advisor assignment for the outbound conversation.

Show child attributes

brandId

string | null

Optional brand id. When provided, only channels linked to this brand are eligible. Omit to consider every channel in the workspace.

Example:

null

campaignId

string | null

Optional campaign reference stored on the conversation for audit and reporting.

Example:

null

forceSend

boolean

default:false

When true, bypass all blockers on the chosen channel: any active conversation (AI-prospecting or human) is ignored and a fresh outbound is created. When no providerChannelId is supplied and every workspace channel is occupied, the first candidate is used instead of raising AllProviderChannelsOccupied. When false (default), an existing active conversation on the chosen channel returns 409.

Examples:

false

true

Response

Successful Response

Response body for a successful LeadScout outbound initiation.

conversation

Conversation · object

required

The newly created AI-controlled conversation.

Show child attributes

contact

Contact · object

required

The contact the conversation was initiated with.

Show child attributes

templateSent

LeadscoutTemplateSent · object

Summary of the template dispatched to open the conversation.

Show child attributes

additionalMessagesPersisted

integer

default:0

Count of follow-up messages persisted on the conversation.

Examples:

0

3

alreadyInitiated

boolean

default:false

True when this request landed on a pre-existing conversation (forceSend=true reuse path); false when a fresh conversation was created. Informational only — the new template and follow-ups are persisted either way.

Examples:

false

true

Get provider channels by workspace id and provider type