Sellinger API

Integrate Sellinger with your stack using our team-scoped MCP REST API (v2), legacy v1 endpoints, outbound webhooks, and the Node MCP server for Claude/Cursor.

1. API key

Create a key under Integrations → API (max 5 active keys per account).

Get API key

2. MCP API (v2)

165+ endpoints for agents, leads, pipeline, analytics — team-scoped.

Full MCP reference

3. Webhooks

Receive real-time events when leads update or convert.

Team REST API base URL

https://app.sellinger.ai/api/v2/mcp

HTTPS REST prefix for scripts and automations — not a remote MCP server URL. For Claude/Cursor MCP protocol, use the local stdio server in MCP server setup.

Legacy — v1 API base URL

https://app.sellinger.ai/api/v1

Authentication

API keys use the sk_live_ prefix. Send your key on every request using one of these headers:

bash

# Recommended
Authorization: Bearer sk_live_your_api_key

# Alternatives
X-API-Key: sk_live_your_api_key
X-Sellinger-API-Key: sk_live_your_api_key

MCP API (v2) also requires your workspace team UUID:

bash

curl https://app.sellinger.ai/api/v2/mcp/agents \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "x-team-id: your-team-uuid"

Security: Never expose API keys in client-side code or public repos. Call APIs from your backend only. Revoke compromised keys immediately in Integrations.

Team context

Sellinger is multi-tenant: agents, leads, segments, and pipeline data belong to a team (workspace). MCP routes always filter by the team in x-team-id.

Copy your team ID from Settings → Team, or from the x-team-id header in browser devtools.
Use GET /api/v2/mcp/teams to list teams and members for your user.
Wrong or missing team ID returns 403 for API key auth.

MCP API (v2) — quick reference

High-traffic endpoints. See the full MCP catalog for 165+ routes.

GET

/api/v2/mcp/agents

List Sellinger agents for the team.

bash

curl https://app.sellinger.ai/api/v2/mcp/agents \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "x-team-id: your-team-uuid"

GET

/api/v2/mcp/leads

List leads (excludes SUGGESTED/DISCARDED). Query: status, stage, limit, offset, query.

bash

curl "https://app.sellinger.ai/api/v2/mcp/leads?status=NEW&limit=25" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "x-team-id: your-team-uuid"

POST

/api/v2/mcp/leads

Create a lead (email, phone, or LinkedIn URL required).

bash

curl -X POST https://app.sellinger.ai/api/v2/mcp/leads \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "x-team-id: your-team-uuid" \
  -H "Content-Type: application/json" \
  -d '{"full_name":"Jane Doe","email":"jane@co.com","lead_source":"API"}'

GET

/api/v2/mcp/pipeline/counts

Lead counts per pipeline stage.

View complete MCP API reference

Legacy API (v1)

The endpoints below use /api/v1 and are user-scoped (no x-team-id). New integrations should use MCP v2 instead.

POST

/leads/add

Add a new lead to your Sellinger account. The lead will be assigned to the specified LinkedIn account.

bash

curl -X POST https://app.sellinger.ai/api/v1/leads/add \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "linkedin_profile_url": "https://linkedin.com/in/johndoe",
    "linkedin_account_id": "your-agent-uuid",
    "agent_config_id": "config-uuid-optional",
    "full_name": "John Doe",
    "email": "john@example.com",
    "lead_source": "Website Form",
    "industry": "Technology",
    "company_size": "50-200",
    "location": "San Francisco, CA"
  }'

Request Body

Parameter	Type	Description
`linkedin_profile_url`required	string	LinkedIn profile URL (e.g., https://linkedin.com/in/username)
`linkedin_account_id`required	uuid	ID of your LinkedIn account to assign the lead
`agent_config_id`	uuid	Agent config/persona ID. If omitted, automatically resolved from linkedin_account_id.
`full_name`	string	Lead's full name
`email`	string	Lead's email address
`status`	string	Initial status (default: NEW). Values: NEW, INVITE_SENT, INTRO_SENT, etc.
`lead_source`	string	Source of the lead (e.g., Website, Referral)
`industry`	string	Lead's industry
`company_size`	string	Company size (e.g., 1-10, 50-200, 500+)
`location`	string	Lead's location
`position_department`	string	Department (e.g., Technology & Engineering, Sales & Revenue)
`position_level`	string	Position level: bottom, middle, top
`notes`	string \| array	Notes about the lead. String or array of note objects with content field.
`conversation_history`	array	Pre-existing conversation messages

Response

201Created

json

{
  "success": true,
  "message": "Lead created successfully",
  "lead": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "linkedin_profile_url": "https://linkedin.com/in/johndoe",
    "full_name": "John Doe",
    "status": "NEW",
    "created_at": "2024-01-15T10:30:00.000Z"
  }
}

