Onboards

Onboards are records that track the buyer connection onboarding process in LeadConduit. When a buyer accepts an invitation to connect with a seller, an onboard record is created to manage and track the setup workflow.

Overview

The onboarding process involves:

  1. Creating an Onboard - When a buyer accepts a connection invitation, an onboard record is created with status created. Optionally, the UI can send a flow_id if already available
  2. In Progress - The UI sends a PUT with the user's flow_id and status in_progress
  3. Completing Setup - The UI must send a PUT with status completed to notify the backend that the onboard process is finished. The backend then calls /onboard/buyer to finish the flow synchronization

Note: The /onboard/buyer endpoint can also be called directly by the UI modal when the user has already completed a previous onboard process.

Onboard Statuses

Status Description
created Initial state when the onboard is first created
in_progress The UI has sent the user's flow_id
completed The backend triggers the buyer delivery setup by calling /onboard/buyer
failed The setup process encountered an error

Buyer Setup Process

The backend automatically triggers the buyer delivery setup when the onboard status is set to completed. This process performs:

  1. Connection Validation - Verifies the connection exists and hasn't already been set up
  2. Seller Flow Discovery - Finds all seller flows that have a buyer step pointing to this buyer
  3. Buyer Flow Setup - Creates or updates the buyer's flow to receive leads from the seller
  4. Seller Flow Updates - Adds the buyer's flow_id to the seller's flow mappings
  5. Notifications - Sends email notifications to seller account users about the new connection
  6. Connection Flagging - Marks the connection as having buyer delivery configured

List all onboards

Returns all the onboard records for the authenticated account. Onboards track the status of buyer connection setup processes.

SecurityAPIKey
Responses
200

OK

401

Authorization information is missing or invalid.

get/onboards
Request samples 
Response samples 
application/json
[
  • {
    • "id": "5fd4371e940df5a34a3888b2",
    • "account_id": "64b8f0f5e4b0c3a1d5e6f7a8",
    • "invitation_id": "64b8f0f5e4b0c3a1d5e6f7a9",
    • "connection_id": "64b8f0f5e4b0c3a1d5e6f7aa",
    • "flow_id": "64b8f0f5e4b0c3a1d5e6f7ab",
    • "status": "created",
    • "created_at": "2019-08-24T14:15:22Z",
    • "updated_at": "2019-08-24T14:15:22Z"
    }
]
Create a new onboard
Creates a new onboard record to track a buyer connection setup process. Requires an invitation_id which will be used to retrieve the associated connection.


SecurityAPIKey 
Request 
Request Body schema: application/json
required
Create a new onboard


invitation_id
required
string^[0-9a-fA-F]{24}$
The invitation ID to create the onboard from


 
flow_id
string^[0-9a-fA-F]{24}$
Optional. The flow ID to use for the onboard if the UI already has it


 
Responses 
201
Created


400
Bad request - Invalid parameters or onboard already exists


401
Authorization information is missing or invalid.


422
Unprocessable entity - Validation error


500
Internal server error


post/onboards
Request samples 
application/json
{
  • "invitation_id": "64b8f0f5e4b0c3a1d5e6f7a8"
}
Response samples 
application/json
{
  • "id": "5fd4371e940df5a34a3888b2",
  • "account_id": "64b8f0f5e4b0c3a1d5e6f7a8",
  • "invitation_id": "64b8f0f5e4b0c3a1d5e6f7a9",
  • "connection_id": "64b8f0f5e4b0c3a1d5e6f7aa",
  • "flow_id": "64b8f0f5e4b0c3a1d5e6f7ab",
  • "status": "created",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}
Get an onboard
Returns the onboard record associated with the given ID


SecurityAPIKey 
Request 
path Parameters
id
required
string (ID) ^[0-9a-fA-F]{24}$
ID of the onboard to get


 
 Example:  5fd4371e940df5a34a3888b2
Responses 
200
OK


401
Authorization information is missing or invalid.


404
Onboard not found


get/onboards/{id}
Request samples 
Response samples 
application/json
{
  • "id": "5fd4371e940df5a34a3888b2",
  • "account_id": "64b8f0f5e4b0c3a1d5e6f7a8",
  • "invitation_id": "64b8f0f5e4b0c3a1d5e6f7a9",
  • "connection_id": "64b8f0f5e4b0c3a1d5e6f7aa",
  • "flow_id": "64b8f0f5e4b0c3a1d5e6f7ab",
  • "status": "created",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}
