Network Mapper API

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.

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": "theswarm.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": "shared_investor",
				"investor": "Felicis Ventures",
				"portfolio_company": "Plaid"
			}],
			"user_id": "c09a9b47-7de1-4f6a-8085-c44ed18db9e0",
			"user_name": "Olivier Roth",
			"user_linkedin_slug": "max-greenwald",
			"connection_strength": 0.1084125480166015,
			"manual_strength": null,
			"strength_normalized": 1,
			"created_at": "2024-07-05T13:49:44.542508Z"
		}, {
			"sources": [{
				"origin": "work_overlap",
				"shared_company": "San Francisco Public Defender's Office",
				"overlap_start_date": "2020-05-01",
				"overlap_end_date": "2020-08-01",
				"overlap_length": "4M"
			}],
			"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"
		}
		]
	}, {
		(...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"
            }
          }
        }
      ]
    }
  }
}