Skip to content
Browse the docs

REST API

Read your clicks and manage your exclusion list from your own code, and send server hits and conversions from your own integrations.

Overview#

The API has two parts. The REST API reads clicks and manages exclusions. The ingest endpoints are what the tag, the plugins and the Next.js package call; you only call them yourself if you are building your own integration.

EndpointKeyPlans
GET /clicksSecretPro, Agency, and AppSumo Studio tier and up
GET /exclusionsSecretPro, Agency, and AppSumo Studio tier and up
POST /exclusionsSecretPro, Agency, and AppSumo Studio tier and up
DELETE /exclusions/{id}SecretPro, Agency, and AppSumo Studio tier and up
POST /collectPublicAll plans
POST /hitSecretAll plans
POST /conversionSecretAll plans

Base URL:

https://spurn.io/api/v1

Requests and responses are JSON over HTTPS.

Authentication#

Keys belong to a site. A key only ever reads and writes the data of the site it belongs to, and there is no key that spans sites.

Send the secret key as a bearer token:

GET /api/v1/clicks HTTP/1.1
Host: spurn.io
Authorization: Bearer sp_sec_XXXXXXXX

Create and revoke keys in Sites, then your site, then the Keys tab. Spurn shows a secret key once, when you create it, and stores only a hash of it; the dashboard lists the first characters so you can tell keys apart. If a key leaks, revoke it and create a new one.

A secret key belongs on a server. Never put it in a page, an app bundle or a public repository. The public key (sp_pub_XXXXXXXX) is the one that goes in pages, and it can only report landings, engagement and conversions through /collect.

Errors#

StatusMeaning
400The body or a parameter is malformed: invalid JSON, a CIDR that does not parse, an unknown verdict or platform value, a date that does not parse.
401The key is missing, unknown or revoked, or it is the wrong kind of key for the endpoint.
403The key is valid but your plan does not include the REST API.
404No such resource for this key's site, for example an exclusion id from another site.
429Too many requests. Wait for the number of seconds in the Retry-After header, then retry.

Example error body. The field shown is an example:

{ "error": "Unknown verdict \"bad\". Use valid, suspicious, invalid or pending." }

Rate limits#

Requests are rate limited. When you go over, Spurn answers 429 Too Many Requests with a Retry-After header giving the seconds to wait. Back off for at least that long before you retry.

Pagination#

GET /clicks returns results a page at a time. Each response carries a cursor for the next page. Pass it back as the cursor parameter, with the same filters, to get the next page. When there is no next cursor, you have everything.

Clicks#

GET /clicks#

Lists paid clicks for the key's site.

ParameterDescription
fromStart of the range, as an ISO 8601 date or date-time.
toEnd of the range, as an ISO 8601 date or date-time.
verdictvalid, suspicious, invalid or pending.
platformgoogle, microsoft, meta, tiktok, linkedin, x, pinterest, snapchat, reddit or other.
cursorThe cursor from the previous page.
curl "https://spurn.io/api/v1/clicks?from=2026-11-01&to=2026-11-14&verdict=invalid&platform=google" \
  -H "Authorization: Bearer sp_sec_XXXXXXXX"

Example response. The field names and values below are examples, not the full schema:

{
  "data": [
    {
      "id": "cm3k2x9q80001",
      "createdAt": "2026-11-14T09:12:44.120Z",
      "platform": "google",
      "clickId": "Cj0KCQiAexample",
      "clickIdType": "gclid",
      "ip": "203.0.113.7",
      "country": "US",
      "networkType": "datacenter",
      "asOrg": "Example Hosting Ltd",
      "deviceType": "desktop",
      "landingUrl": "https://shop.example.com/products/linen-sheets?gclid=Cj0KCQiAexample",
      "campaignId": "21012345678",
      "keyword": "linen sheets",
      "verdict": "invalid",
      "score": 81,
      "reasons": ["DATACENTER", "NO_ENGAGEMENT"],
      "analyzed": true,
      "finalized": true,
      "seenByTag": true,
      "seenByServer": true,
      "seenByPlatform": true,
      "converted": false
    }
  ],
  "nextCursor": "eyJpZCI6ImNtM2sy"
}