Update an existing onboard
Updates an existing onboard record. When the status is set to completed, the backend automatically triggers the buyer delivery setup process by calling the /onboard/buyer endpoint internally. This will:


    

  1. Find the seller account and their flows that deliver to this buyer
    2. 

  2. Update or create a buyer flow with the seller as a source
    3. 

  3. Update seller flows with the buyer's flow_id mapping
    4. 

  4. Send notification emails to seller account users
    5. 

  5. Mark the connection as having buyer delivery setup complete
    6. 



Important: Ensure all required fields (invitation_id, connection_id) are properly set before marking the onboard as completed.


SecurityAPIKey 
Request 
path Parameters
id
required
string (ID) ^[0-9a-fA-F]{24}$
ID of the onboard to update


 
 Example:  5fd4371e940df5a34a3888b2
Request Body schema: application/json
required
Update an onboard


account_id
string^[0-9a-fA-F]{24}$
The account ID that owns this onboard


 
invitation_id
required
string^[0-9a-fA-F]{24}$
The invitation ID associated with this onboard


 
connection_id
string^[0-9a-fA-F]{24}$
The connection ID used for the onboard (retrieved from the invitation)


 
flow_id
string^[0-9a-fA-F]{24}$
The flow ID to be used for the onboard (normally the minimal flow)


 
status
string
Current status of the onboard process, recommended values are: created, in_progress, completed


 
Responses 
200
OK - Onboard updated successfully. If status is set to 'completed', the backend will automatically trigger the buyer delivery setup process.


400
Bad request - Invalid parameters


401
Authorization information is missing or invalid.


404
Onboard not found


409
Conflict - Onboard was not updated


put/onboards/{id}
Request samples 
application/json
{
  • "account_id": "64b8f0f5e4b0c3a1d5e6f7a8",
  • "invitation_id": "64b8f0f5e4b0c3a1d5e6f7a9",
  • "connection_id": "64b8f0f5e4b0c3a1d5e6f7aa",
  • "flow_id": "64b8f0f5e4b0c3a1d5e6f7ab",
  • "status": "created"
}
Response samples 
application/json
{
  • "id": "5fd4371e940df5a34a3888b2",
  • "account_id": "64b8f0f5e4b0c3a1d5e6f7a8",
  • "invitation_id": "64b8f0f5e4b0c3a1d5e6f7a9",
  • "connection_id": "64b8f0f5e4b0c3a1d5e6f7aa",
  • "flow_id": "64b8f0f5e4b0c3a1d5e6f7ab",
  • "status": "created",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}
Complete buyer delivery setup
Completes the buyer delivery setup process for a connection. This endpoint performs several operations:


    

  1. Validates the connection_id or resolves it from invitation_id
    2. 

  2. Finds the seller account and their flows that deliver to this buyer
    3. 

  3. Updates or creates a buyer flow with the seller as a source
    4. 

  4. Updates seller flows with the buyer's flow_id mapping
    5. 

  5. Sends notification emails to seller account users
    6. 

  6. Marks the connection as having buyer delivery setup complete
    7. 



Note: Either connection_id or invitation_id must be provided.


Version Note:


    

  • In the first version of the onboarding modal, this endpoint is called directly by the frontend.
    • 

  • In the second version, this endpoint will be called automatically by the backend when the onboard status changes to completed_flows_sync.
    • 



SecurityAPIKey 
Request 
Request Body schema: application/json
required
Buyer setup request


One of:
Request body for completing buyer onboarding setup. Either connection_id or invitation_id must be provided.


connection_id
required
string^[0-9a-fA-F]{24}$
The connection ID for the buyer setup


 
flow_id
string^[0-9a-fA-F]{24}$
Optional. The existing flow ID to use for buyer delivery


 
Responses 
200
OK - Buyer setup completed successfully


400
Bad request - Invalid parameters or setup already complete


401
Authorization information is missing or invalid.


404
Not found


500
Internal server error


post/onboard/buyer
Request samples 
application/json
{
  • "invitation_id": "64b8f0f5e4b0c3a1d5e6f7a9",
  • "flow_id": "64b8f0f5e4b0c3a1d5e6f7aa"
}
Response samples 
application/json
{
  • "redirect": "/flows/64b8f0f5e4b0c3a1d5e6f7a8"
}