Subscriptions API

Manage LinkedIn profile and company subscriptions. Subscriptions tell Sales Webhooks which entities to monitor for changes.

Quick Reference

POST /api/v1/subscriptions
Create subscription
GET /api/v1/subscriptions
List subscriptions
GET /api/v1/subscriptions/:id
Get subscription
DELETE /api/v1/subscriptions/:id
Cancel subscription
POST /api/v1/subscriptions/bulk
Bulk create
DELETE /api/v1/subscriptions/bulk
Bulk delete

Create Subscription

Subscribe to a LinkedIn profile or company to start monitoring for changes.

POST /api/v1/subscriptions

Headers

X-API-Key: lwa.your_api_key
Content-Type: application/json

Request Body

{
  "entity_type": "contact",  // Required: "contact" or "company"
  "linkedin_id": "john-doe", // Required: LinkedIn username/ID
  "linkedin_url": "https://linkedin.com/in/john-doe" // Optional: Full LinkedIn URL
}

Response

{
  "id": "sub_9Yx7Kj2Mn",
  "entity_type": "contact",
  "linkedin_id": "john-doe",
  "linkedin_url": "https://linkedin.com/in/john-doe",
  "status": "active",
  "created_at": "2025-01-20T10:30:00Z",
  "updated_at": "2025-01-20T10:30:00Z"
}

Example

curl -X POST https://api.saleswebhooks.com/v1/subscriptions \
  -H "X-API-Key: lwa.sk_live_abcdef1234" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "contact",
    "linkedin_url": "https://linkedin.com/in/satya-nadella"
  }'

List Subscriptions

Retrieve a paginated list of your active subscriptions with optional filtering.

GET /api/v1/subscriptions

Query Parameters

Parameter Type Description
entity_type string Filter by "contact" or "company"
status string Filter by "active" or "cancelled"
search string Search by LinkedIn ID or URL
limit integer Results per page (default: 20, max: 100)
offset integer Pagination offset (default: 0)

Response

