Object schemas

Every field of every object, read from the serializers the server runs.

Every object the API returns. A field that is not in these tables is not on the wire.

workspace member lead reply attachment message note task_sequence task meeting event_type event_type_host event_type_form_field slot availability template template_folder asset sequence sequence_step enrollment campaign_tag campaign rep_stat speed_bucket insights_summary campaign_step campaign_insight daily_point

Reading these tables

• Every object has an object field naming its type, so a mixed list is still parseable.
• string | null means the field is always there and can be null. Optional means the key can be missing, which is how expansions work.
• Ids are opaque. The prefix gives the kind: lead_, rep_, msg_, tsk_, mtg_, note_, tpl_, evt_, seq_, ast_, cmp_, usr_. A workspace id is its slug.
• Timestamps are ISO 8601 UTC. Days are YYYY-MM-DD.

How much to trust a field

Every field in every object schema carries a determinism class. This is the single change that keeps a caller from writing code that looks right and is quietly wrong.

Three fields on lead are key-scoped and it matters. has_open_task, next_due_at, and unread all come from rollups that filter on the viewer. the app:

eq(sql`coalesce(${schema.tasks.assignedToId}, ${schema.tasks.userId})`, opts.viewerId),

Two keys owned by two different people get different answers for the same lead, and neither answer is "does this lead have open work". Marking them key-scoped in the field table forces a caller to reason about it. The alternative, silently returning one person's view as if it were the truth, is how a report ends up wrong.

Never returned

These columns are left out of every response, expansion and error message.

The objects

workspace

id is the SLUG, not clients.id. The slug is already the public handle everywhere in this product (it is in every internal URL), it is stable, and it reads well in a caller's code. clients.id is a serial that appears inside signed object ids and never on its own.

synced_at is published under its real name. It is when the sync-eb-workspaces cron last reconciled the workspace against EmailBison, so calling it created_at would invent a meaning for a value that moves every six hours.

counts and sdr_notes are present only when the caller asked for them via ?include=.

member

email is users.google_email: the table has no email column, the sign-in identity is the Google address.

role goes through normalizeRole, which returns only admin or user. Seven legacy values still sit in the column (internal_sdr, client_sdr, client_viewer, client_ae, sdr, client, client_sdr_airpay) and all fold to user, so a caller never has to know they existed.

active is the boolean form of deactivated_at. The timestamp itself stays private: when a person was offboarded is nobody's business outside the agency.

assignment is set only on GET.../leads/{lead}/assignees, where the two extra fields describe the assignment rather than the person.

lead

A lead is a group of reply rows, collapsed to its newest.

responded, unread, has_open_task and next_due_at are resolved for the key's owner, so two keys held by two people report different values for the same lead. responded is team-wide instead.

campaign_id and campaign_name are null far more often than a caller expects. A background job fills them in within 15 minutes, and historical rows stay null with no backfill.

reply

One indexed inbound email, the atomic unit responses_index is keyed on. The full conversation lives at /messages.

status is the raw per-reply last_action, lowercased the same way as a lead's but nullable here, because at the reply level "no tag" is genuinely absent rather than the untagged lifecycle state.

attachment

A filename and an opaque id. That is the whole object.

ReplyAttachment is { id, uuid?, file_name, download_url }. There is no size and no content type in EmailBison's payload, so neither is invented. download_url is withheld: it is a signed EmailBison link whose signature covers the exact path, which makes it a bearer capability, and handing one to a third-party integration gives that integration the file. Downloading needs a proxied endpoint with its own auth, which is v3.

message

One message in a lead's merged timeline.

kind comes from the sign of the raw id. buildLeadThreadMessages synthesizes a campaign send as -e.id so it cannot collide with a real reply id during dedupe, which makes the sign the only marker of provenance. The negative integer itself is never surfaced.

direction and sent_at are delegated to thread-direction.ts and must not be reimplemented. That module exists to kill two live bugs: matching the sender against the stored lead email mislabels a lead who replies from a different address, and EmailBison's date_received on an OUTGOING message is a delivery stamp 6 to 23 minutes late, which sorted a quick reply before the message it answered.

