API integration docs
Public reference for the SocialProof API. Sign in to see your own key and pre-filled samples.
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
| Method | Path | Description | Key parameters |
|---|---|---|---|
| GET | /api/v1/me | Account, plan and quota usage | None |
| GET | /api/v1/campaigns | Campaign list | None |
| GET | /api/v1/notifications | Widgets with their counters | campaign_id |
| GET | /api/v1/leads | Leads (email, name, phone, custom fields) | campaign_id, notification_id, since, until, limit, offset |
| GET | /api/v1/events | Raw tracking events | type, campaign_id, notification_id, since, until, limit, offset |
| GET | /api/v1/stats | Daily impressions, clicks, closes and conversions | days=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.
| Scope | What it allows |
|---|---|
| read | Every read endpoint above |
| write | Everything read allows, plus creating and updating campaigns, widgets, leads and conversions |
| delete | Everything 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.
| Method | Path | Scope | Description |
|---|---|---|---|
| POST | /api/v1/campaigns | write | Create a campaign |
| PUT | /api/v1/campaigns/{id} | write | Update the name, the domain or the enabled state |
| DELETE | /api/v1/campaigns/{id} | delete | Delete a campaign together with its widgets |
| POST | /api/v1/notifications | write | Create a widget inside a campaign |
| PUT | /api/v1/notifications/{id} | write | Update the name, the settings or the enabled state |
| DELETE | /api/v1/notifications/{id} | delete | Delete a widget together with its events and leads |
| POST | /api/v1/leads | write | Push a lead in from another system |
| POST | /api/v1/conversions | write | Report 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.
- Plan, renewal date and invoices — all under Billing, one invoice per charge.
- Payment notifications — every event carries a unique id, so the same delivery arriving twice is ignored instead of counted twice.
- Plan changes — upgrades start straight away, downgrades start when the current period ends.