Network Mapper (for Partners)

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

Where:

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
}

Where:

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.

{ "task_id": "123abc" }

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]?]"
    }
  ]
}

Missing or invalid 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`

See the Network Mapper Status reference. Possible 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"
      }
    }
  }
}

Getting Started

Enrichment Data

Signals

Flat Files

MCP

Team Management

Miscellaneous

Network Mapper (for Partners)

Introduction

Pricing

Authentication

Endpoint

Body parameters

Success response (200 OK)

Async response (202 Accepted)

Error responses

400 — Validation failed

403 — Forbidden

404 — Not found

Callback body — failure

Async status endpoint

Filtering and query customization

Filter by title

Filter by function

Filter by seniority

Intro path to a specific person

​Introduction

​Pricing

​Authentication

​Endpoint

​Body parameters

​Success response (200 OK)

​Async response (202 Accepted)

​Error responses

​400 — Validation failed

​403 — Forbidden

​404 — Not found

​Callback body — failure

​Async status endpoint

​Filtering and query customization

​Filter by title

​Filter by function

​Filter by seniority

​Intro path to a specific person

Introduction

Pricing

Authentication

Endpoint

Body parameters

Success response (200 OK)

Async response (202 Accepted)

Error responses

400 — Validation failed

403 — Forbidden

404 — Not found

Callback body — failure

Async status endpoint

Filtering and query customization

Filter by title

Filter by function

Filter by seniority

Intro path to a specific person