API integration docs

Public reference for the SocialProof API. Sign in to see your own key and pre-filled samples.

Back to plan

Authentication

Every /api/v1/* endpoint authenticates with an API key and only ever returns data from that account. Replace the placeholder below with a key from Account → API keys. These two forms are equivalent:

Authorization: Bearer YOUR_API_KEY
X-API-Key: YOUR_API_KEY

Rate limit: 600 requests per minute per key; over that returns 429.

Read endpoints

MethodPathDescriptionKey parameters
GET/api/v1/meAccount, plan and quota usageNone
GET/api/v1/campaignsCampaign listNone
GET/api/v1/notificationsWidgets with their counterscampaign_id
GET/api/v1/leadsLeads (email, name, phone, custom fields)campaign_id, notification_id, since, until, limit, offset
GET/api/v1/eventsRaw tracking eventstype, campaign_id, notification_id, since, until, limit, offset
GET/api/v1/statsDaily impressions, clicks, closes and conversionsdays=7|14|30|90

All timestamps are UTC, written YYYY-MM-DD or YYYY-MM-DD HH:MM:SS; limit caps at 1000.

Your API keys

The key printed on this page is the account key. It keeps working, but you can also create scoped keys, one per integration, so that revoking one never breaks the others.

ScopeWhat it allows
readEvery read endpoint above
writeEverything read allows, plus creating and updating campaigns, widgets, leads and conversions
deleteEverything write allows, plus deleting campaigns and widgets

A call made with a key that lacks the scope it needs stops with the error insufficient_scope, so it is always clear why something did not go through.

Write endpoints

These need a key that carries the matching scope. Send the body as JSON with Content-Type set to application/json.

MethodPathScopeDescription
POST/api/v1/campaignswriteCreate a campaign
PUT/api/v1/campaigns/{id}writeUpdate the name, the domain or the enabled state
DELETE/api/v1/campaigns/{id}deleteDelete a campaign together with its widgets
POST/api/v1/notificationswriteCreate a widget inside a campaign
PUT/api/v1/notifications/{id}writeUpdate the name, the settings or the enabled state
DELETE/api/v1/notifications/{id}deleteDelete a widget together with its events and leads
POST/api/v1/leadswritePush a lead in from another system
POST/api/v1/conversionswriteReport a conversion from your own backend

Some shared hosts block PUT and DELETE requests before they reach PHP. On those hosts send the same call as POST and add the query parameter _method=PUT — the request body is read exactly the same way.

Example: report a conversion

curl -s -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"notification_id": 1, "order_id": "ORDER-10231", "value": "49.90", "currency": "USD"}' \
  "https://www.ccroo.com/api/v1/conversions"

Sending the same order_id twice is safe: the second call comes back with duplicate set to true instead of counting the sale twice.

Example: pull this month's leads

curl -s \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.ccroo.com/api/v1/leads?since=2026-11-01&limit=100"
const res = await fetch(
  "https://www.ccroo.com/api/v1/leads?since=2026-11-01&limit=100",
  { headers: { Authorization: "Bearer YOUR_API_KEY" } }
);
const { data } = await res.json();
console.log(data.total, data.leads.length);
<?php
$ch = curl_init("https://www.ccroo.com/api/v1/leads?limit=100");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ["Authorization: Bearer YOUR_API_KEY"],
]);
$json = json_decode(curl_exec($ch), true);
foreach ($json["data"]["leads"] as $lead) {
    echo $lead["email"], PHP_EOL;
}

Tracking and conversion callbacks

The two endpoints below authenticate with their own random keys instead of your API key, so they are safe to embed in a page and on a server.

1. Embed the pixel

<script defer src="https://www.ccroo.com/pixel/your-pixel-key.js"></script>

2. Post conversions from your server

Call it once after a successful payment or signup.

curl -s -X POST "https://www.ccroo.com/webhook/your-notification-key" \
  -H "Content-Type: application/json" \
  -d '{"order_id":"SO-10086","amount":"199.00","currency":"USD"}'

Deduplication: for a given widget, a conversion whose body is identical is counted once; a repeat returns duplicate. Put your order id in order_id.

Payments and subscriptions

Checkout takes place on a secure hosted payment page that accepts cards and the major payment methods. Card details are entered on the payment provider’s side and never reach this server.

When a payment goes through, the subscription on this account switches on by itself — there is nothing to activate by hand. The plan, the renewal date and the payment state are read back from the payment provider, so Billing always shows what was actually charged.