Skip to content

CTV Impression API ​

Report affiliate connected TV ad impressions server-to-server for household view-through attribution

Affiliate partners use this endpoint to report an ad impression shown on a connected TV, so Linkrunner can credit an Android or iOS install from the same household IP address. For the setup guide and the attribution rules, see Connected TV (CTV) Impressions.

Endpoint ​

GET https://s2s.linkrunner.io/v1/ctv/impression/{app_id}
GET https://s2s.linkrunner.io/v1/ctv/impression?app_id={app_id}
GET https://s2s.linkrunner.io/v1/ctv/impression?d={domain}

The advertiser is identified by the app ID (or the tracking link's domain) and the campaign by c. The campaign must belong to your partner account. S2S traffic, view-through and CTV must all be on for you on this app. The advertiser turns them on.

Authentication ​

Every request must carry your partner token, the same one you use for S2S clicks and S2S impressions. Send it in a header:

X-Linkrunner-Token: <your_token>

If your ad server can only fire URLs, send it as the lr_token query parameter instead: &lr_token=<your_token>. Linkrunner removes lr_token before it stores the impression, so it never appears in reports or postbacks. A request without a valid token is rejected with 401.

Parameters ​

Send all parameters as URL-encoded query parameters. Each value is limited to 256 characters.

ParameterAliasRequiredDescription
app_idpathOne of app_id or dThe app's Android package name (com.example.app) or App Store ID (id1234567890 or 1234567890). Can also be sent in the path: /v1/ctv/impression/{app_id}.
dOne of app_id or dDomain of your Linkrunner tracking link, for example app.example.com. Wins over app_id when both are sent.
cYesCampaign code, the c value of your tracking link. Must match a campaign of that app or domain exactly.
lr_tokenOnly without the headerYour partner token, for ad servers that can't set the X-Linkrunner-Token header. Removed before the request is stored.
tidclickidYesYour unique impression ID. Returned in the {click_id} and {tid} postback macros.
ipaf_ipYesThe TV's public IP address. This is the value installs are matched on. With server-side ad insertion, use the X-Device-IP value your ad server received.
uaaf_uaYesThe TV's user agent. With server-side ad insertion, use the X-Device-User-Agent value.
impression_timeNoUnix timestamp of the impression, in milliseconds or seconds. Defaults to the time of the request.
vt_lookbackaf_xplatform_vt_lookback, af_viewthrough_lookbackNoYour view-through window for this impression: 1h to 24h, a bare number of hours (6), or 1d. Longer values are capped at 24 hours. It can only shorten the window the advertiser set for you.
partner_campaign_idaf_c_idNoYour own campaign ID. Stored with the impression.
adset_idaf_adset_idNoYour ad set ID. Stored with the impression.
ad_idaf_ad_idNoYour ad ID. Stored with the impression.
site_idaf_siteidNoThe publisher, channel or app the ad played in. Stored with the impression.
source_platformaf_source_platformNoThe TV platform, for example tizen, webos, roku, androidtv, firetv or vidaa. Stored with the impression.
device_categoryaf_source_device_categoryNoThe device type, for example tv, set_top_box, games_console or media_player. Stored with the impression.
tv_ifaNoThe TV's advertising ID. Stored with the impression, never used for matching.
ifa_typeNoThe type of tv_ifa, for example rida, tifa, lgudid, vida, afai or msai. Stored with the impression.
s2af_sub1NoPassthrough value, returned in {s2}.
s3af_sub2NoPassthrough value, returned in {s3}.
s4af_sub3NoPassthrough value, returned in {s4}.

gaid and idfa are not read on this endpoint. If your impressions carry the phone's advertising ID, send them to the S2S Impression API instead.

If both a name and its alias are sent, the name wins. pid, af_xplatform and redirect are ignored.

Responses ​

The response is always JSON.

json
{
  "status": "accepted",
  "impression_id": "4c1f0e1a-52b7-5d0e-9a43-7f8e2c6b1d90"
}
json
{
  "status": "rejected",
  "reason": "missing_ip"
}
json
{
  "status": "rejected",
  "reason": "ctv_not_enabled"
}

impression_id is Linkrunner's ID for the impression. It is the same for every retry of the same tid on the same campaign.

Status codes ​

StatusReasonMeaningRetry
200Impression recorded.
400missing_appNeither app_id nor d was sent.No
400missing_c, missing_tidA required parameter is missing or empty.No
400missing_ipNo ip was sent.No
400invalid_ipip is not a public IP address: a private, loopback, link-local or carrier-grade NAT (100.64.0.0/10) address, or not an IP address at all.No
400datacenter_ipip belongs to a cloud or hosting provider. Send the TV's address, not your ad server's.No
400missing_uaNo ua was sent.No
400unreplaced_macroA value still contains a macro, such as {ip} or %7Bip%7D.No
400value_too_longA value is longer than 256 characters.No
400invalid_impression_timeimpression_time is not a Unix timestamp.No
400impression_too_oldimpression_time is more than 24 hours ago. A time in the future is treated as now.No
400invalid_viewthrough_lookbackvt_lookback is 0, negative, fractional, or not in hours or days.No
400unknown_appNo Linkrunner project has this app ID.No
400ambiguous_appMore than one of the advertiser's projects with S2S on for you has this app ID and campaign code (for example test and live). Send d instead.No
400unknown_domaind is not a Linkrunner click domain.No
400unknown_campaignc does not match a campaign of that app or domain.No
401missing_tokenNo X-Linkrunner-Token header and no lr_token parameter.No
401invalid_tokenThe token is wrong, revoked, or was rotated more than 24 hours ago, or your partner account is suspended.No
403partner_not_enabledThe advertiser hasn't turned on S2S traffic for the partner that owns campaign c. See Turn on S2S clicks for a partner.No
403view_through_disabledS2S traffic is on, but the advertiser hasn't turned on view-through for this partner. See View-through attribution.No
403ctv_not_enabledS2S traffic and view-through are on, but the advertiser hasn't turned on CTV for this partner on this app. See Turn on CTV impressions.No
404s2s_disabledThe S2S impression APIs are turned off.No
429rate_limitedToo many impressions for this campaign.Yes, after Retry-After
503unavailableA temporary error.Yes, after Retry-After

Examples ​

The examples read your token from the LINKRUNNER_S2S_TOKEN environment variable.

bash
curl -G "https://s2s.linkrunner.io/v1/ctv/impression/com.example.app" \
  -H "X-Linkrunner-Token: $LINKRUNNER_S2S_TOKEN" \
  --data-urlencode "c=OgWmhiSXhG" \
  --data-urlencode "tid=ctv-imp-7f3a91" \
  --data-urlencode "ip=203.0.113.24" \
  --data-urlencode "ua=Mozilla/5.0 (SMART-TV; Linux; Tizen 7.0) AppleWebKit/537.36 (KHTML, like Gecko) Version/7.0 TV Safari/537.36" \
  --data-urlencode "impression_time=1790585271181" \
  --data-urlencode "source_platform=tizen" \
  --data-urlencode "device_category=tv"
javascript
const params = new URLSearchParams({
  c: "OgWmhiSXhG",
  tid: impressionId,
  ip: deviceIp,
  ua: deviceUserAgent,
  impression_time: String(Date.now()),
  source_platform: "tizen",
  device_category: "tv",
});

const res = await fetch(`https://s2s.linkrunner.io/v1/ctv/impression/com.example.app?${params}`, {
  headers: { "X-Linkrunner-Token": process.env.LINKRUNNER_S2S_TOKEN },
});
const body = await res.json(); // { status: "accepted", impression_id: "..." }
python
import os, time, requests

res = requests.get("https://s2s.linkrunner.io/v1/ctv/impression/com.example.app", params={
    "c": "OgWmhiSXhG",
    "tid": impression_id,
    "ip": device_ip,
    "ua": device_user_agent,
    "impression_time": int(time.time() * 1000),
    "source_platform": "tizen",
    "device_category": "tv",
}, headers={"X-Linkrunner-Token": os.environ["LINKRUNNER_S2S_TOKEN"]}, timeout=5)
body = res.json()  # {"status": "accepted", "impression_id": "..."}

Retries and deduplication ​

The same tid on the same campaign always maps to the same impression_id, and the impression is stored once, so it is safe to retry. CTV impression IDs are separate from /v1/impression ones, so the same tid on both endpoints does not collide. Retry only 429 and 503, after the delay in the Retry-After header. Keep tid unique per impression: a reused tid is treated as a retry of the earlier impression, so the new one is not recorded.

Need help? Contact support@linkrunner.io.

Need help? Contact support@linkrunner.io