{ "version": "v1", "generated_at": "2026-09-10T21:16:28.788Z", "social_proximity": { "version": 7, "overview": "Social proximity is a requester-relative relationship score. Public people-search responses can expose summary relationship fields and opt-in structured relationship detail; social-proximity detail surfaces expose score breakdowns, evidence, connector paths, and LinkedIn mutual-research status.", "api_surfaces": [ { "name": "People search summary fields", "auth_mode": "api_key", "auth_header": "X-API-Key", "endpoints": [ "POST /api/v1/search/people", "POST /api/v1/search/people/preview", "POST /api/v1/search/people/enrich" ], "model": "Person", "note": "These values are relative to the searching account owner or delegate_user_id. Existing scalar fields remain available when hydrated. Request relationship_detail for the structured relationship object used by MCP/API agents.", "request_parameters": [ { "name": "relationship_detail", "type": "none|summary|intro_paths", "required": false, "description": "Opt-in relationship payload. summary adds social proximity and mutuals. Named connected_to rows may add relationship.public_associations[]: projection-only public employer/industry/location context, distinct from worked_with and without third-party LinkedIn connection dates. intro_paths adds the unified social_map plus confirmed and possible paths. Omit for the lean payload." }, { "name": "intro_path_limit", "type": "number", "required": false, "description": "Maximum confirmed-mutual intro paths returned when relationship_detail=intro_paths. Default 3, server max 20. This does not cap the async scored mutual-connector pool; relationship.intro_paths_status.ranking_status, ranking_pending, and ranking_queue_* fields tell you whether confirmed path order is final." }, { "name": "possible_intro_limit", "type": "number", "required": false, "description": "Maximum first-degree worked-with overlap paths returned in relationship.possible_intro_paths and relationship.social_map path_type=\"experience_intersection\". Default 20, server max 100." }, { "name": "possible_intro_offset", "type": "number", "required": false, "description": "Zero-based offset into first-degree worked-with overlap paths for pagination." }, { "name": "mutual_connection_limit", "type": "number", "required": false, "description": "Maximum relationship.mutual_connections.preview entries returned for this page. Default 50 on direct/detail calls, server max 500." }, { "name": "mutual_connection_offset", "type": "number", "required": false, "description": "Zero-based offset into relationship.mutual_connections.preview for paging persisted/researched mutual connectors." } ], "fields": [ { "name": "social_proximity_score", "type": "number|null", "required": false, "description": "0-100 requester-relative score used for ranking and reachability summaries. This mirrors search_score: researched_score when fresh LinkedIn mutual research exists, otherwise baseline_score." }, { "name": "social_proximity_band", "type": "very_warm|warm|some_signal|weak|null", "required": false, "description": "Machine-friendly band derived from social_proximity_score." }, { "name": "social_proximity_tier", "type": "string|null", "required": false, "description": "Human label for social_proximity_band (Very warm, Warm, Some signal, Weak)." }, { "name": "best_intro_path_type", "type": "supercarl_referral|manual_linkedin_intro|null", "required": false, "description": "Best intro mode inferred from mutual connector availability. SuperCarl referral is preferred when a SuperCarl mutual path exists." }, { "name": "score_version", "type": "number|null", "required": false, "description": "Scoring config version. Current version: 7." }, { "name": "mutual_connections_count", "type": "number", "required": false, "description": "Count of surfaced mutual connectors on the result row." }, { "name": "mutual_connections", "type": "PersonSummary[]", "required": false, "description": "Subset of mutual connectors shown inline on search results." }, { "name": "relationship", "type": "RelationshipDetail|null", "required": false, "description": "Structured requester-relative relationship payload returned when relationship_detail is summary or intro_paths." } ] }, { "name": "API-key social-proximity research", "auth_mode": "api_key", "auth_header": "X-API-Key", "endpoints": [ "POST /api/v1/relationships/social-proximity/research", "GET /api/v1/relationships/social-proximity/research/status" ], "model": "SocialProximityResearchResponse", "note": "Explicitly starts LinkedIn mutual research for one target when recent cached research is unavailable. The status endpoint is read-only and never starts or refreshes research. Search/read endpoints never auto-start research.", "request_parameters": [ { "name": "target_user_id", "type": "string", "required": true, "description": "Target Super Carl user id." }, { "name": "delegate_user_id", "type": "string", "required": false, "description": "Permitted teammate user id to act as." }, { "name": "page_limit", "type": "number", "required": false, "description": "Optional LinkedIn mutual pages to request." }, { "name": "page_size", "type": "number", "required": false, "description": "Optional LinkedIn mutual page size." }, { "name": "reset", "type": "boolean", "required": false, "description": "Request restart for previous/stale research; recent completed research is still reused within the server cooldown." }, { "name": "intro_path_limit", "type": "number", "required": false, "description": "Maximum returned confirmed-mutual intro paths, default 3 and max 20." }, { "name": "possible_intro_limit", "type": "number", "required": false, "description": "Maximum first-degree worked-with overlap paths, default 20 and max 100." }, { "name": "possible_intro_offset", "type": "number", "required": false, "description": "Zero-based offset into first-degree worked-with overlap paths." }, { "name": "mutual_connection_limit", "type": "number", "required": false, "description": "Maximum relationship.mutual_connections.preview entries returned for this page, default 50 and max 500." }, { "name": "mutual_connection_offset", "type": "number", "required": false, "description": "Zero-based offset into the persisted mutual-connection list." } ], "fields": [ { "name": "relationship", "type": "RelationshipDetail|null", "required": false, "description": "Current structured relationship and intro-path payload." }, { "name": "research", "type": "object", "required": true, "description": "Start/continue result from the LinkedIn mutual research workflow." }, { "name": "detail.research_status", "type": "SocialProximityResearchStatus", "required": false, "description": "Current research status and recovery guidance." } ] }, { "name": "Authenticated summaries endpoint", "auth_mode": "jwt", "auth_header": "Authorization: Bearer ", "endpoints": [ "POST /users/social-proximity/summaries" ], "model": "SocialProximitySummaryResponse", "note": "Returns baseline/search scores, evidence, component metadata, and direct-relationship timestamps for each requested target.", "fields": [ { "name": "summaries[].summary.search_score", "type": "number", "required": true, "description": "Primary score used by search ranking and banding." }, { "name": "summaries[].summary.metadata.components", "type": "SocialProximityComponents", "required": false, "description": "Component-level score breakdown used to produce the total." }, { "name": "summaries[].summary.metadata.mutual_connections", "type": "object", "required": false, "description": "Mutual-connection counts, overlap ratios, research readiness, and baseline-vs-researched metadata." }, { "name": "summaries[].summary.metadata.direct_relationship", "type": "object", "required": false, "description": "Normalized direct-relationship timestamps (LinkedIn and SuperCarl) used for evidence and recency bonus handling." }, { "name": "summaries[].summary.evidence", "type": "SocialProximityEvidence[]", "required": false, "description": "Deduped evidence list sorted by strongest score contribution and recency." } ] }, { "name": "Authenticated detail and research endpoints", "auth_mode": "jwt", "auth_header": "Authorization: Bearer ", "endpoints": [ "GET /users/:targetUserId/social-proximity", "POST /users/:targetUserId/social-proximity/research" ], "model": "SocialProximityDetail", "note": "Returns connector path scoring, researched score variants, evidence highlights, and the current LinkedIn mutual-research workflow state.", "fields": [ { "name": "baseline", "type": "SocialProximityScoreCard", "required": true, "description": "Baseline score card using local graph evidence and missing-research fallback rules." }, { "name": "researched", "type": "SocialProximityScoreCard|null", "required": false, "description": "Refined score card after fresh LinkedIn mutual research is available." }, { "name": "connectors_supercarl", "type": "SocialProximityConnector[]", "required": false, "description": "Mutual connectors who can support a SuperCarl referral path." }, { "name": "connectors_linkedin_manual", "type": "SocialProximityConnector[]", "required": false, "description": "Mutual connectors that require a manual LinkedIn intro path." }, { "name": "research_status", "type": "SocialProximityResearchStatus", "required": true, "description": "Current LinkedIn mutual-research state and recovery guidance." } ] } ], "score_resolution": { "clamp_range": "All totals are clamped to the inclusive range 0-100.", "baseline_formula": "baseline_score = direct_relationship + profile_overlap + reciprocal_communication + public_activity + mutual_connections_baseline + cross_network", "researched_formula": "researched_score = direct_relationship + profile_overlap + reciprocal_communication + public_activity + mutual_connections_researched + cross_network", "search_formula": "search_score = researched_score ?? baseline_score", "note": "Search responses expose search_score only. The authenticated detail surface exposes baseline and researched score cards separately." }, "tiers": [ { "min_score": 75, "tier": "very_warm", "band": "very_warm", "label": "Very warm" }, { "min_score": 50, "tier": "warm", "band": "warm", "label": "Warm" }, { "min_score": 25, "tier": "some_signal", "band": "some_signal", "label": "Some signal" }, { "min_score": 0, "tier": "weak", "band": "weak", "label": "Weak" } ], "components": [ { "key": "direct_relationship", "label": "Direct relationship", "max_points": 35, "evidence_category": "direct_relationship", "component_fields": [ "metadata.components.direct_relationship", "metadata.direct_relationship", "evidence[]" ], "description": "Scores the strongest direct relationship source only, then adds a recency bonus when that relationship or verification is recent.", "scoring": { "strongest_source_only": true, "base_by_source": [ { "source": "supercarl", "evidence_label": "Super Carl Connector", "points": 24 }, { "source": "linkedin", "evidence_label": "Connected on LinkedIn", "points": 17 }, { "source": "gmail", "evidence_label": "In your address book", "points": 15 }, { "source": "x", "evidence_label": "Connected through X", "points": 10 }, { "source": "instagram", "evidence_label": "Connected on Instagram", "points": 10 } ], "recency_bonus": { "within_30_days": 6, "within_90_days": 3 } }, "evidence_mapping": [ { "label": "Super Carl Connector", "when": "Strongest direct source = supercarl", "source": "supercarl" }, { "label": "Connected on LinkedIn", "when": "Strongest direct source = linkedin", "source": "linkedin" }, { "label": "In your address book", "when": "Strongest direct source = gmail", "source": "gmail" }, { "label": "Connected through X", "when": "Strongest direct source = x", "source": "x" }, { "label": "Connected on Instagram", "when": "Strongest direct source = instagram", "source": "instagram" }, { "label": "Recent connection or verification", "when": "Strongest direct source was connected or verified within 90 days", "source": null } ] }, { "key": "profile_overlap", "label": "Profile overlap", "max_points": 30, "evidence_category": "profile_overlap", "component_fields": [ "metadata.components.profile_overlap", "evidence[]" ], "description": "Scores shared professional context such as current company, prior company history, timeline overlap, school background, and geography.", "scoring": { "same_small_company": 18, "same_large_company_with_domain_or_leadership": 16, "same_large_company_weak": 8, "prior_company": 8, "shared_current_industry": { "points": 2, "max_company_industry_count": 5, "excluded_industry_labels": [ "Software Development", "IT Services and IT Consulting", "Technology, Information and Internet", "Financial Services", "Business Consulting and Services", "Advertising Services", "Venture Capital and Private Equity Principals", "Information Technology & Services", "Investment Management", "Higher Education", "Human Resources Services", "Computer and Network Security", "Hospitals and Health Care", "Real Estate", "Retail", "Non-profit Organizations", "Technology", "Staffing and Recruiting", "Entertainment", "Retail Apparel and Fashion", "Information and Internet", "Marketing Services", "Professional Training and Coaching", "Entertainment Providers", "Government Administration" ] }, "timeline_overlap_tiers": [ { "minMonths": 36, "score": 9 }, { "minMonths": 12, "score": 7 }, { "minMonths": 1, "score": 5 } ], "shared_company_timeline_bonus_tiers": [ { "minMonths": 36, "score": 10 }, { "minMonths": 12, "score": 8 }, { "minMonths": 1, "score": 6 } ], "school": 4, "geography": 3, "small_company_exec_bonus": 3 }, "evidence_mapping": [ { "label": "Same current company (...)", "when": "Current company matches", "source": null }, { "label": "Same current company (...) with domain or leadership overlap", "when": "Current company matches and a stronger large-company corroboration signal exists", "source": null }, { "label": "Both hold leadership roles at the same company", "when": "Small-company exec bonus applied", "source": null }, { "label": "Shared current industry (...)", "when": "Specific current industry overlap applied", "source": null }, { "label": "Shared company history at ...", "when": "Prior shared company applied", "source": null }, { "label": "Overlapping time at ...", "when": "Timeline overlap tiers applied", "source": null }, { "label": "Shared school background ...", "when": "School overlap applied", "source": null }, { "label": "Same city", "when": "Top geography overlap is same_city", "source": null }, { "label": "Similar geography", "when": "Geography overlap applied without same-city match", "source": null } ] }, { "key": "reciprocal_communication", "label": "Reciprocal communication", "max_points": 15, "evidence_category": "reciprocal_communication", "component_fields": [ "metadata.components.reciprocal_communication", "evidence[]" ], "description": "Scores direct message exchange on SuperCarl. Reciprocal conversations score materially higher than one-way outreach.", "scoring": { "max_points": 15, "formula_notes": [ "Reciprocal message exchange uses a higher base, additional volume credit, and a balance bonus.", "One-way outreach is capped lower." ] }, "evidence_mapping": [ { "label": "Exchanged messages on SuperCarl", "when": "Both users have sent messages to each other", "source": "supercarl" }, { "label": "One-way SuperCarl outreach", "when": "Only one user has messaged the other", "source": "supercarl" } ] }, { "key": "public_activity", "label": "Public activity", "max_points": 20, "evidence_category": "public_activity", "component_fields": [ "metadata.components.public_activity", "evidence[]" ], "description": "Scores post-level interactions such as likes, comments, reposts, and mentions, with decay for older activity and a multiplier for mutual activity.", "scoring": { "max_points": 20, "weights": { "like": 2, "reaction": 2, "comment": 4, "reply": 5, "repost": 5, "mention": 5 }, "mutual_multiplier": 3 }, "evidence_mapping": [ { "label": "Mutual social activity across posts", "when": "Both users have public interactions toward each other", "source": "linkedin_or_activity_source" }, { "label": "One-way likes or reactions", "when": "Strongest public activity is a like or reaction", "source": null }, { "label": "One-way comments on posts", "when": "Strongest public activity is a comment", "source": null }, { "label": "Reposted social content", "when": "Strongest public activity is a repost", "source": null }, { "label": "Mentioned in social activity", "when": "Strongest public activity is a mention", "source": null } ] }, { "key": "mutual_connections", "label": "Mutual connections", "max_points": 20, "evidence_category": "mutual_connections", "component_fields": [ "metadata.components.mutual_connections_baseline", "metadata.components.mutual_connections_researched", "metadata.components.mutual_connections_search", "metadata.mutual_connections", "evidence[]" ], "description": "Scores shared connector overlap from LinkedIn and SuperCarl. When fresh LinkedIn mutual research is missing, a baseline floor is used so known graph overlap still contributes to search ranking.", "scoring": { "max_points": 20, "missing_linkedin_research_baseline": 10, "known_graph_evidence_label": "Some graph overlap, LinkedIn mutual not yet researched", "missing_research_label": "LinkedIn mutual overlap has not been fully researched yet", "linkedin_score_tiers": [ { "minOverlapRatio": 0.02, "minMutualCount": 10, "score": 20, "evidenceLabel": "Very high LinkedIn mutual overlap" }, { "minOverlapRatio": 0.01, "minMutualCount": 10, "score": 15, "evidenceLabel": "Strong LinkedIn mutual overlap" }, { "minOverlapRatio": 0.002, "minMutualCount": 5, "score": 10, "evidenceLabel": "Meaningful LinkedIn mutual overlap" }, { "minOverlapRatio": 0.001, "minMutualCount": 10, "score": 5, "evidenceLabel": "Some LinkedIn mutual overlap" }, { "minOverlapRatio": 0, "minMutualCount": 3, "score": 2, "evidenceLabel": "A few LinkedIn mutuals" }, { "minOverlapRatio": 0, "minMutualCount": 1, "score": 1, "evidenceLabel": "At least one LinkedIn mutual" } ], "supercarl_bonus_tiers": [ { "minCount": 10, "score": 5, "evidenceLabel": "Many shared SuperCarl mutuals" }, { "minCount": 5, "score": 3, "evidenceLabel": "Several shared SuperCarl mutuals" }, { "minCount": 2, "score": 2, "evidenceLabel": "A few shared SuperCarl mutuals" }, { "minCount": 1, "score": 1, "evidenceLabel": "Shared SuperCarl mutuals" } ] }, "evidence_mapping": [ { "label": "Some graph overlap, LinkedIn mutual not yet researched", "when": "Local graph overlap exists but fresh LinkedIn mutual research is not ready", "source": "linkedin" }, { "label": "Very high LinkedIn mutual overlap", "when": "Researched LinkedIn overlap meets minMutualCount=10 and minOverlapRatio=0.02", "source": "linkedin" }, { "label": "Strong LinkedIn mutual overlap", "when": "Researched LinkedIn overlap meets minMutualCount=10 and minOverlapRatio=0.01", "source": "linkedin" }, { "label": "Meaningful LinkedIn mutual overlap", "when": "Researched LinkedIn overlap meets minMutualCount=5 and minOverlapRatio=0.002", "source": "linkedin" }, { "label": "Some LinkedIn mutual overlap", "when": "Researched LinkedIn overlap meets minMutualCount=10 and minOverlapRatio=0.001", "source": "linkedin" }, { "label": "A few LinkedIn mutuals", "when": "Researched LinkedIn overlap meets minMutualCount=3 and minOverlapRatio=0", "source": "linkedin" }, { "label": "At least one LinkedIn mutual", "when": "Researched LinkedIn overlap meets minMutualCount=1 and minOverlapRatio=0", "source": "linkedin" }, { "label": "Many shared SuperCarl mutuals", "when": "SuperCarl mutual count >= 10", "source": "supercarl" }, { "label": "Several shared SuperCarl mutuals", "when": "SuperCarl mutual count >= 5", "source": "supercarl" }, { "label": "A few shared SuperCarl mutuals", "when": "SuperCarl mutual count >= 2", "source": "supercarl" }, { "label": "Shared SuperCarl mutuals", "when": "SuperCarl mutual count >= 1", "source": "supercarl" } ] }, { "key": "cross_network", "label": "Cross-network corroboration", "max_points": 10, "evidence_category": "cross_network", "component_fields": [ "metadata.components.cross_network", "evidence[]" ], "description": "Adds credit when the same relationship is corroborated across more than one direct network source.", "scoring": { "per_additional_source": 5, "max_points": 10 }, "evidence_mapping": [ { "label": "Cross-network corroboration", "when": "Two or more direct relationship sources are present", "source": null } ] } ], "evidence": { "ordering": "Evidence entries are deduped and sorted by descending score weight, then by recency.", "shape": { "label": "string", "category": "direct_relationship|profile_overlap|reciprocal_communication|public_activity|mutual_connections|cross_network", "source": "string|null" }, "categories": [ { "key": "direct_relationship", "description": "Strongest direct relationship source plus optional recency evidence." }, { "key": "profile_overlap", "description": "Shared professional, educational, and geographic context." }, { "key": "reciprocal_communication", "description": "Message exchange on SuperCarl." }, { "key": "public_activity", "description": "Likes, comments, reposts, mentions, and mutual post activity." }, { "key": "mutual_connections", "description": "Local and researched mutual connector overlap across LinkedIn and SuperCarl." }, { "key": "cross_network", "description": "Extra corroboration when multiple direct networks confirm the relationship." } ] }, "path_scoring": { "description": "Connector path scoring ranks confirmed mutual introduction candidates for the authenticated detail endpoints. It blends viewer->connector and connector->target social proximity, then adds an actionability bonus for SuperCarl connectors. Ranking runs asynchronously and is cached; read responses may include provisional/unranked paths until intro_paths_status.ranking_pending is false. Returned path limits do not cap the candidate pool scored for ranking; caps/timeouts and ranking_queue_* stale-queue fields are surfaced in intro_paths_status. API/MCP clients should prefer relationship.social_map.entries[] as the unified list: confirmed mutual connectors use path_type=\"confirmed_mutual\", while possible \"may know\" paths sourced from first-degree viewer connections that pass the worked_with target profile-intersection filter use path_type=\"experience_intersection\" and are not confirmed mutuals.", "formula": "path_score = viewer_connector.search_score * viewerConnectorWeight + connector_target.search_score * connectorTargetWeight + optional supercarlActionabilityBonus", "weights": { "viewer_connector": 0.6, "connector_target": 0.4 }, "supercarl_actionability_bonus": 4, "max_points": 100, "surfaced_on": [ "GET /users/:targetUserId/social-proximity -> connectors_supercarl[]", "GET /users/:targetUserId/social-proximity -> connectors_linkedin_manual[]", "POST /api/v1/search/people relationship_detail=intro_paths -> users[].relationship.social_map.entries[]", "POST /api/v1/search/people relationship_detail=intro_paths -> users[].relationship.intro_paths[]", "POST /api/v1/search/people relationship_detail=intro_paths -> users[].relationship.possible_intro_paths[]", "POST /api/v1/relationships/social-proximity/research -> relationship.social_map.entries[]", "POST /api/v1/relationships/social-proximity/research -> relationship.intro_paths[]", "POST /api/v1/relationships/social-proximity/research -> relationship.possible_intro_paths[]" ] } } }