Core Concepts

Connections

Connections

Voyager provides full connection lifecycle management — send requests with personalized notes, accept inbound invitations, check pending requests, follow/unfollow profiles, and remove connections.

Every Voyager response is wrapped in the standard envelope { success, statusCode, message, data, errors }. The JSON examples below show only the endpoint-specific payload — access res.data.<field> in your client. See Introduction for the full envelope shape.

Send a Connection Request

curl -X POST "$BASE/api/connect" \
  -H "Authorization: Bearer $KEY" \
  -H "X-User-Id: $USER" \
  -H "Content-Type: application/json" \
  -d '{
    "profileUrl": "https://www.linkedin.com/in/janesmith/",
    "message": "Hi Jane, I noticed your work on distributed systems at Acme. Would love to connect."
  }'
{
  "success": true
}

Connection request notes are limited to 300 characters by LinkedIn. The message parameter is optional — requests without a note have a higher acceptance rate according to most studies, but personalized notes work better for cold outreach.

Check Pending Inbound Requests

See who wants to connect with you:

curl -H "Authorization: Bearer $KEY" \
  -H "X-User-Id: $USER" \
  "$BASE/api/connect/received"
{
  "success": true,
  "invitations": [
    {
      "invitationUrn": "urn:li:fsd_invitation:123456",
      "sharedSecret": "abc123",
      "from": {
        "fullName": "John Doe",
        "headline": "CEO at StartupCo",
        "vanityName": "johndoe",
        "profileUrl": "https://www.linkedin.com/in/johndoe/"
      },
      "sentTime": "2026-03-16T10:30:00.000Z",
      "message": "Hey, saw your talk at the conference. Would love to chat."
    }
  ]
}

Accept a Connection Request

Use the invitationUrn and sharedSecret from the received invitations list:

curl -X POST "$BASE/api/connect/accept" \
  -H "Authorization: Bearer $KEY" \
  -H "X-User-Id: $USER" \
  -H "Content-Type: application/json" \
  -d '{
    "invitationUrn": "urn:li:fsd_invitation:123456",
    "sharedSecret": "abc123"
  }'
{
  "success": true
}

Remove a Connection

curl -X DELETE "$BASE/api/connection" \
  -H "Authorization: Bearer $KEY" \
  -H "X-User-Id: $USER" \
  -H "Content-Type: application/json" \
  -d '{"profileUrl": "https://www.linkedin.com/in/janesmith/"}'

Check Relationship Before Connecting

Before sending a connection request, check whether you are already connected or have a pending invitation:

curl -H "Authorization: Bearer $KEY" \
  -H "X-User-Id: $USER" \
  "$BASE/api/relationship/status?profileUrl=https://www.linkedin.com/in/janesmith/"
{
  "success": true,
  "data": {
    "connected": false,
    "connectionDegree": "2ND",
    "canMessageDirectly": false,
    "canConnect": true,
    "openProfile": false,
    "pendingInvitationSent": false
  }
}

Key fields to check:

  • connected: true — Already connected, no need to send request
  • pendingInvitationSent: true — You already sent a request, wait for response
  • canConnect: false — LinkedIn is blocking connection (rate limit or restriction)

Follow / Unfollow

Follow a profile without connecting (you will see their posts in your feed):

# Follow
curl -X POST "$BASE/api/follow" \
  -H "Authorization: Bearer $KEY" \
  -H "X-User-Id: $USER" \
  -H "Content-Type: application/json" \
  -d '{"profileUrl": "https://www.linkedin.com/in/janesmith/"}'
# Unfollow
curl -X POST "$BASE/api/follow" \
  -H "Authorization: Bearer $KEY" \
  -H "X-User-Id: $USER" \
  -H "Content-Type: application/json" \
  -d '{"profileUrl": "https://www.linkedin.com/in/janesmith/", "unfollow": true}'

Visit a Profile

Trigger a “profile viewed” notification (useful for warming up prospects):

curl -X POST "$BASE/api/visit" \
  -H "Authorization: Bearer $KEY" \
  -H "X-User-Id: $USER" \
  -H "Content-Type: application/json" \
  -d '{"profileUrl": "https://www.linkedin.com/in/janesmith/"}'

Profile visits are async jobs. The endpoint returns a jobId — poll GET /api/jobs/:jobId for completion.

Event-Driven Connection Management

Set up webhooks to be notified of new connection requests:

curl -X POST "$BASE/api/webhooks" \
  -H "Authorization: Bearer $KEY" \
  -H "X-User-Id: $USER" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "events": ["connection_received"],
    "secret": "your-hmac-secret"
  }'

Or poll the event feed:

curl -H "Authorization: Bearer $KEY" \
  -H "X-User-Id: $USER" \
  "$BASE/api/events?types=connection.received&since=2026-03-17T00:00:00Z"
  • Connection requests: 60 seconds between requests, max ~20 per day for new accounts
  • Acceptance: No specific limit, but batch-accepting dozens at once may look automated
  • Profile visits: 5-10 seconds between visits

LinkedIn limits the number of weekly connection requests. Exceeding the limit triggers a temporary restriction. Voyager reports usage via GET /api/session/capabilities — your agent should check connectionsRequested and pace accordingly.

Connection Balance

Check your connection request limits and sent invitation count:

curl -H "Authorization: Bearer $KEY" \
  -H "X-User-Id: $USER" \
  "$BASE/api/connect/balance"

Relationship Insights

Find warm paths to a person — mutual connections, shared experiences:

curl -H "Authorization: Bearer $KEY" \
  -H "X-User-Id: $USER" \
  "$BASE/api/relationship/insights?profileUrl=https://www.linkedin.com/in/janesmith/"

Suggested Contacts

Get LinkedIn’s own suggested contacts for your network:

curl -H "Authorization: Bearer $KEY" \
  -H "X-User-Id: $USER" \
  "$BASE/api/contacts/suggested"

Sent Invitations

View your pending outbound connection requests:

curl -H "Authorization: Bearer $KEY" \
  -H "X-User-Id: $USER" \
  "$BASE/api/invitations/sent?start=0&count=20"