Inbound prospects, before they become deals.
List leads
Inbound prospects, before they become deals. Archived and converted leads are included unless you exclude them. To find the lead for a person, send email or phone.
query Parameters
page1-indexed page number, up to 1000000.
page_sizeRows per page. Capped at 100.
updated_sinceISO 8601 date-time, for example 2026-10-01T00:00:00Z. Returns only rows changed at or after it, in updated_at order and then id order, oldest first. A value that is not ISO 8601 gets 400 VALIDATION_ERROR.
after_idUse with updated_since to read the next page of a sync. Send the updated_at and id of the last row you read: the list then starts after that row, and a row that changes while you sync cannot be skipped. Keep page at 1. Without updated_since it gets 400 VALIDATION_ERROR.
include_archivedSend false to exclude archived and converted leads.
lead_form_idOnly the leads that this lead form brought in. Find the id with GET /v1/lead-forms.
emailExact email address. Case and surrounding spaces are ignored. Matches the contact's main email or any additional email. No match returns an empty list, not 404.
phonePhone number in any format. Matches on the last 10 digits, so +1 (587) 555-1234 and 5875551234 find the same contact. Matches the main phone or any additional phone.
qText search over the name, nickname, company, email and phone. Every word must match part of one of them. The same search as the search bar in BrokerPlus.
Filter by a contact custom field: custom_field[<key>]=<value>, for example custom_field[lead_source]=Google. The value takes the same text as a write. An empty value finds records with no answer. Send up to 10; a record must match all of them. Get the keys from GET /v1/custom-fields?entity=contact.
List leads › Responses
Success
successAlways true on a successful response.
The page of results. The endpoint description and the Pagination guide give the order.
Offset pagination. Page forward until page reaches total_pages.
Create a lead
Creates the contact and the lead together, exactly as the in-app Add Lead does. This is the endpoint to point your own website form at. Send custom_fields to set the person's custom fields in the same call.
Headers
Idempotency-KeyOptional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key.
Create a lead › Request Body
first_nameGiven name. The only required field.
last_nameFamily name.
email^(?:[A-Za-z0-9_'+\-]…Must be a valid address if provided.
phoneStored as sent. Any format is accepted.
service_typeWhat they are asking for, in your own words.
first_time_buyerDefaults to false.
next_follow_up_at^(?:(?:\d\d[2468][04…ISO 8601 timestamp. When to follow up next.
additional_detailsFree-text notes to attach to the lead.
Custom field values by key, e.g. {"lead_source": "Google", "click_id": "abc123"}. A lead's custom fields are its contact's fields; list the keys with GET /v1/custom-fields?entity=contact. Each value takes the same text as PATCH /v1/contacts/{id}/custom-fields/{key}. One bad key or value refuses the whole request, and details names each one.
Create a lead › Responses
Success
successAlways true on a successful response.
The requested record.
Update a lead
Changes the fields a broker edits on the Leads board, and the person's custom fields. Only the fields you send are changed. The name, email and phone belong to the contact: change them with PATCH /v1/contacts/{id}.
path Parameters
idResource id.
Update a lead › Request Body
stage_idA stage from GET /v1/lead-stages. Send null to clear it.
service_typeWhat they are asking for, in your own words.
first_time_buyerWhether the borrower is a first-time buyer.
next_follow_up_at^(?:(?:\d\d[2468][04…ISO 8601 timestamp. When to follow up next.
additional_detailsFree-text notes on the lead.
referral_source_idA referral partner from GET /v1/referral-sources. The deal behind the lead gets it too.
channel_idA channel from GET /v1/lead-channels. The deal behind the lead gets it too.
Custom field values by key, e.g. {"lead_source": "Google", "click_id": "abc123"}. A lead's custom fields are its contact's fields; list the keys with GET /v1/custom-fields?entity=contact. Each value takes the same text as PATCH /v1/contacts/{id}/custom-fields/{key}. One bad key or value refuses the whole request, and details names each one.
Update a lead › Responses
Success
successAlways true on a successful response.
The requested record.
Archive a lead
Takes the lead out of the funnel without a deal, as Archive does in BrokerPlus. Archiving an archived lead changes nothing.
path Parameters
idResource id.
Headers
Idempotency-KeyOptional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key.
Archive a lead › Responses
Success
successAlways true on a successful response.
The requested record.
Unarchive a lead
Puts an archived lead back in the funnel. Unarchiving an open lead changes nothing.
path Parameters
idResource id.
Headers
Idempotency-KeyOptional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key.
Unarchive a lead › Responses
Success
successAlways true on a successful response.
The requested record.
Convert a lead to a deal
Starts a deal from the lead, as Create Deal does in BrokerPlus. The lead becomes converted and converted_deal_id is the new deal. Converting a converted lead changes nothing and returns the same deal.
path Parameters
idResource id.
Headers
Idempotency-KeyOptional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key.
Convert a lead to a deal › Request Body
typeDeal type. Defaults to purchase. Decides which pipeline the deal lands on when you do not name one.
board_idPipeline to land on, from GET /v1/pipelines. Omit to use the broker's pipeline for the type.
stage_idStage within board_id. Omit to land on the pipeline's first stage. Requires board_id.
Convert a lead to a deal › Responses
Success
successAlways true on a successful response.
The requested record.
List a lead's custom fields
The custom fields of the lead's contact, with their values. A lead's custom fields are its contact's fields, so this is the same list as GET /v1/contacts/{contact_id}/custom-fields.
path Parameters
idResource id.
query Parameters
page1-indexed page number, up to 1000000.
page_sizeRows per page. Capped at 100.
List a lead's custom fields › Responses
Success
successAlways true on a successful response.
The page of results. The endpoint description and the Pagination guide give the order.
Offset pagination. Page forward until page reaches total_pages.
Set a custom field on a lead
Sets one of the lead's contact fields by its key. Send an empty string to clear it. To set several at once, send custom_fields to PATCH /v1/leads/{id}.
path Parameters
idResource id.
keyResource id.
Set a custom field on a lead › Request Body
valueThe value to store, as text. A short_text field takes one line of 200 characters or fewer, and line breaks change to spaces. A number,money or percent field takes a number like 1200 or 4.5, a date field takes YYYY-MM-DD, a checkbox takes true or false, a url takes a full web address, a select field takes one of its options, and a multi_select field takes a JSON array of its options, like ["Appraisal","Insurance"]. Send an empty string to clear the field.
Set a custom field on a lead › Responses
Success
successAlways true on a successful response.
The requested record.
List lead stages
The columns of the brokerage's Leads board, in order. Send one as stage_id on a lead.
query Parameters
page1-indexed page number, up to 1000000.
page_sizeRows per page. Capped at 100.
List lead stages › Responses
Success
successAlways true on a successful response.
The page of results. The endpoint description and the Pagination guide give the order.
Offset pagination. Page forward until page reaches total_pages.
Create a lead stage
Adds a column to the end of the Leads board, the same as the board settings in BrokerPlus. A name that a deleted stage had restores that stage.
Headers
Idempotency-KeyOptional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key.
Create a lead stage › Request Body
nameWhat the brokerage calls it, 40 characters or fewer. It must be unique among the live ones.
Create a lead stage › Responses
Success
successAlways true on a successful response.
The requested record.
Put lead stages in order
Sets the column order of the Leads board. Send the stage ids first to last. Returns the stages in the new order.
Headers
Idempotency-KeyOptional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key.
Put lead stages in order › Request Body
idsLead stage ids in the new board order, first to last. Each id must be a live stage of your brokerage, or nothing changes.
Put lead stages in order › Responses
Success
successAlways true on a successful response.
The page of results. The endpoint description and the Pagination guide give the order.
Offset pagination. Page forward until page reaches total_pages.
Delete a lead stage
Removes a column from the Leads board, the same as Delete in BrokerPlus. The leads in the stage move to move_to, or to the first stage that stays when you omit it. The board must keep one stage.
path Parameters
idResource id.
query Parameters
move_toThe lead stage that gets the leads of the deleted stage. Defaults to the first stage that stays.
Delete a lead stage › Responses
Success
successAlways true on a successful response.
The requested record.
Rename a lead stage
Changes the name of a column on the Leads board. The leads in the stage stay in it.
path Parameters
idResource id.
Rename a lead stage › Request Body
nameWhat the brokerage calls it, 40 characters or fewer. It must be unique among the live ones.
Rename a lead stage › Responses
Success
successAlways true on a successful response.
The requested record.
List referral sources
The referral partners the brokerage tags leads with. Send one as referral_source_id on a lead.
query Parameters
page1-indexed page number, up to 1000000.
page_sizeRows per page. Capped at 100.
List referral sources › Responses
Success
successAlways true on a successful response.
The page of results. The endpoint description and the Pagination guide give the order.
Offset pagination. Page forward until page reaches total_pages.
Create a referral partner
Adds a referral partner, the same as Add Partner on the Partners page. A referral partner is a referral source with a contact behind it. Send contact_id to use a contact you have. Omit it, and BrokerPlus makes a partner contact from the name and the details you send. The new partner goes to the end of the order.
Headers
Idempotency-KeyOptional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key.
Create a referral partner › Request Body
nameThe partner's name, 120 characters or fewer. It must be unique among the live partners.
contact_idA contact in your brokerage to use as the partner. Omit it, and BrokerPlus makes a partner contact from name, first_name, last_name, email, and phone.
first_nameThe first name of the new partner contact. Ignored when you send contact_id.
last_nameThe last name of the new partner contact. Ignored when you send contact_id.
emailThe email address of the new partner contact. Ignored when you send contact_id.
phoneThe phone number of the new partner contact. Ignored when you send contact_id.
typeWhat kind of partner this is, for example realtor or lawyer. BrokerPlus stores a known kind in its usual spelling.
companyThe firm the partner works for. When another partner has the same firm with different capital letters, BrokerPlus uses that spelling.
contact_detailsHow to reach the partner, in the broker's own words. An email address or a phone number here also goes on the partner's contact.
notesThe broker's notes on the relationship.
last_contact_at^(?:(?:\d\d[2468][04…ISO 8601 timestamp. When the broker was last in touch with the partner.
next_follow_up_at^(?:(?:\d\d[2468][04…ISO 8601 timestamp. When the broker means to get back in touch.
Create a referral partner › Responses
Success
successAlways true on a successful response.
The requested record.
Archive a referral partner
Removes the partner from the list, the same as Delete on the Partners page. The leads that named the partner as their referral source then have no referral source. The partner's contact stays in the book.
path Parameters
idResource id.
Archive a referral partner › Responses
Success
successAlways true on a successful response.
The requested record.
Update a referral partner
Changes the details of a referral partner. A new name, company, or email address or phone number in contact_details also goes on the partner's contact. Send null or an empty string to clear a field.
path Parameters
idResource id.
Update a referral partner › Request Body
nameA new name for the partner. The partner's contact gets the same name.
typeWhat kind of partner this is, for example realtor or lawyer. BrokerPlus stores a known kind in its usual spelling.
companyThe firm the partner works for. When another partner has the same firm with different capital letters, BrokerPlus uses that spelling.
contact_detailsHow to reach the partner, in the broker's own words. An email address or a phone number here also goes on the partner's contact.
notesThe broker's notes on the relationship.
last_contact_at^(?:(?:\d\d[2468][04…ISO 8601 timestamp. When the broker was last in touch with the partner.
next_follow_up_at^(?:(?:\d\d[2468][04…ISO 8601 timestamp. When the broker means to get back in touch.
Update a referral partner › Responses
Success
successAlways true on a successful response.
The requested record.
List lead channels
How leads find the brokerage, e.g. Google or a referral. Send one as channel_id on a lead.
query Parameters
page1-indexed page number, up to 1000000.
page_sizeRows per page. Capped at 100.
List lead channels › Responses
Success
successAlways true on a successful response.
The page of results. The endpoint description and the Pagination guide give the order.
Offset pagination. Page forward until page reaches total_pages.
Create a lead channel
Adds a channel to the end of the brokerage's list, the same as the channel settings in BrokerPlus.
Headers
Idempotency-KeyOptional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key.
Create a lead channel › Request Body
nameWhat the brokerage calls it, 40 characters or fewer. It must be unique among the live ones.
Create a lead channel › Responses
Success
successAlways true on a successful response.
The requested record.
Archive a lead channel
Removes the channel from the list. The leads and deals that had the channel then have no channel, and the funnel report stops counting it.
path Parameters
idResource id.
Archive a lead channel › Responses
Success
successAlways true on a successful response.
The requested record.
Update a lead channel
Renames a channel, or moves it in the order. You cannot rename a channel that BrokerPlus made for every brokerage.
path Parameters
idResource id.
Update a lead channel › Request Body
nameA new name, 40 characters or fewer. You cannot rename a channel that BrokerPlus made for every brokerage, because the funnel report compares brokerages on these names.
positionThe channel's place in the brokerage's own order, lowest first.
Update a lead channel › Responses
Success
successAlways true on a successful response.
The requested record.
Create or update leads in a batch
Creates or updates up to 100 leads in one request. Each item is the body of POST /v1/leads for a new lead, or of PATCH /v1/leads/{id} for a lead that exists. Send external_id with namespace, and the next batch with that id updates the same lead. The items are not one transaction: an item that fails does not stop the others. Each item counts as one request against the rate limit. Refer to Migrate from another CRM.
Headers
Idempotency-KeyOptional for POST. An authorized retry with the same method, path, and exact body returns the stored response. Reservations last 24 hours. They belong to the original API key and broker. Reconcile uncertain results before you use a new key.
Create or update leads in a batch › Request Body
From 1 to 100 records. BrokerPlus writes them in this order.
namespace^[A-Za-z0-9_.-]+$The name of the system that your external_id values come from, for example zoho. It is not case-sensitive. It is necessary when an item has an external_id. Two systems can then use the same id without a conflict.
Create or update leads in a batch › Responses
Success
successAlways true on a successful response.
The requested record.