body_text is derived. There is no plaintext column anywhere in the read path: EbThreadMessage has no text_body, so this is htmlToText(html_body), which collapses tags and is explicitly not a sanitizer. Good enough for a model to read, wrong for rendering.

to_email is usually null on a real reply. It comes from primary_to_email_address, which only the synthesized campaign sends carry.

note

task_sequence

task

Four columns this object claims do not exist on tasks, and each absence is load-bearing.

There is no client_id. The tenant is derived through response_id -> responses_index.client_id, and every query adds isNotNull(response_id) because response_id is nullable so a task can hang off a dead CRM company_id instead. Those rows have no lead, no reply and no derivable workspace, so they are invisible to the API. That is also why reply_id here is non-null.

There is no status. Open is completed_at IS NULL AND deleted_at IS NULL. Soft-deleted rows are filtered out of the query and never surface as a status.

There is no title. The only source is followup_sequence_steps.title, so a manually created task is always null here. The field stays in the shape so a caller does not have to branch, and writes reject it outright rather than accepting it and dropping it.

assignee_id is coalesce(assigned_to_id, user_id).

sequence is the only sanctioned view of the materialization internals. The raw sequence_id, enrollment_id, sequence_step_id, email_template_id, email_body and linkedin_text are all withheld.

meeting

host_id is assigned_ae_id, the round-robin-picked host whose calendar holds the event. booked_by_id is the operator who ran the booking form, which for a calendar booking is usually not the host. Keeping them apart matters for attribution: insights credit bookings to booked_by_id.

custom_fields keys are event_type_form_fields.field_key values.

Times can lag a host-side reschedule by up to 15 minutes, because the API read path deliberately skips syncUpcomingMeetingTimes: that helper makes a live Google or Microsoft call per row and writes corrected times back, which is a per-row cost on a per-request budget and burns the host's OAuth quota on a read.

meet_link and google_event_html_link are never returned in v1. Both are join capability URLs: anyone holding one can walk into the client's sales call. internal_notes is passed only on the single-object read and only for a key holding meetings:write; its schema comment is the most explicit internal-only marker in the whole database.

event_type

default_field_config is stored as {} when the built-in defaults apply, so this resolves it through resolveDefaultFieldConfig and always returns the concrete map. A caller never has to know the empty-object convention.

public_url is null when no public origin is configured, rather than a localhost link a caller would send to a prospect.

external_id is withheld: it is a provider-side event-type id that is only useful paired with the workspace's connector credential, so publishing it moves half of a credential pair outside the building. exclude_from_insights is an internal reporting flag. The whole of event_type_email_settings stays private: the subject and body templates are internal copy and host_notify_user_ids is internal routing.

event_type_host

member_id is the opaque form of event_type_hosts.user_id.

event_type_form_field

slot

A start and an end, and nothing else, deliberately. No host identity on a slot, so a caller cannot enumerate who on the team is free when, which is private calendar information about a person rather than a fact about the workspace.

availability

reason carries a short cause when slots is empty and the cause is knowable (outside_booking_window, no_active_hosts, no_calendar_connected), so a caller can tell "nothing free" from "misconfigured".

Raw calendar busy blocks are never returned. They are the host's private calendar, and the free slots are the only part that is the caller's business.

template

body is the RAW template, unresolved {{tokens}} and all. Never send it as an email: POST.../templates/{id}/render exists for exactly that, and it is the single most likely way an agent damages a client.

scope exists because of a real cross-tenant quirk. visibleWhere in the templates route returns every row with visibility = "global" from ANY workspace, with no client_id bound on that branch, so a list under one workspace legitimately contains rows owned by another. Rather than hide that, scope names it and a global template reports workspace: null, which keeps the nested-path invariant from being quietly broken.

visibility null is reported as workspace, matching how every read path in the app already treats it, so a caller never has to handle a third state that means the same as the second.

