Scoping relationships to a child team

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 to request access.

This walkthrough shows how to use child teams and the x-authenticate-team header to scope a Relationships query to a curated subset of connectors — instead of your organization’s entire network.

When to use this

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

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.

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:

{
  "team_id": "child-team-id-123"
}

See Create Team for full parameters.

2. Find the people you want as connectors

Use Search Profiles to find the profiles matching your criteria — here, VP-and-above sales leaders at your company.

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

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

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.

For the full response schema, see Models > Relationships.

What to expect

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.

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

​When to use this

​Prerequisites

​Walkthrough: ABM outreach from revenue leaders

​1. Create a child team for the segment

​2. Find the people you want as connectors

​3. Add them as connectors to the child team

​4. Query intro paths scoped to the child team

​5. Interpret the response

​What to expect

​Reusing the pattern

When to use this

Prerequisites

Walkthrough: ABM outreach from revenue leaders

1. Create a child team for the segment

2. Find the people you want as connectors

3. Add them as connectors to the child team

4. Query intro paths scoped to the child team

5. Interpret the response

What to expect

Reusing the pattern