> ## Documentation Index
> Fetch the complete documentation index at: https://docs.theswarm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Relationships

> Explore your team's network. The Relationships endpoint queries connection data using OpenSearch DSL and returns the people connected to your team, with full connection details.

## 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](/docs/endpoints/v3/relationships). For example queries, see [Relationships endpoint examples](/docs/examples/relationships-endpoint).

<Note>
  Relationships requests do not consume API credits. See [Credits & Usage](/docs/api-reference/credits-usage).
</Note>

## 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.

```json theme={null}
{
  "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`.

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

Because `team_connections` is nested, the query must use a [nested query](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-nested-query.html):

```json theme={null}
{
  "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)](/docs/enrichment-data/profile/mappings-v3). For more examples, see [Relationships endpoint examples](/docs/examples/relationships-endpoint).

## Success response (200 OK)

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

```json theme={null}
[
  {
    "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](/docs/examples/relationships-endpoint).

```json theme={null}
{
  "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**

```json theme={null}
{
  "query": {
    "term": {
      "profile_info.current_company_website": {
        "value": "google.com"
      }
    }
  },
  "limit": 100
}
```

**Response (more pages available)**

```json theme={null}
{
  "items": [...],
  "count": 100,
  "total_count": 340,
  "pagination_token": "eyJzYXAiOnsic2Vhc..."
}
```

**Next-page request**

```json theme={null}
{
  "query": {
    "term": {
      "profile_info.current_company_website": {
        "value": "google.com"
      }
    }
  },
  "limit": 100,
  "pagination_token": "eyJzYXAiOnsic2Vhc..."
}
```