409Conflict

json

{
  "error": "Lead already exists",
  "message": "A lead with this LinkedIn URL already exists for this account",
  "existing_lead_id": "existing-uuid",
  "existing_lead_status": "RESPONDED"
}

GET

/agents

List all your LinkedIn accounts and their IDs. Use this to find the linkedin_account_id needed for adding leads.

bash

curl https://app.sellinger.ai/api/v1/agents \
  -H "Authorization: Bearer sk_live_your_api_key"

200Success

json

{
  "agents": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "John Smith",
      "status": "OK",
      "is_active": true,
      "created_at": "2024-01-01T00:00:00.000Z"
    }
  ]
}

Leads

Retrieve and manage your leads programmatically. List, search, and update lead information.

GET

/leads

List leads with filtering, pagination, and search capabilities.

bash

curl "https://app.sellinger.ai/api/v1/leads?status=RESPONDED&limit=50" \
  -H "Authorization: Bearer sk_live_your_api_key"

Query Parameters

Parameter	Type	Description
`linkedin_account_id`	uuid	Filter by specific agent
`status`	string	Filter by status (NEW, PENDING_CONNECTION, RESPONDED, CONVERTED, etc.)
`search`	string	Search by name or LinkedIn URL
`limit`	integer	Results per page (default: 50, max: 100)
`offset`	integer	Pagination offset (default: 0)

200Success

json

{
  "leads": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "full_name": "John Doe",
      "linkedin_profile_url": "https://linkedin.com/in/johndoe",
      "email": "john@example.com",
      "status": "RESPONDED",
      "headline": "VP of Engineering",
      "agent_name": "Your Agent",
      "created_at": "2024-01-15T10:30:00.000Z",
      "updated_at": "2024-01-20T14:22:00.000Z"
    }
  ],
  "pagination": {
    "total": 1250,
    "limit": 50,
    "offset": 0,
    "has_more": true
  }
}

GET

/leads/:id

Get detailed information about a single lead, including conversation history and notes.

bash

curl "https://app.sellinger.ai/api/v1/leads/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer sk_live_your_api_key"

200Success

json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "full_name": "John Doe",
  "linkedin_profile_url": "https://linkedin.com/in/johndoe",
  "email": "john@example.com",
  "status": "RESPONDED",
  "headline": "VP of Engineering",
  "company_analysis": "TechCorp is a B2B SaaS company...",
  "conversation_history": [
    {"sender": "bot", "message": "Hi John...", "timestamp": "2024-01-18T10:00:00Z"},
    {"sender": "lead", "message": "Thanks for reaching out...", "timestamp": "2024-01-18T14:30:00Z"}
  ],
  "notes": [
    {"content": "Interested in demo", "date_added": "2024-01-19T09:00:00Z"}
  ],
  "agent": {
    "id": "agent-uuid",
    "name": "Your Agent"
  }
}

PATCH

/leads/:id

Update a lead's status, add notes, or trigger human takeover.

bash

curl -X PATCH "https://app.sellinger.ai/api/v1/leads/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "CONVERTED",
    "note": "Deal closed via API",
    "human_takeover": false
  }'

Request Body

Field	Type	Description
`status`	string	New status (NEW, CONVERTED, IRRELEVANT, etc.)
`note`	string	Add a note to the lead
`human_takeover`	boolean	Enable/disable human takeover mode
`meeting_notes`	string	Notes from meeting
`meeting_interest_level`	string	Interest level (very_high, high, medium, low)

200Success

json

{
  "success": true,
  "message": "Lead updated successfully",
  "lead": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "CONVERTED",
    "human_takeover": false,
    "updated_at": "2024-01-20T15:00:00.000Z"
  }
}

Analytics

Access your campaign analytics programmatically. Perfect for building automated reporting pipelines and dashboards.

Data Freshness

Metrics are updated in near-real-time (within seconds of each action).
Daily counters (invites sent today, messages sent today) reset at 00:00 UTC.
The total_leads field is always an all-time count regardless of date filters.
For daily reporting, we recommend calling the API once per day per account.

GET

/analytics/dashboard

Get aggregated dashboard statistics including invites sent, conversations started, and conversions.

bash