ai_variables exposes name and read_website only. instructions is withheld: it is free-text model instructions, which is internal copy and a prompt-injection surface if a caller can read and echo it. reply_templates.group is withheld as legacy bucketing superseded by folder_id.

template_folder

asset

url carries the link for loom, doc and link; body carries the snippet for text and is null otherwise.

client_assets.visibility has only TWO values, private and workspace. There is no global, unlike reply_templates.visibility and followup_sequences.visibility, which have three. An agent that learned visibility on templates and sends global here gets a 422, and GET /v1/capabilities calls the difference out.

Rows with visibility: "private" are filtered to the key's owner in the query, not here.

sequence

Both forms of the sending window are returned. send_days is readable and send_days_mask is the value a write would have to send back, and these pages say the basis is UTC: a sequence set to weekdays fires on UTC weekdays, not the rep's.

followup_sequences.deleted_at is withheld and soft-deleted rows are filtered out of the query, so a caller never sees a tombstone.

sequence_step

wait_for_previous is the column wait_for_prev, spelled out on the wire.

enrollment

followup_enrollments.client_id is notNull with NO foreign key, so the read path filters it and ALSO joins responses_index through response_id, which does carry a cascading foreign key. The raw column is withheld.

campaign_tag

These ids are the match key for assignment_rules.tag_ids and sdr_note_sets.tag_ids, both matched by Postgres array overlap.

campaign

Proxied live from EmailBison with the per-workspace token from clients.eb_token. That token is stored in PLAIN TEXT, which is exactly why this is a hand-written five-field mapper and never a spread of an upstream response: no field EmailBison invents tomorrow can arrive on the wire by accident, and the token cannot ride along in a response, an error or a log.

The tags here are the inline { id, name } form, not full campaign_tag objects, so a campaign row does not carry a count nobody asked for.

rep_stat

RepStat.image is dropped: an avatar URL belongs on a member, and repeating it in an aggregate invites a caller to build a directory out of a report.

The booking-rate inputs are approximate and these pages say so. Interested is attributed through action_log and booked through scheduled_meetings.booked_by_id, and those two can disagree for the same rep.

speed_bucket

insights_summary

EVERY RATE IS A RATIO IN [0,1], never a percentage. A caller that multiplies by 100 twice is a documentation failure, and the way to avoid it is to never ship a percent.

meetingsTimeline and bookingTimeline are NOT included. Both are fixed "last 12 ISO weeks" series that ignore the requested window, so returning them next to a windowed funnel would put two different time ranges in one object. GET /insights/daily is the windowed series.

speed_to_lead is deploy-forward only: lead_response_times rows exist from the day the feature shipped, so a window reaching earlier under-counts.

generated_at is passed in as a JS Date. Never now() in SQL: every timestamp column here is timestamp without time zone read back as UTC, so a SQL now() writes local wall-clock and lands hours off.

campaign_step

step_id is EbSequenceStepStat.sequence_step_id, a CADENCE step id, and it is the one raw upstream integer in the whole API. It is published because a caller comparing two runs needs to line the rows up, and it is not sensitive: it names a step inside a campaign the caller can already read. It is NOT durable, though. Removing a variant in EmailBison resets per-variant ids and breaks historical metrics, which is a documented production hazard.

campaign_insight

The array is steps, not variants, on purpose. They come from EmailBison sequence steps, and the UI's "Variant A" labels are preserved, but calling the array variants would invite every consumer to read it as A/B test output. EmailBison stamps a reply with its campaign and not with the variant that produced the sent email, so there is no per-step booked or showed and none is invented.

There is no unique_opens. Every campaign ships open_tracking: false, so the number does not exist and a null field would only invite someone to chart it.

bounced here is a reporting number, not the deliverability gate the daily diagnosis runs on.

clientSlug and clientName from CampaignStat are dropped: the workspace is already in the request path, and repeating it per row is how a cross-client report gets built by accident.

daily_point

date is a UTC calendar day and the series is DENSE: a day with no activity comes back as zeros rather than being omitted, so a caller can chart it without gap-filling.