> ## 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
> Find connected profiles with their connection details. Renamed from Network Mapper in v3.
Relationships requests do not consume API credits. See [Credits & Usage](/docs/api-reference/credits-usage).
By default, the Relationships endpoint returns profiles connected to the team that owns the API key, along with connection details. Responses are returned synchronously.
Partners can scope the query to a specific child team by passing the child team's ID in the `x-authenticate-team` header — the response then reflects the connectors and connections of that child team's network instead. See [Partner teams](#partner-teams) below.
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](/docs/examples/relationships-endpoint).
For the response schema, see [Models > Network Mapper](/docs/intelligence/relationships).
## 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](/docs/endpoints/v3/search-profiles).
See [OpenSearch Profile Mappings (v3)](/docs/enrichment-data/profile/mappings-v3) for the full list of indexed fields, and [Relationships endpoint examples](/docs/examples/relationships-endpoint) for ready-to-use queries.
## Partner teams
Partners can execute a request in the context of a child team by passing the child team's ID in the `x-authenticate-team` header:
```http theme={null}
x-authenticate-team:
```
* **With the header** — the query runs against the child team's network (its connectors and their connections).
* **Without the header** — the query runs against the network of the team that owns the API key (default).
The `child_team_id` is returned when you [create a child team](/docs/endpoints/v3/create-team).
### Example request
```bash theme={null}
curl -X POST https://bee.theswarm.com/v3/relationships \
-H "x-api-key: YOUR_API_KEY" \
-H "x-authenticate-team: child-team-id-123" \
-H "Content-Type: application/json" \
-d '{
"query": {
"term": {
"profile_info.current_company_website": {
"value": "theswarm.com"
}
}
},
"limit": 10
}'
```
## OpenAPI
````yaml openapi.json POST /v3/relationships
openapi: 3.1.0
info:
title: Swarm API
version: 1.0.0
contact:
name: The Swarm
url: https://theswarm.com
email: hello@theswarm.com
servers:
- url: https://bee.theswarm.com
security:
- ApiKeyAuth: []
tags:
- name: profiles
description: Operations related to profiles
- name: companies
description: Operations related to companies
- name: teams
description: Operations for managing teams and connectors
- name: social
description: Operations related to social media posts and interactions
- name: mcp
description: Model Context Protocol endpoint for AI assistant integrations
- name: credits
description: Operations related to credit usage
- name: network-mapper
description: Operations for mapping connections and relationships across your network
paths:
/v3/relationships:
post:
tags:
- network-mapper
summary: Relationships
description: >-
Find connected profiles with their connection details. Renamed from
Network Mapper in v3.
operationId: relationshipsV3
parameters:
- $ref: '#/components/parameters/AuthenticateTeamHeader'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
query:
type: object
description: >-
Search query in the [ElasticSearch Query
DSL](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html)
format. [Find mapping
here](https://docs.theswarm.com/docs/mappings/profile-v2)
example:
match:
profile_info.job_title:
query: Data Scientist
limit:
type: integer
description: Limit the number of results
default: 100
minimum: 0
maximum: 1000
pagination_token:
type: string
description: Pagination token received in the previous response
required:
- query
responses:
'200':
description: >-
list of found profiles that are connected to your team, and match
your query
content:
application/json:
schema:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/NetworkMapperItem'
count:
type: integer
total_count:
type: integer
pagination_token:
description: Pagination token for the next request
type: string
required:
- items
- count
- total_count
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
5XX:
$ref: '#/components/responses/5XX'
security:
- ApiKeyAuth: []
components:
parameters:
AuthenticateTeamHeader:
name: x-authenticate-team
in: header
required: false
description: >-
Partner accounts only. When present, the request is executed in the
context of the specified child team (use the `team_id` returned by
[Create Team](/docs/endpoints/v3/create-team)). When omitted, the
request runs as the team that owns the API key.
schema:
type: string
schemas:
NetworkMapperItem:
type: object
properties:
profile:
$ref: '#/components/schemas/NetworkMapperProfile'
connections:
type: array
items:
$ref: '#/components/schemas/NetworkMapperConnection'
NetworkMapperProfile:
type: object
properties:
id:
type: string
format: uuid
full_name:
type: string
current_title:
type: string
linkedin_url:
type: string
work_email:
type: string
current_company_name:
type: string
current_company_website:
type: string
required:
- full_name
NetworkMapperConnection:
type: object
properties:
connector_id:
type: string
format: uuid
connector_name:
type: string
connector_linkedin_url:
type: string
connector_current_title:
type: string
connector_current_company_name:
type: string
connection_strength_normalized:
type: integer
connection_strength:
type: number
format: float
manual_strength:
type: number
format: float
sources:
type: array
items:
$ref: '#/components/schemas/NetworkMapperConnectionSource'
ErrorResponse:
type: object
properties:
code:
description: Error status code
type: integer
errors:
type: array
items:
type:
- string
- object
required:
- code
NetworkMapperConnectionSource:
type: object
properties:
origin:
type: string
enum:
- linkedin_connection
- work_overlap
- email_contact
- calendar_events
- manual_import
- education_overlap
- shared_investor
shared_company:
type: string
description: Name of the shared company from work overlap
shared_company_id:
type: string
format: uuid
description: ID of the shared company from work overlap
shared_company_website:
type: string
description: Website of the shared company from work overlap
shared_company_linkedin_slug:
type: string
description: Linkedin Slug of the shared company from work overlap
overlap_start_date:
type: string
description: Start Date of work overlap
overlap_end_date:
type: string
description: End Date of work overlap
overlap_duration_months:
type: integer
description: Months Duration of work overlap
shared_school:
type: string
description: Name of school from education overlap
shared_major:
type: string
description: Name of major from education overlap
graduation_year:
type: string
description: Graduation year from education overlap
investor:
type: string
description: Name of common investor from investor overlap
portfolio_company:
type: string
description: Name of portfolio company from investor overlap
required:
- origin
description: Source of connection, only properties that describe given source are set
responses:
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
'403':
description: Forbidden
5XX:
description: Unexpected error
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
````