Skip to main content
POST
/
v3
/
relationships
Relationships
curl --request POST \
  --url https://bee.theswarm.com/v3/relationships \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "query": {
    "match": {
      "profile_info.job_title": {
        "query": "Data Scientist"
      }
    }
  },
  "limit": 100,
  "pagination_token": "<string>"
}
'
{
  "items": [
    {
      "profile": {
        "full_name": "<string>",
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "current_title": "<string>",
        "linkedin_url": "<string>",
        "work_email": "<string>",
        "current_company_name": "<string>",
        "current_company_website": "<string>"
      },
      "connections": [
        {
          "connector_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "connector_name": "<string>",
          "connector_linkedin_url": "<string>",
          "connector_current_title": "<string>",
          "connector_current_company_name": "<string>",
          "connection_strength_normalized": 123,
          "connection_strength": 123,
          "manual_strength": 123,
          "sources": [
            {
              "shared_company": "<string>",
              "shared_company_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
              "shared_company_website": "<string>",
              "shared_company_linkedin_slug": "<string>",
              "overlap_start_date": "<string>",
              "overlap_end_date": "<string>",
              "overlap_duration_months": 123,
              "shared_school": "<string>",
              "shared_major": "<string>",
              "graduation_year": "<string>",
              "investor": "<string>",
              "portfolio_company": "<string>"
            }
          ]
        }
      ]
    }
  ],
  "count": 123,
  "total_count": 123,
  "pagination_token": "<string>"
}
Relationships requests do not consume API credits. See Credits & Usage.
The Relationships endpoint returns profiles connected to the team that owns the API key, along with connection details. Responses are returned synchronously. The request body accepts a standard OpenSearch DSL query plus optional limit and pagination_token top-level parameters. For request and response examples, see Relationships endpoint examples. For the response schema, see Models > Network Mapper.

​
Filtering by indexed fields

The OpenSearch DSL query body lets you filter on any indexed field on the profile document. The most common patterns are:
  • Filter by a specific team member (connector) — query the top-level connected_users field (keyword) with a term clause.
  • Filter by how the connection was synced — query the nested team_connections.origins field (keyword) with a nested query, typically scoped to your team_connections.team_id.
  • Filter by profile attributes — query any indexed profile field (title, company, location, seniority, etc.) the same way you would in Search Profiles.
See OpenSearch Profile Mappings (v3) for the full list of indexed fields, and Relationships endpoint examples for ready-to-use queries.

Authorizations

​
x-api-key
string
header
required

Body

application/json
​
query
object
required

Search query in the ElasticSearch Query DSL format. Find mapping here

Example:
{
  "match": {
    "profile_info.job_title": { "query": "Data Scientist" }
  }
}
​
limit
integer
default:100

Limit the number of results

Required range: 0 <= x <= 1000
​
pagination_token
string

Pagination token received in the previous response

Response

list of found profiles that are connected to your team, and match your query

​
items
object[]
required
​
count
integer
required
​
total_count
integer
required
​
pagination_token
string

Pagination token for the next request