# API objects

> The objects the Broker & Agent API answers with and webhooks carry: contacts, tasks, appointments, transactions and more, field by field.

The shapes the API answers with and webhooks carry. Fields are only ever added within v1, so build clients that ignore fields they don’t know.

## Error

| Field | Type | |
|---|---|---|
| `error` | object |  |

## Contact

| Field | Type | |
|---|---|---|
| `id` | string |  |
| `name` | string |  |
| `email` | string or null |  |
| `phone` | string or null |  |
| `stage` | `new`, `engaged`, `qualified`, `touring`, `under-contract`, `closed`, `nurture`, `lost` |  |
| `customStage` | string or null | The custom board column, when it isn't the stage itself. |
| `intent` | `buy`, `sell`, `both`, `rent`, `unknown` |  |
| `lane` | string or null |  |
| `score` | number |  |
| `source` | string |  |
| `tags` | array of string |  |
| `areas` | array of string |  |
| `budgetMin` | number or null |  |
| `budgetMax` | number or null |  |
| `homeAddress` | string or null |  |
| `custom` | object |  |
| `handled` | boolean | False while a website lead still waits in the Lead Inbox. |
| `createdAt` | date-time |  |
| `lastActivityAt` | date-time |  |
| `lastContactedAt` | date-time or null |  |

## Task

| Field | Type | |
|---|---|---|
| `id` | string |  |
| `title` | string |  |
| `detail` | string or null |  |
| `kind` | `call`, `sms`, `email`, `todo` |  |
| `due` | date-time |  |
| `done` | boolean |  |
| `contactId` | string or null |  |

## Appointment

| Field | Type | |
|---|---|---|
| `id` | string |  |
| `title` | string |  |
| `kind` | string | showing, listing-appt, open-house, closing, inspection, meeting, call or other, or one of the workspace's own appointment types. |
| `startAt` | date-time |  |
| `endAt` | date-time or null |  |
| `location` | string or null |  |
| `contactId` | string or null |  |

## AppointmentDetail

| Field | Type | |
|---|---|---|
| `id` | string |  |
| `title` | string |  |
| `kind` | string | showing, listing-appt, open-house, closing, inspection, meeting, call or other, or one of the workspace's own appointment types. |
| `startAt` | date-time |  |
| `endAt` | date-time or null |  |
| `location` | string or null |  |
| `contactId` | string or null |  |
| `notes` | string or null |  |
| `recurrence` | `daily`, `weekly`, `biweekly`, `monthly` or null |  |
| `recurrenceUntil` | date-time or null | A repeat's last occurrence is at or before this; null repeats for good. |
| `recurrenceSkip` | array of date-time | A repeat's occurrences deleted one at a time, by their start. |
| `timezone` | string or null | The IANA zone it was booked in; a repeat keeps that zone's wall clock. |
| `attendees` | array of string | Seat ids of the teammates on it. |
| `createdBy` | string or null |  |

## Transaction

| Field | Type | |
|---|---|---|
| `id` | string |  |
| `property` | string |  |
| `side` | `buyer`, `seller` |  |
| `status` | `active`, `pending-close`, `closed`, `fell-through` |  |
| `customStage` | string or null |  |
| `price` | number or null |  |
| `contactId` | string or null |  |
| `contractDate` | date-time or null | The day, as that day's UTC midnight (2026-12-01T00:00:00.000Z). |
| `closingDate` | date-time or null | The day, as that day's UTC midnight. |

## Envelope

| Field | Type | |
|---|---|---|
| `id` | string |  |
| `title` | string |  |
| `status` | `sent`, `completed`, `declined`, `voided`, `expired` |  |
| `documentId` | string |  |
| `finalDocumentId` | string or null |  |
| `finalSha256` | string or null |  |
| `contactId` | string or null |  |
| `transactionId` | string or null |  |
| `signingOrder` | `parallel`, `sequential` |  |
| `expiresAt` | date-time or null |  |
| `createdAt` | date-time |  |
| `completedAt` | date-time or null |  |
| `recipients` | array of object |  |

## Webhook

| Field | Type | |
|---|---|---|
| `id` | string |  |
| `url` | string |  |
| `events` | array of string |  |
| `active` | boolean |  |
| `description` | string or null |  |
| `createdAt` | date-time |  |
| `lastSuccessAt` | date-time or null |  |
| `lastFailureAt` | date-time or null |  |

## WebhookWithSecret

| Field | Type | |
|---|---|---|
| `id` | string |  |
| `url` | string |  |
| `events` | array of string |  |
| `active` | boolean |  |
| `description` | string or null |  |
| `createdAt` | date-time |  |
| `lastSuccessAt` | date-time or null |  |
| `lastFailureAt` | date-time or null |  |
| `secret` | string | whsec_…; shown this once. |