What the main fields mean:

  • verdict and score follow the rules in How detection works. A click is pending until its verdict is final, at most a few minutes after landing.
  • reasons holds reason codes, worst first. The full list of codes is in How detection works.
  • analyzed is false for clicks recorded after your monthly clicks and click packs ran out. They have no score and no reasons.
  • seenByTag, seenByServer and seenByPlatform say which witnesses reported the click: the tag, a server hit or tracking template, and Google's own click record.

Exclusions#

An exclusion is one network Spurn keeps away from your ads: a single IP address, or a /24 (IPv4) or /48 (IPv6) block. See Google Ads exclusion lists for how they reach Google Ads.

GET /exclusions#

Lists the exclusions for the key's site, both the ones Spurn added and the ones people added.

curl https://spurn.io/api/v1/exclusions \
  -H "Authorization: Bearer sp_sec_XXXXXXXX"

Example response. The field names and values below are examples, not the full schema:

{
  "data": [
    {
      "id": "cm3k3a1b20007",
      "cidr": "198.51.100.0/24",
      "kind": "subnet",
      "source": "auto",
      "state": "active",
      "reasons": ["DATACENTER", "REPEAT_IP"],
      "clickCount": 14,
      "note": null,
      "firstSeenAt": "2026-11-12T16:03:10.000Z",
      "lastSeenAt": "2026-11-14T08:41:52.000Z",
      "expiresAt": "2026-12-14T08:41:52.000Z"
    },
    {
      "id": "cm3k3a1b20009",
      "cidr": "203.0.113.24/32",
      "kind": "ip",
      "source": "manual",
      "state": "active",
      "reasons": [],
      "clickCount": 0,
      "note": "Competitor office",
      "firstSeenAt": "2026-11-10T11:20:00.000Z",
      "lastSeenAt": "2026-11-10T11:20:00.000Z",
      "expiresAt": null
    }
  ]
}

state is active, expired or removed. expiresAt is null for an exclusion that lasts until someone removes it.

POST /exclusions#

Adds a network to the site's exclusion list. Spurn delivers it to your linked ad accounts the same way as one you add in the dashboard, and records it in the change log.

FieldDescription
cidrAn IPv4 or IPv6 address, or a /24 (IPv4) or /48 (IPv6) block. A single address is stored as /32 or /128.
noteOptional. Up to 500 characters, shown next to the entry in the dashboard.
curl -X POST https://spurn.io/api/v1/exclusions \
  -H "Authorization: Bearer sp_sec_XXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{ "cidr": "203.0.113.24", "note": "Competitor office" }'

The response is the new exclusion, in the same shape as an item from GET /exclusions.

DELETE /exclusions/{id}#

Removes an exclusion. Spurn takes its entries off every linked ad account and records the removal in the change log. A removed exclusion can be restored from the dashboard.

curl -X DELETE https://spurn.io/api/v1/exclusions/cm3k3a1b20009 \
  -H "Authorization: Bearer sp_sec_XXXXXXXX"

Success returns 204 No Content.

Ingest endpoints#

These are the endpoints Spurn's own integrations call. Use them when you build an integration Spurn does not ship. Only paid landings are recorded; anything else is ignored.

POST /collect#

What the tag in the browser calls, with the site's public key. The body is JSON sent as text/plain, so the browser sends it without a CORS preflight; send it with fetch and keepalive: true, or with navigator.sendBeacon. Any origin may call it, and Spurn checks the request's origin and the landing host against the site's domain and extra hosts.

Every event has these fields:

{ "v": 1, "k": "sp_pub_XXXXXXXX", "t": "land", "pv": "<pageview uuid>", "vid": "<visitor id>" }

t is the event type: land, eng or conv. Each type adds its own fields.

A landing (land), sent once per page view:

{
  "v": 1, "k": "sp_pub_XXXXXXXX", "t": "land",
  "pv": "<pageview uuid>", "vid": "<visitor id>",
  "url": "https://shop.example.com/?gclid=Cj0KCQiAexample",
  "ref": "https://www.google.com/",
  "fp": "<fingerprint>",
  "tz": "Europe/London",
  "lang": "en-GB",
  "fbp": "fb.1.1794690000000.123",
  "fbc": "fb.1.1794690000000.IwARexample",
  "sig": {}
}

