Skip to main content

​
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. For now, each company needs 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.

​
Endpoint

URL: 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.
KeyValue
Content-Typeapplication/json
x-Api-Key<YOUR_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_website": {
       "value": "google.com"
     }
   }
 }
}
Where:
  • profile_info.current_company_website - A valid website domain of the company you want to query relationships for. 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.).

​
Success Response (200 OK)

When the query is successful, the API returns a list of connections in the following format. 
[
	{
		"profile": {
			"full_name": "David Connors",
			"current_title": "Co-Founder & CEO",
			"linkedin_slug": "connorsdavid",
			"work_email": "david@theswarm.com",
			"current_company_name": "The Swarm",
			"current_company_website": "theswarm.com",
			"current_company_industry": "Computer Software"
		},
		"connections": [
		{
			"sources": [{
				"origin": "work_overlap",
				"shared_company": "Sequoia Capital",
				"overlap_start_date": "2020-05-01",
				"overlap_end_date": "2020-11-01",
				"overlap_length": "6M"
			}],
			"user_id": "3ac2930c-2ff1-49ec-9a02-ab9cb8d6a56e",
			"user_name": "Nabil Saad",
			"user_linkedin_name": "nabil-saad-4845bb1b6",
			"connection_strength": 0.3257573518327063,
			"manual_strength": null,
			"strength_normalized": 2,
			"created_at": "2024-07-04T11:57:56.678785Z"
		},
		{
			"sources": [{
				"origin": "shared_investor",
				"investor": "Felicis Ventures",
				"portfolio_company": "Plaid"
			}],
			"user_id": "52296b0b-7c2c-497c-9342-8a17211d8085",
			"user_name": "Elisa Schreiber",
			"user_linkedin_slug": "elisaschreiber",
			"connection_strength": 0.1084125480166015,
			"manual_strength": null,
			"strength_normalized": 1,
			"created_at": "2024-07-05T13:49:44.542508Z"
		}
		]
	}, {
		"(...another profile meeting the query conditions)"
	}
]
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

​
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 query: 
{
  "query": {
    "bool": {
      "must": [
        {
          "term": {
            "profile_info.current_company_website": {
              "value": "theswarm.com"
            }
          }
        },
        {
          "match": {
            "profile_info.current_title": {
              "query": "software engineer",
              "operator": "AND"
            }
          }
        }
      ]
    }
  }
}

​
Pagination Limitations

Important: The Network Mapper endpoint currently does not support pagination when retrieving connection data.
A single query is limited to returning a maximum of 50 connections per response. If your network contains more than 50 profiles that match your query criteria, the results will be truncated. Recommended Workaround: For comprehensive data retrieval of all profiles within your team’s network, use a combination of the Search and Fetch endpoints instead:
  1. Use the Search endpoint (/v2/profiles/search) with the inNetworkOnly: true parameter and appropriate limit value (up to 1000 profile IDs per request)
  2. Retrieve the list of profile IDs that match your query
  3. Use the Fetch endpoint (/v2/profiles/fetch) to retrieve detailed information for the returned profile IDs (supports up to 1000 profiles per request)
This approach allows you to download complete profile data for your entire team network without the 50-connection limitation imposed by the Network Mapper endpoint.
⌘I