Add Connector

Overview

The Add Connector endpoint allows you to programmatically add one or more connector accounts to your team in a single request by providing a list of LinkedIn profile URLs. This enables automated team management and efficient bulk connector operations.

Endpoint Configuration

URL: https://bee.theswarm.com/team/add-connector
HTTP Method: POST
Content Type: application/json
Authentication: API key (How to get an API key?)

Additional Header for Partner Accounts

If you are a partner managing multiple teams, include the target team ID:

x-authenticate-team: CHILD_TEAM_ID

Behavior:

With team header: Connectors added to specified child team
Without team header: Connectors added to parent team associated with API key

Request Format

Request Body Structure

{
  "linkedin_usernames": ["john-doe", "jane-smith"],
  "group": "employees"
}

Parameter Details

Parameter	Type	Required	Description
`linkedin_usernames`	array of strings	Yes	One or more LinkedIn usernames to add as connectors. A single-item array is valid.
`group`	string	No	Assigns all connectors in the request to a member group. Accepted values: `employees`, `investors`, `customers`, `portfolio`, `advisors`, `others`.

`linkedin_usernames`

An array of LinkedIn usernames:

// Username only
"linkedin_usernames": ["john-doe"]

// Multiple connectors in one request
"linkedin_usernames": ["john-doe", "jane-smith", "alex-johnson"]

`group` (Optional)

Categorizes the added connectors within your team. All connectors in a single request receive the same group assignment.

Value	Use for
`employees`	Current or former employees of your organization
`investors`	Investors in your organization
`customers`	Customers
`portfolio`	Portfolio companies
`advisors`	Advisors
`others`	Any other relationship type

If omitted, connectors are added without a group assignment.

Response Codes and Behavior

HTTP 202 Accepted (Success)

At least one username was found and the add-connectors job was queued. Mapping is asynchronous and typically completes within seconds, though it may take up to a few minutes for profiles with large networks. The response lists users_added (new connectors being added), users_exist (already connectors in the team, skipped without creating duplicates) and usernames_not_found. If every username already exists, the response is still 202, with an empty users_added.

Example 202 response

{
  "users_added": ["john-doe"],
  "users_exist": ["jane-smith"],
  "usernames_not_found": ["unknown-slug"]
}

HTTP 200 OK

None of the provided usernames were found. No connectors were queued, and the usernames are listed in usernames_not_found. In this case users_added and users_exist come back as null, not empty arrays.

HTTP 409 Conflict

Adding these connectors would exceed the team’s connector limit. No connectors were added.

HTTP 400 Bad Request

Invalid request format or missing required parameters.

Code Examples

Add Multiple Connectors

curl -X POST https://bee.theswarm.com/team/add-connector \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "linkedin_usernames": ["john-doe", "jane-smith", "alex-johnson"]
  }'

Add Connectors with a Group

curl -X POST https://bee.theswarm.com/team/add-connector \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "linkedin_usernames": ["john-doe", "jane-smith"],
    "group": "employees"
  }'

Add a Single Connector

curl -X POST https://bee.theswarm.com/team/add-connector \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "linkedin_usernames": ["john-doe"]
  }'

Partner Request (Child 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", "john-doe"]
  }'

Partner Team Management

Partners can use this endpoint to manage connectors across multiple child teams. For detailed information on team creation and management, see Team Management documentation. Team Targeting Logic:

Include x-authenticate-team header: Connectors added to specified child team
Omit x-authenticate-team header: Connectors added to parent team

Processing Details

Asynchronous Operation

The connector mapping happens in the background after a successful 202 response. Processing typically completes within seconds but may take up to a few minutes for profiles with extensive connection networks.

Idempotent Behavior

Duplicate requests for existing connectors return 202 without creating duplicates. Existing connectors are reported in users_exist. This makes the endpoint safe for retry scenarios and batch operations.

Troubleshooting Guide

Slow Processing

Cause: Profiles have extensive connection networks
Solution: This is normal behavior; wait for processing to complete

Support Contact

For additional support regarding technical issues, contact the Swarm team at support@theswarm.com.

Getting Started

Enrichment Data

Signals

Flat Files

MCP

Team Management

Miscellaneous

Overview

Endpoint Configuration

Additional Header for Partner Accounts

Request Format

Request Body Structure

Parameter Details

`linkedin_usernames`

`group` (Optional)

Response Codes and Behavior

HTTP 202 Accepted (Success)

HTTP 200 OK

HTTP 409 Conflict

HTTP 400 Bad Request

Code Examples

Add Multiple Connectors

Add Connectors with a Group

Add a Single Connector

Partner Request (Child Team)

Partner Team Management

Processing Details

Asynchronous Operation

Idempotent Behavior

Troubleshooting Guide

Slow Processing

Support Contact

​Overview

​Endpoint Configuration

​Additional Header for Partner Accounts

​Request Format

​Request Body Structure

​Parameter Details

​linkedin_usernames

​group (Optional)

​Response Codes and Behavior

​HTTP 202 Accepted (Success)

​HTTP 200 OK

​HTTP 409 Conflict

​HTTP 400 Bad Request

​Code Examples

​Add Multiple Connectors

​Add Connectors with a Group

​Add a Single Connector

​Partner Request (Child Team)

​Partner Team Management

​Processing Details

​Asynchronous Operation

​Idempotent Behavior

​Troubleshooting Guide

​Slow Processing

​Support Contact

Overview

Endpoint Configuration

Additional Header for Partner Accounts

Request Format

Request Body Structure

Parameter Details

`linkedin_usernames`

`group` (Optional)

Response Codes and Behavior

HTTP 202 Accepted (Success)

HTTP 200 OK

HTTP 409 Conflict

HTTP 400 Bad Request

Code Examples

Add Multiple Connectors

Add Connectors with a Group

Add a Single Connector

Partner Request (Child Team)

Partner Team Management

Processing Details

Asynchronous Operation

Idempotent Behavior

Troubleshooting Guide

Slow Processing

Support Contact