> ## 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.
# Network Mapper (for Partners)
> The Network Mapper endpoint builds an entire relationship graph for a target company. Partner permission required.
## Introduction
The Network Mapper endpoint builds an entire relationship graph for a target company. It analyzes data points to (1) identify relationships and (2) calculate Connection Strength scores for every relationship.
For team-owned connections, use the free [Relationships](/docs/intelligence/relationships) endpoint instead.
As part of the process, we map the "overlaps" of a company's "connectors":
**Overlaps:**
* Work history overlap — people who work or worked at the same company
* Education overlap — people who graduated from the same university in the same year
**Connectors:**
* Employees of the company
* The company's VCs (when applicable)
* Execs of portfolio companies of the company's VCs (when applicable)
* Any other stakeholders added manually
For the API specification, see [Network Mapper endpoint reference](/docs/endpoints/v3/network-mapper).
**Partner permission required.** Calls from an API key not tied to a team with the partner permission in Stripe return **403 Forbidden**.
## Pricing
| Response | Cost |
| ------------------ | ------------------------- |
| Non-empty response | **1 credit per response** |
| Empty response | Free |
## Authentication
Authenticate with your partner-managed API key in the `x-api-key` header.
| Header | Value |
| -------------- | ------------------ |
| `Content-Type` | `application/json` |
| `x-api-key` | `` |
## Endpoint
| | |
| ------ | -------------------------------------------- |
| URL | `https://bee.theswarm.com/v3/network-mapper` |
| Method | `POST` |
## Body parameters
In the example below, we query for connections to a target company identified by website domain.
```json theme={null}
{
"query": {
"term": {
"profile_info.current_company_websites": {
"value": "openai.com"
}
}
},
"mapping_company_website": "theswarm.com",
"callback_url": "www.callback.com/some-async-webhook"
}
```
Where:
* `profile_info.current_company_website` — A valid website domain of the target company.
The following fields are required for partner-managed accounts:
* `mapping_company_website` — Website domain of the company to be mapped (the customer's company).
* `callback_url` — URL for async response. Data is sent to this URL when company mapping is finished.
## Success response (200 OK)
```json theme={null}
{
"items": [
{
"profile": {
"id": "f0f9f467-7798-4b15-a913-3d1375c85390",
"full_name": "David Connors",
"current_title": "Co-Founder & CEO",
"linkedin_url": "https://linkedin.com/in/connorsdavid",
"work_email": "david@theswarm.com",
"current_company_name": "The Swarm",
"current_company_website": "theswarm.com"
},
"connections": [
{
"connector_id": "c050884c-001a-488c-b280-0f617cf4f7bc",
"connector_name": "Michal Bil",
"connector_linkedin_url": "https://www.linkedin.com/in/michal-bil/",
"connector_current_title": "Co-Founder & CTO",
"connector_current_company_name": "The Swarm",
"connection_strength_normalized": 3,
"connection_strength": 0.8840964268278736,
"sources": [
{ "origin": "linkedin_connection" },
{
"origin": "work_overlap",
"shared_company": "The Swarm",
"shared_company_id": "09d9c510-c9f6-4c6e-9e62-fe5fedbeda87",
"shared_company_website": "theswarm.com",
"overlap_start_date": "2022-02-01",
"overlap_duration_months": 35
},
{ "origin": "email_contact" },
{ "origin": "calendar_events" }
]
}
]
}
],
"count": 50,
"total_count": 213
}
```
Where:
* `profile` — Basic information about the connection.
* `connections` — Team members connected to the profile.
* `connections.sources` — Describes how the profile is connected. The shape depends on `origin`. Accepted `origin` values: `linkedin_connection`, `work_overlap`, `email_contact`, `calendar_events`, `manual_import`, `education_overlap`, `shared_investor`.
* `count` — Number of returned items (max 50).
* `total_count` — Total available connections.
## Async response (202 Accepted)
If the target company is not yet mapped, the request is processed asynchronously and a `task_id` is returned. The full result is delivered to the `callback_url`.
```json theme={null}
{ "task_id": "123abc" }
```
Poll task status using the [Network Mapper Status endpoint](/docs/endpoints/v3/network-mapper-status).
## Error responses
### 400 — Validation failed
Wrong query syntax:
```json theme={null}
{
"status": 400,
"title": "Validation failed",
"errors": [
{
"path": "query",
"violation": "ParsingException[unknown query [matchd] did you mean any of [match, match_all]?]"
}
]
}
```
Missing or invalid `mapping_company_website`:
```json theme={null}
{
"status": 400,
"errors": [
{ "message": "mapping_company_website missing in request" }
]
}
```
### 403 — Forbidden
The API key is not tied to a team with partner permission.
### 404 — Not found
The company with the given `mapping_company_website` is not in our database.
```json theme={null}
{
"status": 404,
"errors": [
{ "message": "mapping_company_website not found - can't perform network mapping" }
]
}
```
### Callback body — failure
```json theme={null}
{
"status": 500,
"errors": [
{ "message": "failed to map team with company domain theswarm.com" }
]
}
```
## Async status endpoint
Poll the status of a long-running mapping task.
| | |
| ------ | --------------------------------------------------- |
| URL | `https://bee.theswarm.com/v3/network-mapper/status` |
| Method | `GET` |
See the [Network Mapper Status reference](/docs/endpoints/v3/network-mapper-status).
Possible `task_status` values: `in_progress`, `done`, `failed`.
## Filtering and query customization
The endpoint accepts any OpenSearch DSL query — narrow results by job title, function, seniority, or any indexed field.
### Filter by title
```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"
}
}
}
]
}
}
}
```
### Filter by function
Canonical values: `IT & Engineering`, `Human Resources`, `Operations & Supply Chain`, `Marketing & Product Management`, `Sales & Business Development`, `Customer Service & Support`, `Finance & Accounting`, `Legal & Compliance`, `Healthcare & Medical Services`, `Education & Training`, `Consulting & Strategy`, `Real Estate & Property Management`, `Media, Publishing & Journalism`, `Design & Creative Services`, `Trades & Skilled Labor`, `Public Relations & Communications`, `Quality Assurance & Control`, `Program & Project Management`, `Banking & Financial Services`, `Administration & Office Support`.
### Filter by seniority
Canonical values: `c-level`, `director`, `vp`, `manager`, `senior`, `junior`.
### Intro path to a specific person
```json theme={null}
{
"query": {
"term": {
"profile_info.linkedin_usernames": {
"value": "michal-bil"
}
}
}
}
```