Relationships

Overview

The Relationships endpoint returns profiles connected to the team that owns the API key, along with the connection details for each match (who they’re connected to and how). It is the v3 successor to the team-network Network Mapper endpoint and behaves like the previous inNetwork=true flow. For the API specification, see Relationships endpoint reference. For example queries, see Relationships endpoint examples.

Relationships requests do not consume API credits. See Credits & Usage.

Authentication

Authenticate with your 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/relationships`
Method	`POST`

The request body is a standard OpenSearch DSL query.

Body parameters

In the example below, we query for connections working at a company identified by website domain.

{
  "query": {
    "term": {
      "profile_info.current_company_website": {
        "value": "google.com"
      }
    }
  }
}

You can use any OpenSearch DSL clause (bool, match, term, terms, nested, etc.) to refine results — e.g. by job title, location, or seniority.

Filtering connections by sync origin

The profile document includes a nested team_connections field that stores how each connection was synced. You can query against team_connections.origins, typically scoped to your team_connections.team_id, to limit results to connections from a particular source. Accepted team_connections.origins values (provisional, may change): csv, plugin, overlaps, google, google-calendar, user-profile, manual-csv, education-overlaps, investor-overlaps, manual-url.

This is the query-side vocabulary. The response-side connections[].sources[].origin field uses a different value set — see the response field reference below.

Because team_connections is nested, the query must use a nested query:

{
  "query": {
    "nested": {
      "path": "team_connections",
      "query": {
        "bool": {
          "must": [
            {
              "term": {
                "team_connections.team_id": {
                  "value": "<your team id>"
                }
              }
            },
            {
              "terms": {
                "team_connections.origins": ["overlaps", "plugin"]
              }
            }
          ]
        }
      }
    }
  }
}

For the full v3 mapping, see OpenSearch Profile Mappings (v3). For more examples, see Relationships endpoint examples.

Success response (200 OK)

The API returns a list of matched profiles and their team connections.

[
  {
    "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"
      }
    ]
  }
]

Where:

profile — Basic information about the matched person.
connections — Team members who are connected to the profile.
connections.sources — Describes how the profile is connected to each team member. There can be multiple ways connecting two people. The connection type is defined by sources.origin. Accepted origin values: linkedin_connection, work_overlap, email_contact, calendar_events, manual_import, education_overlap, shared_investor.

Filtering and query customization

The endpoint accepts any OpenSearch DSL query, so you can narrow results further — e.g. people with specific job titles at a target company. For more example queries, see Relationships endpoint examples.

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

Pagination

The Relationships endpoint supports cursor-based pagination via limit and pagination_token.

Parameter	Type	Default	Max	Description
`limit`	integer	100	1000	Number of results to return per page
`pagination_token`	string	—	—	Token returned in the previous response; omit on the first request

When there are more results beyond the current page, the response includes a pagination_token. Pass it in the next request body alongside the same query to retrieve the next page. When the response contains no pagination_token, you have reached the last page. First request

{
  "query": {
    "term": {
      "profile_info.current_company_website": {
        "value": "google.com"
      }
    }
  },
  "limit": 100
}

Response (more pages available)

{
  "items": [...],
  "count": 100,
  "total_count": 340,
  "pagination_token": "eyJzYXAiOnsic2Vhc..."
}

Next-page request

{
  "query": {
    "term": {
      "profile_info.current_company_website": {
        "value": "google.com"
      }
    }
  },
  "limit": 100,
  "pagination_token": "eyJzYXAiOnsic2Vhc..."
}

Getting Started

Enrichment Data

Signals

Flat Files

MCP

Team Management

Miscellaneous

Overview

Authentication

Endpoint

Body parameters

Filtering connections by sync origin

Success response (200 OK)

Filtering and query customization

​Overview

​Authentication

​Endpoint

​Body parameters

​Filtering connections by sync origin

​Success response (200 OK)

​Filtering and query customization

​Pagination

Overview

Authentication

Endpoint

Body parameters

Filtering connections by sync origin

Success response (200 OK)

Filtering and query customization

Pagination