## TimelineEvent

| Field | Type | |
|---|---|---|
| `id` | string |  |
| `kind` | string | note, call, sms_in, sms_out, email_in, email_out, showing, stage_change, form, site_visit and the rest of the timeline's kinds. |
| `title` | string |  |
| `detail` | string or null |  |
| `at` | date-time |  |

## Flow

| Field | Type | |
|---|---|---|
| `id` | string |  |
| `name` | string |  |
| `description` | string or null |  |
| `enabled` | boolean |  |
| `triggers` | array of string |  |

## Lane

| Field | Type | |
|---|---|---|
| `id` | string |  |
| `label` | string |  |
| `anchor` | `buy`, `sell`, `rent`, `none` |  |
| `count` | integer |  |
| `stages` | array of object |  |

## Report

| Field | Type | |
|---|---|---|
| `volume` | object |  |
| `forecast` | object |  |
| `speedToLead` | object |  |
| `sources` | array of object |  |
| `funnel` | array of object |  |
| `activity30` | array of object |  |
| `engagement` | object |  |

## Thread

| Field | Type | |
|---|---|---|
| `contactId` | string or null | The contact the thread is with; null for a number nobody has saved. |
| `contactName` | string or null |  |
| `phone` | string or null |  |
| `lastChannel` | `sms`, `voicemail`, `call`, `portal`, `email` |  |
| `lastDirection` | `in`, `out` |  |
| `preview` | string |  |
| `lastAt` | date-time |  |
| `unread` | integer |  |
| `muted` | boolean |  |
| `pinned` | boolean |  |
| `done` | boolean |  |

## Message

| Field | Type | |
|---|---|---|
| `id` | string |  |
| `channel` | `sms`, `voicemail`, `call`, `portal`, `email` |  |
| `direction` | `in`, `out` |  |
| `contactId` | string or null |  |
| `seatId` | string or null | Who on the team sent or took it, when known. |
| `from` | string |  |
| `to` | string |  |
| `subject` | string or null | Email only. |
| `body` | string | Plain text: the text message, the call's or voicemail's note, or the email's text. |
| `status` | string or null | Texts and calls: queued, sent, delivered, undelivered, failed or received. Null for email. |
| `at` | date-time |  |

## Document

| Field | Type | |
|---|---|---|
| `id` | string |  |
| `name` | string |  |
| `kind` | `contract`, `disclosure`, `inspection`, `pre-approval`, `addendum`, `policy`, `form-template`, `filled-form`, `site`, `other` |  |
| `status` | `uploaded`, `needs-signature`, `signed`, `missing`, `superseded` |  |
| `mimeType` | string |  |
| `sizeBytes` | integer |  |
| `contactId` | string or null |  |
| `transactionId` | string or null |  |
| `summary` | string or null | The key facts read from it at upload, when there are any. |
| `readable` | boolean | Its text was extracted, so the assistant can read it. |
| `uploadedAt` | date-time |  |

## Tour