{
  "data": [
    {
      "id": "sub_9Yx7Kj2Mn",
      "entity_type": "contact",
      "linkedin_id": "john-doe",
      "linkedin_url": "https://linkedin.com/in/john-doe",
      "status": "active",
      "last_checked_at": "2025-01-20T08:00:00Z",
      "created_at": "2025-01-15T10:30:00Z"
    },
    // ... more subscriptions
  ],
  "pagination": {
    "total": 142,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}

Examples

# Get all active contact subscriptions
curl "https://api.saleswebhooks.com/v1/subscriptions?entity_type=contact&status=active" \
  -H "X-API-Key: lwa.sk_live_abcdef1234"

# Search for specific LinkedIn ID
curl "https://api.saleswebhooks.com/v1/subscriptions?search=john-doe" \
  -H "X-API-Key: lwa.sk_live_abcdef1234"

# Paginate through results
curl "https://api.saleswebhooks.com/v1/subscriptions?limit=50&offset=50" \
  -H "X-API-Key: lwa.sk_live_abcdef1234"

Get Subscription

Retrieve details for a specific subscription.

GET /api/v1/subscriptions/:id

Path Parameters

  • id - The subscription ID (e.g., sub_9Yx7Kj2Mn)

Response

{
  "id": "sub_9Yx7Kj2Mn",
  "entity_type": "contact",
  "linkedin_id": "john-doe",
  "linkedin_url": "https://linkedin.com/in/john-doe",
  "status": "active",
  "last_checked_at": "2025-01-20T08:00:00Z",
  "last_change_at": "2025-01-18T14:30:00Z",
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z",
  "metadata": {
    "check_count": 5,
    "change_count": 2
  }
}

Cancel Subscription

Cancel an active subscription. This performs a soft delete - the subscription is marked as cancelled but not removed from the database.

DELETE /api/v1/subscriptions/:id

Response

{
  "id": "sub_9Yx7Kj2Mn",
  "status": "cancelled",
  "cancelled_at": "2025-01-20T10:30:00Z"
}

Note: Cancelled subscriptions stop monitoring immediately. You can create a new subscription for the same entity if needed.

Bulk Create Subscriptions

Create multiple subscriptions in a single request. Ideal for importing contact lists.

POST /api/v1/subscriptions/bulk

Request Body

{
  "subscriptions": [
    {
      "entity_type": "contact",
      "linkedin_url": "https://linkedin.com/in/john-doe"
    },
    {
      "entity_type": "contact",
      "linkedin_id": "jane-smith"
    },
    {
      "entity_type": "company",
      "linkedin_url": "https://linkedin.com/company/acme-corp"
    }
  ]
}

Response

{
  "created": 3,
  "failed": 0,
  "subscriptions": [
    {
      "id": "sub_9Yx7Kj2Mn",
      "entity_type": "contact",
      "linkedin_id": "john-doe",
      "status": "active"
    },
    // ... other created subscriptions
  ],
  "errors": []
}

Error Handling

If some subscriptions fail, they'll be listed in the errors array:

{
  "created": 2,
  "failed": 1,
  "subscriptions": [ /* successfully created */ ],
  "errors": [
    {
      "index": 2,
      "linkedin_id": "invalid-url",
      "error": "Invalid LinkedIn URL format"
    }
  ]
}

Tip: Maximum 100 subscriptions per request. For larger imports, batch your requests.

Bulk Delete Subscriptions

Cancel multiple subscriptions in a single request.

DELETE /api/v1/subscriptions/bulk

Request Body

{
  "subscription_ids": [
    "sub_9Yx7Kj2Mn",
    "sub_8Wx6Ki1Lo",
    "sub_7Vx5Jh0Kn"
  ]
}

Response

{
  "cancelled": 3,
  "failed": 0,
  "subscriptions": [
    {
      "id": "sub_9Yx7Kj2Mn",
      "status": "cancelled"
    },
    // ... other cancelled subscriptions
  ],
  "errors": []
}

Export Subscriptions

Export all your subscriptions as CSV for backup or analysis.

GET /api/v1/subscriptions/export

Query Parameters

  • format - Export format: "csv" (default) or "json"
  • status - Filter by status: "active", "cancelled", or "all" (default)

Response

subscription_id,entity_type,linkedin_id,linkedin_url,status,created_at
sub_9Yx7Kj2Mn,contact,john-doe,https://linkedin.com/in/john-doe,active,2025-01-15T10:30:00Z
sub_8Wx6Ki1Lo,company,acme-corp,https://linkedin.com/company/acme-corp,active,2025-01-16T14:00:00Z

Example

# Export all active subscriptions as CSV
curl "https://api.saleswebhooks.com/v1/subscriptions/export?status=active" \
  -H "X-API-Key: lwa.sk_live_abcdef1234" \
  -o subscriptions.csv

Rate Limits

Subscription endpoints are subject to the following rate limits:

  • Create/Update: 100 requests per 15 minutes
  • Read operations: 1000 requests per 15 minutes
  • Bulk operations: 10 requests per 15 minutes

Error Responses

Common Errors

409 Conflict - Duplicate Subscription

{
  "error": "DUPLICATE_SUBSCRIPTION",
  "message": "A subscription for this LinkedIn entity already exists",
  "details": {
    "existing_subscription_id": "sub_9Yx7Kj2Mn",
    "linkedin_id": "john-doe"
  }
}

403 Forbidden - Tier Limit Exceeded

{
  "error": "TIER_LIMIT_EXCEEDED",
  "message": "Your account has reached its subscription limit",
  "details": {
    "current_count": 100,
    "tier_limit": 100,
    "tier": "starter"
  }
}

400 Bad Request - Invalid LinkedIn URL

{
  "error": "VALIDATION_ERROR",
  "message": "Invalid LinkedIn URL format",
  "details": {
    "field": "linkedin_url",
    "value": "not-a-valid-url"
  }
}

Best Practices

💡 Subscription Tips

  • • Use bulk endpoints when creating or deleting multiple subscriptions
  • • Prefer LinkedIn URLs over IDs for better reliability
  • • Implement pagination when listing large numbers of subscriptions
  • • Export subscriptions regularly for backup
  • • Monitor your usage to avoid hitting tier limits

Next Steps

Now that you understand subscriptions: