Leads, tenders and accounts
The services behind Leads (people and public tenders), AI calls, agency clients and
Settings › Integrations. Package pulse.v1; the least role of each method
is in its table. See Leads and
Connections.
Notes
- Integrations are the caller’s own rows, so reading them is open to a
viewer and changing them needs an editor, not an admin. HubSpot and GitHub
connections go through the shared
ConnectionsServiceinstead; see Shared components. - Sign-in connections.
StartSocialConnectreturns the consent address forinstagram,youtubeorlinkedin(company_pagesadds the LinkedIn page scopes whenLINKEDIN_COMPANY_PAGESis on). The platform returns to/oauth/social/callback, which seals the tokens. The answer isconfigured=falsewith amessagewhen the server has no app client or no httpsPULSE_PUBLIC_BASE_URL.ListSocialConnectionsreports one status per platform and, per feature, the permissions needed and granted.DisconnectSocialrevokes the grant at the platform where its API allows, then deletes the sealed tokens. See Setup. - Outbound.
SendOutreachEmailneedsPULSE_PUBLISH_EMAILarmed and a connected mailbox;AICallService.PlaceAICall, the one RPC that calls a lead, needsPULSE_OUTBOUND_CALLS,PULSE_AI_CALLSand the lead’s recorded consent. See Switches and arming order. - Agencies. A client is its own owner id. Sending
x-pulse-clientwith a client the caller is a member of makes that client the caller. - Public tenders (the tender cards on the Leads board) are read from open procurement data; nothing is sent or submitted. Their service keeps its older proto name.
LeadService
Synced CRM leads — currently HubSpot contacts. ListLeads reads the local cache table; SyncLeads triggers a live pull from the configured CRM integration (see IntegrationService above for how the access token is stored) and upserts into that cache.
pulse.v1.LeadService, declared in pulse.proto.
| Method | Request → Response | Least role | Notes |
|---|---|---|---|
SyncLeads | SyncLeadsRequest → SyncLeadsResponse | editor | SyncLeads pulls the latest contacts from the connected CRM (HubSpot) and upserts them into the local leads cache. |
ListLeads | ListLeadsRequest → ListLeadsResponse | viewer | ListLeads returns paginated, previously-synced leads. |
CreateLead | CreateLeadRequest → Lead | editor | CreateLead captures a new lead by hand or from a web form / intake — customer acquisition, not just CRM mirroring. |
UpdateLeadStage | UpdateLeadStageRequest → Lead | editor | UpdateLeadStage moves a lead through the acquisition pipeline (new → contacted → qualified → won / lost). |
GenerateOutreach | GenerateOutreachRequest → stream StreamChunk | editor | GenerateOutreach AI-drafts a personalized cold-outreach asset for a lead (email, cold-call script, or LinkedIn DM), grounded in the lead + an optional diagnosis, and persists it. Streams tokens like GenerateContent. |
ListOutreach | ListOutreachRequest → ListOutreachResponse | viewer | ListOutreach returns the outreach drafts generated for a lead. |
ScrapeLeads | ScrapeLeadsRequest → stream StreamChunk | editor | ScrapeLeads finds NEW prospects on the public web for a niche (chromedp + gocolly), drafts a targeted cold-call script, email, and social DM for each (grounded in the diagnosis), persists them, and pushes them to the connected HubSpot contact list. Streams progress like GenerateOutreach. |
SetLeadDeal | SetLeadDealRequest → Lead | editor | SetLeadDeal sets (or clears) a lead’s deal value at any stage. |
GetLeadRevenue | GetLeadRevenueRequest → LeadRevenue | viewer | GetLeadRevenue: open pipeline value per stage and won revenue for a period, per currency. A read; it spends nothing. |
GetWebsiteForm | GetWebsiteFormRequest → WebsiteForm | viewer | Website form (inbound enquiries → leads). The link is public: anyone with its secret may post an enquiry to /inbound/leads/{secret}. Only the secret’s hash is stored, so the secret is returned once, by Rotate. |
RotateWebsiteForm | RotateWebsiteFormRequest → WebsiteFormSecret | editor | RotateWebsiteForm creates the link, or replaces its secret (the old link stops working at once). |
SetWebsiteFormOrigins | SetWebsiteFormOriginsRequest → WebsiteForm | editor | SetWebsiteFormOrigins lists the sites (https://host[:port]) whose pages may post to the link; a browser post from any other origin is refused. |
DisableWebsiteForm | DisableWebsiteFormRequest → WebsiteForm | editor | DisableWebsiteForm turns the link off. |
GetEmailSendReadiness | GetEmailSendReadinessRequest → EmailSendReadiness | viewer | GetEmailSendReadiness says whether SendOutreachEmail can send right now for the caller, and if not, why. |
SendOutreachEmail | SendOutreachEmailRequest → SendOutreachEmailResponse | editor | SendOutreachEmail sends one email to a lead from the caller’s OWN connected mailbox (Gmail, Microsoft 365 or SMTP), records it in outreach_sends and moves a new lead to contacted. Behind PULSE_APPLY_ENABLED and PULSE_PUBLISH_EMAIL; refused as “withheld”. |
CheckReplies | CheckRepliesRequest → CheckRepliesResponse | editor | CheckReplies looks now for replies to the caller’s sent emails (the background tracker also does, every 15 minutes) and marks replied leads. |
SkipLeadStep | SkipLeadStepRequest → Lead | editor | SkipLeadStep puts the lead’s next step off by one day (To do today’s “Skip”); the step itself is unchanged. |
GetLeadSearchDefaults | GetLeadSearchDefaultsRequest → LeadSearchDefaults | viewer | GetLeadSearchDefaults is what the caller’s latest audit found, for the Find new leads fields: the niche, who buys, the region when one is known and the competitors. Empty fields were not found, never guessed. |
ListOutreachSends | ListOutreachSendsRequest → ListOutreachSendsResponse | viewer | ListOutreachSends is a lead’s contact history: every email send attempt (sent, withheld or failed), newest first, with what was found of a reply, and every automatic WhatsApp/SMS reply (auto_reply). A read; it spends nothing. |
Also uses StreamChunk, PaginationRequest, PaginationResponse, AssistantToolEvent, AssistantProposal.
message ListOutreachSendsRequest {
string lead_id = 1;
}
message OutreachSendRecord {
string id = 1;
string lead_id = 2;
string channel = 3; // "email" | "whatsapp" | "sms"
string status = 4; // sent | withheld | failed
string reason = 5; // why it was withheld or failed
// The lead's address as it is now: a send row keeps no address.
string recipient = 6;
// The sent draft's subject; "" when the send kept no draft.
string subject = 7;
google.protobuf.Timestamp sent_at = 8;
// "" not checked yet | none | replied | not_tracked | read_not_granted
string reply_state = 9;
google.protobuf.Timestamp replied_at = 10;
string reply_snippet = 11;
// An automatic WhatsApp or SMS reply to the lead's inbound message
// (whatsapp.go): every one is logged here, sent or not. received is what
// the lead sent, body what PULSE replied; both sealed at rest.
bool auto_reply = 12;
string received = 13;
string body = 14;
}
message ListOutreachSendsResponse {
repeated OutreachSendRecord sends = 1;
}
// The newest HubSpot import of the caller: running, ok (with how many
// contacts) or failed (with why). Unset on ListLeadsResponse = never synced.
message LeadSyncStatus {
string platform = 1; // "hubspot"
string state = 2; // running | ok | failed
google.protobuf.Timestamp started_at = 3;
google.protobuf.Timestamp finished_at = 4;
int32 synced_count = 5; // state ok only
string reason = 6; // state failed only
string trigger = 7; // "connect" (right after connecting) | "manual"
}
message CheckRepliesRequest {}
message CheckRepliesResponse {
int32 checked = 1; // sends looked at
int32 replied = 2; // new replies found
// "tracked" | "read_not_granted" (reconnect and allow reading) |
// "not_tracked" (SMTP: no inbox to read) | "no_mailbox" | "error".
string state = 3;
string reason = 4;
}
message GetWebsiteFormRequest {}
message RotateWebsiteFormRequest {}
message DisableWebsiteFormRequest {}
message SetWebsiteFormOriginsRequest {
repeated string allowed_origins = 1;
}
message WebsiteForm {
bool enabled = 1;
repeated string allowed_origins = 2;
google.protobuf.Timestamp created_at = 3;
// Unset until the first enquiry arrives.
google.protobuf.Timestamp last_received_at = 4;
}
message WebsiteFormSecret {
WebsiteForm form = 1;
// The link's secret. Shown once; PULSE keeps only its hash.
string token = 2;
// `/inbound/leads/{token}`, relative to this backend.
string endpoint_path = 3;
// Absolute URL when PULSE_PUBLIC_BASE_URL is set, else empty.
string endpoint_url = 4;
}
message GetEmailSendReadinessRequest {}
message EmailSendReadiness {
bool can_send = 1;
// blocked_by when can_send is false: "switch_off" | "no_mailbox" |
// "mailbox_error" | "daily_limit" | "role".
string blocked_by = 2;
string reason = 3;
string provider = 4; // "gmail" | "microsoft365" | "smtp", "" with no mailbox
string from_address = 5;
int32 sent_last_day = 6; // emails SENT in the last 24 hours
int32 daily_limit = 7;
// Whether replies to sends from this mailbox can be read.
bool replies_tracked = 8;
// Why not, when replies_tracked is false: "reconnect" (the mailbox was
// connected without the read permission) | "smtp" (no inbox to read) | "".
string replies_note = 9;
}
message SendOutreachEmailRequest {
string lead_id = 1;
// A saved email draft of this lead (ListOutreach), or subject + body.
string draft_id = 2;
string subject = 3;
string body = 4;
// A marketing (not 1:1) send: adds a List-Unsubscribe header. Default 1:1.
bool marketing = 5;
}
message SendOutreachEmailResponse {
string status = 1; // "sent" | "withheld" | "failed"
string reason = 2; // why, when not sent
string provider = 3;
string from_address = 4;
string provider_message_id = 5;
google.protobuf.Timestamp sent_at = 6;
string pipeline_stage = 7; // the lead's stage after the send
string send_id = 8; // the outreach_sends row
}
message SyncLeadsRequest {
string platform = 1; // "hubspot" — the only supported source today
}
message SyncLeadsResponse {
int32 synced_count = 1;
google.protobuf.Timestamp synced_at = 2;
}
message ListLeadsRequest {
PaginationRequest pagination = 1;
string lifecycle_stage_filter = 2; // e.g. "lead", "marketingqualifiedlead" — empty = all
}
message ListLeadsResponse {
repeated Lead leads = 1;
PaginationResponse pagination = 2;
// The newest HubSpot import; unset when the caller never synced.
LeadSyncStatus last_sync = 3;
}
// Lead is a synced CRM contact — deliberately a thin, read-mostly local
// cache of what the CRM already tracks, not a PULSE-owned lead-scoring
// model (avoids the two systems disagreeing about what a lead even is).
message Lead {
string id = 1;
string platform = 2; // "hubspot"
string external_id = 3; // the CRM's own contact ID
string email = 4;
string first_name = 5;
string last_name = 6;
string company = 7;
string lifecycle_stage = 8; // CRM's own lifecycle stage string, shown as-is
string lead_status = 9;
google.protobuf.Timestamp crm_created_at = 10;
google.protobuf.Timestamp last_synced_at = 11;
// PULSE acquisition-pipeline stage: "new","contacted","replied",
// "meeting_booked" (outreach.proto moves a lead there),"qualified","won","lost".
string pipeline_stage = 12;
string phone = 13;
string title = 14; // job title / role
string notes = 15;
string source = 16; // "hubspot","manual","webform"
// The deal's value in minor units of `currency` (cents for EUR). Unset =
// not valued yet, which is not a value of 0.
optional int64 deal_value_minor = 17;
string currency = 18; // ISO 4217, e.g. "EUR"
// When the lead last moved to "won"; unset for any other stage.
google.protobuf.Timestamp won_at = 19;
// The next follow-up step PULSE suggests for the lead's stage:
// "first_message" (new), "follow_up" (contacted), "book_call" (qualified),
// or "" for won/lost. next_step_due is when, counted from the stage change
// (1, 3 and 2 days); a cadence PULSE sets, not a date anyone agreed.
string next_step = 20;
google.protobuf.Timestamp next_step_due = 21;
// When the newest reply to an email PULSE sent this lead arrived; unset =
// no reply found (or replies are not tracked for the mailbox).
google.protobuf.Timestamp replied_at = 22;
string reply_snippet = 23; // a short plain snippet of that reply
// How PULSE would take next_step for the user: "email", "ai_call",
// "whatsapp" or "sms", chosen from what the lead record holds (an address
// for email, a number for a call or a message); "" = no way to reach them.
string next_channel = 24;
// Where phone came from ("" = not recorded: PULSE never messages it).
string phone_source = 25;
// The number replied STOP to PULSE's messaging sender (and not START since):
// no WhatsApp or SMS is sent to it.
bool messaging_opted_out = 26;
// Why the stored address is not usable ("" = it is, or there is none): a
// placeholder or garbled address kept from before PULSE checked them. Such
// a lead gets no email task.
string email_problem = 27;
// Why next_step_due is not the stage's cadence: "skipped" (put off to
// tomorrow on To do today) | "churn_risk" (the daily check rated the lead
// likely to stall and brought the step forward) | "" (the cadence).
string next_step_reason = 28;
// The churn check's last verdict: "high" | "medium" | "low"; "" = never
// checked or no usable verdict (not "low").
string churn_risk = 29;
// Its one-line reason, in the model's words; "" when it gave none.
string churn_reason = 30;
// When the check last looked at this lead; unset = never.
google.protobuf.Timestamp churn_checked_at = 31;
}
message CreateLeadRequest {
string first_name = 1;
string last_name = 2;
string email = 3;
string company = 4;
string phone = 5;
string title = 6;
string notes = 7;
string source = 8; // default "manual"
}
message UpdateLeadStageRequest {
string id = 1;
string pipeline_stage = 2;
// Moving to "won" needs a deal value: this one, else the lead's own. The
// currency is this one, else the lead's, else the account's billing
// currency when one is on record; with none, the move is refused.
optional int64 deal_value_minor = 3;
string currency = 4;
}
message SetLeadDealRequest {
string id = 1;
// Unset clears the value.
optional int64 deal_value_minor = 2;
string currency = 3; // ISO 4217; required with a value unless the lead has one
}
message GetLeadRevenueRequest {
// Won revenue counts leads whose won_at is in [won_from, won_to). Both
// unset = the current calendar month (UTC) up to now.
google.protobuf.Timestamp won_from = 1;
google.protobuf.Timestamp won_to = 2;
}
// One stage's open value in one currency. currency "" counts the stage's
// leads that have no deal value (total_minor is then 0 and is not a figure).
message LeadStageValue {
string stage = 1;
string currency = 2;
int64 total_minor = 3;
int32 lead_count = 4;
int32 minor_units = 5; // digits after the decimal point for currency
}
message LeadCurrencyTotal {
string currency = 1; // "" = won deals with no value
int64 total_minor = 2;
int32 deal_count = 3;
int32 minor_units = 4;
}
message LeadRevenue {
// Open stages only: new, contacted, qualified.
repeated LeadStageValue pipeline = 1;
// Won in the period, per currency (amounts in different currencies are
// never added together).
repeated LeadCurrencyTotal won = 2;
google.protobuf.Timestamp won_from = 3;
google.protobuf.Timestamp won_to = 4;
// Won leads with no won_at (moved to won before it was recorded): in no
// period, counted here so they are not silently lost.
int32 won_undated = 5;
// The account's billing currency when one is on record, else "".
string default_currency = 6;
}
message GenerateOutreachRequest {
string lead_id = 1;
string channel = 2; // "email","call_script","linkedin_dm"
string diagnostic_id = 3; // optional — grounds the pitch in a diagnosis
string additional_context = 4;
string tone = 5; // "professional","casual","bold","consultative"
string language = 6; // e.g. "en", "pt-BR"
}
message LeadOutreach {
string id = 1;
string lead_id = 2;
string channel = 3;
string subject = 4; // populated for email
string body = 5;
google.protobuf.Timestamp created_at = 6;
}
message ListOutreachRequest {
string lead_id = 1;
}
message ListOutreachResponse {
repeated LeadOutreach outreach = 1;
}
message ScrapeLeadsRequest {
string niche = 1; // what to prospect for, e.g. "logistics SaaS"
string region = 2; // optional geographic focus
int32 max_results = 3; // cap on new leads to pull (default 10)
string diagnostic_id = 4; // ground the outreach drafts in this diagnosis
// Who buys ("food manufacturers, building materials distributors, 3PLs").
// Given (or found on the named diagnosis), the search looks for the
// companies that BUY, with the niche's sellers excluded; without it, it
// searches the niche, which finds the companies that sell it.
string target_audience = 5;
string competitors = 6; // names or domains to exclude, comma separated
}
message SkipLeadStepRequest {
string id = 1;
}
message GetLeadSearchDefaultsRequest {}
message LeadSearchDefaults {
string niche = 1; // the latest audit's niche
string who_buys = 2; // "who buys from you", as the wizard was told
string region = 3; // "" = no region known
repeated string competitors = 4; // named by the owner, then found by the audit
string diagnostic_id = 5;
string run_id = 6; // the audit these came from; "" = no audit yet
// How region was found: the check on the site that measured it, or "your
// answer in the check-up"; "" when region is "".
string region_source = 7;
}InboundService
InboundService — Leads › Inbound (owner, 2026-11-06): the people who came to the business, from the sources PULSE already has, each scored for FIT (against who the check-up and Tune say buys) and INTENT (source, page, recency, reply), every point with its reason. Scores are computed when read; only the person’s decisions (accept for sales, disqualify, requalify) are stored. Won and Lost are the lead’s own pipeline stage.
pulse.v1.InboundService, declared in growth_plan.proto.
| Method | Request → Response | Least role | Notes |
|---|---|---|---|
ListInbound | ListInboundRequest → InboundBoard | viewer | |
SetInboundStatus | SetInboundStatusRequest → InboundLead | editor |
Also uses GrowthReasoned, ReasonStep, BenchmarkSource.
message ListInboundRequest {}
message SetInboundStatusRequest {
string lead_id = 1;
// qualified | sales_accepted | disqualified | new | won | lost
string status = 2;
string reason = 3; // required for disqualified
}
message InboundBoard {
repeated InboundSource sources = 1;
repeated InboundLead leads = 2;
// Who the scores compare against, each with its source.
repeated InboundIcpItem icp = 3;
string audit_run_id = 4; // the check-up the profile comes from ("" = none)
// The qualification bars, reasoned for this business (fit_bar, intent_bar).
repeated GrowthReasoned bars = 5;
}
message InboundSource {
// website_form | hubspot | google_analytics | mailbox_replies
string key = 1;
// connected | not_connected | no_data | unreadable
string state = 2;
int32 leads = 3; // inbound leads it brought (people sources)
google.protobuf.Timestamp last_at = 4;
string detail = 5; // the error, when unreadable
string connect_route = 6; // where to connect it
// Google Analytics only: conversions in the last 28 days, site-wide (GA
// does not name the people). Unset = not read.
optional int32 conversions = 7;
}
message InboundIcpItem {
string kind = 1; // segment | industry | offering | competitor | region
string value = 2;
string source = 3; // tuning | audit | site
}
message InboundReason {
string factor = 1; // segment | role | company_size | offer | competitor | email | source | page | recency | reply
int32 points = 2;
int32 max_points = 3;
bool measured = 4; // false: not counted; code says why
// The evidence: the words that matched, the page, the date.
string detail = 5;
// Why these points, for the page to say: match | no_match | no_profile |
// no_text | decision_maker | title_only | no_title | no_size | offer_named |
// no_offerings | no_message | competitor | email_problem | website_form |
// hubspot | intent_page | any_page | no_page | days_7 | days_30 | days_90 |
// older | no_date | replied | no_reply | replies_not_tracked
string code = 6;
}
message InboundLead {
string lead_id = 1;
string name = 2;
string company = 3;
string email = 4;
string title = 5;
string source = 6; // website_form | hubspot
string page = 7; // the page the enquiry came from ("" = not sent)
google.protobuf.Timestamp arrived_at = 8;
bool fit_measured = 9;
int32 fit = 10; // 0..100 over the measured factors
repeated InboundReason fit_reasons = 11;
bool intent_measured = 12;
int32 intent = 13;
repeated InboundReason intent_reasons = 14;
// new | contacted | replied | meeting_booked | qualified | sales_accepted |
// won | lost | disqualified (contacted, replied and meeting_booked are the
// lead's own stage, moved by outreach)
string status = 15;
// Why the status: by_scores | below_scores | fit_not_measured |
// intent_not_measured | competitor | email_problem | pipeline | by_hand
string status_reason = 16;
bool status_by_hand = 17; // false: set by the scores or the pipeline
// reply_within_day | book_call | send_proposal | none
string next_action = 18;
google.protobuf.Timestamp next_due = 19;
string pipeline_stage = 20;
// The person's own words for a status set by hand, or the evidence of an
// automatic one (the competitor's name, the address problem).
string status_note = 21;
int32 fit_bar = 22; // the bars this status was decided with
int32 intent_bar = 23;
}OutreachService
OutreachService — one outreach sequence per lead, from the first touch to a booked meeting (owner, 2026-11-06: “the email automation part managing cold calls until they become meeting prospects”). Cold email, timed follow-ups, CALL tasks for a person (talking points drafted from the lead and the check-up; the call goes through the existing Call command), a LinkedIn touch as a task.
The rules a reader can rely on: * Nothing is sent without approval: every email is a draft until the person approves it (each step, or the rest of the sequence after the first approval, as they chose). Sending is from the person’s OWN connected Gmail or Microsoft 365 mailbox and still needs every publish switch (PULSE_APPLY_ENABLED, PULSE_PUBLISH_EMAIL). * Every email carries the sender’s identity, a postal address and a one-click unsubscribe link, added by PULSE, never by the model; an email missing one is refused by the compliance check. * A sequence stops by itself on a reply, a bounce, an unsubscribe or a booked meeting. An unsubscribe goes on the suppression list and stops every sequence to that address. * Sends keep the per-mailbox daily cap and the lead’s working hours (no weekends, no nights). * Only B2B addresses found legitimately (the business’s own site or form, the CRM, a published notice) are sequenced.
pulse.v1.OutreachService, declared in outreach.proto.
| Method | Request → Response | Least role | Notes |
|---|---|---|---|
GetOutreach | GetOutreachRequest → OutreachBoard | viewer | GetOutreach returns the settings, the sequences (one lead’s, or all) and the loop’s spec. |
StartSequence | StartSequenceRequest → OutreachSequence | editor | StartSequence starts (or returns) the lead’s sequence. Its steps are laid out from the reasoned cadence; the first email is drafted for approval. Refused for an address that is suppressed, not B2B or not found legitimately. |
SetSequenceState | SetSequenceStateRequest → OutreachSequence | editor | SetSequenceState pauses, resumes or stops a sequence. |
ApproveStep | ApproveStepRequest → OutreachSequence | editor | ApproveStep approves one drafted email (with the person’s edits). Every email needs its own approval, per_sequence too: a later email is drafted at its due time, so approve_rest (recorded as rest_approved) never approves a text nobody has seen. |
CompleteStep | CompleteStepRequest → OutreachSequence | editor | CompleteStep marks a call or LinkedIn task done or skipped, and can record the meeting the call booked. |
SaveOutreachSettings | OutreachSettings → OutreachSettings | editor | SaveOutreachSettings saves the sender identity, postal address, booking link or times, daily cap and working hours. |
Suppress | SuppressRequest → OutreachBoard | editor | Suppress adds an address to the suppression list (stops its sequences). |
ListMeetings | ListMeetingsRequest → ListMeetingsResponse | viewer | ListMeetings lists the meetings outreach booked. |
Also uses GrowthReasoned, ReasonStep, BenchmarkSource.
message GetOutreachRequest {
string lead_id = 1; // "" = every sequence
}
message StartSequenceRequest {
string lead_id = 1;
string approval_mode = 2; // per_step (default) | per_sequence
string plan_action_id = 3; // the 90-day plan's action it serves, if any
}
message SetSequenceStateRequest {
string sequence_id = 1;
string action = 2; // pause | resume | stop
}
message ApproveStepRequest {
string step_id = 1;
string subject = 2; // "" = as drafted
string body = 3; // "" = as drafted
bool approve_rest = 4;
}
message CompleteStepRequest {
string step_id = 1;
string outcome = 2; // done | skipped
bool meeting_booked = 3;
google.protobuf.Timestamp meeting_at = 4;
}
message SuppressRequest {
string email = 1;
string reason = 2;
}
message ListMeetingsRequest {}
message OutreachSettings {
string sender_name = 1;
string postal_address = 2;
string booking_link = 3;
string available_times = 4; // free text, e.g. "Tue/Thu 10:00-12:00"
int32 daily_cap = 5; // emails a day from sequences
int32 daily_cap_max = 6; // the server's per-mailbox limit (read only)
int32 sent_today = 7; // read only
string mailbox_address = 8; // read only
string mailbox_provider = 9; // read only: gmail | microsoft365 | "" none
bool can_send = 10; // read only
string blocked_reason = 11; // read only
int32 work_start_hour = 12; // lead's local time, default 8
int32 work_end_hour = 13; // default 18
int32 utc_offset_minutes = 14; // the leads' time zone when not known per lead
int32 suppressed = 15; // read only: addresses on the suppression list
}
message OutreachStep {
string id = 1;
int32 position = 2;
string kind = 3; // email | call | linkedin
string purpose = 4; // cold | follow_up | meeting | call | linkedin
google.protobuf.Timestamp due_at = 5;
// planned | awaiting_approval | approved | sent | done | skipped |
// withheld | failed | cancelled
string status = 6;
string subject = 7;
string body = 8; // the draft, without the footer
string footer = 9; // what PULSE adds: sender, address, unsubscribe
repeated string talking_points = 10;
string reason = 11; // why withheld, failed, waiting
google.protobuf.Timestamp sent_at = 12;
repeated string compliance = 13; // what is missing; empty = compliant
}
message OutreachSequence {
string id = 1;
string lead_id = 2;
string lead_name = 3;
string company = 4;
string email = 5;
string status = 6; // active | paused | stopped | completed
// reply | bounce | unsubscribe | meeting | manual | suppressed | not_b2b
string stop_reason = 7;
string approval_mode = 8; // per_step | per_sequence
bool rest_approved = 9;
repeated OutreachStep steps = 10;
// interested | not_now | not_interested | referral | unclassified
string reply_intent = 11;
repeated ReasonStep reply_reasoning = 12;
string reply_snippet = 13;
google.protobuf.Timestamp meeting_at = 14;
bool meeting_booked = 15;
google.protobuf.Timestamp created_at = 16;
string plan_action_id = 17;
string lead_stage = 18;
bool handoff = 19; // a reply that is not clearly negative waits for the person
string address_basis = 20; // where the address was found
}
// The loop the sequence runs on, in the shape of inference/loops.Spec (the
// same field names; wired to that package once pulse/agent-loops lands).
message OutreachLoopSpec {
string app = 1;
string id = 2;
string name = 3;
string goal = 4;
repeated string non_goals = 5;
string scope = 6;
string cadence = 7;
string level = 8;
string maker = 9;
string checker = 10;
int32 max_iterations = 11;
int32 max_attempts_per_item = 12;
int32 daily_model_call_cap = 13;
string cap_note = 14;
repeated string handoff_triggers = 15;
string action_allowlist = 16;
string denylist = 17;
}
message OutreachBoard {
OutreachSettings settings = 1;
repeated OutreachSequence sequences = 2;
OutreachLoopSpec loop = 3;
// The reasoned cadence (sequence_touches, sequence_gap_days).
repeated GrowthReasoned cadence = 4;
// Shown with the settings: who may receive cold B2B email.
string legal_note = 5;
}
message OutreachMeeting {
string sequence_id = 1;
string lead_id = 2;
string lead_name = 3;
string company = 4;
google.protobuf.Timestamp meeting_at = 5;
google.protobuf.Timestamp booked_at = 6;
}
message ListMeetingsResponse {
repeated OutreachMeeting meetings = 1;
}OpportunityService
OpportunityService — Audience › Opportunities (owner, 2026-10-30): public tenders and private requests for proposals that need what the account sells (websites, custom applications, content …), and a drafted response.
The rules a reader can rely on: * Sources are official open procurement data (EU TED, UK Find a Tender and Contracts Finder, Brazil PNCP, CanadaBuys; US SAM.gov with the account’s own key from Integrations) plus private requests for proposals PULSE’s own crawler finds. No login is scraped. * Each source reports read (with a count), empty, unreadable (with the reason) or not connected. A source that could not be read is never shown as having nothing. * A figure a notice does not state (value, deadline) is absent, never 0. * Matching is the account’s offerings (audit + tuning) mapped to procurement codes (CPV, UNSPSC, NAICS) plus lexical word matching (no embeddings); every card says why it matched. * A drafted response is a draft: nothing here submits anywhere. The person submits, and records it by moving the card to Submitted.
pulse.v1.OpportunityService, declared in opportunities.proto.
| Method | Request → Response | Least role | Notes |
|---|---|---|---|
ListOpportunities | ListOpportunitiesRequest → ListOpportunitiesResponse | viewer | ListOpportunities is the board: the cards, the KPIs, and what the last discovery read from each source. |
FindOpportunities | FindOpportunitiesRequest → ListOpportunitiesResponse | editor | FindOpportunities reads every source now (reading only) and returns the board. |
MoveOpportunity | MoveOpportunityRequest → Opportunity | editor | MoveOpportunity moves a card to another column. |
DismissOpportunity | DismissOpportunityRequest → Opportunity | editor | DismissOpportunity is “Not for us”, with the reason. |
DraftOpportunityResponse | DraftOpportunityResponseRequest → Opportunity | editor | DraftOpportunityResponse runs the opportunity-response skill on our own inference: a qualification draft and the documents checklist. |
GetOpportunityPreferences | GetOpportunityPreferencesRequest → OpportunityPreferences | viewer | |
SaveOpportunityPreferences | OpportunityPreferences → OpportunityPreferences | editor | |
ListFreelance | ListFreelanceRequest → FreelanceBoard | viewer | ListFreelance is Leads › Freelance (owner, 2026-11-06): contracts that match the expertise the business sells, in two segments: public buyers’ tenders (TED, UK Contracts Finder, PNCP) and private companies hiring contractors directly or through agencies (their own Greenhouse, Lever and Ashby boards; Jobicy and Himalayas as job boards). The expertise terms are INFERRED from the audit’s offerings, the site’s own pages and Tune (never the niche alone), for the audit opened this session. Read at view time; nothing is stored or written. |
SaveFreelanceLead | SaveFreelanceLeadRequest → SaveFreelanceLeadResponse | editor | SaveFreelanceLead saves one Freelance & contracts item as the caller’s own lead (owner, 2026-11-06: “move the freelancer as a Lead category type … everything that can bring money on the same place”). It enters the pipeline at New, valued from the item’s published total value when it states one. Saving the same item again returns the same lead. Unsaved items stay read-only and are never stored. |
message OpportunityCode {
// CPV | UNSPSC | NAICS
string scheme = 1;
string id = 2;
}
message OpportunityRequirement {
string ref = 1;
string requirement = 2;
string response = 3;
// addressed | not_covered
string status = 4;
// The account's facts (F1 …) the answer rests on.
repeated string facts = 5;
}
message OpportunityDocument {
string document = 1;
// The requirement ref that asks for it.
string asked_in = 2;
string status = 3;
}
message OpportunityCheck {
string id = 1;
double score = 2;
bool pass = 3;
repeated string findings = 4;
// The check could not run: never read as a pass.
string error = 5;
}
message OpportunityDraft {
// none | ready | withheld
string state = 1;
string summary = 2;
string deadline = 3;
string submission = 4;
repeated OpportunityRequirement requirements = 5;
repeated OpportunityDocument documents = 6;
repeated OpportunityCheck checks = 7;
// Why it was withheld.
string reason = 8;
// RFC 3339.
string drafted_at = 9;
repeated string asks = 10;
// The account's facts, F1 … as the draft cites them.
repeated string facts = 11;
}
message Opportunity {
string id = 1;
// eu_ted | uk_fts | uk_cf | br_pncp | ca_canadabuys | us_samgov | web_rfp
string source = 2;
string notice_id = 3;
string title = 4;
string description = 5;
string buyer = 6;
// public | private
string buyer_type = 7;
// ISO 3166-1 alpha-2; "" = not stated.
string country = 8;
string region = 9;
string language = 10;
repeated OpportunityCode codes = 11;
// false = the notice states no value (never 0).
bool value_stated = 12;
double value_amount = 13;
string value_currency = 14;
// RFC 3339; "" = the notice states no deadline.
string deadline = 15;
string published = 16;
string url = 17;
// Where or how to respond, when the notice says; "" otherwise.
string submission = 18;
// found | interested | preparing | submitted | won | lost | dismissed
string stage = 19;
string dismiss_reason = 20;
// 0–100: fit (60) + time to deadline (25) + value (15).
int32 score = 21;
double fit = 22;
string matched_offering = 23;
repeated string matched_words = 24;
repeated string matched_codes = 25;
// RFC 3339.
string found_at = 26;
string updated_at = 27;
OpportunityDraft draft = 28;
}
message OpportunitySourceStatus {
string source = 1;
// read | empty | unreadable | not_connected
string state = 2;
string reason = 3;
int32 count = 4;
// RFC 3339.
string at = 5;
}
// Counts from the account's own board. measured = false before the first
// discovery: every count is then absent, not 0.
message OpportunityKpis {
bool measured = 1;
int32 new_this_week = 2;
int32 matching = 3;
int32 closing_soon = 4;
int32 in_progress = 5;
int32 submitted = 6;
int32 won = 7;
}
message ListOpportunitiesRequest {
bool include_dismissed = 1;
}
message ListOpportunitiesResponse {
repeated Opportunity opportunities = 1;
OpportunityKpis kpis = 2;
repeated OpportunitySourceStatus sources = 3;
// RFC 3339 of the last discovery; "" = never.
string last_run_at = 4;
// Why nothing could be matched (e.g. PULSE does not know what you sell yet).
string note = 5;
// The offerings the matching used.
repeated string offerings = 6;
// Whether the daily discovery runs on this server (PULSE_OPPORTUNITIES_DISCOVERY).
bool daily_discovery = 7;
}
message FindOpportunitiesRequest {}
message MoveOpportunityRequest {
string id = 1;
string stage = 2;
}
message DismissOpportunityRequest {
string id = 1;
string reason = 2;
}
message DraftOpportunityResponseRequest {
string id = 1;
}
message GetOpportunityPreferencesRequest {}
message OpportunityPreferences {
// ISO alpha-2; empty = every country.
repeated string countries = 1;
// ISO 639-1; empty = every language.
repeated string languages = 2;
// 0 = no minimum / maximum; in `currency`, other currencies not converted.
double min_value = 3;
double max_value = 4;
string currency = 5;
// Skip notices closing sooner than this (default 7).
int32 min_days = 6;
// public | private; empty = both.
repeated string buyer_types = 7;
// Show newly found matches in the bell (default on).
bool notify_new = 8;
// Draft a response for the best new matches after each discovery (spends
// model time; default off).
bool auto_draft = 9;
// Remind this many days before a deadline of a card being prepared (default 7).
int32 remind_days = 10;
// false = defaults, nothing saved yet.
bool saved = 11;
}
message ListFreelanceRequest {
// The audit opened this session (required: the tab is session-scoped).
string audit_run_id = 1;
// all | public | private ("" = all). Only that segment's sources are read.
string segment = 2;
}
// One expertise term and where it came from.
message FreelanceTerm {
string term = 1;
// site (the audit's offerings, quoted from the site) | site_page (an
// expertise phrase found in the site's own pages) | tuning (what the
// person named in Tune)
string source = 2;
// The words it rests on: the site's quote, or the page and the words
// around the phrase.
string ref = 3;
// How much a match on it counts, 0–1 (a match in a title counts twice).
double weight = 4;
}
message FreelanceItem {
string id = 1;
// eu_ted | uk_cf | br_pncp | greenhouse | lever | ashby | jobicy | himalayas
string source = 2;
string title = 3;
// The buyer or the company.
string company = 4;
// freelance | temporary | fixed_term | tender
string contract_type = 5;
// The rate or the contract value as published; "" = not published
// (never 0).
string rate = 6;
// RFC 3339; "" = the posting states no deadline.
string deadline = 7;
string published = 8;
repeated string matched_terms = 9;
// The posting on its board (the board's own apply link, unchanged).
string url = 10;
string location = 11;
// public | private_direct | private_agency
string segment = 12;
// tender | direct (the company's own board) | job_board
string channel = 13;
// How long the contract runs, as published; "" = not published.
string duration = 14;
// Relevance: each matched term's weight (twice in the title), plus the
// board's cpv_bonus for a tender filed under an IT, data or R&D code.
double score = 15;
bool cpv_match = 16;
// Why it is "via agency" ("" for direct and public).
string agency_why = 17;
// The caller's lead this item was saved as ("" = not saved).
string saved_lead_id = 18;
// The total value the item publishes (a tender's estimated value), 0 =
// none; a rate per period is not a total and stays in rate.
double value_amount = 19;
string value_currency = 20;
}
message SaveFreelanceLeadRequest {
// The audit opened this session (the item came from its Freelance list).
string audit_run_id = 1;
FreelanceItem item = 2;
}
message SaveFreelanceLeadResponse {
string lead_id = 1;
// false: the item was already saved as this lead.
bool created = 2;
// true: the lead carries the item's published total value as its deal.
bool valued = 3;
}
message FreelanceSourceStatus {
string source = 1;
// read | empty | unreadable
string state = 2;
string reason = 3;
int32 count = 4;
// The page the source's terms were checked on.
string terms_url = 5;
// public | private
string segment = 6;
// tender | direct | job_board
string channel = 7;
// What it was asked for: the terms, the codes, or the companies whose
// boards were tried.
repeated string searched = 8;
}
// A source checked and not read, and why.
message FreelanceSourceNotUsed {
string source = 1;
string reason = 2;
string terms_url = 3;
}
message FreelanceBoard {
string audit_run_id = 1;
repeated FreelanceTerm terms = 2;
repeated FreelanceItem items = 3;
repeated FreelanceSourceStatus sources = 4;
// Where the search came from, in plain words. With terms: whether they are
// the person's own (Tune) or the check-up's, and where the company job
// boards came from (the check-up's leads, partners and competitors, or
// none: with no check-up open there is no company to read). With no terms:
// why there is nothing to search with, and the next step (name your
// expertise in Tune, or open a check-up). Never empty on a read board.
string note = 5;
// The segment read: all | public | private.
string segment = 6;
// An item matching no term, or scoring under min_score, is not listed.
double min_score = 7;
double cpv_bonus = 8;
int32 dropped_below_threshold = 9;
// Permanent roles read from a board (not contracts).
int32 dropped_not_contract = 10;
// The same role read from two sources, listed once.
int32 dropped_duplicate = 11;
repeated FreelanceSourceNotUsed not_used = 12;
}InfluencerService
SERVICE 15: InfluencerService (Favikon-style CRM)
pulse.v1.InfluencerService, declared in pulse.proto.
| Method | Request → Response | Least role | Notes |
|---|---|---|---|
ListInfluencers | google.protobuf.Empty → ListInfluencersResponse | viewer | |
SaveInfluencer | SaveInfluencerRequest → Influencer | editor | |
UpdateInfluencer | UpdateInfluencerRequest → Influencer | editor | UpdateInfluencer edits a followed partner the caller owns. An edited partner a check-up imported keeps the edit when the next check-up runs. |
RemoveInfluencer | RemoveInfluencerRequest → google.protobuf.Empty | editor | RemoveInfluencer stops following a partner. A partner a check-up imported stays removed when the next check-up finds it again. |
message UpdateInfluencerRequest {
string id = 1;
string name = 2;
string handle = 3;
string platform = 4;
double score = 5;
string notes = 6;
}
message RemoveInfluencerRequest {
string id = 1;
}
message Influencer {
string id = 1;
string name = 2;
string handle = 3;
string platform = 4;
double score = 5;
string notes = 6;
// Provenance of an imported row ("" for one the user added by hand).
// category "guest_opportunity" = imported from Radar guest-opportunity
// discovery; source_url is the show's search-verified URL.
string category = 7;
string source_url = 8;
// What score measures. "relevance" = Radar's topical-fit relevance score
// (0-100), NOT a follower or engagement metric; "" = the user's own rating.
string score_kind = 9;
}
message ListInfluencersResponse {
repeated Influencer influencers = 1;
}
message SaveInfluencerRequest {
string name = 1;
string handle = 2;
string platform = 3;
double score = 4;
string notes = 5;
}AICallService
AICallService places AI voice calls to leads (an AI assistant talks to the lead over Twilio, through org-runink/ui comms/voiceagent) and keeps the records those calls need: the lead’s prior express consent, the lead’s time zone, the tenant’s do-not-call list, each call’s outcome and sealed transcript, and the follow-up task a call leaves behind.
SERVER-SIDE GUARDS (PlaceAICall refuses, with every reason, unless all hold): - PULSE_APPLY_ENABLED=true, PULSE_OUTBOUND_CALLS and PULSE_AI_CALLS on; - the caller is an editor or admin (read from the users row); - the lead’s phone has a consent record (who recorded it, when and how it was given) for THAT number, not revoked — an AI voice is an artificial voice under the TCPA (FCC, February 2024); - the number is not on the tenant’s do-not-call list; - the lead’s local time (its time zone is required) is inside the calling-hours window, itself inside 08:00–21:00; - fewer than max_attempts AI calls to the lead in the last 30 days, and none in progress; - the tenant’s Twilio caller ID is configured (the call is placed from it). Every call opens with “an AI assistant calling on behalf of” and the company, then the recording notice; “stop” / “do not call” on a call puts the number on the do-not-call list.
Automations call PlaceAICall as a step with origin “automation:” plus the automation id; a refusal is a result (placed=false, refusals), not an RPC error.
pulse.v1.AICallService, declared in aicall.proto.
| Method | Request → Response | Least role | Notes |
|---|---|---|---|
PlaceAICall | PlaceAICallRequest → PlaceAICallResponse | editor | PlaceAICall dials one lead (or, with validate_only, only checks). |
GetAICall | GetAICallRequest → AICall | editor | GetAICall returns one call; the transcript only when asked for. |
ListAICalls | ListAICallsRequest → ListAICallsResponse | viewer | ListAICalls returns a lead’s calls, newest first. |
GetLeadCallProfile | GetLeadCallProfileRequest → LeadCallProfile | viewer | GetLeadCallProfile: consent, time zone, do-not-call state of a lead. |
RecordCallConsent | RecordCallConsentRequest → LeadCallProfile | editor | RecordCallConsent records the lead’s prior express consent to AI calls. |
RevokeCallConsent | RevokeCallConsentRequest → LeadCallProfile | editor | RevokeCallConsent withdraws it (no AI call is placed after this). |
SetLeadTimeZone | SetLeadTimeZoneRequest → LeadCallProfile | editor | SetLeadTimeZone sets the lead’s IANA time zone (calling hours use it). |
ListDoNotCall | ListDoNotCallRequest → ListDoNotCallResponse | viewer | ListDoNotCall lists the tenant’s do-not-call numbers (masked). |
AddDoNotCall | AddDoNotCallRequest → DoNotCallEntry | editor | AddDoNotCall adds a lead’s number to the tenant’s do-not-call list. |
ListLeadFollowUps | ListLeadFollowUpsRequest → ListLeadFollowUpsResponse | viewer | ListLeadFollowUps returns the follow-up tasks calls created for a lead. |
enum AICallGoal {
AI_CALL_GOAL_UNSPECIFIED = 0;
AI_CALL_GOAL_BOOK_MEETING = 1;
AI_CALL_GOAL_QUALIFY = 2;
AI_CALL_GOAL_FOLLOW_UP = 3;
}
enum VoicemailBehavior {
VOICEMAIL_BEHAVIOR_UNSPECIFIED = 0; // = hang up
VOICEMAIL_BEHAVIOR_LEAVE_MESSAGE = 1;
VOICEMAIL_BEHAVIOR_HANG_UP = 2;
}
enum AICallOutcome {
AI_CALL_OUTCOME_UNSPECIFIED = 0; // not known yet (dialing / in progress)
AI_CALL_OUTCOME_CONNECTED = 1;
AI_CALL_OUTCOME_VOICEMAIL = 2;
AI_CALL_OUTCOME_NO_ANSWER = 3; // also busy
AI_CALL_OUTCOME_DECLINED = 4; // the lead asked not to be called
AI_CALL_OUTCOME_MEETING_REQUESTED = 5;
AI_CALL_OUTCOME_FAILED = 6; // the carrier could not place or carry it
}
enum AICallState {
AI_CALL_STATE_UNSPECIFIED = 0;
AI_CALL_STATE_DIALING = 1;
AI_CALL_STATE_IN_PROGRESS = 2;
AI_CALL_STATE_COMPLETED = 3;
}
enum ConsentMethod {
CONSENT_METHOD_UNSPECIFIED = 0;
CONSENT_METHOD_WEB_FORM = 1; // a form the lead submitted
CONSENT_METHOD_WRITTEN = 2; // signed / e-mailed agreement
CONSENT_METHOD_RECORDED_VERBAL = 3; // a recorded call where the lead agreed
CONSENT_METHOD_OTHER = 4; // evidence must say what
}
// CallingHours is a window in the LEAD's local time. Hours 0–23; end is
// exclusive. Weekdays 1 = Monday … 7 = Sunday. Defaults 09–17, Mon–Fri.
message CallingHours {
int32 start_hour = 1;
int32 end_hour = 2;
repeated int32 weekdays = 3;
}
message AICallConfig {
AICallGoal goal = 1; // default BOOK_MEETING
string voice = 2; // ttsd voice name; empty = ttsd's call voice
CallingHours calling_hours = 3;
int32 max_attempts = 4; // per lead per 30 days, 1–3 (default 1)
VoicemailBehavior voicemail = 5;
string voicemail_message = 6; // optional; default per goal
int32 max_call_seconds = 7; // default 300, at most 900
// The drafted call script to follow (a lead_outreach id); empty = the
// lead's newest drafted call script. No script → refused.
string script_outreach_id = 8;
// The company the AI assistant calls on behalf of; said in the first
// sentence. Required.
string on_behalf_of = 9;
}
message PlaceAICallRequest {
string lead_id = 1;
AICallConfig config = 2;
bool validate_only = 3; // check every guard, dial nothing
string origin = 4; // "leads", or "automation:" plus the automation id
}
message PlaceAICallResponse {
bool placed = 1;
AICall call = 2; // set when placed
// Every reason the call was not placed, as sentences. Empty when placed
// (or, with validate_only, when it would be).
repeated string refusals = 3;
// When the calling-hours window refused: its next opening, in UTC.
google.protobuf.Timestamp next_window_start = 4;
}
message AICallLine {
string speaker = 1; // CALLER | AGENT | SYSTEM
string kind = 2; // TRANSCRIPT | EVENT
string text = 3;
google.protobuf.Timestamp at = 4;
}
message AICall {
string id = 1;
string lead_id = 2;
AICallState state = 3;
AICallOutcome outcome = 4;
AICallConfig config = 5;
string origin = 6;
string summary = 7; // empty until the call is summarised
string next_step = 8;
string follow_up_task_id = 9;
string end_reason = 10; // the loop's reason, or the carrier's status
google.protobuf.Timestamp created_at = 11;
google.protobuf.Timestamp ended_at = 12;
int32 duration_seconds = 13; // 0 = not connected / not known
repeated AICallLine transcript = 14; // GetAICall with include_transcript
string number_masked = 15;
}
message GetAICallRequest {
string call_id = 1;
bool include_transcript = 2;
}
message ListAICallsRequest {
string lead_id = 1;
}
message ListAICallsResponse {
repeated AICall calls = 1;
}
message LeadCallProfile {
string lead_id = 1;
string number_masked = 2;
string time_zone = 3; // empty = unknown (AI calls refused)
bool consent_on_record = 4; // for the lead's CURRENT number, not revoked
ConsentMethod consent_method = 5;
string consent_evidence = 6;
google.protobuf.Timestamp consent_given_at = 7;
string consent_recorded_by = 8; // user id
google.protobuf.Timestamp consent_recorded_at = 9;
google.protobuf.Timestamp consent_revoked_at = 10;
bool on_do_not_call = 11;
// Set when a consent record exists but names another number.
bool consent_for_other_number = 12;
}
message GetLeadCallProfileRequest {
string lead_id = 1;
}
message RecordCallConsentRequest {
string lead_id = 1;
ConsentMethod method = 2;
// Where and how it was given: the form URL and submission, the document,
// the recorded call. Required.
string evidence = 3;
google.protobuf.Timestamp given_at = 4; // when the lead gave it; not in the future
}
message RevokeCallConsentRequest {
string lead_id = 1;
}
message SetLeadTimeZoneRequest {
string lead_id = 1;
string time_zone = 2; // IANA, e.g. "America/New_York"
}
message DoNotCallEntry {
string id = 1;
string number_masked = 2;
string reason = 3;
string source = 4; // "call" (said on a call) | "manual"
google.protobuf.Timestamp added_at = 5;
string added_by = 6; // user id, or "call:" plus the call id
}
message ListDoNotCallRequest {}
message ListDoNotCallResponse {
repeated DoNotCallEntry entries = 1;
}
message AddDoNotCallRequest {
string lead_id = 1;
string reason = 2;
}
message FollowUpTask {
string id = 1;
string lead_id = 2;
string title = 3;
string detail = 4;
google.protobuf.Timestamp due_at = 5;
string status = 6; // "open" | "done"
string source_call_id = 7;
google.protobuf.Timestamp created_at = 8;
}
message ListLeadFollowUpsRequest {
string lead_id = 1;
}
message ListLeadFollowUpsResponse {
repeated FollowUpTask tasks = 1;
}IntegrationService
Social platform connections and external service integrations.
pulse.v1.IntegrationService, declared in pulse.proto.
| Method | Request → Response | Least role | Notes |
|---|---|---|---|
ListIntegrations | ListIntegrationsRequest → ListIntegrationsResponse | viewer | ListIntegrations returns all configured integrations. |
ConfigureIntegration | ConfigureIntegrationRequest → Integration | editor | ConfigureIntegration sets up or updates an integration. |
TestConnection | TestConnectionRequest → TestConnectionResponse | editor | TestConnection tests if an integration’s credentials are valid. |
DisconnectIntegration | DisconnectIntegrationRequest → google.protobuf.Empty | editor | DisconnectIntegration removes an integration’s credentials. |
StartMailboxConnect | StartMailboxConnectRequest → StartMailboxConnectResponse | editor | StartMailboxConnect begins the OAuth connect of the caller’s own mailbox (“gmail” or “microsoft365”): it returns the provider’s consent URL. The provider redirects to /oauth/mail/callback, which stores the sealed tokens. |
ListLinkedInOrganizations | ListLinkedInOrganizationsRequest → ListLinkedInOrganizationsResponse | editor | ListLinkedInOrganizations lists the company pages the connected LinkedIn token may post as (organizationAcls, roles ADMINISTRATOR or CONTENT_ADMINISTRATOR). Needs rw_organization_admin, which LinkedIn grants only to apps approved for the Community Management API; note says why the list is empty. |
SetLinkedInAuthor | SetLinkedInAuthorRequest → Integration | editor | SetLinkedInAuthor chooses who LinkedIn posts are authored by: "" = the token’s member, or one of ListLinkedInOrganizations’ pages. |
StartSocialConnect | StartSocialConnectRequest → StartSocialConnectResponse | editor | StartSocialConnect begins “Connect with Instagram” (Facebook Login for Business) or “Connect with YouTube” (Google OAuth): it returns the consent URL; the provider redirects to /oauth/social/callback, which seals the tokens and finds the account. configured=false (with message) when this server has no app client: only then is a pasted token accepted. |
ListSocialConnections | ListSocialConnectionsRequest → ListSocialConnectionsResponse | viewer | ListSocialConnections is one status per sign-in platform (Instagram, YouTube, LinkedIn): connected, expiring, expired, missing permission or not set up, with the permissions each feature needs and has. |
DisconnectSocial | DisconnectSocialRequest → DisconnectSocialResponse | editor | DisconnectSocial revokes PULSE’s sign-in at the platform where its API allows, then deletes the sealed tokens; the account’s settings stay for a reconnect. |
Also uses IntegrationStatus.
message StartMailboxConnectRequest {
string provider = 1; // "gmail" | "microsoft365"
}
message StartMailboxConnectResponse {
string authorize_url = 1;
string redirect_uri = 2; // the callback the instance's OAuth client must allow
}
message ListLinkedInOrganizationsRequest {}
message LinkedInOrganization {
string urn = 1; // `urn:li:organization:{id}`
string name = 2; // localizedName; empty when LinkedIn did not say
string role = 3; // ADMINISTRATOR | CONTENT_ADMINISTRATOR
}
message ListLinkedInOrganizationsResponse {
repeated LinkedInOrganization organizations = 1;
string author_urn = 2; // the current choice; "" = the member
string note = 3; // why the list is empty, when it is
}
message SetLinkedInAuthorRequest {
string author_urn = 1;
}
message Integration {
string id = 1;
string user_id = 2;
string platform = 3; // "linkedin", "instagram", "google_analytics", "google_ads", "hubspot", "github", "gmail", "microsoft365", "smtp"
IntegrationStatus status = 4;
string account_name = 5;
string account_id = 6;
map<string, string> config = 7; // platform-specific configuration
google.protobuf.Timestamp connected_at = 8;
google.protobuf.Timestamp last_sync_at = 9;
string error_message = 10;
}
message ListIntegrationsRequest {
string user_id = 1;
}
message ListIntegrationsResponse {
repeated Integration integrations = 1;
}
message ConfigureIntegrationRequest {
string platform = 1;
string access_token = 2;
string refresh_token = 3;
string account_id = 4;
map<string, string> config = 5;
}
message TestConnectionRequest {
string integration_id = 1;
}
message TestConnectionResponse {
bool success = 1;
string message = 2;
int32 latency_ms = 3;
}
message DisconnectIntegrationRequest {
string integration_id = 1;
}
message StartSocialConnectRequest {
string platform = 1; // "instagram" | "youtube" | "linkedin"
// Ask again for permissions the person declined (Meta auth_type=rerequest;
// Google always shows consent).
bool reconnect = 2;
// LinkedIn only: also ask for the company-page permissions
// (r_organization_social, w_organization_social, rw_organization_admin).
bool company_pages = 3;
}
message StartSocialConnectResponse {
bool configured = 1; // false: this server has no app client for it
string authorize_url = 2; // open it in the browser
string redirect_uri = 3; // the callback the app client must allow
string message = 4; // why sign-in is not available (configured=false)
repeated string scopes = 5; // the permissions / scopes it asks for
}
message ListSocialConnectionsRequest {}
message ListSocialConnectionsResponse {
repeated SocialConnection connections = 1; // instagram, youtube, linkedin
}
// One permission (the platform's own name) a feature needs.
message SocialPermission {
string name = 1;
bool granted = 2; // meaningful only when SocialConnection.granted_known
}
// What one feature needs: "publish" | "read_back" | "comments" | "dms".
message SocialFeature {
string feature = 1;
bool available = 2; // false: the platform has no API for it
repeated SocialPermission permissions = 3;
bool company_pages_only = 4; // LinkedIn: only for company pages
}
// Who LinkedIn posts can be authored by.
message SocialAuthor {
string urn = 1;
string name = 2;
string kind = 3; // "person" | "organization"
}
message SocialConnection {
string platform = 1;
// "connected" | "expiring" | "expired" | "missing_permission" |
// "not_set_up" | "not_connected"
string state = 2;
string integration_id = 3;
string account_name = 4;
bool signed_in = 5; // false: a pasted token
google.protobuf.Timestamp expires_at = 6; // unset: not known
bool renews = 7; // PULSE renews it before expires_at
repeated string missing_env = 8; // what an administrator must set
repeated string missing_permissions = 9; // asked for and not granted
bool granted_known = 10; // false: never read back (pasted)
repeated SocialFeature features = 11;
string last_refresh_error = 12;
google.protobuf.Timestamp last_refresh_failed_at = 13;
bool sign_in_available = 14;
repeated SocialAuthor authors = 15; // LinkedIn: the member and pages
string author_urn = 16; // LinkedIn: "" = the member
bool company_pages_available = 17; // LinkedIn: this server may ask for pages
}
message DisconnectSocialRequest {
string platform = 1;
}
message DisconnectSocialResponse {
bool revoked = 1; // the platform confirmed PULSE's access was removed
string note = 2; // what the person must still do, when not revoked
}AgencyService
AgencyService — one agency runs several client businesses in PULSE. Each client is its own owner: its brand, accounts, autopilot, approvals and reports are the client’s rows, and every owner-scoped query keeps them apart. The app picks the client with the x-pulse-client request header; the server checks the caller’s membership on every call.
Roles per client: agency_admin (runs everything for the client, adds people) and client_approver (sees the client’s work and approves or rejects content and replies — nothing else).
pulse.v1.AgencyService, declared in autopilot.proto.
| Method | Request → Response | Least role | Notes |
|---|---|---|---|
ListClients | ListClientsRequest → ListClientsResponse | viewer | |
CreateClient | CreateClientRequest → AgencyClient | editor | |
ListClientMembers | ListClientMembersRequest → ListClientMembersResponse | viewer | |
SetClientMember | SetClientMemberRequest → ClientMember | editor | SetClientMember adds a person of this PULSE (by e-mail) to a client, or changes their role. agency_admin only. |
RemoveClientMember | RemoveClientMemberRequest → ListClientMembersResponse | editor |
message AgencyClient {
string id = 1;
string name = 2;
// The caller's role on this client.
string role = 3;
google.protobuf.Timestamp created_at = 4;
}
message ListClientsRequest {}
message ListClientsResponse {
repeated AgencyClient clients = 1;
}
message CreateClientRequest {
string name = 1;
}
message ClientMember {
string client_id = 1;
string user_id = 2;
string email = 3;
string role = 4;
}
message ListClientMembersRequest {
string client_id = 1;
}
message ListClientMembersResponse {
repeated ClientMember members = 1;
}
message SetClientMemberRequest {
string client_id = 1;
string email = 2;
// agency_admin | client_approver
string role = 3;
}
message RemoveClientMemberRequest {
string client_id = 1;
string user_id = 2;
}AttributionService
AttributionService links what PULSE published or sent to the leads and the won deals it produced (owner, 2026-11-16).
The rules a reader can rely on: * TAGGING. Links PULSE publishes (social posts) or sends (outreach and sequence emails) that point at the account’s OWN sites carry utm_source, utm_medium, utm_campaign, utm_content and pulse_ref. A link to any other site is never changed, nor one that already carries utm_source or pulse_ref. Tagging runs after every publish and send gate, so it never sends anything those gates withheld. Per account, on unless the account turns it off (AttributionSettings.tag_links). * CAPTURE. A touch is one recorded reason a lead came: a website-form enquiry whose landing address carried UTM tags or a pulse_ref, or whose referrer was another site; or a reply to an outreach sequence. Stored: the UTM values, the pulse_ref, the landing PATH (no query string) and the referrer HOST. Nothing else (no IP, no user agent). * JOIN. Two models, both stated, no weights. First touch: the lead’s earliest touch. Last touch: its latest touch (for a won deal, the latest at or before won_at). A lead with no touch is UNATTRIBUTED, counted and labelled by where it came from, never guessed.
pulse.v1.AttributionService, declared in attribution.proto.
| Method | Request → Response | Least role | Notes |
|---|---|---|---|
GetAttribution | GetAttributionRequest → AttributionReport | viewer | |
GetAttributionSettings | GetAttributionSettingsRequest → AttributionSettings | viewer | |
SaveAttributionSettings | AttributionSettings → AttributionSettings | editor |
Also uses DateRange.
message GetAttributionRequest {
// Leads count when their date is in the range: the first touch's time,
// else the day PULSE captured the lead. Won deals count when won_at is in
// the range. Unset start or end = unbounded on that side.
DateRange date_range = 1;
}
// AttributionMoney is a sum in one currency, in minor units (cents).
message AttributionMoney {
string currency = 1;
int64 amount_minor = 2;
}
// AttributionRow is one channel (source + medium) or one campaign.
message AttributionRow {
string source = 1; // utm_source, or the referring host
string medium = 2; // utm_medium, or "referral"
string campaign = 3; // utm_campaign ("" on a channel row)
int64 leads = 4;
int64 won_deals = 5;
repeated AttributionMoney won_revenue = 6;
// Won deals with no deal value recorded: counted, never valued at 0.
int64 won_without_value = 7;
}
// AttributionModel is the report under one model.
message AttributionModel {
string model = 1; // "first_touch" | "last_touch"
repeated AttributionRow channels = 2;
repeated AttributionRow campaigns = 3;
int64 unattributed_leads = 4;
int64 unattributed_won_deals = 5;
repeated AttributionMoney unattributed_won_revenue = 6;
}
// UnattributedOrigin is where unattributed leads came from, by the lead's
// stored source kind: "manual", "website_form" (an enquiry with no tag and
// no outside referrer), "hubspot", "scraped", "prospecting", or another
// stored source as is.
message UnattributedOrigin {
string origin = 1;
int64 leads = 2;
}
message AttributionReport {
int64 leads = 1;
int64 won_deals = 2;
repeated AttributionMoney won_revenue = 3;
int64 won_without_value = 4;
AttributionModel first_touch = 5;
AttributionModel last_touch = 6;
repeated UnattributedOrigin unattributed_by_origin = 7;
// The account's tagging switch, so the page can say tagging is off.
bool tag_links = 8;
}
message GetAttributionSettingsRequest {}
// AttributionSite is one site links to which are tagged, and why PULSE
// counts it as the account's own.
message AttributionSite {
string host = 1;
string from = 2; // "listed" | "website_form" | "check_up"
}
message AttributionSettings {
// Tag links to the account's own sites. On unless turned off.
bool tag_links = 1;
// The sites the account listed. Empty = PULSE uses the sites allowed to
// post to the website form and the site of the latest check-up.
repeated string own_sites = 2;
// What tagging uses now (read only).
repeated AttributionSite effective_sites = 3;
}