curl "https://app.sellinger.ai/api/v1/analytics/dashboard?start_date=2024-01-01&end_date=2024-01-31" \
  -H "Authorization: Bearer sk_live_your_api_key"

Query Parameters

Parameter	Type	Description
`date`	string	Single day snapshot (YYYY-MM-DD). Use this OR start_date/end_date.
`start_date`	string	Start of date range (YYYY-MM-DD)
`end_date`	string	End of date range (YYYY-MM-DD)
`linkedin_account_id`	uuid	Filter by specific agent. Omit for all agents.

200Success

json

{
  "date": "2024-01-29",
  "linkedin_account_id": null,
  "total_leads": 10965,
  "total_invites_sent": 485,
  "connections": {
    "count": 215,
    "rate": 44.3
  },
  "conversations": {
    "count": 102,
    "rate": 21.0
  },
  "conversions": {
    "count": 7,
    "rate": 1.4
  },
  "response_time": {
    "hours": 43.2,
    "label": "Moderate"
  },
  "best_performing_stage": {
    "name": "Connection",
    "percentage": 44.3
  },
  "biggest_dropoff_stage": {
    "name": "Connection",
    "percentage": 55.7
  }
}

GET

/analytics/lead-status-distribution

Get a breakdown of all lead statuses with counts and percentages.

bash

curl "https://app.sellinger.ai/api/v1/analytics/lead-status-distribution" \
  -H "Authorization: Bearer sk_live_your_api_key"

Query Parameters

Parameter	Type	Description
`date`	string	Single day snapshot (YYYY-MM-DD)
`start_date`	string	Filter leads created after this date
`end_date`	string	Filter leads created before this date
`linkedin_account_id`	uuid	Filter by specific agent
`agent_config_id`	uuid	Filter by specific agent config/persona

200Success

json

{
  "date": "2024-01-29",
  "linkedin_account_id": null,
  "total_leads": 10965,
  "statuses": [
    {"status": "NEW", "display_name": "Queued", "count": 9297, "percentage": 84.8},
    {"status": "IRRELEVANT", "display_name": "Irrelevant", "count": 873, "percentage": 8.0},
    {"status": "PENDING_CONNECTION", "display_name": "Invite Sent", "count": 332, "percentage": 3.0},
    {"status": "AWAITING_RESPONSE", "display_name": "Intro Sent", "count": 177, "percentage": 1.6},
    {"status": "CONVERTED", "display_name": "Converted", "count": 7, "percentage": 0.1}
  ]
}

GET

/analytics/performance

Get daily metrics for building performance charts and trend analysis.

bash

# Option 1: Use days parameter (simplest)
curl "https://app.sellinger.ai/api/v1/analytics/performance?days=30" \
  -H "Authorization: Bearer sk_live_your_api_key"

# Option 2: Use explicit date range
curl "https://app.sellinger.ai/api/v1/analytics/performance?start_date=2025-01-01&end_date=2025-01-31" \
  -H "Authorization: Bearer sk_live_your_api_key"

Query Parameters

Use either days or start_date + end_date. If both are provided, start_date/end_date take precedence.

Parameter	Type	Description
`days`	integer	Number of days to look back (default: 7, max: 90)
`start_date`	string	Start of date range (YYYY-MM-DD). Requires end_date.
`end_date`	string	End of date range (YYYY-MM-DD). Requires start_date.
`linkedin_account_id`	uuid	Filter by specific agent

200Success

json

{
  "period": {
    "start": "2024-01-01",
    "end": "2024-01-07",
    "days": 7
  },
  "totals": {
    "invites": 485,
    "conversations": 102,
    "conversions": 7
  },
  "daily": [
    {"date": "2024-01-01", "invites": 72, "conversations": 15, "conversions": 1},
    {"date": "2024-01-02", "invites": 68, "conversations": 14, "conversions": 0},
    {"date": "2024-01-03", "invites": 71, "conversations": 16, "conversions": 2}
  ]
}

GET

/analytics/agents

Get performance metrics for each of your LinkedIn accounts, perfect for comparison and optimization.

bash

curl "https://app.sellinger.ai/api/v1/analytics/agents?days=30" \
  -H "Authorization: Bearer sk_live_your_api_key"

200Success

json

