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

# Scoping relationships to a child team

> Use partner child teams to run Relationships queries against a curated subset of connectors — a targeted network for ABM, sales pods, or region-specific outreach.

<Note>
  **Partner permission required.** Creating child teams and using the `x-authenticate-team` header requires the partner permission on your account. If you don't have it, email [support@theswarm.com](mailto:support@theswarm.com) to request access.
</Note>

This walkthrough shows how to use **child teams** and the [`x-authenticate-team`](/docs/api-reference/introduction#partner-accounts-acting-on-behalf-of-a-child-team) header to scope a [Relationships](/docs/endpoints/v3/relationships) query to a curated subset of connectors — instead of your organization's entire network.

## When to use this

<Info>
  **Child-team Relationships vs. Network Mapper.** These solve different problems.

  * Use a **child team + `/v3/relationships`** when you want warm intro paths through a **specific subset of your own connectors** (e.g. just your revenue leaders, just your APAC pod). Free, synchronous, returns your team's connections.
  * Use [**Network Mapper**](/docs/endpoints/v3/network-mapper) when you want intro paths across the **entire partner network** — connectors you don't own. Paid per non-empty response, and only available to partners.
</Info>

Typical scenarios for the child-team approach:

* **ABM outreach** — warm intro paths from revenue leaders only, not the whole company.
* **Regional sales pods** — scope introductions to a specific geography's team.
* **Investor / advisor networks** — treat a specific group of connectors as its own searchable network.
* **Portfolio work** — one child team per portfolio company, each with its own connector set.

## Prerequisites

* A partner API key.
* Team owner or admin role.
* LinkedIn usernames (or profile URLs) for the people you want to add as connectors.

## Walkthrough: ABM outreach from revenue leaders

You're running account-based outreach and want intro paths **only through your revenue leaders** into a set of target accounts.

### 1. Create a child team for the segment

Create a dedicated child team so its network stays isolated from the rest of your org's connectors. Save the returned `team_id` — you'll pass it in every subsequent request.

```bash theme={null}
curl -X POST https://bee.theswarm.com/team/create-team \
  -H "x-api-key: YOUR_PARTNER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "team_name": "ABM — Revenue leaders",
    "owner_email": "rev-ops@yourcompany.com"
  }'
```

Response:

```json theme={null}
{
  "team_id": "child-team-id-123"
}
```

See [Create Team](/docs/endpoints/v3/create-team) for full parameters.

### 2. Find the people you want as connectors

Use [Search Profiles](/docs/endpoints/v3/search-profiles) to find the profiles matching your criteria — here, VP-and-above sales leaders at your company.

```bash theme={null}
curl -X POST https://bee.theswarm.com/v3/profiles/search \
  -H "x-api-key: YOUR_PARTNER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "bool": {
        "must": [
          { "term":  { "profile_info.current_company_website": { "value": "yourcompany.com" } } },
          { "terms": { "profile_info.current_seniorities": ["vp", "cxo", "founder"] } },
          { "match": { "profile_info.current_title": { "query": "sales revenue", "operator": "OR" } } }
        ]
      }
    },
    "limit": 50
  }'
```

Then hydrate the IDs with [Fetch Profile](/docs/endpoints/v3/fetch-profile) if you need LinkedIn usernames for the next step.

### 3. Add them as connectors to the child team

Pass the child team's ID in the `x-authenticate-team` header so the connectors land in the child team's network, not the parent team.

```bash theme={null}
curl -X POST https://bee.theswarm.com/team/add-connector \
  -H "x-api-key: YOUR_PARTNER_API_KEY" \
  -H "x-authenticate-team: child-team-id-123" \
  -H "Content-Type: application/json" \
  -d '{
    "linkedin_usernames": [
      "jane-smith-vp-sales",
      "john-doe-cro",
      "alex-johnson-vp-revenue"
    ],
    "group": "employees"
  }'
```

Connector mapping runs asynchronously. Small teams typically finish within a few seconds; larger ones may take a few minutes. See [Add Connector](/docs/endpoints/v3/add-connector) for details.

### 4. Query intro paths scoped to the child team

Now run a Relationships query against the child team's network. Every request must include `x-authenticate-team: <child-team-id>` — otherwise the query falls back to the parent team.

```bash theme={null}
curl -X POST https://bee.theswarm.com/v3/relationships \
  -H "x-api-key: YOUR_PARTNER_API_KEY" \
  -H "x-authenticate-team: child-team-id-123" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "terms": {
        "profile_info.current_company_website": [
          "target-account-1.com",
          "target-account-2.com",
          "target-account-3.com"
        ]
      }
    },
    "limit": 100
  }'
```

The response only reflects connections held by the connectors in the child team — not by everyone in your organization.

### 5. Interpret the response

Each hit in the response corresponds to a person your child team can reach, plus the connectors who can introduce them. Key fields:

* **`connections[].connector_id`** — the child-team connector who knows the person.
* **`connections[].strength`** — the connection strength signal (higher = warmer path).
* **`connections[].sources[]`** — how the connection was inferred (LinkedIn, email, calendar, etc.). See the [sources field FAQ](/docs/getting-started/faq#what-does-the-sources-field-in-connections-mean).

For the full response schema, see [Models > Relationships](/docs/intelligence/relationships).

## What to expect

<Warning>
  **Sparse results on small teams are expected.** Because the query only considers the child team's connectors, results reflect the size and shape of that subset — not your whole organization's network. A handful of connectors will produce far fewer intro paths than a full-org query. This is by design, not a bug.
</Warning>

Practical tips:

* Start with **10–30 well-chosen connectors** per child team. Broader is not always better — the point of a child team is precision.
* Wait for connector mapping to finish before running Relationships queries. See the mapping-status guidance in [Add Connector](/docs/endpoints/v3/add-connector).
* Re-run the query as new connectors are added; the child team's network grows over time.
* If you want intro paths beyond your own connectors, use [Network Mapper](/docs/endpoints/v3/network-mapper) instead.

## Reusing the pattern

The same four-step pattern applies to any segment you want to treat as its own network — regional pods, portfolio companies, investor groups. Create one child team per segment, keep the connector set curated, and always pass `x-authenticate-team` on subsequent requests.