Introduction
The Network Mapper endpoint builds an entire relationship graph for a target company. It analyzes data points to (1) identify relationships and (2) calculate Connection Strength scores for every relationship.
For team-owned connections, use the free Relationships endpoint instead.
As part of the process, we map the “overlaps” of a company’s “connectors”:
Overlaps:
- Work history overlap — people who work or worked at the same company
- Education overlap — people who graduated from the same university in the same year
Connectors:
- Employees of the company
- The company’s VCs (when applicable)
- Execs of portfolio companies of the company’s VCs (when applicable)
- Any other stakeholders added manually
For the API specification, see Network Mapper endpoint reference.
Partner permission required. Calls from an API key not tied to a team with the partner permission in Stripe return 403 Forbidden.
Pricing
| Response | Cost |
|---|
| Non-empty response | 1 credit per response |
| Empty response | Free |
Authentication
Authenticate with your partner-managed API key in the x-api-key header.
| Header | Value |
|---|
Content-Type | application/json |
x-api-key | <YOUR_API_KEY> |
Endpoint
| |
|---|
| URL | https://bee.theswarm.com/v3/network-mapper |
| Method | POST |
Body parameters
In the example below, we query for connections to a target company identified by website domain.
{
"query": {
"term": {
"profile_info.current_company_websites": {
"value": "openai.com"
}
}
},
"mapping_company_website": "theswarm.com",
"callback_url": "www.callback.com/some-async-webhook"
}
profile_info.current_company_website — A valid website domain of the target company.
The following fields are required for partner-managed accounts:
mapping_company_website — Website domain of the company to be mapped (the customer’s company).callback_url — URL for async response. Data is sent to this URL when company mapping is finished.
Success response (200 OK)
{
"items": [
{
"profile": {
"id": "f0f9f467-7798-4b15-a913-3d1375c85390",
"full_name": "David Connors",
"current_title": "Co-Founder & CEO",
"linkedin_url": "https://linkedin.com/in/connorsdavid",
"work_email": "david@theswarm.com",
"current_company_name": "The Swarm",
"current_company_website": "theswarm.com"
},
"connections": [
{
"connector_id": "c050884c-001a-488c-b280-0f617cf4f7bc",
"connector_name": "Michal Bil",
"connector_linkedin_url": "https://www.linkedin.com/in/michal-bil/",
"connector_current_title": "Co-Founder & CTO",
"connector_current_company_name": "The Swarm",
"connection_strength_normalized": 3,
"connection_strength": 0.8840964268278736,
"sources": [
{ "origin": "linkedin_connection" },
{
"origin": "work_overlap",
"shared_company": "The Swarm",
"shared_company_id": "09d9c510-c9f6-4c6e-9e62-fe5fedbeda87",
"shared_company_website": "theswarm.com",
"overlap_start_date": "2022-02-01",
"overlap_duration_months": 35
},
{ "origin": "email_contact" },
{ "origin": "calendar_events" }
]
}
]
}
],
"count": 50,
"total_count": 213
}
profile — Basic information about the connection.connections — Team members connected to the profile.connections.sources — Describes how the profile is connected. The shape depends on origin. Accepted origin values: linkedin_connection, work_overlap, email_contact, calendar_events, manual_import, education_overlap, shared_investor.count — Number of returned items (max 50).total_count — Total available connections.
Async response (202 Accepted)
If the target company is not yet mapped, the request is processed asynchronously and a task_id is returned. The full result is delivered to the callback_url.
Poll task status using the Network Mapper Status endpoint.
Error responses
400 — Validation failed
Wrong query syntax:
{
"status": 400,
"title": "Validation failed",
"errors": [
{
"path": "query",
"violation": "ParsingException[unknown query [matchd] did you mean any of [match, match_all]?]"
}
]
}
mapping_company_website:
{
"status": 400,
"errors": [
{ "message": "mapping_company_website missing in request" }
]
}
403 — Forbidden
The API key is not tied to a team with partner permission.
404 — Not found
The company with the given mapping_company_website is not in our database.
{
"status": 404,
"errors": [
{ "message": "mapping_company_website not found - can't perform network mapping" }
]
}
Callback body — failure
{
"status": 500,
"errors": [
{ "message": "failed to map team with company domain theswarm.com" }
]
}
Async status endpoint
Poll the status of a long-running mapping task.
| |
|---|
| URL | https://bee.theswarm.com/v3/network-mapper/status |
| Method | GET |
task_status values: in_progress, done, failed.
Filtering and query customization
The endpoint accepts any OpenSearch DSL query — narrow results by job title, function, seniority, or any indexed field.
Filter by title
{
"query": {
"bool": {
"must": [
{
"term": {
"profile_info.current_company_website": {
"value": "theswarm.com"
}
}
},
{
"match": {
"profile_info.current_title": {
"query": "software engineer",
"operator": "AND"
}
}
}
]
}
}
}
Filter by function
Canonical values: IT & Engineering, Human Resources, Operations & Supply Chain, Marketing & Product Management, Sales & Business Development, Customer Service & Support, Finance & Accounting, Legal & Compliance, Healthcare & Medical Services, Education & Training, Consulting & Strategy, Real Estate & Property Management, Media, Publishing & Journalism, Design & Creative Services, Trades & Skilled Labor, Public Relations & Communications, Quality Assurance & Control, Program & Project Management, Banking & Financial Services, Administration & Office Support.
Filter by seniority
Canonical values: c-level, director, vp, manager, senior, junior.
Intro path to a specific person
{
"query": {
"term": {
"profile_info.linkedin_usernames": {
"value": "michal-bil"
}
}
}
}
