Skip to content
Leads, tenders and accounts

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 ConnectionsService instead; see Shared components.
  • Sign-in connections. StartSocialConnect returns the consent address for instagram, youtube or linkedin (company_pages adds the LinkedIn page scopes when LINKEDIN_COMPANY_PAGES is on). The platform returns to /oauth/social/callback, which seals the tokens. The answer is configured=false with a message when the server has no app client or no https PULSE_PUBLIC_BASE_URL. ListSocialConnections reports one status per platform and, per feature, the permissions needed and granted. DisconnectSocial revokes the grant at the platform where its API allows, then deletes the sealed tokens. See Setup.
  • Outbound. SendOutreachEmail needs PULSE_PUBLISH_EMAIL armed and a connected mailbox; AICallService.PlaceAICall, the one RPC that calls a lead, needs PULSE_OUTBOUND_CALLS, PULSE_AI_CALLS and the lead’s recorded consent. See Switches and arming order.
  • Agencies. A client is its own owner id. Sending x-pulse-client with 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.

MethodRequest → ResponseLeast roleNotes
SyncLeadsSyncLeadsRequest → SyncLeadsResponseeditorSyncLeads pulls the latest contacts from the connected CRM (HubSpot) and upserts them into the local leads cache.
ListLeadsListLeadsRequest → ListLeadsResponseviewerListLeads returns paginated, previously-synced leads.
CreateLeadCreateLeadRequest → LeadeditorCreateLead captures a new lead by hand or from a web form / intake — customer acquisition, not just CRM mirroring.
UpdateLeadStageUpdateLeadStageRequest → LeadeditorUpdateLeadStage moves a lead through the acquisition pipeline (new → contacted → qualified → won / lost).
GenerateOutreachGenerateOutreachRequest → stream StreamChunkeditorGenerateOutreach 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.
ListOutreachListOutreachRequest → ListOutreachResponseviewerListOutreach returns the outreach drafts generated for a lead.
ScrapeLeadsScrapeLeadsRequest → stream StreamChunkeditorScrapeLeads 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.
SetLeadDealSetLeadDealRequest → LeadeditorSetLeadDeal sets (or clears) a lead’s deal value at any stage.
GetLeadRevenueGetLeadRevenueRequest → LeadRevenueviewerGetLeadRevenue: open pipeline value per stage and won revenue for a period, per currency. A read; it spends nothing.
GetWebsiteFormGetWebsiteFormRequest → WebsiteFormviewerWebsite 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.
RotateWebsiteFormRotateWebsiteFormRequest → WebsiteFormSecreteditorRotateWebsiteForm creates the link, or replaces its secret (the old link stops working at once).
SetWebsiteFormOriginsSetWebsiteFormOriginsRequest → WebsiteFormeditorSetWebsiteFormOrigins lists the sites (https://host[:port]) whose pages may post to the link; a browser post from any other origin is refused.
DisableWebsiteFormDisableWebsiteFormRequest → WebsiteFormeditorDisableWebsiteForm turns the link off.
GetEmailSendReadinessGetEmailSendReadinessRequest → EmailSendReadinessviewerGetEmailSendReadiness says whether SendOutreachEmail can send right now for the caller, and if not, why.
SendOutreachEmailSendOutreachEmailRequest → SendOutreachEmailResponseeditorSendOutreachEmail 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”.
CheckRepliesCheckRepliesRequest → CheckRepliesResponseeditorCheckReplies looks now for replies to the caller’s sent emails (the background tracker also does, every 15 minutes) and marks replied leads.
SkipLeadStepSkipLeadStepRequest → LeadeditorSkipLeadStep puts the lead’s next step off by one day (To do today’s “Skip”); the step itself is unchanged.
GetLeadSearchDefaultsGetLeadSearchDefaultsRequest → LeadSearchDefaultsviewerGetLeadSearchDefaults 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.
ListOutreachSendsListOutreachSendsRequest → ListOutreachSendsResponseviewerListOutreachSends 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.

MethodRequest → ResponseLeast roleNotes
ListInboundListInboundRequest → InboundBoardviewer
SetInboundStatusSetInboundStatusRequest → InboundLeadeditor

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.

MethodRequest → ResponseLeast roleNotes
GetOutreachGetOutreachRequest → OutreachBoardviewerGetOutreach returns the settings, the sequences (one lead’s, or all) and the loop’s spec.
StartSequenceStartSequenceRequest → OutreachSequenceeditorStartSequence 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.
SetSequenceStateSetSequenceStateRequest → OutreachSequenceeditorSetSequenceState pauses, resumes or stops a sequence.
ApproveStepApproveStepRequest → OutreachSequenceeditorApproveStep 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.
CompleteStepCompleteStepRequest → OutreachSequenceeditorCompleteStep marks a call or LinkedIn task done or skipped, and can record the meeting the call booked.
SaveOutreachSettingsOutreachSettings → OutreachSettingseditorSaveOutreachSettings saves the sender identity, postal address, booking link or times, daily cap and working hours.
SuppressSuppressRequest → OutreachBoardeditorSuppress adds an address to the suppression list (stops its sequences).
ListMeetingsListMeetingsRequest → ListMeetingsResponseviewerListMeetings 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.

MethodRequest → ResponseLeast roleNotes
ListOpportunitiesListOpportunitiesRequest → ListOpportunitiesResponseviewerListOpportunities is the board: the cards, the KPIs, and what the last discovery read from each source.
FindOpportunitiesFindOpportunitiesRequest → ListOpportunitiesResponseeditorFindOpportunities reads every source now (reading only) and returns the board.
MoveOpportunityMoveOpportunityRequest → OpportunityeditorMoveOpportunity moves a card to another column.
DismissOpportunityDismissOpportunityRequest → OpportunityeditorDismissOpportunity is “Not for us”, with the reason.
DraftOpportunityResponseDraftOpportunityResponseRequest → OpportunityeditorDraftOpportunityResponse runs the opportunity-response skill on our own inference: a qualification draft and the documents checklist.
GetOpportunityPreferencesGetOpportunityPreferencesRequest → OpportunityPreferencesviewer
SaveOpportunityPreferencesOpportunityPreferences → OpportunityPreferenceseditor
ListFreelanceListFreelanceRequest → FreelanceBoardviewerListFreelance 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.
SaveFreelanceLeadSaveFreelanceLeadRequest → SaveFreelanceLeadResponseeditorSaveFreelanceLead 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.

MethodRequest → ResponseLeast roleNotes
ListInfluencersgoogle.protobuf.Empty → ListInfluencersResponseviewer
SaveInfluencerSaveInfluencerRequest → Influencereditor
UpdateInfluencerUpdateInfluencerRequest → InfluencereditorUpdateInfluencer edits a followed partner the caller owns. An edited partner a check-up imported keeps the edit when the next check-up runs.
RemoveInfluencerRemoveInfluencerRequest → google.protobuf.EmptyeditorRemoveInfluencer 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.

MethodRequest → ResponseLeast roleNotes
PlaceAICallPlaceAICallRequest → PlaceAICallResponseeditorPlaceAICall dials one lead (or, with validate_only, only checks).
GetAICallGetAICallRequest → AICalleditorGetAICall returns one call; the transcript only when asked for.
ListAICallsListAICallsRequest → ListAICallsResponseviewerListAICalls returns a lead’s calls, newest first.
GetLeadCallProfileGetLeadCallProfileRequest → LeadCallProfileviewerGetLeadCallProfile: consent, time zone, do-not-call state of a lead.
RecordCallConsentRecordCallConsentRequest → LeadCallProfileeditorRecordCallConsent records the lead’s prior express consent to AI calls.
RevokeCallConsentRevokeCallConsentRequest → LeadCallProfileeditorRevokeCallConsent withdraws it (no AI call is placed after this).
SetLeadTimeZoneSetLeadTimeZoneRequest → LeadCallProfileeditorSetLeadTimeZone sets the lead’s IANA time zone (calling hours use it).
ListDoNotCallListDoNotCallRequest → ListDoNotCallResponseviewerListDoNotCall lists the tenant’s do-not-call numbers (masked).
AddDoNotCallAddDoNotCallRequest → DoNotCallEntryeditorAddDoNotCall adds a lead’s number to the tenant’s do-not-call list.
ListLeadFollowUpsListLeadFollowUpsRequest → ListLeadFollowUpsResponseviewerListLeadFollowUps 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.

MethodRequest → ResponseLeast roleNotes
ListIntegrationsListIntegrationsRequest → ListIntegrationsResponseviewerListIntegrations returns all configured integrations.
ConfigureIntegrationConfigureIntegrationRequest → IntegrationeditorConfigureIntegration sets up or updates an integration.
TestConnectionTestConnectionRequest → TestConnectionResponseeditorTestConnection tests if an integration’s credentials are valid.
DisconnectIntegrationDisconnectIntegrationRequest → google.protobuf.EmptyeditorDisconnectIntegration removes an integration’s credentials.
StartMailboxConnectStartMailboxConnectRequest → StartMailboxConnectResponseeditorStartMailboxConnect 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.
ListLinkedInOrganizationsListLinkedInOrganizationsRequest → ListLinkedInOrganizationsResponseeditorListLinkedInOrganizations 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.
SetLinkedInAuthorSetLinkedInAuthorRequest → IntegrationeditorSetLinkedInAuthor chooses who LinkedIn posts are authored by: "" = the token’s member, or one of ListLinkedInOrganizations’ pages.
StartSocialConnectStartSocialConnectRequest → StartSocialConnectResponseeditorStartSocialConnect 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.
ListSocialConnectionsListSocialConnectionsRequest → ListSocialConnectionsResponseviewerListSocialConnections 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.
DisconnectSocialDisconnectSocialRequest → DisconnectSocialResponseeditorDisconnectSocial 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.

MethodRequest → ResponseLeast roleNotes
ListClientsListClientsRequest → ListClientsResponseviewer
CreateClientCreateClientRequest → AgencyClienteditor
ListClientMembersListClientMembersRequest → ListClientMembersResponseviewer
SetClientMemberSetClientMemberRequest → ClientMembereditorSetClientMember adds a person of this PULSE (by e-mail) to a client, or changes their role. agency_admin only.
RemoveClientMemberRemoveClientMemberRequest → ListClientMembersResponseeditor
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.

MethodRequest → ResponseLeast roleNotes
GetAttributionGetAttributionRequest → AttributionReportviewer
GetAttributionSettingsGetAttributionSettingsRequest → AttributionSettingsviewer
SaveAttributionSettingsAttributionSettings → AttributionSettingseditor

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;
}