Skip to main content

​
Introduction

The Network Mapper API builds an entire relationship graph for a company. It analyzes data points to (1) identify relationships and (2) calculate Connection Strength scores for every relationship. As part of the process, we map the “overlaps” of a company’s “connectors”: Overlaps are:
  • Work history overlap: people who work or worked at the same company
  • Education overlap: People who graduated the same university in the same year
Connectors are:
  • Employees of the company
  • Company’s VCs (when applicable)
  • Execs of the portfolio companies of the company’s VCs (when applicable)
  • Any other stakeholders added manually

​
The Swarm API Reference

The Swarm API is designed using the REST architectural style, employing standard HTTP methods for communication. Responses from the API are formatted in JSON (JavaScript Object Notation), a lightweight data-interchange format widely supported across various programming languages and platforms. This design choice ensures simplicity, flexibility, and ease of integration for developers utilizing the API.

​
Authentication

Access to the API is authenticated using an API key mechanism. Each company can bring an individual API key provided by The Swarm. The API key should be included in the request headers (as x-api-key header) for each API call to authorize access to the endpoints. When using a Partner-managed API key, Swarm API expects additional body parameters in the request (see below)

​
Endpoint

Production URL: [https://bee.theswarm.com/v2/profiles/network-mapper\\\\](https://bee.theswarm.com/v2/profiles/network-mapper\) Method: POST
Description: This endpoint allows to query the relationship database using OpenSearch DSL to retrieve all connections in the network meeting the query criteria.

​
Headers:

KeyValue
Content-Typeapplication/json
x-Api-KeyYOUR_API_KEY

​
Body Parameters

The request body must contain an OpenSearch DSL query to search for a subset of the network. In the example below, we query for connections working in a 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. This is the key field that is used to filter connections.
You can include other fields and filters in the OpenSearch DSL query if you need to refine the results further (e.g., filtering by job title, location, etc.). Additional fields are required for Partner-managed Swarm accounts. For non-partner API keys, these fields are ignored:
  • mapping_company_website - website domain of the company to be mapped (customer’s company).
  • callback_url - URL for async response. Data will be sent to this URL when company mapping is finished.

​
Success Response (200 OK)

When the query is successful, the API returns a list of connections in the following format. 
{
  "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 who are connected to the profile.
  • connections.sources: Describes the ways the profile is connected to the team member. There can be multiple ways connecting two people. The type of connection is defined by connection.sources.origin and the schema of the elements depends on it. Below is the list of all values origin can currently take:
    • linkedin_connection
    • calendar_events
    • email_contact
    • manual_import
    • work_overlap
    • education_overlap
    • shared_investor
  • count: number of returned items (max 50)
  • total_count: number of all available connections

​
Success Async Response (202 Accepted)

When the query is successful, but the company with the given mapping_company_website is not yet mapped, the request will be processed asynchronously and a task_id is returned. Task status can be checked at a separate endpoint: https://bee.theswarm.com/v2/profiles/network-mapper-task-status The response to the asynchronous request will be sent to the callback. 
{
  "task_id": "123abc"
}

​
Unsuccessful Response Bad Request (400)

  • Wrong query:
{
  "status": 400,
  "title": "Validation failed",
  "errors": [
    {
      "path": "query",
      "violation": "ParsingException[unknown query [matchd] did you mean any of [match, match_all]?]; nested: NamedObjectNotFoundException[[1:20] unknown field [matchd]];; org.openserrch.core.xcontent.NamedObjectNotFoundException: [1:20] unknown field [matchd]"
    }
  ]
}
  • Wrong mapping_company_website
{
  "status": 400,
  "errors": [
    {
      "message": "mapping_company_websites"
    }
  ]
}
  • Missing mapping_company_website (when using Partner API Key)
{
  "status": 400,
  "errors": [
    {
      "message": "mapping_company_website missing in request"
    }
  ]
}

​
Unsuccessful Response- Company with domain not found (404 Not Found)

In this case, we don’t have a company with a given domain in our database at the moment, so we can’t perform requests for ‘My Company Domain’ 
{
  "status": 404,
  "errors": [
    {
      "message": "mapping_company_website not found - can't perform network mapping"
    }
  ]
}

​
Callback requests body:

Successful: the body has the same format as 200 network mapper response Failed: 
{
  "status": 500,
  "errors": [
    {
      "message": "failed to map team with company domain theswarm.com"
    }
  ]
}
Message - description of what went wrong on our side.

​
Async Request Status Endpoint

This endpoint allows looking up the status of the company mapping process. URL: [https://bee.theswarm.com/v2/profiles/network-mapper-task-status\\\\](https://bee.theswarm.com/v2/profiles/network-mapper-task-status\) Method: POST
Description: This endpoint allows to check the status of the mapping task with a given ID. Works only with the partner-managed API key.
KeyValue
Content-Typeapplication/json
x-Api-KeyPARTNER_API_KEY

​
Body Parameters

{
  "task_id": "123abc"
}

​
Responses:

​
Success Response (200 OK)

Successfully checked task status. 
{
  "task_status": "<status>"
}
Possible values:
  • in_progress
  • done
  • failed

​
Task Not Found (404)

{
  "status": 404,
  "errors": [
    {
      "message": "can't find status for task with id '123abc'"
    }
  ]
}

​
Failed To Check Task Status (500)

{
  "status": 500,
  "errors": [
    {
      "message": "internal problem occured"
    }
  ]
}

​
Filtering & Query Customization

As mentioned above, the endpoint accepts an OpenSearch query of any type, so it can be used to narrow the results down even further. E.g. you can refine the query to return only people with certain job titles at the company. For more information on The Swarm API search capabilities refer to our main documentation.

​
Example OpenSearch DSL queries are below.

​
When looking for the best software engineers on earth:

{
  "query": {
    "bool": {
      "must": [
        {
          "term": {
            "profile_info.current_company_website": {
              "value": "theswarm.com"
            }
          }
        },
        {
          "match": {
            "profile_info.current_title": {
              "query": "software engineer",
              "operator": "AND"
            }
          }
        }
      ]
    }
  }
}

​
When looking for profiles in specific function:

{
  "query": {
    "bool": {
      "must": [
        {
          "match": {
            "profile_info.current_company_websites": {
              "query": "theswarm.com"
            }
          }
        },
        {
          "match": {
            "profile_info.current_job_function": {
              "query": "Engineering"
            }
          }
        }
      ]
    }
  }
}
Canonical values for function:
  • “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”

​
When looking for profiles with specific seniority:

{
  "query": {
    "bool": {
      "must": [
        {
          "match": {
            "profile_info.current_company_websites": {
              "query": "theswarm.com"
            }
          }
        },
        {
          "match": {
            "profile_info.current_seniority": {
              "query": "Engineering"
            }
          }
        }
      ]
    }
  }
}
Canonical values for seniority:
  • c-level
  • director
  • vp
  • manager
  • senior
  • junior

​
When looking for an intro path to a specific person:

{
  "query": {
    "term": {
      "profile_info.linkedin_usernames": {
        "value": "michal-bil"
      }
    }
  }
}