API Reference
Conversions
Report a backend conversion and attribute it to the page visit that produced it.
/v1/analytics/report-conversionWhen a conversion happens in your backend — a purchase clears, a demo is booked, a trial converts — this endpoint attributes it back to the SuperFunnel page visit and campaign that produced it.
For the full picture of how session identifiers are captured, see offline conversion tracking in the guides.
Matching a conversion to a visit
SuperFunnel appends a unique session identifier to outbound URLs a visitor clicks. Capture it, store it with your record, and send it back here.
You can match on any one of these:
| Identifier | Where it comes from |
|---|---|
sessionHash, hash, visitHash, sessionId | Appended by SuperFunnel to outbound URLs |
shortHash, shortSessionHash, shortVisitHash | Short forms of the same identifiers |
gclid, gbraid, wbraid, fbclid, msclkid, ttclid, li_fat_id, epik, twclid, sclid, tblci, ob_click_id, rdt_cid, aleid, alart | The ad platform that sent the click |
Send exactly one identifier
Send one identifier per item — no more. A request carrying none is rejected,
and so is one carrying two, because there would be no way to tell which visit
you meant. Google is the case that catches people out: it sends an empty
gclid alongside gbraid or wbraid, and an empty value does not count.
If the identifier does not match a session in your account, the item comes
back with status: "unmatched" and reported: false — the request itself
still succeeds with 200, so check each result rather than only the status
code.
Reporting a value
Send the amount as a top-level value, with currency as a three-letter
ISO 4217 code:
{
"sessionHash": "3f8a91c2b47e",
"value": 249.99,
"currency": "USD",
"eventId": "order-10482"
}A numeric string works too — "249.99" is accepted — but an empty string is
rejected rather than read as zero.
Restating a value
Give a conversion your own eventId and you can report it again to correct the
amount. The later report wins, ordered by when it arrives rather than by
createdOn, and it replaces the value instead of recording a second
conversion.
Zero is a real value here, not an omission: reporting value: 0 against an
existing eventId restates that conversion down to nothing, which is what you
want for a refund or a cancelled order.
The old `conversion` object is deprecated
Earlier integrations sent conversion: { value }. That still works, so
nothing you have built needs changing today, but send the top-level value
in new code — if you send both, the top-level one wins. The nested type
field is gone; it was never stored.
Batching
Send a single object, or an array of them to report many at once. The response mirrors what you sent: one object in, one object back; an array in, an array back, in the same order.
Batching is the right way to stay inside the rate limits when backfilling.
Reporting from a URL
Some platforms will only let you configure a plain URL — a thank-you page
redirect, or a postback with no request body. For those, the same report works
as a GET with the fields in the query string:
GET https://api.superfunnel.ai/v1/analytics/report-conversion?sessionHash=3f8a91c2b47e&value=249.99¤cy=USDA query string cannot express the nested conversion object or extra, so
those two are POST-only, and so is reporting a batch.
/v1/analytics/report-conversionReport a conversion by query string
The query-string form of the same report, for callers that can only fire a URL — a thank-you page redirect, or a platform that only lets you configure a plain GET. Takes the same fields as the POST body except `conversion` and `extra`, which a query string cannot express, and reports one conversion rather than a batch.
Query parameters
hashstring | number | nullsessionHashstring | number | nullsessionIdstring | number | nullvisitHashstring | number | nullshortHashstring | nullshortSessionHashstring | nullshortVisitHashstring | nullgclidstring | nullgbraidstring | nullwbraidstring | nullfbclidstring | nullmsclkidstring | nullttclidstring | nullli_fat_idstring | nullepikstring | nulltwclidstring | nullsclidstring | nulltblcistring | nullob_click_idstring | nullrdt_cidstring | nullaleidstring | nullalartstring | nulleventstringcreatedOnany | nulleventIdstring | nullvaluenumber | string | nullcurrencystring | nullResponse · 200
_idstringreportedbooleanrequiredstatusenumrequiredOne of: reported, unmatched, failed
errorstringreasonstringExample response
{
"_id": "9pQrStUvWxYz",
"reported": true,
"status": "reported"
}Errors: 400, 401, 404, 405, 429, 500. See Errors for the response shape.
/v1/analytics/report-conversionStored in this browser tab only. Requests go directly to the API — the token never reaches the docs site.
Query parameters
https://api.superfunnel.ai/v1/analytics/report-conversion
curl -X GET 'https://api.superfunnel.ai/v1/analytics/report-conversion' \
-H 'x-api-key: Bearer YOUR_API_TOKEN'Request body
hashstring | number | nullsessionHashstring | number | nullsessionIdstring | number | nullvisitHashstring | number | nullshortHashstring | nullshortSessionHashstring | nullshortVisitHashstring | nullgclidstring | nullgbraidstring | nullwbraidstring | nullfbclidstring | nullmsclkidstring | nullttclidstring | nullli_fat_idstring | nullepikstring | nulltwclidstring | nullsclidstring | nulltblcistring | nullob_click_idstring | nullrdt_cidstring | nullaleidstring | nullalartstring | nulleventstringEvent name to record. Defaults to a conversion event.
createdOnany | nulleventIdstring | nullvaluenumber | string | nullcurrencystring | nullconversionobject | nullDeprecated. Use the top-level `value` instead.
Show 1 propertiesHide properties
conversionobject | nullvaluenumber | string | nullextraobject | nullExample response
{
"_id": "9pQrStUvWxYz",
"reported": true,
"status": "reported"
}Errors: 400, 401, 404, 405, 429, 500. See Errors for the response shape.