{
  "period": {
    "start": "2024-01-01",
    "end": "2024-01-31",
    "days": 30
  },
  "agents": [
    {
      "id": "agent-uuid-1",
      "name": "Sales Agent 1",
      "profile_picture_url": "https://...",
      "total_leads": 1250,
      "invites_sent": 485,
      "conversations": 102,
      "conversions": 7,
      "conversion_rate": 1.44
    },
    {
      "id": "agent-uuid-2", 
      "name": "Sales Agent 2",
      "profile_picture_url": "https://...",
      "total_leads": 890,
      "invites_sent": 312,
      "conversations": 78,
      "conversions": 5,
      "conversion_rate": 1.60
    }
  ]
}

Activity

Access the activity feed to see recent actions across your leads and agents.

GET

/activity

Get a paginated list of recent activity including status changes, messages sent, and connection requests.

bash

curl "https://app.sellinger.ai/api/v1/activity?limit=50" \
  -H "Authorization: Bearer sk_live_your_api_key"

Query Parameters

Parameter	Type	Description
`linkedin_account_id`	uuid	Filter by specific agent
`action_type`	string	Filter by action type (INVITE_SENT, MESSAGE_SENT, STATUS_CHANGE, etc.)
`limit`	integer	Results per page (default: 50, max: 100)
`offset`	integer	Pagination offset (default: 0)

200Success

json

{
  "activities": [
    {
      "id": "activity-uuid-1",
      "action_type": "INVITE_SENT",
      "lead_id": "lead-uuid",
      "lead_name": "John Doe",
      "agent_id": "agent-uuid",
      "agent_name": "Sales Agent 1",
      "details": {},
      "created_at": "2024-01-20T14:30:00.000Z"
    },
    {
      "id": "activity-uuid-2",
      "action_type": "STATUS_CHANGE",
      "lead_id": "lead-uuid-2",
      "lead_name": "Jane Smith",
      "agent_id": "agent-uuid",
      "agent_name": "Sales Agent 1",
      "details": {"old_status": "PENDING_CONNECTION", "new_status": "AWAITING_RESPONSE"},
      "created_at": "2024-01-20T14:25:00.000Z"
    }
  ],
  "pagination": {
    "total": 5420,
    "limit": 50,
    "offset": 0,
    "has_more": true
  }
}

Portal Clients

Manage whitelabel portal clients programmatically. Create, update, and deactivate clients with their own access codes, agent limits, and permissions.

Prerequisite: These endpoints require an active whitelabel portal configuration. Enable your portal from the Integrations page before using these APIs.

GET

/clients

List all portal clients with their agent counts and permissions.

bash

curl "https://app.sellinger.ai/api/v1/clients?is_active=true" \
  -H "Authorization: Bearer sk_live_your_api_key"

Query Parameters

Parameter	Type	Description
`is_active`	string	Filter by active status ('true' or 'false'). Omit to return all.

200Success

json

{
  "clients": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Acme Corp",
      "max_agents": 5,
      "agent_count": 2,
      "is_active": true,
      "has_access_code": true,
      "can_configure_agents": false,
      "can_add_leads": true,
      "created_at": "2024-01-15T10:30:00.000Z",
      "updated_at": "2024-01-20T14:22:00.000Z"
    }
  ],
  "total": 1
}

POST

/clients

Create a new portal client with an access code and permissions.

bash

curl -X POST "https://app.sellinger.ai/api/v1/clients" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "access_code": "acme-secret-2024",
    "max_agents": 5,
    "can_configure_agents": false,
    "can_add_leads": true
  }'

Request Body

Parameter	Type	Description
`name`required	string	Client display name
`access_code`required	string	Access code for portal login (min 6 characters, stored as hash)
`max_agents`	integer	Maximum agents this client can have assigned (default: 5)
`can_configure_agents`	boolean	Allow client to configure agent settings (default: false)
`can_add_leads`	boolean	Allow client to add leads via the portal (default: false)

201Created

json

{
  "client": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Acme Corp",
    "max_agents": 5,
    "agent_count": 0,
    "is_active": true,
    "has_access_code": true,
    "can_configure_agents": false,
    "can_add_leads": true,
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:30:00.000Z"
  }
}

GET

/clients/:id

Get detailed information about a single portal client.

bash

curl "https://app.sellinger.ai/api/v1/clients/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer sk_live_your_api_key"

PUT

/clients/:id

Update a portal client's name, limits, access code, or permissions. All fields are optional.

bash

curl -X PUT "https://app.sellinger.ai/api/v1/clients/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp Updated",
    "max_agents": 10,
    "can_configure_agents": true
  }'

Request Body

