Add Connector

​

Overview

The Add Connector endpoint allows you to programmatically add new connector accounts to your team by providing a LinkedIn username. This enables automated team management and bulk connector operations.

​

Endpoint Configuration

• URL: https://bee.theswarm.com/team/add-connector
• HTTP Method: POST
• Content Type: application/json
• Authentication: API key with special connector permissions required (How to get 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: Connector added to specified child team
• Without team header: Connector added to parent team associated with API key

​

Request Format

​

Request Body Structure

{
  "linkedin_username": "target-linkedin-username"
}

​

Parameter Details

• linkedin_username (required, string): The LinkedIn username without the full URL
• Format: Use “john-doe” instead of “https://linkedin.com/in/john-doe”

​

Response Codes and Behavior

​

HTTP 202 Accepted (Success)

The connector addition process has been successfully initiated. The mapping process is asynchronous and typically completes within seconds, though it may take up to a few minutes depending on the number of connections.

Important: If a connector with the provided LinkedIn username already exists in the team, no action is taken, but the response remains 202.

​

HTTP 404 Not Found

The provided LinkedIn username was not found in the system.

​

HTTP 403 Forbidden

The API key lacks required permissions for this endpoint.

​

HTTP 400 Bad Request

Invalid request format or missing required parameters.

​

Code Examples

​

Basic cURL Request

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

​

Partner cURL 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_username": "jane-smith"}'

​

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: Connector added to specified child team
• Omit x-authenticate-team header: Connector 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. This makes the endpoint safe for retry scenarios.

​

LinkedIn Username Format

Always use only the username portion, not the full LinkedIn URL:

• Correct: “john-doe”
• Incorrect: “https://linkedin.com/in/john-doe”

​

Troubleshooting Guide

​

HTTP 403 Forbidden Error

Cause: API key lacks required permissions Solution: Contact support@theswarm.com to upgrade API key permissions

​

HTTP 404 Not Found Error

Cause: LinkedIn username not found in system Solution: Verify LinkedIn username exists and is correctly formatted

​

Slow Processing

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

​

Support Contact

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