| Field | Type | |
|---|---|---|
| `id` | string |  |
| `title` | string |  |
| `status` | `planned`, `done` |  |
| `date` | date-time or null |  |
| `contactId` | string or null |  |
| `createdAt` | date-time |  |
| `stops` | array of [TourStop](https://brokerandagent.com/developers/api/reference/objects#tourstop) |  |

## TourStop

| Field | Type | |
|---|---|---|
| `id` | string |  |
| `order` | integer |  |
| `address` | string |  |
| `lat` | number or null |  |
| `lng` | number or null |  |
| `note` | string or null |  |
| `time` | string or null | As the agent typed it, e.g. 10:00 AM. |
| `price` | number or null |  |
| `beds` | number or null |  |
| `baths` | number or null |  |
| `sqft` | number or null |  |
| `listingUrl` | string or null |  |
| `shown` | boolean |  |

## CalendarEvent

| Field | Type | |
|---|---|---|
| `id` | string | Stable per occurrence: a repeating appointment has one per repeat. |
| `title` | string |  |
| `start` | string | An ISO instant, or a YYYY-MM-DD date when allDay. |
| `end` | string or null |  |
| `allDay` | boolean |  |
| `source` | `appointments`, `tasks`, `transactions` |  |
| `location` | string or null |  |
| `appointmentId` | string or null |  |
| `taskId` | string or null |  |
| `transactionId` | string or null |  |
| `contactId` | string or null |  |
| `outcome` | string or null | Appointments: held, no-show, rescheduled or cancelled, once recorded. |
| `createdBy` | string or null |  |
| `attendees` | array of string |  |

## SmartList

| Field | Type | |
|---|---|---|
| `id` | string |  |
| `name` | string |  |
| `description` | string or null |  |
| `emoji` | string or null |  |
| `count` | integer |  |
| `builtin` | boolean |  |
| `level` | `company`, `team`, `personal` | Whose list it is: "company" (everyone has it), "team" (everyone on that team has it) or "personal" (the key's person alone). Its members are always the people the key's person may see. |

## SmartListMember

| Field | Type | |
|---|---|---|
| `contact` | [Contact](https://brokerandagent.com/developers/api/reference/objects#contact) |  |
| `why` | string | Why they're on the list, in a few words. |

## LibraryItem

| Field | Type | |
|---|---|---|
| `kind` | `email`, `automation`, `design`, `checklist` | An email or text template, an automation, a design template or an office checklist. |
| `id` | string |  |
| `name` | string |  |
| `audience` | string | "workspace" (everyone at the company), a place's id (a region, office or team: everyone at and under it), or "private" (just its maker, not sent anywhere yet). |
| `locked` | boolean | The people it reaches use it as it is and can't change it. |
| `mine` | boolean | The credential's person made it. |
| `mayChange` | boolean | The credential's person may send it somewhere else or lock it (an admin where it's held, or its maker while it's private). |

## LibraryPlace

| Field | Type | |
|---|---|---|
| `id` | string | "workspace", or a place's id. |
| `name` | string |  |
| `kind` | string | workspace, region, office or team. |

## Seat

| Field | Type | |
|---|---|---|
| `id` | string |  |
| `name` | string |  |
| `email` | string |  |
| `role` | `owner`, `admin`, `team-lead`, `agent`, `transaction-coordinator` |  |
| `seatType` | `agent`, `manager`, `transaction-coordinator` or null |  |
| `teamIds` | array of string |  |
| `active` | boolean |  |
| `companyRole` | string |  |
| `primaryOwner` | boolean |  |

## Team

| Field | Type | |
|---|---|---|
| `id` | string |  |
| `name` | string |  |
| `parentTeamId` | string or null |  |
| `kind` | `region`, `office`, `team` |  |
| `members` | array of object |  |

## PondLead

| Field | Type | |
|---|---|---|
| `id` | string | The contact's id. |
| `name` | string |  |
| `source` | string |  |
| `intent` | string |  |
| `areas` | array of string |  |
| `createdAt` | date-time |  |
| `teamId` | string or null | The team whose pond it's in; null for the workspace's own. |

## RoutingRule

| Field | Type | |
|---|---|---|
| `id` | string |  |
| `sources` | array of string | The lead sources it catches; empty catches every source. |
| `kind` | `person`, `round_robin`, `pond` |  |
| `teamId` | string or null | A team rotation's team, or the team whose pond it is. |
| `seatIds` | array of string | Who it deals to today, in turn order: a team rotation's live roster, active seats only. Empty for a pond, or when nobody's left (its leads then wait in the pond). |
| `nextSeatId` | string or null | Who gets the next lead it catches; null for a pond. |
| `when` | object or null | The rule's "Only when…": every condition set must match, and a lead missing a field one needs passes the rule by to the next. Null when it has none. |

## BusinessHours

| Field | Type | |
|---|---|---|
| `days` | array of object | Each open day with its own hours; a day not listed is closed. Unless a workspace changes them: Monday to Friday 9 to 6, Saturday 10 to 4. |
| `timeZone` | string | The workspace's time zone (its owner's). |

## ReviewQueueEntry

| Field | Type | |
|---|---|---|
| `id` | string |  |
| `name` | string |  |
| `kind` | `listing`, `contract`, `custom` |  |
| `waiting` | integer |  |

## ReviewItem

| Field | Type | |
|---|---|---|
| `id` | string | The review's id: answer it with answerReview. |
| `transactionId` | string |  |
| `property` | string |  |
| `itemId` | string | The checklist item's id on the deal. |
| `itemLabel` | string |  |
| `queueId` | string |  |
| `documentId` | string or null | The document attached to the item, if any. |
| `note` | string or null | What the agent said with it. |
| `sentBy` | string or null | The seat that sent it. |
| `sentAt` | date-time |  |
| `round` | integer | 1 for the first send; 2 once it was sent back and sent again, and so on. |
| `precheck` | object or null | The crew's first read of the document as it landed: what it noticed, for the reviewer. A hint; it never approves or sends anything back. Null when none ran. |

---

Source: https://brokerandagent.com/developers/api/reference/objects
