Contacts

Everyone in the brokerage book: leads, clients, partners and co-brokers. Use updated_since to sync incrementally rather than re-reading page 1.

One of first_name or company_name is required. The API does not check the book for a duplicate unless you ask it to with check_duplicates.

A single contact by id. Returns 404 if it belongs to another brokerage. A contact that was merged into another returns 410 with the other contact's id.

Only the fields you send are changed.

The sets of contacts that look like the same person, as the Duplicates page shows them: the same email, the same phone, or the same name. Merge a set with POST /contacts/{id}/merge. A set the broker marked as not a duplicate is not listed. updated_since returns the sets with a contact changed at or after it. A set has no position to resume after, so after_id gets 400 VALIDATION_ERROR: page with page.

Merges the contacts in duplicate_ids into this contact, the same as Merge on the Duplicates page. Their deals, notes, documents, tasks and history move to this contact, which survives. The duplicates are retired, and GET /contacts/{id} on one of them returns 410 with this contact's id. A merge cannot be undone. Returns the merged contact.

Takes the contact out of the book, the same as Archive on the contact page. The contact keeps their history, and an import or a new lead with the same email finds them. Archiving an archived contact also succeeds. Returns the contact.

Puts an archived contact back in the book. Restoring a contact in the book also succeeds. Returns the contact.

The ways to reach a contact beyond the primary email and phone on the contact: extra emails, phones and fax numbers, and social profiles with a link to each. Oldest first.

Adds an extra email, phone, fax number or social profile. A social profile takes a link or a handle. Adding one the contact already has returns 409.

Removes one extra email, phone, fax number or social profile. The primary email and phone are not methods.

The people this contact is related to, as the contact page shows them, worded from this contact's side. A relationship to a contact your key cannot read is not listed.

Pinned first, then newest - the order a broker sees in BrokerPlus.

The note is attributed to the broker your key acts as.

Deletes the note and its replies. You cannot undo this. Any teammate who can edit the contact can delete its notes, as in BrokerPlus.

Edit the words, pin or unpin the note, or change its kind. Only the fields you send change. A teammate newly named with a mention gets a notification, as in BrokerPlus.

The teammates on the contact's team, by name. To mention one in a note, put <span data-mention="USER_ID">@Name</span> in the body. The teammate gets a notification, as in BrokerPlus. A mention of somebody who is not in this list is kept as text, and nobody gets a notification.

Adds or takes off one emoji reaction of the broker your key acts as. Sending the same reaction again changes nothing. A reaction also marks a mention of that broker in the note as seen.

Send the file as multipart/form-data in a file field, or as JSON with content_base64. The file must be a PDF of at most 25 MB. BrokerPlus checks the content, not the name. The response does not include a link: get one with the file's id.

A signed link to the PDF, valid for five minutes.

Writes an sms or email draft into the review queue of the broker your key acts as. The API never sends it. The broker reads the draft in BrokerPlus, and approves, edits, or rejects it there. Use this endpoint when your own system writes the message and a person must read it before a client does.

Sends an email or sms to this contact now, from the connected mailbox or phone number of the broker your key acts as. Set send_at to send it later instead. The message is the broker's own: it is in their drafts folder as sent (or scheduled), and in Sent. The response is 201 with the draft. Read the sent message with GET /v1/communications/{id} and the draft's communication_id. An email is sent in the background, so communication_id can be null for a short time. A key with the no_sending limit gets 403. Supports Idempotency-Key.

The drafts filed through the API (new messages, replies and forwards) that the broker your key acts as can review, newest first. Use status to see which ones were sent, scheduled or discarded. Drafts written in BrokerPlus itself are not listed.

One draft filed through the API, with its review status.

Changes a draft that waits for review, as the broker does in their drafts folder: the subject, the text, who it goes to, and its files. Send only the fields to change. Nothing goes to the client. Send it afterwards with POST /drafts/{id}/send.

The broker's own addresses for this contact, primary first. Residence history from a mortgage application is not here; read it through the application.

The first address on a contact becomes primary whatever you send. Send is_primary: true on a later one to move the primary; the previous primary is demoted in the same write.

If the removed address was primary, the oldest remaining address becomes primary.

Send only the fields to change. is_primary: false is ignored: a contact always has one primary, so demote an address by promoting another.

How many deals the contact borrowed on, how many funded, the dollars funded, whether they are a repeat client, their referrals, and the last thing that happened with them. Computed on read from the deals your key can see. Each figure names its basis.

Whether the brokerage may send this person commercial email and SMS, by category, and whether a hard suppression stands. A missing preference is implied consent.

Records an opt-out, clears one, or records express consent from something the client did. Opting in never records express consent on its own. A hard suppression is not changed here.

Only the tags currently on this contact. For the full vocabulary see GET /contact-tags.

Assigning a tag the contact already has is a no-op, not an error. A tag newly put on fires the contact.tag_assigned automation trigger.

Idempotent - removing a tag that was not there still returns 200.

What the contact does for the broker's clients, for example realtor or lawyer, with their title, website, booking link and photo. A contact with any role is a partner.

Adds a role, for example realtor, and makes the contact a partner, as the role picker on the contact page does. If the contact already holds the role, the role is kept and its title is updated when you send one.

Removes the role. When the contact's last role goes, the contact is no longer a partner. The contact itself stays in the book.

Changes the title, website or booking link on one of the contact's roles. Only the fields you send change. The photo is uploaded in BrokerPlus.

Creates or updates up to 100 contacts in one request. Each item is the body of POST /v1/contacts for a new contact, or of PATCH /v1/contacts/{id} for a contact that exists. Send external_id with namespace, and the next batch with that id updates the same contact. 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.

Sends a draft that waits for review now, as it is written, the same as Send in the broker's drafts folder. The response is the draft, with status sent, or scheduled when the draft has a send time. A key with the no_sending limit gets 403.

Sets a draft that waits for review to go out at send_at, the same as Schedule in the broker's drafts folder. A draft that is already scheduled moves to the new time. It goes out without anybody pressing Send, so a key with the no_sending limit gets 403. Stop it with POST /drafts/{id}/unschedule.

Takes a scheduled draft back to pending_review, so it does not go out. It keeps its time: sending it with POST /drafts/{id}/send schedules it for that time again, unless the time has passed.

Discards a draft that waits for review, the same as Discard in the broker's drafts folder. It stays in the list as discarded and can no longer be sent. You cannot undo this.

Every custom field the brokerage keeps on a contact, with this contact's value. A field that nobody has answered returns a value of null, so the list is the same length on every contact.

Sets one field by its key. The write is idempotent: the same request twice leaves the same value. Send an empty string to clear the field, which makes it unanswered again.

The activity trail of a person across every deal, newest first: the messages and calls with them, and the changes to the deals that they are on. It holds the newest 200 entries of each kind.