Field	Type	Description
`name`	string	Updated client name
`max_agents`	integer	New agent limit (cannot be lower than current assigned count)
`access_code`	string	New access code (min 6 characters)
`is_active`	boolean	Activate or deactivate the client
`can_configure_agents`	boolean	Update agent configuration permission
`can_add_leads`	boolean	Update lead adding permission

Note: You cannot reduce max_agents below the current number of assigned agents. Unassign agents first if you need to lower the limit.

DELETE

/clients/:id

Deactivate a portal client and unassign all its agents. This is a soft delete — the client record is preserved but marked inactive.

bash

curl -X DELETE "https://app.sellinger.ai/api/v1/clients/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer sk_live_your_api_key"

200Success

json

{
  "success": true,
  "message": "Client \"Acme Corp\" has been deactivated and its agents unassigned."
}

Webhooks

Receive real-time notifications when specific events occur in your Sellinger account. Configure your webhook URL in the Integrations page.

Available Events

INVITE_ACCEPTEDFired when a LinkedIn connection request is accepted

INTRO_SENTFired when the first DM (intro message) is sent to a lead

STATUS_CHANGEDFired on any lead status change (includes old_status, new_status, reason)

CONVERTEDFired when a lead is marked as converted

AWAITING_ACCEPTNewFired when a connection request is sent (lead enters Awaiting Accept)

ACTIVE_CHATNewFired when a lead enters active conversation (intro sent, awaiting reply)

RESPONDEDNewFired when a lead replies to a message

FOLLOWUP_SENTNewFired when a follow-up message is sent to a non-responsive lead

Request Headers

Header	Description
`X-Sellinger-Signature`	HMAC-SHA256 signature of the payload
`X-Sellinger-Timestamp`	Unix timestamp of when the webhook was sent
`X-Sellinger-Event`	The event type (e.g. INVITE_ACCEPTED, CONVERTED, AWAITING_ACCEPT, ACTIVE_CHAT, RESPONDED, etc.)
`X-Sellinger-Event-ID`	Unique event ID for idempotency

Payload Structure

All webhook payloads include lead and LinkedIn account data. The client_id field is included for multi-client/whitelabel setups to route events to the correct destination.

json

{
  "event": "INVITE_ACCEPTED",
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "lead": {
      "id": "lead-uuid",
      "full_name": "John Doe",
      "linkedin_profile_url": "https://linkedin.com/in/johndoe",
      "email": "john@example.com",
      "status": "ACTIVE",
      "industry": "Technology",
      "company_size": "50-200",
      "location": "San Francisco, CA"
    },
    "linkedin_account": {
      "id": "account-uuid",
      "full_name": "Your Agent Name",
      "client_id": "client-uuid-if-whitelabel"
    },
    "client_id": "client-uuid-if-whitelabel"
  }
}

STATUS_CHANGED Payload

The STATUS_CHANGED event includes additional status_change data with the old status, new status, and reason for the change.

json

{
  "event": "STATUS_CHANGED",
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "lead": {
      "id": "lead-uuid",
      "full_name": "John Doe",
      "linkedin_profile_url": "https://linkedin.com/in/johndoe",
      "status": "IRRELEVANT"
    },
    "linkedin_account": {
      "id": "account-uuid",
      "full_name": "Your Agent Name"
    },
    "client_id": "client-uuid-if-whitelabel",
    "status_change": {
      "old_status": "AWAITING_RESPONSE",
      "new_status": "IRRELEVANT",
      "reason": "Lead marked irrelevant by AI"
    }
  }
}

Verifying Signatures

Always verify webhook signatures to ensure requests are from Sellinger.

javascript

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const computed = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(computed)
  );
}

// Express.js example
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-sellinger-signature'];
  
  if (!verifyWebhookSignature(req.body.toString(), signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  const event = JSON.parse(req.body);
  // Handle event...
  
  res.status(200).send('OK');
});

Rate Limits

API requests are rate limited to ensure fair usage and system stability.

Requests per minute

10,000

Requests per day

When you exceed the rate limit, you'll receive a 429 Too Many Requests response. Implement exponential backoff in your integration to handle rate limiting gracefully.

Security Best Practices

Keep API Keys Secret

Never commit API keys to version control or expose them in client-side code. Use environment variables to store sensitive credentials.

Rotate Keys Regularly

Generate new API keys periodically and revoke old ones. You can manage your keys from the Integrations page.

Use HTTPS

All API requests must be made over HTTPS. HTTP requests will be rejected. Webhook endpoints must also use HTTPS.

Verify Webhook Signatures

Always verify the signature header on incoming webhooks to ensure the request originated from Sellinger and hasn't been tampered with.