REST API
Programmatic access to your SocialScalr data. Useful for syncing leads into a CRM, scheduling posts from your editorial system, or building custom dashboards.
Authentication
Every request needs your API token in the Authorization header:
Authorization: Bearer ss_xxxxxxxxxxxxxxxxxxxxxxxx
Find your token at Settings & billing. The token is per-user and bypasses RLS - treat it like a password. Rotate it from the Settings page anytime.
Base URL
https://socialscalr.com/api/v1
Conventions
- All requests and responses are JSON.
- Timestamps are ISO 8601 UTC.
- Errors return
{ "error": "human-readable message" }with an appropriate HTTP status. - Soft per-token rate limit: 60 req/min. Burst above and you'll see HTTP 429.
Endpoints
GET/api/v1/me
Confirm a token works. Returns your identity.
{
"id": "uuid",
"email": "[email protected]",
"fullName": "Your Name",
"plan": "pro",
"teamRole": "owner"
}
GET/api/v1/campaigns
List your campaigns. Returns up to 200, most recent first.
{
"campaigns": [
{ "id": "...", "name": "Q4 founders", "status": "active", ... }
]
}
POST/api/v1/campaigns
Create a new campaign.
// Body { "name": "Q4 founders", "search_url": "https://www.linkedin.com/search/...", "targeting": { "titleKeywords": ["founder", "ceo"] }, "templates": { "note": "Hi {{first_name}}, ..." } }
GET/api/v1/leads?campaignId=...&status=...&limit=...
List leads. All filters optional. Default limit 100, max 500.
POST/api/v1/leads
Bulk-add leads to a campaign. Duplicates (same campaign_id + profile_url) are ignored.
{
"campaignId": "uuid",
"leads": [
{ "name": "Ada Lovelace",
"profileUrl": "https://www.linkedin.com/in/ada/",
"title": "Founder",
"location": "London" }
]
}
GET/api/v1/posts
List your scheduled + published posts (most recent 200).
POST/api/v1/posts
Schedule a LinkedIn post.
{
"content": "Thoughts on Q4...",
"scheduled_for": "2026-06-01T13:00:00Z",
"link_url": "https://socialscalr.com",
"first_comment": "More on this..."
}
Webhooks
You can also receive events instead of polling. Register a webhook in Settings. We POST a JSON body when subscribed events fire:
POST your-url
Content-Type: application/json
X-SocialScalr-Event: lead.invited
X-SocialScalr-Signature: sha256=<hex>
{
"event": "lead.invited",
"sentAt": "2026-05-23T20:00:00Z",
"apiVersion": "2024-12-18",
"data": { ... }
}
Verify the signature: hex(hmac_sha256(secret, raw_body)) must equal the value after sha256=. The secret is shown once when you create the webhook.
Available webhook events
leads.scraped- extension added new leads to a campaignlead.invited- connection request sentlead.messaged- follow-up message sentpost.published- scheduled post went outcomment.posted- approved comment posted*- subscribe to all events