Social proximity
Requester-relative warmth, evidence, and intro-path scoring fields.
Context guidance: Use when interpreting relationship evidence or proximity scores.
Social proximity
Full proximity scoring and evidence schema are available in /docs/social-proximity.json.
{
"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 <token>",
"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 <token>",
"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[]"
]
}
}Machine-readable JSON
- Focused JSON for this page: /docs/social-proximity.json
- Full schema JSON: /docs/schema.json
- Canonical API schema: https://api.supercarl.ai/public/docs/schema
- Canonical MCP schema: https://api.supercarl.ai/public/docs/mcp
- Canonical changelog: https://api.supercarl.ai/public/docs/changelog