url is the full landing URL and ref the referrer. fp is a hash of stable device signals. tz is the browser's IANA timezone and lang its language. fbp and fbc are Meta's browser ids, sent when the Meta pixel has set them. sig carries browser signals; its contents are internal to Spurn's tag and can change between tag versions.

Engagement (eng), sent at 10 seconds, at 30 seconds and when the page is hidden or closed:

{
  "v": 1, "k": "sp_pub_XXXXXXXX", "t": "eng",
  "pv": "<pageview uuid>", "vid": "<visitor id>",
  "dwell": 12000, "scroll": 64, "moves": 31, "acts": 2, "pages": 1
}

dwell is milliseconds on the page, scroll the furthest scroll as a percentage, moves pointer movements, acts interactions and pages pages viewed.

A conversion (conv):

{
  "v": 1, "k": "sp_pub_XXXXXXXX", "t": "conv",
  "pv": "<pageview uuid>", "vid": "<visitor id>",
  "value": 49.9, "cur": "USD", "oid": "1001", "cid": "<click id from the _spc cookie, optional>"
}

The response to land:

{ "ok": true, "verdict": "pending", "score": 0, "meta": false, "uet": false }

verdict is valid, suspicious, invalid or pending, and score runs from 0 to 100. meta and uet tell the tag whether to fire its Meta and Microsoft UET events for this visitor (see GTM and pixel events). eng and conv return 204 No Content.

curl -X POST https://spurn.io/api/v1/collect \
  -H "Content-Type: text/plain" \
  -H "Origin: https://shop.example.com" \
  -d '{"v":1,"k":"sp_pub_XXXXXXXX","t":"land","pv":"6f1c2e1a-1b7d-4c8e-9a51-2f0d3c4b5a69","vid":"v_8d2f","url":"https://shop.example.com/?gclid=test-123","ref":"","fp":"a1b2c3d4","tz":"Europe/London","lang":"en-GB","sig":{}}'

POST /hit#

A server hit: the visitor's IP address and user agent, sent from your server when a paid landing arrives. It lets Spurn see clicks whose page JavaScript never runs.

FieldDescription
urlThe full landing URL, query string included.
ipThe visitor's IP address. Behind a proxy or CDN, take it from the header your proxy sets, not from the socket.
uaThe visitor's user agent.
refOptional. The referrer.
tsOptional. When the landing happened.
langOptional. The Accept-Language value.
sourcewoocommerce, wordpress, nextjs, cloudflare, node or custom. Use custom for your own integration.
curl -X POST https://spurn.io/api/v1/hit \
  -H "Authorization: Bearer sp_sec_XXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://shop.example.com/products/linen-sheets?gclid=Cj0KCQiAexample",
    "ip": "203.0.113.7",
    "ua": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
    "ref": "https://www.google.com/",
    "lang": "en-GB",
    "source": "custom"
  }'

If url is not a paid landing, Spurn ignores the hit and returns 204. Otherwise it merges the hit into a click the tag reported with the same click id in the last 10 minutes, or creates a server-only click. Any 2xx means the hit was accepted.

Send hits without making the visitor wait: fire and forget, as the WordPress plugin (non-blocking request) and the Next.js package (waitUntil) do.

POST /conversion#

Records an order or lead against the click that brought it, from your server. A purchase lowers a click's score; see Mitigation in How detection works.

FieldDescription
orderIdYour order or lead id.
valueThe order value, in major units (49.9 for $49.90).
currencyISO 4217 code, such as USD.
clickIdOptional. The click id, from the _spc cookie or your own records.
pageviewIdOptional. The page view id, from the _spc cookie.
visitorIdOptional. The tag's visitor id.
tsOptional. When the conversion happened.
curl -X POST https://spurn.io/api/v1/conversion \
  -H "Authorization: Bearer sp_sec_XXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{ "orderId": "1001", "value": 49.9, "currency": "USD", "clickId": "Cj0KCQiAexample" }'

Spurn matches the conversion to the most recent click from the last 30 days with the same page view, click id or visitor. Send at least one of the three. The _spc cookie the tag sets holds {pageviewId}.{clickId}, with - in place of a missing click id, so a server that can read the shopper's cookies can pass both.