Skip to main content

​
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.
HeaderValue
Content-Typeapplication/json
x-api-key<YOUR_API_KEY>

​
Endpoint

URLhttps://bee.theswarm.com/v3/relationships
MethodPOST
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.
ParameterTypeDefaultMaxDescription
limitinteger1001000Number of results to return per page
pagination_tokenstring——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..."
}