{"openapi":"3.1.0","info":{"title":"Rightlander API","version":"v1","description":"The Rightlander API gives you programmatic access to the partner intelligence you already see in the workbench: the domains and social profiles connected to your programme, everything we hold on any one of them, and the alerts we raise about them.\n\nIt is a REST API. Resources live under /apis/rightlander/v1, responses are JSON, and every response carries an \"ok\" boolean so a failure is never mistaken for an empty result.\n\nThere are four things you can do. List your assets. Retrieve one asset in as much or as little detail as you want. Ask us to refresh a social profile. Read your alerts.\n\nAnd one way to keep up without asking about each asset in turn: the activity feed lists what changed across your whole programme, newest first.\n\nAffiliate networks can also send us domains to scan, for themselves and for each of their clients, and read one client's feed at a time. See Networks and clients.\n\nCompliance teams can read what they see in the Compliance Workbench, with the actions taken on each item, by market and month or for the current scan cycle. See Compliance Workbench.\n\nDomains are scanned on a schedule set by your subscription, so there is no endpoint to force a domain rescan. Social profiles can be refreshed on demand because the cost of doing so is yours to decide.\n\nInstructions for AI assistants: https://aw1.rightlander.com/apis/rightlander/v1/llms.php\n\nDocumentation and playground: https://aw1.rightlander.com/intelv2/partnerIntelApiPortal.php\n\nCreate a key (main account login): https://aw1.rightlander.com/intelv2/partnerIntelApiKeys.php. Only live endpoints are listed here."},"servers":[{"url":"https://aw1.rightlander.com"}],"security":[{"bearerAuth":[]},{"apiKeyQuery":[]}],"tags":[{"name":"Assets"},{"name":"Reports"},{"name":"Activity"},{"name":"Compliance"},{"name":"Network"},{"name":"Network settings"},{"name":"Domains"},{"name":"Social profiles"}],"paths":{"/apis/rightlander/assets.php":{"get":{"operationId":"assets_list","summary":"List every domain and social profile connected to your account","description":"One entry per asset. Domains and social profiles come back in the same list, each carrying its type, the identifier the detail endpoints take, where it came from, when we last looked at it and whether you can ask us to look again.\n\nWhen to use it: Start here. Walk it with the cursor to synchronise your own systems, or filter it to find the identifier you need. Domains are returned first, alphabetically, then social profiles by platform and handle.\n\nCost: free within your daily allowance. Permission: read.\n\nFreshness: Reflects the most recent completed scan or assessment for each asset. last_scanned dates every row.\n\nNotes: Paging is by position, not offset, so rows added or removed between calls cannot make you skip or repeat one. next_cursor of \"s:\" with no key means the domains are finished and the social segment starts next. CHANGED 10 AUG: at detail=full, a domain row's social_profiles was a list of \"platform:handle\" strings and is now a list of objects. The id field carries the exact string it used to, so reading .id is the whole migration.","tags":["Assets"],"parameters":[{"name":"type","in":"query","required":false,"description":"Restrict to one kind of asset.","schema":{"type":"string","enum":["all","domain","social"],"default":"all"}},{"name":"detail","in":"query","required":false,"description":"simple returns identity and status. full adds partner, vertical, traffic band, and the social accounts found on each domain, each with its own assessed_for block.","schema":{"type":"string","enum":["simple","full"],"default":"simple"}},{"name":"iso","in":"query","required":false,"description":"Two-letter market code. Applies to domains only - social profiles are not market scoped.","schema":{"type":"string","examples":["GB"]}},{"name":"platform","in":"query","required":false,"description":"Restrict the social side to one platform.","schema":{"type":"string","enum":["instagram","tiktok","youtube","twitter","pinterest"]}},{"name":"search","in":"query","required":false,"description":"Substring match on the domain or the handle.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Rows per page, up to 500.","schema":{"type":"integer","default":100}},{"name":"cursor","in":"query","required":false,"description":"Pass back the next_cursor from the previous response. Null next_cursor means you have seen everything.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success. Check ok before reading the rest.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":["boolean","null"],"description":"True on success, false on failure. Check this before anything else - an empty result and a failure are not the same thing."},"error":{"type":["string","null"],"description":"Human-readable message. Present only on failure."},"error_code":{"type":["string","null"],"description":"Stable code to branch on. Match on this, not on the message text."},"status":{"type":["integer","null"],"description":"HTTP status, repeated in the body for clients that cannot see it."},"request":{"type":"object","properties":{"queried_at":{"type":["string","null"],"format":"date-time","description":"When we answered."},"took_ms":{"type":["integer","null"],"description":"How long it took us."},"key_source":{"type":["string","null"],"description":"header or query - where your key was read from."},"rate_limit":{"type":"object","properties":{"requests_per_day":{"type":["integer","null"],"description":"Your daily allowance."},"used_today":{"type":["integer","null"],"description":"Requests used today."},"remaining":{"type":["integer","null"],"description":"What is left."},"resets_at":{"type":["string","null"],"format":"date-time","description":"When it resets. 00:00 UTC."}}},"credits_charged":{"type":["integer","null"],"description":"Credits taken by this request. Present only when it cost something."}}},"summary":{"type":"object","properties":{"total":{"type":["integer","null"],"description":"Assets returned in this response."},"domains":{"type":["integer","null"],"description":"How many of those are domains."},"social_profiles":{"type":["integer","null"],"description":"How many are social profiles."}}},"assets":{"type":"array","items":{"type":"object","properties":{"type":{"type":["string","null"],"description":"domain or social. Everything else on the row depends on this."},"id":{"type":["string","null"],"description":"The identifier the detail endpoints take: the domain, or platform:handle. Null on a social row whose handle we cannot resolve - see note."},"status":{"type":["string","null"],"description":"Domains: scanned, in_progress or unscanned. Social: assessed or requested."},"last_scanned":{"type":["string","null"],"format":"date","description":"When we last completed a scan or assessment. Empty means never."},"next_scheduled":{"type":["string","null"],"format":"date","description":"ESTIMATE, domains only: the last scan plus your account cycle. It is not a booked slot and it can move."},"refreshable":{"type":["boolean","null"],"description":"Whether you can ask us to look again. Always false for domains - they run to a schedule you cannot change. False on a social profile inside its seven-day cooldown, or on a platform we record but do not assess."},"note":{"type":["string","null"],"description":"Only present when something about the row needs explaining, e.g. an assessment we hold but cannot tie to a usable handle."},"iso":{"type":["string","null"],"description":"The market of the scan this row describes."},"markets":{"type":"array","items":{"type":"array","items":{},"description":"Every market we hold activity for on this domain."},"description":"Every market we hold activity for on this domain."},"platform":{"type":["string","null"],"description":"instagram, tiktok, youtube, twitter or pinterest. x is normalised to twitter."},"handle":{"type":["string","null"],"description":"Account handle, lower-cased and with the @ stripped."},"request_status":{"type":["string","null"],"description":"Only when an assessment is queued. Where that request has got to."},"site_id":{"type":["string","null"],"description":"Our internal site id. Domain rows."},"vertical":{"type":["string","null"],"description":"Sector the domain was classified into."},"partner_company":{"type":["string","null"],"description":"Partner or publisher name, where we have resolved one."},"partner_affid":{"type":["string","null"],"description":"Affiliate id we hold against the domain."},"est_monthly_traffic":{"type":["string","null"],"description":"A BAND, e.g. \"100k - 500k\". Never a raw visit count - that data is third-party licensed."},"social_profiles":{"type":"array","items":{"type":"array","items":{},"description":"Domain rows: the platform:handle ids this domain's own scan links to. Each is a separate asset in the social segment, where its state and scores live."},"description":"Domain rows: the platform:handle ids this domain's own scan links to. Each is a separate asset in the social segment, where its state and scores live."},"profile_id":{"type":["string","null"],"description":"Social rows: our internal id for the profile."},"followers":{"type":["integer","null"],"description":"Social rows: audience size. Null when we hold no figure."}}}},"next_cursor":{"type":["string","null"],"description":"Pass back as ?cursor= for the next page. NULL means you have seen everything. \"s:\" with no key means the domains are finished and the social segment starts next."}}},"examples":{"assets_list":{"summary":"List every domain and social profile connected to your account","value":{"ok":true,"summary":{"total":100,"domains":82,"social_profiles":18},"assets":[{"type":"domain","id":"example.com","iso":"GB","markets":["GB","IE"],"status":"scanned","last_scanned":"2026-07-28","next_scheduled":"2026-08-28","refreshable":false,"social_profiles":[{"id":"tiktok:examplemedia","platform":"tiktok","handle":"examplemedia","assessed_for":{"basis":"generic","assessed_for_you":false,"last_assessed_for_you":null,"last_assessed":"2026-07-12","rescan_recommended":true}}]},{"type":"social","id":"tiktok:examplemedia","platform":"tiktok","handle":"examplemedia","status":"assessed","last_scanned":"2026-08-01","refreshable":true,"assessed_for":{"basis":"your_account","assessed_for_you":true,"last_assessed_for_you":"2026-08-01","last_assessed":"2026-08-01","rescan_recommended":false}}],"next_cursor":"s:tiktok|examplemedia"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/apis/rightlander/domain-list.php":{"get":{"operationId":"domain_list_legacy","summary":"Summary row per domain","description":"The per-domain summary the Domain Intelligence table is built from: scan status, vertical, sub-network detection, partner, traffic band, health priority counts, social profiles and top countries.\n\nWhen to use it: Use this when you want the domain view specifically. For domains and social profiles together, use /v1/assets.\n\nCost: free within your daily allowance. Permission: read.\n\nFreshness: Scan status and dates come from the latest run per domain and market.","tags":["Assets"],"parameters":[{"name":"action","in":"query","required":true,"description":"Set this to choose the request: action=list for summary row per domain.","schema":{"type":"string","enum":["list"],"default":"list"}},{"name":"iso","in":"query","required":false,"description":"Two-letter market code. Omit or send XX for all markets.","schema":{"type":"string","examples":["GB"]}},{"name":"search","in":"query","required":false,"description":"Substring match on the domain.","schema":{"type":"string"}},{"name":"include","in":"query","required":false,"description":"raw adds the heavier exposure, offers and growth blocks per domain.","schema":{"type":"string","enum":["raw"]}},{"name":"health","in":"query","required":false,"description":"Restrict to domains with health findings.","schema":{"type":"string","enum":["1"]}},{"name":"auditfilter","in":"query","required":false,"description":"Audit field id to require a match for. Adds audit_evidence to each row.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Maximum rows, capped at 5000.","schema":{"type":"integer","default":5000}}],"responses":{"200":{"description":"Success. Check ok before reading the rest.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":["boolean","null"],"description":"True on success, false on failure. Check this before anything else - an empty result and a failure are not the same thing."},"error":{"type":["string","null"],"description":"Human-readable message. Present only on failure."},"error_code":{"type":["string","null"],"description":"Stable code to branch on. Match on this, not on the message text."},"status":{"type":["integer","null"],"description":"HTTP status, repeated in the body for clients that cannot see it."},"request":{"type":"object","properties":{"queried_at":{"type":["string","null"],"format":"date-time","description":"When we answered."},"took_ms":{"type":["integer","null"],"description":"How long it took us."},"key_source":{"type":["string","null"],"description":"header or query - where your key was read from."},"rate_limit":{"type":"object","properties":{"requests_per_day":{"type":["integer","null"],"description":"Your daily allowance."},"used_today":{"type":["integer","null"],"description":"Requests used today."},"remaining":{"type":["integer","null"],"description":"What is left."},"resets_at":{"type":["string","null"],"format":"date-time","description":"When it resets. 00:00 UTC."}}},"credits_charged":{"type":["integer","null"],"description":"Credits taken by this request. Present only when it cost something."}}},"summary":{"type":"object","properties":{"total_domains":{"type":["integer","null"],"description":"Domains in the response."},"scanned_count":{"type":["integer","null"],"description":"Domains whose last run completed."},"in_progress_count":{"type":["integer","null"],"description":"Domains with a run that has not completed."},"subnetwork_count":{"type":["integer","null"],"description":"Domains identified as sub-network or sub-affiliate."},"exposure_count":{"type":["integer","null"],"description":"Domains with brand exposure. include=raw only."},"offers_count":{"type":["integer","null"],"description":"Domains with monitored offers. include=raw only."},"growth_count":{"type":["integer","null"],"description":"Domains with a growth opportunity. include=raw only."},"review_pass_count":{"type":["integer","null"],"description":"Domains a reviewer marked pass."},"review_fail_count":{"type":["integer","null"],"description":"Domains a reviewer marked fail."},"review_ticked_count":{"type":["integer","null"],"description":"Domains ticked off by a reviewer."},"priority_critical_total":{"type":["integer","null"],"description":"Critical health findings across all domains."},"priority_important_total":{"type":["integer","null"],"description":"Important findings across all domains."},"priority_interesting_total":{"type":["integer","null"],"description":"Interesting findings across all domains."}}},"domains":{"type":"array","items":{"type":"object","properties":{"domain":{"type":["string","null"],"description":"The domain."},"iso":{"type":["string","null"],"description":"Market this row describes."},"site_id":{"type":["string","null"],"description":"Our internal site id."},"scan_status":{"type":["string","null"],"description":"Raw status of the latest run, e.g. completed."},"scanned_at":{"type":["string","null"],"format":"date-time","description":"When the latest scan ran."},"updated_at":{"type":["string","null"],"format":"date-time","description":"When the scan record last changed."},"pagehash":{"type":["string","null"],"description":"Content hash of the scanned page, for change detection."},"vertical":{"type":["string","null"],"description":"Sector the domain was classified into."},"is_subnetwork":{"type":["boolean","null"],"description":"Whether the domain looks like a sub-network or sub-affiliate."},"subnetwork_label":{"type":["string","null"],"description":"Readable reason, e.g. Subnetwork via <entity>."},"subnetwork_signals":{"type":"array","items":{"type":"array","items":{},"description":"What triggered it: signal, affid, entity, networkcode, ctype, description."},"description":"What triggered it: signal, affid, entity, networkcode, ctype, description."},"partner_company":{"type":["string","null"],"description":"Partner or publisher company name."},"partner_affid":{"type":["string","null"],"description":"Affiliate id."},"est_monthly_traffic":{"type":["integer","null"],"description":"Banded monthly visits. Rounded, never the raw figure."},"top_countries":{"type":"array","items":{"type":"array","items":{},"description":"Largest traffic markets, with share."},"description":"Largest traffic markets, with share."},"social_profiles":{"type":"object","description":"One URL per platform found on the site: facebook, instagram, twitter, youtube, linkedin, pinterest, tiktok, linktree."},"exposure_pages":{"type":["integer","null"],"description":"Unique pages carrying a brand link, mention or topic match."},"offers":{"type":"object","properties":{"monitored":{"type":["boolean","null"],"description":"Whether offer monitoring is on for this domain."},"page_count":{"type":["integer","null"],"description":"Pages with monitored offers."},"is_fresh":{"type":["boolean","null"],"description":"Whether the offer data is newer than the last domain scan."}}},"has_growth":{"type":["boolean","null"],"description":"Whether any actionable growth opportunity exists."},"audit_evidence":{"type":["string","null"],"description":"Only when auditfilter is supplied. The evidence that matched."}}}},"health":{"type":"object","properties":{"priority_counts":{"type":"object","properties":{"critical":{"type":["integer","null"],"description":"Critical findings outstanding."},"important":{"type":["integer","null"],"description":"Important findings outstanding."},"interesting":{"type":["integer","null"],"description":"Interesting findings outstanding."}}},"priority_labels":{"type":"object","description":"The finding names behind each count."},"has_priorities_configured":{"type":["boolean","null"],"description":"False means nobody has set priorities, so zero counts mean untested rather than clean."},"verdict":{"type":["string","null"],"description":"pass, fail or empty."},"tick_state":{"type":["integer","null"],"description":"Reviewer tick state."},"note":{"type":["string","null"],"description":"Reviewer note."},"reviewed_at":{"type":["string","null"],"format":"date-time","description":"When it was reviewed."},"reviewed_by":{"type":["string","null"],"description":"Who reviewed it."}}}}},"examples":{"domain_list_legacy":{"summary":"Summary row per domain","value":{"ok":true,"summary":{"total_domains":1102,"scanned_count":1041},"domains":[{"domain":"example.com","iso":"GB","scan_status":"completed","scanned_at":"2026-07-28 04:12:00","vertical":"ecommerce","partner_company":"Example Media Ltd","health":{"priority_counts":{"critical":1,"important":3}},"social_profiles":{"tiktok":"https://tiktok.com/@examplemedia"}}]}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/apis/rightlander/reports.php":{"get":{"operationId":"reports_get","summary":"Reports (2 requests on one address)","description":"This address answers 2 requests, chosen by the parameters you send.\n\n**List the reports your account can run** (no parameters needed). Every report on your Reports board, with the id to run it, the views it offers, the periods it can be narrowed to and the exact columns it will return.\n\n**Run one report and return its rows** (send report). The rows of one report, in the same columns and the same order as the spreadsheet that report downloads - because it is the same report definition, the same column set and the same sort, resolved once.\n\nCost: free within your daily allowance. Permission: read.","tags":["Reports"],"parameters":[{"name":"iso","in":"query","required":false,"description":"Two-letter market code. Affects which risk reports exist, because priorities can be set per market.","schema":{"type":"string","examples":["GB"]}},{"name":"report","in":"query","required":false,"description":"A report id from /v1/reports. Omit it entirely and you get the list instead. Required for: run one report and return its rows.","schema":{"type":"string","examples":["risk_adult_content_present"]}},{"name":"grain","in":"query","required":false,"description":"Which view of the report. Defaults to the first one it offers; a report with only one view ignores this.","schema":{"type":"string","enum":["domain","social","page"]}},{"name":"days","in":"query","required":false,"description":"Period, for the reports that have one - see windows on the list. Anything else falls back to the widest the report offers.","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Rows per page, up to 1000.","schema":{"type":"integer","default":100}},{"name":"cursor","in":"query","required":false,"description":"Pass back next_cursor from the previous response. Null next_cursor means you have seen everything.","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Success. Check ok before reading the rest.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"ok":{"type":["boolean","null"],"description":"True on success, false on failure. Check this before anything else - an empty result and a failure are not the same thing."},"error":{"type":["string","null"],"description":"Human-readable message. Present only on failure."},"error_code":{"type":["string","null"],"description":"Stable code to branch on. Match on this, not on the message text."},"status":{"type":["integer","null"],"description":"HTTP status, repeated in the body for clients that cannot see it."},"request":{"type":"object","properties":{"queried_at":{"type":["string","null"],"format":"date-time","description":"When we answered."},"took_ms":{"type":["integer","null"],"description":"How long it took us."},"key_source":{"type":["string","null"],"description":"header or query - where your key was read from."},"rate_limit":{"type":"object","properties":{"requests_per_day":{"type":["integer","null"],"description":"Your daily allowance."},"used_today":{"type":["integer","null"],"description":"Requests used today."},"remaining":{"type":["integer","null"],"description":"What is left."},"resets_at":{"type":["string","null"],"format":"date-time","description":"When it resets. 00:00 UTC."}}},"credits_charged":{"type":["integer","null"],"description":"Credits taken by this request. Present only when it cost something."}}},"summary":{"type":"object","properties":{"total":{"type":["integer","null"],"description":"How many reports your account can run."}}},"reports":{"type":"array","items":{"type":"object","properties":{"report":{"type":["string","null"],"description":"The id to pass back as ?report=. Stable; safe to store against your own records."},"name":{"type":["string","null"],"description":"What the report is called on your board, including any rename an administrator made."},"description":{"type":["string","null"],"description":"What the report answers, in one sentence."},"category":{"type":["string","null"],"description":"risk, insights or growth - the board column it sits in."},"family":{"type":["string","null"],"description":"The finer grouping used to order cards within a column."},"priority":{"type":["string","null"],"description":"Your own severity for the underlying check, on risk reports. Empty elsewhere - intelligence reports have no severity matrix behind them, and an empty value there is the absence of the concept rather than a level."},"grains":{"type":"array","items":{"type":"array","items":{},"description":"The views this report offers: domain, social, page. Only ones that can actually be run are listed."},"description":"The views this report offers: domain, social, page. Only ones that can actually be run are listed."},"default_grain":{"type":["string","null"],"description":"What you get if you do not send grain."},"windows":{"type":"array","items":{"type":"array","items":{},"description":"Periods in days this report can be narrowed to with ?days=. Empty means the report is about current state and has no period."},"description":"Periods in days this report can be narrowed to with ?days=. Empty means the report is about current state and has no period."},"tags":{"type":"array","items":{"type":"array","items":{},"description":"The hashtags shown on the card, including any your account has added."},"description":"The hashtags shown on the card, including any your account has added."},"columns":{"type":"array","items":{"type":"object","properties":{"key":{"type":["string","null"],"description":"The key each row is keyed by in report_get. Never changes."},"label":{"type":["string","null"],"description":"The heading, as your account has it. Editable, so do not key off it."},"essential":{"type":["boolean","null"],"description":"True where the column is set for the whole account and cannot be switched off. False means it is optional and somebody on your account chose to include it."}}}},"href":{"type":["string","null"],"description":"A ready-made URL that runs this report with its defaults."}}}}}},{"type":"object","properties":{"ok":{"type":["boolean","null"],"description":"True on success, false on failure. Check this before anything else - an empty result and a failure are not the same thing."},"error":{"type":["string","null"],"description":"Human-readable message. Present only on failure."},"error_code":{"type":["string","null"],"description":"Stable code to branch on. Match on this, not on the message text."},"status":{"type":["integer","null"],"description":"HTTP status, repeated in the body for clients that cannot see it."},"request":{"type":"object","properties":{"queried_at":{"type":["string","null"],"format":"date-time","description":"When we answered."},"took_ms":{"type":["integer","null"],"description":"How long it took us."},"key_source":{"type":["string","null"],"description":"header or query - where your key was read from."},"rate_limit":{"type":"object","properties":{"requests_per_day":{"type":["integer","null"],"description":"Your daily allowance."},"used_today":{"type":["integer","null"],"description":"Requests used today."},"remaining":{"type":["integer","null"],"description":"What is left."},"resets_at":{"type":["string","null"],"format":"date-time","description":"When it resets. 00:00 UTC."}}},"credits_charged":{"type":["integer","null"],"description":"Credits taken by this request. Present only when it cost something."}}},"report":{"type":"object","properties":{"id":{"type":["string","null"],"description":"The report id."},"name":{"type":["string","null"],"description":"Its name on your board."},"description":{"type":["string","null"],"description":"What it answers."},"category":{"type":["string","null"],"description":"risk, insights or growth."},"grain":{"type":["string","null"],"description":"The view actually served. A report offering one view serves that view whatever you asked for."},"grains":{"type":"array","items":{"type":"array","items":{},"description":"Every view it offers."},"description":"Every view it offers."},"iso":{"type":["string","null"],"description":"The market applied, or empty for all markets."},"days":{"type":["integer","null"],"description":"The period applied, or null where the report has no period. Not always what you sent - a value the report does not offer falls back to the widest it does."},"windows":{"type":"array","items":{"type":"array","items":{},"description":"The periods available, for building your own control."},"description":"The periods available, for building your own control."},"built_at":{"type":["string","null"],"format":"date","description":"When the index these rows came from was built. Empty on the page reports, which read live tables."}}},"columns":{"type":"array","items":{"type":"object","properties":{"key":{"type":["string","null"],"description":"The key this column appears under on every row."},"label":{"type":["string","null"],"description":"The heading your account uses for it."},"type":{"type":["string","null"],"description":"string, number, date or url - enough to format a cell without inspecting the values."}}}},"paging":{"type":"object","properties":{"total":{"type":["integer","null"],"description":"Rows the report returns in total for this market and period."},"returned":{"type":["integer","null"],"description":"Rows in this response."},"limit":{"type":["integer","null"],"description":"The page size applied."},"cursor":{"type":["integer","null"],"description":"Where this page started."},"next_cursor":{"type":["integer","null"],"description":"Pass back as ?cursor=. Null means you have seen everything."},"stable":{"type":["boolean","null"],"description":"True where the rows come from the overnight index, which does not move during the day, so a walk sees one consistent set. False on the page reports, which read live tables - a row inserted mid-walk can shift the rest by one."}}},"rows":{"type":"array","items":{"type":"object","properties":{"DOMAIN":{"type":["string","null"],"description":"The partner site."},"PARTNER":{"type":["string","null"],"description":"The partner, by name where we hold one and by affiliate id otherwise. Always populated where we know anything at all about who runs the site."},"PARTNER_ID":{"type":["string","null"],"description":"The affiliate id on its own."},"ISO":{"type":["string","null"],"description":"The market this row was found in."},"SCAN_AT":{"type":["string","null"],"format":"date","description":"When the row was last scanned or assessed."},"RISK_CRITICAL":{"type":["number","null"],"description":"Critical findings on the site or profile - all of them, not only the one this report is about."},"RISK_ITEMS":{"type":"array","items":{},"description":"The OTHER findings on the row, as names rather than field ids, with this report's own check removed. An array, not a comma string - a label can contain a comma."},"EVIDENCE":{"type":["string","null"],"description":"What we found, for the check this report is about. Empty is a real answer: some checks match on a signal there is nothing to quote for."},"PROFILE_URL":{"type":["string","null"],"description":"The way back into Rightlander for this row."},"OUTREACH_URL":{"type":["string","null"],"description":"Straight into the outreach page with this partner in focus."},"PLATFORM":{"type":["string","null"],"description":"Social rows: the platform."},"HANDLE":{"type":["string","null"],"description":"Social rows: the account handle."},"LINKED_DOMAIN":{"type":["string","null"],"description":"Social rows: the site the profile belongs to, where we can tie it to one."},"SOV_SHARE":{"type":["number","null"],"description":"Share of voice as a number, not a formatted percentage. Null where we found no pages to divide by, which is not the same as a nil share."},"PAGE_URL":{"type":["string","null"],"description":"Page reports: the URL the row is about."}}}}}}]},"examples":{"reports_list":{"summary":"List the reports your account can run","value":{"ok":true,"summary":{"total":68},"reports":[{"report":"risk_adult_content_present","name":"Adult Content on Partner Sites","description":"Partner sites carrying adult or pornographic content.","category":"risk","grains":["domain","social"],"default_grain":"domain","windows":[],"tags":["domains","social","brandsafety"],"columns":[{"key":"DOMAIN","label":"Site","essential":true},{"key":"PARTNER","label":"Partner","essential":true},{"key":"EVIDENCE","label":"What we found","essential":false}],"href":"/apis/rightlander/v1/reports.php?report=risk_adult_content_present"}]}},"report_get":{"summary":"Run one report and return its rows","value":{"ok":true,"report":{"id":"risk_adult_content_present","name":"Adult Content on Partner Sites","grain":"domain","iso":"GB","days":null,"built_at":"2026-08-29 03:14:00"},"columns":[{"key":"DOMAIN","label":"Site","type":"string"},{"key":"PARTNER","label":"Partner","type":"string"},{"key":"RISK_CRITICAL","label":"Critical risks","type":"number"},{"key":"EVIDENCE","label":"What we found","type":"string"}],"paging":{"total":412,"returned":100,"limit":100,"cursor":0,"next_cursor":100,"stable":true},"rows":[{"DOMAIN":"example.com","PARTNER":"Example Media Ltd","RISK_CRITICAL":3,"RISK_ITEMS":["Impersonates Brand","Thin / Spun Content"],"EVIDENCE":"Adult imagery on two pages reached from the homepage.","PROFILE_URL":"https://aw1.rightlander.com/intelv2/domainProfile.php?domain=example.com&iso=GB"}]}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/apis/rightlander/v1/activity.php":{"get":{"operationId":"activity_feed","summary":"What happened across your partner programme, newest first","description":"The Partner Activity Feed as data: critical risks, brand bidding, offer changes, link anomalies, growth pages, AI influence, partner post mentions and team activity, one row per item, ordered by when it happened.\n\nWhen to use it: Poll it once a day to drive your own alerting or a changelog, and de-duplicate on id. For what is outstanding rather than what changed, use Reports.\n\nCost: 1 credit per day, per account. Permission: read.\n\nFreshness: Mixed, and every row says which. Critical risks, growth pages and link anomalies come from an index rebuilt overnight, so a finding from today's scan appears tomorrow and window.index_built_at dates it. AI influence follows its own scheduled build. Offer changes, partner posts and team activity are live.\n\nNotes: ONE ITEM IS ONE ROW, however many times it was logged in the window: repeats says how often, last_seen_at how recently, and the row is dated by its FIRST sighting. The window is compared by day on purpose - a finding from the overnight index is dated at midnight on its scan day and only becomes readable the next morning, so a strict 24-hour clock would never return it. The price of that is an item from early on the first day appearing in two consecutive daily calls, which is what id is for. Parameters also answer to the Activity Feed page's own names - feeddays, feedmax, feedcat and feediso - so a URL copied from the page works. CHANGED 7 OCT: every item now carries scope and affiliate_id, and networks can pass client_ref - see the networks guide.","tags":["Activity"],"parameters":[{"name":"days","in":"query","required":false,"description":"How far back to look, 1 to 90. 1 is the last 24 hours. Compared by day, like the daily alert email, so the window starts at midnight on the first day it covers. Sets the price.","schema":{"type":"integer","default":1,"examples":[1]}},{"name":"category","in":"query","required":false,"description":"Restrict to these kinds of item. Comma separated for more than one. Omit for all. An unknown value is a 400 that lists the valid ones.","schema":{"type":"string","enum":["risk_domain","risk_social","ppc","offers","anomalies","growth","llm","social_brand","social_comp","social_topic","team"]}},{"name":"iso","in":"query","required":false,"description":"Two-letter market code. Omit or send XX for every market.","schema":{"type":"string","examples":["GB"]}},{"name":"max","in":"query","required":false,"description":"Most items to return, 1 to 500. The newest are kept; summary.capped says whether any were left out.","schema":{"type":"integer","default":100}},{"name":"accounts","in":"query","required":false,"description":"Comma separated account codes. Omit for the account your key belongs to. Each account read is charged separately, and a code your key is not authorised for is refused with 403.","schema":{"type":"string"}},{"name":"client_ref","in":"query","required":false,"description":"Networks: your ID for one client. Returns that client's feed - items from its own account (scope client) once it has signed up, and from your scans (scope network) - limited to the domains you sent for it. Cannot be combined with accounts; team items are left out. Charged as one account.","schema":{"type":"string"}},{"name":"uid","in":"query","required":false,"description":"Networks that personalise per user: one user of client_ref. Returns that user's feed - limited to the partner domains you sent for the user (the client's list until you send one), and the user's own items once it has personalised. client.personalise_url is signed for that user. Ignored, with a note, if your feeds are personalised per client.","schema":{"type":"string"}},{"name":"render","in":"query","required":false,"description":"html adds ready-made HTML in your feed style: each item's html, plus render.html for the whole page. The stylesheet is downloaded once from your guided setup, not sent here. Set the style in your guided setup or with feed_style on POST /v1/network. Omit for data only.","schema":{"type":"string","enum":["html"]}}],"responses":{"200":{"description":"Success. Check ok before reading the rest.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":["boolean","null"],"description":"True on success, false on failure. Check this before anything else - an empty result and a failure are not the same thing."},"error":{"type":["string","null"],"description":"Human-readable message. Present only on failure."},"error_code":{"type":["string","null"],"description":"Stable code to branch on. Match on this, not on the message text."},"status":{"type":["integer","null"],"description":"HTTP status, repeated in the body for clients that cannot see it."},"request":{"type":"object","properties":{"queried_at":{"type":["string","null"],"format":"date-time","description":"When we answered."},"took_ms":{"type":["integer","null"],"description":"How long it took us."},"key_source":{"type":["string","null"],"description":"header or query - where your key was read from."},"rate_limit":{"type":"object","properties":{"requests_per_day":{"type":["integer","null"],"description":"Your daily allowance."},"used_today":{"type":["integer","null"],"description":"Requests used today."},"remaining":{"type":["integer","null"],"description":"What is left."},"resets_at":{"type":["string","null"],"format":"date-time","description":"When it resets. 00:00 UTC."}}},"credits_charged":{"type":["integer","null"],"description":"Credits taken by this request. Present only when it cost something."},"endpoint":{"type":["string","null"],"description":"Always activity."},"accounts":{"type":"array","items":{"type":"array","items":{},"description":"The account codes read. Your own unless you named others your key is authorised for."},"description":"The account codes read. Your own unless you named others your key is authorised for."},"days":{"type":["integer","null"],"description":"The window in days, after any adjustment."},"max":{"type":["integer","null"],"description":"The item limit applied."},"categories":{"type":"array","items":{"type":"array","items":{},"description":"The categories read, or all."},"description":"The categories read, or all."},"iso":{"type":["string","null"],"description":"The market applied, or XX for every market."},"client_ref":{"type":["string","null"],"description":"The client_ref sent, or null."},"adjusted":{"type":"array","items":{"type":"array","items":{},"description":"Anything we changed about your request and why - a days value above 90 is reduced, for example. Empty when nothing was."},"description":"Anything we changed about your request and why - a days value above 90 is reduced, for example. Empty when nothing was."}}},"client":{"type":"object","properties":{"client_ref":{"type":["string","null"],"description":"Your ID for the client."},"status":{"type":["string","null"],"description":"pending (not signed up), active or cancelled."},"personalised":{"type":["boolean","null"],"description":"True when items from the client's own account are included. False means network items only."},"account":{"type":["string","null"],"description":"The client's Rightlander account code when personalised. Null otherwise."},"partner_domains":{"type":["integer","null"],"description":"Active domains on the list you sent for this client - the list every item was limited to."},"personalise_url":{"type":["string","null"],"description":"The \"Personalise my feed\" link for this client, signed by us, valid for 7 days. Show it as a button marked data-rl-personalise, so networkModal.js opens it in a modal. Optional prefills may be added to the end, URL-encoded and unsigned: email (shown read-only; free email services other than gmail.com refused unless signed), name, company, brand, domain. Null once the client has a personalised feed."},"settings_url":{"type":["string","null"],"description":"The \"Edit my feed settings\" link for a personalised client, signed by us, valid for 7 days. Show it as a button marked data-rl-personalise: it opens the client's settings in the modal, where it can change its products, what its feed shows and its plan, or ask to cancel. Null until the client is personalised."}}},"window":{"type":"object","properties":{"hours":{"type":["integer","null"],"description":"days x 24."},"from":{"type":["string","null"],"format":"date","description":"The first day included. The window is compared by day, so it starts at midnight on this date."},"to":{"type":["string","null"],"format":"date-time","description":"When the request was answered."},"grain":{"type":["string","null"],"description":"Always day - stated rather than left to be discovered."},"index_built_at":{"type":["string","null"],"format":"date-time","description":"When the overnight index behind the overnight categories was last built. Null if it has never been built."},"index_ok":{"type":["boolean","null"],"description":"False when that index could not be read, so the overnight categories may be missing rather than empty."}}},"credits":{"type":"object","properties":{"charged":{"type":["integer","null"],"description":"Credits taken. 0 when the window was empty, and always 0 on a trial."},"price":{"type":["integer","null"],"description":"What the request costs when it returns something: days x accounts x the unit price."},"basis":{"type":["string","null"],"description":"The unit price in words."},"trial":{"type":["boolean","null"],"description":"True on a trial account, which is metered by its request allowance instead of by credits."},"free_when_empty":{"type":["boolean","null"],"description":"Always true: an empty window is never charged."}}},"summary":{"type":"object","properties":{"returned":{"type":["integer","null"],"description":"Items in events."},"total_in_window":{"type":["integer","null"],"description":"Items found in the window before max was applied."},"capped":{"type":["boolean","null"],"description":"True when max left items out. The newest are the ones kept."},"folded_repeats":{"type":["integer","null"],"description":"Repeat sightings folded into existing items rather than listed again."},"by_family":{"type":"object","properties":{"risk":{"type":["integer","null"],"description":"Returned items in the risk family."},"opportunity":{"type":["integer","null"],"description":"Returned items in the opportunity family."},"team":{"type":["integer","null"],"description":"Returned items describing what your team did."}}},"by_scope":{"type":"object","properties":{"network":{"type":["integer","null"],"description":"Returned items from your own account's scans."},"client":{"type":["integer","null"],"description":"Returned items from the client's own account, under client_ref."}}},"by_category":{"type":"object","description":"Returned items per category key. Every category is present, at 0 when it had nothing."},"not_on_client_list":{"type":["integer","null"],"description":"Under client_ref, items left out because their domain is not on the client's list. Null on an ordinary call."}}},"by_day":{"type":"array","items":{"type":"object","properties":{"day":{"type":["string","null"],"format":"date","description":"The day."},"total":{"type":["integer","null"],"description":"Returned items dated that day."},"categories":{"type":"object","description":"Those items per category key. Empty on a quiet day."}}}},"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":["string","null"],"description":"Stable identity for the item: the same thing seen again tomorrow has the same id. De-duplicate on this."},"revision":{"type":["string","null"],"description":"Changes when the findings behind a risk item change, so the same site with a different problem can be told apart from the same problem still there. Null on items that carry no findings."},"account":{"type":["string","null"],"description":"The account the item belongs to."},"scope":{"type":["string","null"],"description":"network - from your own account's scans. client - from the client's own account, under client_ref. example - networks only: Relevant content, found by the generic product profiles for your verticals, not for any one client."},"scope_label":{"type":["string","null"],"description":"Relevant content on example items. Null otherwise."},"example_note":{"type":["string","null"],"description":"On example items only: the note to show beside the item. Null otherwise."},"brands_hidden":{"type":["boolean","null"],"description":"Networks only: true on a Brand bidding indicator in the network's own items - seen bidding on brand searches, with the brands, the ad text and its links left out for privacy. Absent otherwise."},"category":{"type":["string","null"],"description":"The category key - see categories."},"category_label":{"type":["string","null"],"description":"Its name as the Activity Feed page shows it."},"category_colour":{"type":["string","null"],"description":"The category's colour as a hex value, such as #d93025 for a critical risk on a site - the colour the Activity Feed page and our emails use, so you can match them."},"family":{"type":["string","null"],"description":"risk, opportunity or team."},"happened_at":{"type":["string","null"],"format":"date-time","description":"When it happened - the FIRST sighting in the window. A scan finding carries its scan date at midnight; a post carries its publish time."},"day":{"type":["string","null"],"format":"date","description":"The date part of happened_at."},"last_seen_at":{"type":["string","null"],"format":"date-time","description":"The latest sighting, when there was more than one. Null otherwise."},"repeats":{"type":["integer","null"],"description":"How many times the item was logged in the window."},"iso":{"type":["string","null"],"description":"The market it was found in. Null where the source has no market."},"markets":{"type":"array","items":{"type":"array","items":{},"description":"Every market it was found in, when there were several."},"description":"Every market it was found in, when there were several."},"title":{"type":["string","null"],"description":"What happened, in words."},"detail":{"type":["string","null"],"description":"The evidence in one line - the fields found, the phrase matched, the page."},"evidence":{"type":"array","items":{"type":"object","properties":{"text":{"type":["string","null"],"description":"One line of evidence. Social items carry a line per post."},"url":{"type":["string","null"],"description":"Where to see that evidence. Null when there is nowhere to send you."},"external":{"type":["boolean","null"],"description":"True when the link leaves Rightlander - the partner's own page or post."}}}},"items":{"type":["integer","null"],"description":"How many things the item stands for, where that is more than one - cited pages on an AI influence item, ID combinations on an anomaly. Null otherwise."},"asset":{"type":"object","properties":{"kind":{"type":["string","null"],"description":"domain, social or account."},"name":{"type":["string","null"],"description":"What it happened to - a domain, or platform / @handle."},"handle":{"type":["string","null"],"description":"The social handle, without the at sign. Null on other items."},"domain":{"type":["string","null"],"description":"The partner's domain the item resolves to. On a social item, the site the account belongs to. Null when there is none."},"url":{"type":["string","null"],"description":"The asset's own home - the site, or the profile. Null when it cannot be trusted."}}},"partner":{"type":"object","properties":{"name":{"type":["string","null"],"description":"The partner, where we hold one."},"affid":{"type":["string","null"],"description":"Their affiliate id, where we hold one."}}},"affiliate_id":{"type":["string","null"],"description":"The affiliate ID you sent with the domain on POST /v1/partner-domains, else partner.affid. The field to join an item to your own affiliate records on. Null when neither is held."},"audience":{"type":"object","properties":{"count":{"type":["integer","null"],"description":"How many people the asset reaches. The whole audience object is null when unknown."},"unit":{"type":["string","null"],"description":"What count measures: visits for a site, followers for an account. Never read the number without it."}}},"links":{"type":"object","properties":{"rightlander":{"type":["string","null"],"description":"The Rightlander screen to act on the item. Null in a feed for a client or user (client_ref): use open there."},"share":{"type":["string","null"],"description":"A link to hand to a colleague - the partner's Domain Profile where the item has a domain. Null in a feed for a client or user (client_ref): use open there."},"external":{"type":["string","null"],"description":"The item itself off-platform - the post or the cited page. Null when there is none."}}},"by":{"type":["string","null"],"description":"On team items, the name of the colleague who did it. Null on everything else."},"freshness":{"type":["string","null"],"description":"overnight, scheduled or live - how current this category's data is."},"link":{"type":["string","null"],"description":"Networks only: a read-only page for this one item that your client can open without a login, in your branding. Works for 30 days; the same item keeps the same link. Null for other accounts. Open it in a new window."},"open":{"type":["string","null"],"description":"Networks, in a feed for a client or user that has personalised: on the client's own items (scope client), a link that opens the Rightlander page for the item, signed in as the client, with no Rightlander menus, read only. Works for 7 days; the same item keeps the same link. Open it in a new window (a top-level window, not a frame). Null on other items: use link. Brand mention, competitor mention and product relevance items open the page or post itself instead: links.external."},"personalise_url":{"type":["string","null"],"description":"Networks, in a feed for a client or user that has not personalised: a \"Personalise my feed\" link signed for them, on brand, competitor, growth and product relevance items, when Rightlander has switched this on for you (every item, or every nth). Absent otherwise."},"html":{"type":["string","null"],"description":"The item as a ready-made block of HTML in your feed style."}}}},"sources":{"type":"array","items":{"type":"object","properties":{"category":{"type":["string","null"],"description":"The category key."},"label":{"type":["string","null"],"description":"Its name."},"status":{"type":["string","null"],"description":"ok, partial (some accounts read, some did not), skipped or unavailable."},"items":{"type":["integer","null"],"description":"Items the source found, before repeats were folded and max applied."},"freshness":{"type":["string","null"],"description":"overnight, scheduled or live."},"note":{"type":["string","null"],"description":"Why a source is partial or unavailable. Null when it read normally."}}}},"categories":{"type":"array","items":{"type":"object","properties":{"category":{"type":["string","null"],"description":"The key to pass in ?category=."},"label":{"type":["string","null"],"description":"Its name."},"colour":{"type":["string","null"],"description":"Its colour as a hex value, as the Activity Feed page shows it."},"family":{"type":["string","null"],"description":"risk, opportunity or team."},"description":{"type":["string","null"],"description":"What an item in it means, in one sentence."},"freshness":{"type":["string","null"],"description":"overnight, scheduled or live."}}}},"render":{"type":"object","properties":{"wrapper":{"type":["string","null"],"description":"The classes for the div you put the saved items in, such as rlf-feed rlf-cards rlf-light rlf-comfortable. The stylesheet itself is downloaded once from your guided setup."},"html":{"type":["string","null"],"description":"Every item returned, in a wrapper, ready to drop into your page."},"style":{"type":"object","description":"The feed style used - the same object as feed_style on GET /v1/network."}}},"notes":{"type":"array","items":{"type":"array","items":{},"description":"Short sentences. Includes a note when nothing was charged because the window was empty."},"description":"Short sentences. Includes a note when nothing was charged because the window was empty."}}},"examples":{"activity_feed":{"summary":"What happened across your partner programme, newest first","value":{"ok":true,"request":{"endpoint":"activity","accounts":["ABC123"],"days":1,"max":100,"categories":["all"],"iso":"XX","client_ref":null,"adjusted":[]},"client":null,"window":{"hours":24,"from":"2026-09-14","to":"2026-09-15T09:12:04+01:00","grain":"day","index_built_at":"2026-09-15 03:10:00","index_ok":true},"credits":{"charged":1,"price":1,"basis":"1 credit per day, per account","trial":false,"free_when_empty":true},"summary":{"returned":1,"total_in_window":1,"capped":false,"folded_repeats":3,"by_family":{"risk":1,"opportunity":0,"team":0},"by_scope":{"network":1,"client":0},"by_category":{"offers":1},"not_on_client_list":null},"by_day":[{"day":"2026-09-15","total":1,"categories":{"offers":1}},{"day":"2026-09-14","total":0,"categories":[]}],"events":[{"id":"3f1c0a9e5b7d2c4e6f8a0b1c2d3e4f5a6b7c8d9e","revision":null,"account":"ABC123","scope":"network","category":"offers","category_label":"Offer change","family":"risk","happened_at":"2026-09-15T07:40:00+01:00","day":"2026-09-15","last_seen_at":"2026-09-15T08:55:00+01:00","repeats":4,"iso":"GB","markets":["GB"],"title":"Offer changed","detail":"Welcome bonus now 50 free spins (was 20)","evidence":[{"text":"Welcome bonus now 50 free spins (was 20)","url":"https://www.example.com/offers/","external":true}],"items":null,"asset":{"kind":"domain","name":"example.com","handle":null,"domain":"example.com","url":"https://example.com"},"partner":{"name":"Example Media Ltd","affid":"10442"},"affiliate_id":"10442","audience":{"count":180000,"unit":"visits"},"links":{"rightlander":"https://aw1.rightlander.com/intelv2/workbenchQualityOfferMonitoringIndex.php","share":"https://aw1.rightlander.com/intelv2/domainProfile.php?domain=example.com&iso=GB","external":"https://www.example.com/offers/"},"by":null,"freshness":"live"}],"sources":[{"category":"offers","label":"Offer change","status":"ok","items":1,"freshness":"live","note":null},{"category":"ppc","label":"Brand bidding","status":"ok","items":0,"freshness":"live","note":null}],"categories":[{"category":"offers","label":"Offer change","family":"risk","description":"An offer a partner is publishing about you has changed or appeared.","freshness":"live"}],"notes":["Items are newest first. One item is one row however many times it was logged in the window; repeats and last_seen_at say how often and how recently."]}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-rightlander-credits":"1 credit per day, per account"}},"/apis/rightlander/v1/compliance.php":{"get":{"operationId":"compliance_get","summary":"Compliance (3 requests on one address)","description":"This address answers 3 requests, chosen by the parameters you send.\n\n**Your compliance markets, months and reports** (send view=markets). The markets you have compliance reports in, the month tables we hold for each and which source they come from. It also lists your reports with their ids and priorities.\n\n**The items in the current scan cycle, with their actions** (send period=cycle, iso). The items the Compliance Workbench shows for one market, from this month and last month together, with the action taken on each, who took it and when.\n\n**The items reported in one month, with their latest action** (send iso, month). The compliance items reported in one market in one month, with the latest action on each. Reports you have since switched off are included.\n\nCost: free within your daily allowance. Permission: read.","tags":["Compliance"],"parameters":[{"name":"view","in":"query","required":false,"description":"Set this to choose the request: view=markets for your compliance markets, months and reports.","schema":{"type":"string","enum":["markets"]}},{"name":"period","in":"query","required":false,"description":"Set this to choose the request: period=cycle for the items in the current scan cycle, with their actions.","schema":{"type":"string","enum":["cycle"]}},{"name":"iso","in":"query","required":false,"description":"Two-letter market, or XX for worldwide. Required for: the items in the current scan cycle, with their actions; the items reported in one month, with their latest action.","schema":{"type":"string","examples":["GB"]}},{"name":"source","in":"query","required":false,"description":"discovery is our scanning across the market as a whole and requested is the scanning set up for your account alone. Omit for both.","schema":{"type":"string","enum":["discovery","requested"]}},{"name":"status","in":"query","required":false,"description":"Which items. resolved is any action. Omit for all of them.","schema":{"type":"string","enum":["all","unresolved","resolved","flagged","non_issue","ignored"],"default":"all"}},{"name":"report_id","in":"query","required":false,"description":"One of your reports, from GET /v1/compliance/markets.","schema":{"type":"integer"}},{"name":"report_priority","in":"query","required":false,"description":"Reports of one priority: 1 high, 2 medium, 3 low.","schema":{"type":"integer","enum":["1","2","3"]}},{"name":"domain","in":"query","required":false,"description":"One partner domain.","schema":{"type":"string"}},{"name":"affid","in":"query","required":false,"description":"One affiliate ID. The prefixed forms the scanner records (btag=, affid= and so on) are matched too.","schema":{"type":"string"}},{"name":"brand","in":"query","required":false,"description":"One or more of your brand names, comma separated.","schema":{"type":"string"}},{"name":"state","in":"query","required":false,"description":"With iso=XX only: a two-letter state or country code the item was scanned in.","schema":{"type":"string"}},{"name":"since","in":"query","required":false,"description":"YYYY-MM-DD. Items reported, scanned or actioned on or after this date.","schema":{"type":"string"}},{"name":"detail","in":"query","required":false,"description":"simple leaves out findings and returns finding_count and the short issue text in result.","schema":{"type":"string","enum":["full","simple"],"default":"full"}},{"name":"limit","in":"query","required":false,"description":"Items per page, up to 500.","schema":{"type":"integer","default":100}},{"name":"cursor","in":"query","required":false,"description":"Pass back next_cursor from the previous response. Null next_cursor means you have seen everything.","schema":{"type":"string"}},{"name":"month","in":"query","required":false,"description":"YYYYMM or YYYY-MM. GET /v1/compliance/markets lists the months that exist. Required for: the items reported in one month, with their latest action.","schema":{"type":"string","examples":["202610"]}}],"responses":{"200":{"description":"Success. Check ok before reading the rest.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"ok":{"type":["boolean","null"],"description":"True on success, false on failure. Check this before anything else - an empty result and a failure are not the same thing."},"error":{"type":["string","null"],"description":"Human-readable message. Present only on failure."},"error_code":{"type":["string","null"],"description":"Stable code to branch on. Match on this, not on the message text."},"status":{"type":["integer","null"],"description":"HTTP status, repeated in the body for clients that cannot see it."},"request":{"type":"object","properties":{"queried_at":{"type":["string","null"],"format":"date-time","description":"When we answered."},"took_ms":{"type":["integer","null"],"description":"How long it took us."},"key_source":{"type":["string","null"],"description":"header or query - where your key was read from."},"rate_limit":{"type":"object","properties":{"requests_per_day":{"type":["integer","null"],"description":"Your daily allowance."},"used_today":{"type":["integer","null"],"description":"Requests used today."},"remaining":{"type":["integer","null"],"description":"What is left."},"resets_at":{"type":["string","null"],"format":"date-time","description":"When it resets. 00:00 UTC."}}},"credits_charged":{"type":["integer","null"],"description":"Credits taken by this request. Present only when it cost something."},"endpoint":{"type":["string","null"],"description":"Always compliance_markets."},"compliance_limit":{"type":"object","properties":{"calls_per_day":{"type":["integer","null"],"description":"Compliance calls your account is allowed a day, shared by the three compliance endpoints."},"used_today":{"type":["integer","null"],"description":"Compliance calls made today, including this one."},"remaining":{"type":["integer","null"],"description":"What is left today."},"resets_at":{"type":["string","null"],"format":"date-time","description":"When it resets. 00:00 UTC."}}}}},"account":{"type":["string","null"],"description":"Your account code."},"scan_cycle":{"type":"object","properties":{"months":{"type":"array","items":{"type":"array","items":{},"description":"The two months of the current scan cycle, newest first, as YYYY-MM."},"description":"The two months of the current scan cycle, newest first, as YYYY-MM."},"from":{"type":["string","null"],"format":"date","description":"The first day of the cycle."},"rolls_over_at":{"type":["string","null"],"format":"date-time","description":"When the cycle moves on and the older month leaves it."}}},"sources":{"type":"array","items":{"type":"object","properties":{"source":{"type":["string","null"],"description":"discovery or requested."},"status":{"type":["string","null"],"description":"ok, or unavailable when that source could not be read just now."}}}},"markets":{"type":"array","items":{"type":"object","properties":{"iso":{"type":["string","null"],"description":"Two-letter market, or XX for worldwide."},"name":{"type":["string","null"],"description":"The market name."},"sources":{"type":"array","items":{"type":"object","properties":{"source":{"type":["string","null"],"description":"discovery or requested."},"status":{"type":["string","null"],"description":"Always ok here: a source that could not be read is reported in sources instead."},"months":{"type":"array","items":{"type":"array","items":{},"description":"Month tables that exist, newest first, as YYYY-MM, up to 24 months back."},"description":"Month tables that exist, newest first, as YYYY-MM, up to 24 months back."},"reports":{"type":["integer","null"],"description":"How many of your reports this source holds for the market."}}}}}}},"reports":{"type":"array","items":{"type":"object","properties":{"report_id":{"type":["integer","null"],"description":"The report id."},"source":{"type":["string","null"],"description":"discovery or requested. Ids are only unique within a source."},"iso":{"type":["string","null"],"description":"The market the report runs in."},"title":{"type":["string","null"],"description":"The report title."},"priority":{"type":["integer","null"],"description":"1 high, 2 medium, 3 low."},"priority_label":{"type":["string","null"],"description":"High, Medium or Low."},"active":{"type":["boolean","null"],"description":"False for a report that has been switched off. Its items still appear in a month read."}}}},"notes":{"type":"array","items":{"type":"array","items":{},"description":"Notes about this response."},"description":"Notes about this response."}}},{"type":"object","properties":{"ok":{"type":["boolean","null"],"description":"True on success, false on failure. Check this before anything else - an empty result and a failure are not the same thing."},"error":{"type":["string","null"],"description":"Human-readable message. Present only on failure."},"error_code":{"type":["string","null"],"description":"Stable code to branch on. Match on this, not on the message text."},"status":{"type":["integer","null"],"description":"HTTP status, repeated in the body for clients that cannot see it."},"request":{"type":"object","properties":{"queried_at":{"type":["string","null"],"format":"date-time","description":"When we answered."},"took_ms":{"type":["integer","null"],"description":"How long it took us."},"key_source":{"type":["string","null"],"description":"header or query - where your key was read from."},"rate_limit":{"type":"object","properties":{"requests_per_day":{"type":["integer","null"],"description":"Your daily allowance."},"used_today":{"type":["integer","null"],"description":"Requests used today."},"remaining":{"type":["integer","null"],"description":"What is left."},"resets_at":{"type":["string","null"],"format":"date-time","description":"When it resets. 00:00 UTC."}}},"credits_charged":{"type":["integer","null"],"description":"Credits taken by this request. Present only when it cost something."},"endpoint":{"type":["string","null"],"description":"Always compliance_items."},"iso":{"type":["string","null"],"description":"The market read."},"period":{"type":["string","null"],"description":"cycle, or the month read as YYYY-MM."},"source":{"type":["string","null"],"description":"discovery, requested or all."},"status":{"type":["string","null"],"description":"The status filter applied."},"detail":{"type":["string","null"],"description":"full or simple."},"limit":{"type":["integer","null"],"description":"Items per page."},"filters":{"type":"object","description":"The other filters applied, by name."},"adjusted":{"type":"array","items":{"type":"array","items":{},"description":"Anything we changed about the request, such as a limit brought down to the maximum."},"description":"Anything we changed about the request, such as a limit brought down to the maximum."},"compliance_limit":{"type":"object","properties":{"calls_per_day":{"type":["integer","null"],"description":"Compliance calls your account is allowed a day, shared by the three compliance endpoints."},"used_today":{"type":["integer","null"],"description":"Compliance calls made today, including this one."},"remaining":{"type":["integer","null"],"description":"What is left today."},"resets_at":{"type":["string","null"],"format":"date-time","description":"When it resets. 00:00 UTC."}}}}},"period":{"type":"object","properties":{"type":{"type":["string","null"],"description":"cycle or month."},"tables":{"type":"array","items":{"type":"array","items":{},"description":"Cycle only. The two month tables, newest first, such as GB202611."},"description":"Cycle only. The two month tables, newest first, such as GB202611."},"from":{"type":["string","null"],"format":"date","description":"Cycle only. The first day of the cycle."},"to":{"type":["string","null"],"format":"date","description":"Cycle only. The last day of the current month."},"rolls_over_at":{"type":["string","null"],"format":"date-time","description":"Cycle only. When the cycle moves on."},"table":{"type":["string","null"],"description":"Month only. The table read, such as GB202610."},"month":{"type":["string","null"],"description":"Month only. YYYY-MM."},"in_current_cycle":{"type":["boolean","null"],"description":"Month only. True while the month is in the scan cycle and its actions can still change."}}},"sources":{"type":"array","items":{"type":"object","properties":{"source":{"type":["string","null"],"description":"discovery or requested."},"status":{"type":["string","null"],"description":"ok, partial or unavailable."},"items":{"type":["integer","null"],"description":"Items from this source on this page."},"reports":{"type":["integer","null"],"description":"Your reports this source holds for the market and period."},"note":{"type":["string","null"],"description":"Present when status is not ok."}}}},"summary":{"type":"object","properties":{"items":{"type":["integer","null"],"description":"Items across all pages."},"unresolved":{"type":["integer","null"],"description":"Items with no action yet."},"flagged":{"type":["integer","null"],"description":"Items flagged for action."},"non_issue":{"type":["integer","null"],"description":"Items marked as a non-issue."},"ignored":{"type":["integer","null"],"description":"Items ignored."},"by_report_priority":{"type":"object","description":"The same four counts for high, medium and low priority reports."},"domains":{"type":["integer","null"],"description":"Distinct partner domains among the items."}}},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":["string","null"],"description":"The item id, such as discovery:GB202611-4821. Also what the screenshot link takes."},"issue_key":{"type":["string","null"],"description":"The same for the same issue on the same page in any month, so you can follow it when id changes."},"source":{"type":["string","null"],"description":"discovery (our scanning across the market) or requested (scanning set up for your account)."},"table":{"type":["string","null"],"description":"The month table the item is from, such as GB202611."},"row_id":{"type":["integer","null"],"description":"The row within that table."},"also_reported_in":{"type":"array","items":{"type":"array","items":{},"description":"Cycle only. The same issue in the older month of the cycle, by item id."},"description":"Cycle only. The same issue in the older month of the cycle, by item id."},"iso":{"type":["string","null"],"description":"The market."},"state_iso":{"type":["string","null"],"description":"Where it differs from iso, the state or country the item was scanned in, such as NJ. Null otherwise."},"status":{"type":["string","null"],"description":"unresolved, flagged, non_issue or ignored."},"report":{"type":"object","properties":{"id":{"type":["integer","null"],"description":"The report that found it."},"title":{"type":["string","null"],"description":"Its title."},"priority":{"type":["integer","null"],"description":"1 high, 2 medium, 3 low."},"priority_label":{"type":["string","null"],"description":"High, Medium or Low."}}},"page":{"type":"object","properties":{"url":{"type":["string","null"],"description":"The page. For a social post, the post itself."},"domain":{"type":["string","null"],"description":"The partner domain."},"title":{"type":["string","null"],"description":"The page title, where we recorded one."},"type":{"type":["string","null"],"description":"web, social, telegram or email."},"page_scan":{"type":["boolean","null"],"description":"True when the page came from a set of pages rather than a scan of the whole site."},"site_id":{"type":["integer","null"],"description":"Our id for the scanned site."},"brand_link_page":{"type":["string","null"],"description":"For reports that look for your brand anywhere on the site, the page where your link was found. Null otherwise."}}},"partner":{"type":"object","properties":{"affiliate_id":{"type":["string","null"],"description":"The affiliate ID found with the item, without the parameter name. Null when none was found."},"company":{"type":["string","null"],"description":"The partner company for that affiliate ID, where you have recorded one. Null otherwise."}}},"brand_affected":{"type":["string","null"],"description":"Your brand the issue concerns."},"brands_on_page":{"type":"array","items":{"type":"array","items":{},"description":"Brands found on the page."},"description":"Brands found on the page."},"scanned_at":{"type":["string","null"],"format":"date","description":"When the page was scanned."},"reported_at":{"type":["string","null"],"format":"date","description":"When the issue was first reported."},"first_scan":{"type":["string","null"],"format":"date","description":"When we first scanned the site."},"action":{"type":"object","properties":{"type":{"type":["string","null"],"description":"flagged, non_issue or ignored."},"scope":{"type":["string","null"],"description":"site (the whole site) or page (this page only). Null when the action does not say."},"temporary":{"type":["boolean","null"],"description":"True for a temporary ignore."},"label":{"type":["string","null"],"description":"The action in plain English, as the workbench describes it."},"origin":{"type":["string","null"],"description":"this_cycle, or carried_forward when the action was made in an earlier month and still applies."},"carried_from":{"type":"object","description":"For carried_forward: table, month (YYYY-MM) and row_id of the item it was made on. Null otherwise."},"actioned_at":{"type":["string","null"],"format":"date-time","description":"When the action was taken."},"actioned_at_estimated":{"type":["boolean","null"],"description":"True when we could not find the exact time and actioned_at is the report date or the start of the month instead."},"actioned_by":{"type":["string","null"],"description":"The name of the person who took it. Null when we cannot tell."}},"description":"Null when the item is unresolved."},"case_id":{"type":["string","null"],"description":"The open case management case holding the item. Null when there is none."},"findings":{"type":"array","items":{"type":"object","properties":{"text":{"type":["string","null"],"description":"The sentence as found on the page."},"translated_text":{"type":["string","null"],"description":"An English translation, where the page is in another language."},"full_sentence":{"type":["string","null"],"description":"The longer passage around it, where we recorded one."},"matched_phrase":{"type":["string","null"],"description":"The phrase the report looks for."},"exact_phrase":{"type":["string","null"],"description":"The wording actually found."},"relevance":{"type":["string","null"],"description":"How close your brand is to the sentence: Very High, High, Medium or Low."},"relevance_reason":{"type":["string","null"],"description":"Why, in plain English."},"brand_affected":{"type":["string","null"],"description":"Your brand this sentence concerns."},"brand_before":{"type":["string","null"],"description":"The nearest brand before the sentence."},"brand_after":{"type":["string","null"],"description":"The nearest brand after the sentence."},"item_hash":{"type":["string","null"],"description":"Identifies the same sentence and brand wherever it appears."},"verify_url":{"type":["string","null"],"description":"The page with the sentence highlighted, in browsers that support it."},"ai_analysis":{"description":"Our AI reading of the sentence, where the report has it switched on and we hold one. Null otherwise."}}},"description":"detail=full. The sentences on the page the workbench shows for this item."},"finding_count":{"type":["integer","null"],"description":"detail=simple. How many sentences the item has."},"result":{"type":["string","null"],"description":"detail=simple. The short issue text stored with the item."},"screenshot_url":{"type":["string","null"],"description":"Opens our screenshot of the page after you sign in to Rightlander."}}}},"paging":{"type":"object","properties":{"limit":{"type":["integer","null"],"description":"Items per page."},"returned":{"type":["integer","null"],"description":"Items on this page."},"next_cursor":{"type":["string","null"],"description":"Pass it back as cursor for the next page. Null when you have everything."},"complete":{"type":["boolean","null"],"description":"True on the last page."}}},"notes":{"type":"array","items":{"type":"array","items":{},"description":"Notes about this response."},"description":"Notes about this response."}}}]},"examples":{"compliance_markets":{"summary":"Your compliance markets, months and reports","value":{"ok":true,"request":{"endpoint":"compliance_markets","compliance_limit":{"calls_per_day":250,"used_today":3,"remaining":247,"resets_at":"2026-11-13T00:00:00+00:00"}},"account":"ABC123","scan_cycle":{"months":["2026-11","2026-10"],"from":"2026-10-01","rolls_over_at":"2026-12-01T00:00:00+00:00"},"sources":[{"source":"discovery","status":"ok"},{"source":"requested","status":"ok"}],"markets":[{"iso":"GB","name":"United Kingdom","sources":[{"source":"discovery","status":"ok","months":["2026-11","2026-10","2026-09"],"reports":3},{"source":"requested","status":"ok","months":["2026-11","2026-10"],"reports":1}]}],"reports":[{"report_id":10004417,"source":"discovery","iso":"GB","title":"Significant Terms","priority":1,"priority_label":"High","active":true},{"report_id":20001276,"source":"requested","iso":"GB","title":"Batch Workbench - Significant Terms","priority":1,"priority_label":"High","active":true}],"notes":["months lists the month tables that exist for each market, newest first, up to 24 months back."]}},"compliance_cycle":{"summary":"The items in the current scan cycle, with their actions","value":{"ok":true,"request":{"endpoint":"compliance_items","iso":"GB","period":"cycle","source":"all","status":"all","detail":"full","limit":1,"filters":[],"adjusted":[],"compliance_limit":{"calls_per_day":250,"used_today":4,"remaining":246,"resets_at":"2026-11-13T00:00:00+00:00"}},"period":{"type":"cycle","tables":["GB202611","GB202610"],"from":"2026-10-01","to":"2026-11-30","rolls_over_at":"2026-12-01T00:00:00+00:00"},"sources":[{"source":"discovery","status":"ok","items":1,"reports":3},{"source":"requested","status":"ok","items":0,"reports":1}],"summary":{"items":353,"unresolved":201,"flagged":88,"non_issue":51,"ignored":13,"by_report_priority":{"high":{"unresolved":120,"flagged":61,"non_issue":30,"ignored":4},"medium":{"unresolved":66,"flagged":22,"non_issue":17,"ignored":7},"low":{"unresolved":15,"flagged":5,"non_issue":4,"ignored":2}},"domains":74},"items":[{"id":"discovery:GB202611-4821","issue_key":"6c1f0e9a2b7d4c55","source":"discovery","table":"GB202611","row_id":4821,"also_reported_in":["discovery:GB202610-3302"],"iso":"GB","state_iso":null,"status":"flagged","report":{"id":10004417,"title":"Significant Terms","priority":1,"priority_label":"High"},"page":{"url":"https://www.example.com/bonuses/examplebet/","domain":"example.com","title":"ExampleBet Bonus Review","type":"web","page_scan":false,"site_id":100234,"brand_link_page":null},"partner":{"affiliate_id":"a_12345b_678","company":"Example Media Ltd"},"brand_affected":"ExampleBet","brands_on_page":["ExampleBet","OtherBet"],"scanned_at":"2026-11-04","reported_at":"2026-11-04","first_scan":"2024-03-11","action":{"type":"flagged","scope":"site","temporary":false,"label":"Issue flagged for action sitewide","origin":"this_cycle","carried_from":null,"actioned_at":"2026-11-06T14:22:10+00:00","actioned_at_estimated":false,"actioned_by":"Sarah Jones"},"case_id":null,"findings":[{"text":"Claim your ExampleBet welcome bonus with no wagering on winnings.","translated_text":null,"full_sentence":"Claim your ExampleBet welcome bonus with no wagering on winnings.","matched_phrase":"no wagering","exact_phrase":"no wagering","relevance":"Very High","relevance_reason":"ExampleBet is referenced in very close context","brand_affected":"ExampleBet","brand_before":"ExampleBet","brand_after":"ExampleBet","item_hash":"3b9e1d7a0c2f44e6a1d0e5b7c9f21a40","verify_url":"https://www.example.com/bonuses/examplebet/#:~:text=Claim%20your%20ExampleBet%20welcome%20bonus%20with%20no%20wagering%20on%20winnings&text=no%20wagering&text=ExampleBet","ai_analysis":null}],"screenshot_url":"https://aw1.rightlander.com/intelv2/partnerIntelAPIRedirect.php?item=discovery%3AGB202611-4821"}],"paging":{"limit":1,"returned":1,"next_cursor":"discovery.GB202611.4821","complete":false},"notes":["The scan cycle is this month's and last month's tables, the same items the Compliance Workbench shows."]}},"compliance_month":{"summary":"The items reported in one month, with their latest action","value":{"ok":true,"request":{"endpoint":"compliance_items","iso":"GB","period":"2026-10","source":"all","status":"all","detail":"full","limit":1,"filters":[],"adjusted":[],"compliance_limit":{"calls_per_day":250,"used_today":4,"remaining":246,"resets_at":"2026-11-13T00:00:00+00:00"}},"period":{"type":"month","table":"GB202610","month":"2026-10","in_current_cycle":true},"sources":[{"source":"discovery","status":"ok","items":0,"reports":4},{"source":"requested","status":"ok","items":1,"reports":1}],"summary":{"items":353,"unresolved":201,"flagged":88,"non_issue":51,"ignored":13,"domains":74},"items":[{"id":"requested:GB202610-917","issue_key":"6c1f0e9a2b7d4c55","source":"requested","table":"GB202610","row_id":917,"also_reported_in":[],"iso":"GB","state_iso":null,"status":"non_issue","report":{"id":20001276,"title":"Batch Workbench - Significant Terms","priority":1,"priority_label":"High"},"page":{"url":"https://www.example.com/bonuses/examplebet/","domain":"example.com","title":"ExampleBet Bonus Review","type":"web","page_scan":false,"site_id":100234,"brand_link_page":null},"partner":{"affiliate_id":"a_12345b_678","company":"Example Media Ltd"},"brand_affected":"ExampleBet","brands_on_page":["ExampleBet","OtherBet"],"scanned_at":"2026-11-04","reported_at":"2026-11-04","first_scan":"2024-03-11","action":{"type":"non_issue","scope":"site","temporary":false,"label":"Item resolved permanently sitewide","origin":"carried_forward","carried_from":{"table":"GB202604","month":"2026-04","row_id":12877},"actioned_at":"2026-04-17T09:41:55+00:00","actioned_at_estimated":false,"actioned_by":"Tom Hughes"},"case_id":null,"findings":[{"text":"Claim your ExampleBet welcome bonus with no wagering on winnings.","translated_text":null,"full_sentence":"Claim your ExampleBet welcome bonus with no wagering on winnings.","matched_phrase":"no wagering","exact_phrase":"no wagering","relevance":"Very High","relevance_reason":"ExampleBet is referenced in very close context","brand_affected":"ExampleBet","brand_before":"ExampleBet","brand_after":"ExampleBet","item_hash":"3b9e1d7a0c2f44e6a1d0e5b7c9f21a40","verify_url":"https://www.example.com/bonuses/examplebet/#:~:text=Claim%20your%20ExampleBet%20welcome%20bonus%20with%20no%20wagering%20on%20winnings&text=no%20wagering&text=ExampleBet","ai_analysis":null}],"screenshot_url":"https://aw1.rightlander.com/intelv2/partnerIntelAPIRedirect.php?item=requested%3AGB202610-917"}],"paging":{"limit":1,"returned":1,"next_cursor":"requested.GB202610.917","complete":false},"notes":["A month is the items reported in that month with their latest action. While a month is in the scan cycle its actions can still change."]}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/apis/rightlander/v1/partner-domains.php":{"post":{"operationId":"partner_domains_post","summary":"Send affiliate domains to be scanned, for your network or for one client","description":"Records the domains you send against your account, or with client_ref against one of your clients, and queues each new one for scanning: under your own account, or under the client's once it has signed up for a personalised feed. Every domain comes back with what was done with it.\n\nWhen to use it: Once a day, with each list in full and mode=replace, so ours always matches yours. Use mode=add for a few new domains in between, and mode=remove to take some off.\n\nCost: 1 credit. Permission: domains.\n\nFreshness: Queued domains follow the account's normal scan schedule; first results usually arrive within days. Domains already held keep the schedule they have.\n\nNotes: An empty replace is refused rather than read as \"remove everything\". A removed domain leaves the client's feed straight away. Not available on a trial key: scanning is a paid operation. One request against your daily allowance whatever the list size; no credits.","tags":["Network"],"responses":{"200":{"description":"Success. Check ok before reading the rest.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":["boolean","null"],"description":"True on success, false on failure. Check this before anything else - an empty result and a failure are not the same thing."},"error":{"type":["string","null"],"description":"Human-readable message. Present only on failure."},"error_code":{"type":["string","null"],"description":"Stable code to branch on. Match on this, not on the message text."},"status":{"type":["integer","null"],"description":"HTTP status, repeated in the body for clients that cannot see it."},"request":{"type":"object","properties":{"queried_at":{"type":["string","null"],"format":"date-time","description":"When we answered."},"took_ms":{"type":["integer","null"],"description":"How long it took us."},"key_source":{"type":["string","null"],"description":"header or query - where your key was read from."},"rate_limit":{"type":"object","properties":{"requests_per_day":{"type":["integer","null"],"description":"Your daily allowance."},"used_today":{"type":["integer","null"],"description":"Requests used today."},"remaining":{"type":["integer","null"],"description":"What is left."},"resets_at":{"type":["string","null"],"format":"date-time","description":"When it resets. 00:00 UTC."}}},"credits_charged":{"type":["integer","null"],"description":"Credits taken by this request. Present only when it cost something."},"client_ref":{"type":["string","null"],"description":"The client_ref sent, or null for your own list."},"mode":{"type":["string","null"],"description":"add, replace or remove."},"iso":{"type":["string","null"],"description":"The default market sent, or null."}}},"credits":{"type":"object","properties":{"charged":{"type":["integer","null"],"description":"Credits this send used: 1, however many domains it held. 0 on a trial key."},"price":{"type":["integer","null"],"description":"The price of a send."}}},"client":{"type":"object","properties":{"client_ref":{"type":["string","null"],"description":"Your ID for the client."},"status":{"type":["string","null"],"description":"pending, active or cancelled."},"personalised":{"type":["boolean","null"],"description":"True when the client has signed up and its domains are scanned under its own account."},"account":{"type":["string","null"],"description":"The client's account code when personalised. Null otherwise."},"name":{"type":["string","null"],"description":"As you sent it. Null when never sent."},"brand_domain":{"type":["string","null"],"description":"As you sent it. Null when never sent."},"linked_at":{"type":["string","null"],"format":"date-time","description":"When the client's account was linked. Null until then."}}},"scanned_under":{"type":["string","null"],"description":"An account code, or null."},"summary":{"type":"object","properties":{"received":{"type":["integer","null"],"description":"Entries in the request."},"accepted":{"type":["integer","null"],"description":"Distinct domains that could be used."},"rejected":{"type":["integer","null"],"description":"Entries that could not - see rejected."},"duplicates":{"type":["integer","null"],"description":"Repeats of a domain already in the request. The last one wins."},"added":{"type":["integer","null"],"description":"New to the list."},"updated":{"type":["integer","null"],"description":"Already on it, with a new affiliate ID or market."},"unchanged":{"type":["integer","null"],"description":"Already on it, as sent."},"restored":{"type":["integer","null"],"description":"Previously removed, now back."},"removed":{"type":["integer","null"],"description":"Taken off the list by this post."},"not_held":{"type":["integer","null"],"description":"mode=remove only: named, but not on the list."},"queued":{"type":["integer","null"],"description":"Put into the scanning intake."},"held":{"type":["integer","null"],"description":"Already on the account; nothing to queue."},"over_allowance":{"type":["integer","null"],"description":"Past the account's partner-site allowance. Recorded; queued by a later post once it is raised."},"no_profile":{"type":["integer","null"],"description":"In a market where the client has no product profile yet. Recorded; scanned as soon as the client adds a product profile for that market."},"waiting":{"type":["integer","null"],"description":"Recorded, waiting for the client to sign up."},"failed":{"type":["integer","null"],"description":"Could not be queued just now. Post again to retry."}}},"allowance":{"type":"object","properties":{"limit":{"type":["integer","null"],"description":"Partner sites the account may hold."},"used":{"type":["integer","null"],"description":"Held now."},"pending":{"type":["integer","null"],"description":"Queued and not yet added."},"remaining":{"type":["integer","null"],"description":"Room left."}}},"domains":{"type":"array","items":{"type":"object","properties":{"domain":{"type":["string","null"],"description":"The domain as we hold it - the registrable domain, lower case."},"input":{"type":["string","null"],"description":"What you sent."},"affiliate_id":{"type":["string","null"],"description":"The affiliate ID held for it, or null."},"iso":{"type":["string","null"],"description":"Its market."},"result":{"type":["string","null"],"description":"added, updated, unchanged, restored, removed or not_held."},"scan":{"type":["string","null"],"description":"queued, held, over_allowance, waiting, failed, no_profile (the client has no product profile in that market yet; scanned once it adds one) or not_scanned."}}}},"removed":{"type":"array","items":{"type":"array","items":{},"description":"Every domain removed, by mode=remove or by a replace."},"description":"Every domain removed, by mode=remove or by a replace."},"removed_by_replace":{"type":"array","items":{"type":"array","items":{},"description":"Those removed because a replace left them out."},"description":"Those removed because a replace left them out."},"rejected":{"type":"array","items":{"type":"object","properties":{"input":{"type":["string","null"],"description":"What you sent."},"reason":{"type":["string","null"],"description":"Why it was not used."}}}},"notes":{"type":"array","items":{"type":"array","items":{},"description":"Short sentences."},"description":"Short sentences."}}},"examples":{"partner_domains_post":{"summary":"Send affiliate domains to be scanned, for your network or for one client","value":{"ok":true,"request":{"endpoint":"partner-domains","method":"POST","client_ref":"C-1042","mode":"replace","iso":"GB"},"client":{"client_ref":"C-1042","status":"active","personalised":true,"account":"XYZ789","name":"Example Brand","brand_domain":"examplebrand.com","linked_at":"2026-10-01T10:00:00+01:00"},"scanned_under":"XYZ789","summary":{"received":3,"accepted":2,"rejected":1,"duplicates":0,"added":1,"updated":0,"unchanged":1,"restored":0,"removed":1,"not_held":0,"queued":1,"held":1,"over_allowance":0,"waiting":0,"failed":0},"allowance":{"limit":300,"used":41,"pending":1,"remaining":258},"domains":[{"domain":"example.com","input":"https://www.example.com/","affiliate_id":"10442","iso":"GB","result":"added","scan":"queued"},{"domain":"example.net","input":"example.net","affiliate_id":"10587","iso":"GB","result":"unchanged","scan":"held"}],"removed":["oldpartner.com"],"removed_by_replace":["oldpartner.com"],"rejected":[{"input":"not a domain","reason":"not a domain"}],"notes":[]}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"x-rightlander-credits":"1 credit","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domains":{"type":"string","examples":["example.com|10442, example.net|10587"],"description":"Up to 1000 per request. In a JSON body, an array of strings or of objects { \"domain\", \"affiliate_id\", \"iso\" }. As a form field, domains separated by commas, spaces or new lines, each optionally as domain|affiliate_id or domain|affiliate_id|iso. A full URL is fine; it is reduced to its domain."},"iso":{"type":"string","examples":["GB"],"description":"Two-letter market for any domain that does not carry its own. Needed unless every entry has one."},"client_ref":{"type":"string","description":"Your ID for the client these domains belong to. Omit to send your own network list. A client_ref you have not used before is created."},"uid":{"type":"string","description":"Networks that personalise per user: the user of client_ref these domains belong to. The list is that user's, and its size sets the user's suggested scan credits. Refused if your feeds are personalised per client."},"mode":{"type":"string","enum":["add","replace","remove"],"default":"add","description":"add keeps everything already on the list. replace removes anything not in this request. remove takes the domains named off the list."},"client_name":{"type":"string","description":"Optional. The client's name, kept on its record."},"client_domain":{"type":"string","description":"Optional. The client's own brand site, which its partner list is filed under."}},"required":["domains"]}}}}},"get":{"operationId":"partner_domains_list","summary":"The domains you have sent, and where each one's scan stands","description":"Your network list, or with client_ref one client's, as we hold it: affiliate ID, market, whether it is active or removed, and its scan state.\n\nWhen to use it: To reconcile your records with ours, or to see which domains are still waiting for a client to sign up.\n\nCost: free within your daily allowance. Permission: read.\n\nFreshness: Live.","tags":["Network"],"parameters":[{"name":"client_ref","in":"query","required":false,"description":"Your ID for the client. Omit for your own network list.","schema":{"type":"string"}},{"name":"uid","in":"query","required":false,"description":"One user of client_ref (networks that personalise per user).","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Which domains to list.","schema":{"type":"string","enum":["active","removed","all"],"default":"active"}},{"name":"limit","in":"query","required":false,"description":"Rows per page, up to 5000.","schema":{"type":"integer","default":500}},{"name":"cursor","in":"query","required":false,"description":"Pass back next_cursor from the previous response. Null next_cursor means you have seen everything.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success. Check ok before reading the rest.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":["boolean","null"],"description":"True on success, false on failure. Check this before anything else - an empty result and a failure are not the same thing."},"error":{"type":["string","null"],"description":"Human-readable message. Present only on failure."},"error_code":{"type":["string","null"],"description":"Stable code to branch on. Match on this, not on the message text."},"status":{"type":["integer","null"],"description":"HTTP status, repeated in the body for clients that cannot see it."},"request":{"type":"object","properties":{"queried_at":{"type":["string","null"],"format":"date-time","description":"When we answered."},"took_ms":{"type":["integer","null"],"description":"How long it took us."},"key_source":{"type":["string","null"],"description":"header or query - where your key was read from."},"rate_limit":{"type":"object","properties":{"requests_per_day":{"type":["integer","null"],"description":"Your daily allowance."},"used_today":{"type":["integer","null"],"description":"Requests used today."},"remaining":{"type":["integer","null"],"description":"What is left."},"resets_at":{"type":["string","null"],"format":"date-time","description":"When it resets. 00:00 UTC."}}},"credits_charged":{"type":["integer","null"],"description":"Credits taken by this request. Present only when it cost something."}}},"client":{"type":"object","properties":{"status":{"type":["string","null"],"description":"pending, active or cancelled."},"personalised":{"type":["boolean","null"],"description":"True when the client's domains are scanned under its own account."}}},"summary":{"type":"object","properties":{"active":{"type":["integer","null"],"description":"Active domains."},"removed":{"type":["integer","null"],"description":"Removed domains."},"by_scan":{"type":"object","description":"Active domains per scan state."},"returned":{"type":["integer","null"],"description":"Rows on this page."}}},"domains":{"type":"array","items":{"type":"object","properties":{"domain":{"type":["string","null"],"description":"The domain."},"affiliate_id":{"type":["string","null"],"description":"Your affiliate ID for it, or null."},"iso":{"type":["string","null"],"description":"Its market."},"status":{"type":["string","null"],"description":"active or removed."},"scan":{"type":["string","null"],"description":"queued, held, over_allowance, waiting, failed, no_profile (the client has no product profile in that market yet; scanned once it adds one) or not_scanned."},"added_at":{"type":["string","null"],"format":"date-time","description":"First sent."},"last_posted_at":{"type":["string","null"],"format":"date-time","description":"Last sent."},"removed_at":{"type":["string","null"],"format":"date-time","description":"When removed. Null while active."}}}},"next_cursor":{"type":["string","null"],"description":"Pass back as cursor. Null when there is nothing more."}}},"examples":{"partner_domains_list":{"summary":"The domains you have sent, and where each one's scan stands","value":{"ok":true,"request":{"endpoint":"partner-domains","method":"GET","client_ref":"C-1042","status":"active","limit":500},"client":{"client_ref":"C-1042","status":"pending","personalised":false,"account":null,"name":null,"brand_domain":null,"linked_at":null},"scanned_under":null,"summary":{"active":2,"removed":1,"by_scan":{"waiting":2},"returned":2},"domains":[{"domain":"example.com","affiliate_id":"10442","iso":"GB","status":"active","scan":"waiting","added_at":"2026-10-07T09:00:00+01:00","last_posted_at":"2026-10-07T09:00:00+01:00","removed_at":null}],"next_cursor":null}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/apis/rightlander/v1/clients.php":{"get":{"operationId":"clients_list","summary":"Your clients, and which have a personalised feed","description":"Every client_ref your account has used, with its status - pending, requested, approved, declined, active or cancelled - its usage estimate and allocation, and its partner domain counts.\n\nWhen to use it: In your daily job: send your client list with client_refs (up to 100 per call), save each client's status and personalise_url for the day, then call the activity feed with client_ref for each client with personalised true. Your feed page then needs no call.\n\nCost: free within your daily allowance. Permission: read.\n\nFreshness: Live. A client appears as active as soon as its sign-up is linked.","tags":["Network"],"parameters":[{"name":"status","in":"query","required":false,"description":"Which clients to list. The default is the ones with a personalised feed; requested is the ones waiting for your decision.","schema":{"type":"string","enum":["active","requested","approved","declined","pending","cancelled","all"],"default":"active"}},{"name":"client_ref","in":"query","required":false,"description":"One client only, whatever its status, with its users. A client_ref we have not seen is recorded as pending. Use it to get the client's personalise_url for its button.","schema":{"type":"string"}},{"name":"client_refs","in":"query","required":false,"description":"Up to 100 clients in one call, comma separated, returned in the order sent whatever their status. New ones are recorded as pending. Each comes back with its status and, if not personalised, its personalise_url, so your daily job can save every client's button link for the day. Networks that personalise per user can send ref|uid entries.","schema":{"type":"string"}},{"name":"uid","in":"query","required":false,"description":"With client_ref: one user only, recorded as pending if new, with that user's own personalise_url (networks that personalise per user).","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Rows per page, up to 1000.","schema":{"type":"integer","default":500}},{"name":"cursor","in":"query","required":false,"description":"Pass back next_cursor from the previous response.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success. Check ok before reading the rest.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":["boolean","null"],"description":"True on success, false on failure. Check this before anything else - an empty result and a failure are not the same thing."},"error":{"type":["string","null"],"description":"Human-readable message. Present only on failure."},"error_code":{"type":["string","null"],"description":"Stable code to branch on. Match on this, not on the message text."},"status":{"type":["integer","null"],"description":"HTTP status, repeated in the body for clients that cannot see it."},"request":{"type":"object","properties":{"queried_at":{"type":["string","null"],"format":"date-time","description":"When we answered."},"took_ms":{"type":["integer","null"],"description":"How long it took us."},"key_source":{"type":["string","null"],"description":"header or query - where your key was read from."},"rate_limit":{"type":"object","properties":{"requests_per_day":{"type":["integer","null"],"description":"Your daily allowance."},"used_today":{"type":["integer","null"],"description":"Requests used today."},"remaining":{"type":["integer","null"],"description":"What is left."},"resets_at":{"type":["string","null"],"format":"date-time","description":"When it resets. 00:00 UTC."}}},"credits_charged":{"type":["integer","null"],"description":"Credits taken by this request. Present only when it cost something."}}},"network":{"type":"object","properties":{"code":{"type":["string","null"],"description":"Your own Rightlander account code (your MASTERUSERCODE)."},"billing":{"type":["string","null"],"description":"subscription (clients sign up and pay through the Rightlander Subscription System) or network (you bill and approve them)."}}},"summary":{"type":"object","properties":{"returned":{"type":["integer","null"],"description":"Clients on this page."},"by_status":{"type":"object","description":"Clients on this page per status."}}},"clients":{"type":"array","items":{"type":"object","properties":{"client_ref":{"type":["string","null"],"description":"Your ID for the client."},"status":{"type":["string","null"],"description":"pending (domains sent, no request yet), requested, approved, declined, active or cancelled."},"personalised":{"type":["boolean","null"],"description":"True when a client_ref call returns the client's own items."},"billing":{"type":["string","null"],"description":"subscription or network - the route the request took. Null before a request."},"uid":{"type":["string","null"],"description":"Your ID for the user, for networks that personalise per user. Null for a client as a whole."},"account":{"type":["string","null"],"description":"The client's Rightlander account code (its MASTERUSERCODE) when personalised. Null otherwise. Every user of a client shares it."},"user_account":{"type":["string","null"],"description":"Per-user networks: the user's own Rightlander login under the client account (its USERCODE) when personalised. Null otherwise. With network.code, client_ref, uid and account, it lets you map your client and user to ours. No code carries any access on its own."},"name":{"type":["string","null"],"description":"As you sent it, or null."},"brand_domain":{"type":["string","null"],"description":"As you sent it, or null."},"contact":{"type":"object","description":"name, email and company the client gave on its request. Null when none."},"estimate":{"type":"object","description":"partner_domains, markets, social_profiles and health_checks_per_month (scans a month) worked out when the client clicked, and package: the scan credits a month the client chose. Null before a request."},"allocation":{"type":["integer","null"],"description":"The scan credits a month you approved (for example 5000). Null until approved."},"extra_product_profiles":{"type":["integer","null"],"description":"Extra product profiles on top of those included: what the client chose, then what you approved. 0 for none."},"markets":{"type":"array","items":{},"description":"The markets (two-letter codes) the client chose when it asked to personalise; it confirms them at setup. Null before a request."},"feed_categories":{"type":"array","items":{},"description":"The kinds of item the client chose for its personalised feed, within what your feed carries; critical risks are always in. Null means everything your feed carries. Once personalised, GET /v1/activity for this client returns only these."},"personalise_url":{"type":["string","null"],"description":"The \"Personalise my feed\" link for this client, signed by us, valid for 7 days. Show it as a button marked data-rl-personalise, so networkModal.js opens it in a modal. Optional prefills may be added to the end, URL-encoded and unsigned: email (shown read-only; free email services other than gmail.com refused unless signed), name, company, brand, domain. Null once the client has a personalised feed."},"settings_url":{"type":["string","null"],"description":"The \"Edit my feed settings\" link for a personalised client, signed by us, valid for 7 days. Show it as a button marked data-rl-personalise: it opens the client's settings in the modal, where it can change its products, what its feed shows and its plan, or ask to cancel. Null until the client is personalised."},"allocation_pending":{"type":"object","description":"Fewer credits or extra profiles waiting to take effect: allocation, extra_product_profiles and from (a date, the 1st of a month). Null when there is none."},"first_seen_at":{"type":["string","null"],"format":"date-time","description":"The first time you used this client_ref."},"requested_at":{"type":["string","null"],"format":"date-time","description":"When the client clicked \"Personalise my feed\". Null before that."},"decided_at":{"type":["string","null"],"format":"date-time","description":"When you approved or declined it. Null otherwise."},"decision_note":{"type":["string","null"],"description":"The note you gave with the decision, or null."},"linked_at":{"type":["string","null"],"format":"date-time","description":"When the client's account was linked. Null until then."},"cancelled_at":{"type":["string","null"],"format":"date-time","description":"When the personalised feed was cancelled. Null otherwise."},"partner_domains":{"type":"object","properties":{"active":{"type":["integer","null"],"description":"Active domains on the client's list."},"removed":{"type":["integer","null"],"description":"Removed domains."},"by_scan":{"type":"object","description":"Active domains per scan state."},"last_posted_at":{"type":["string","null"],"format":"date-time","description":"The last time you sent this client's domains."}}}}}},"next_cursor":{"type":["string","null"],"description":"Pass back as cursor. Null when there is nothing more."}}},"examples":{"clients_list":{"summary":"Your clients, and which have a personalised feed","value":{"ok":true,"request":{"endpoint":"clients","status":"active","limit":500,"cursor":null},"network":{"code":"NET123","billing":"network"},"summary":{"returned":1,"by_status":{"pending":0,"requested":0,"approved":0,"declined":0,"active":1,"cancelled":0}},"clients":[{"client_ref":"C-1042","uid":null,"status":"active","personalised":true,"billing":"network","account":"XYZ789","user_account":null,"name":"Example Brand","brand_domain":"examplebrand.com","contact":{"name":"Sam Lee","email":"sam@examplebrand.com","company":"Example Brand Ltd"},"estimate":{"partner_domains":240,"markets":2,"social_profiles":240,"health_checks_per_month":480,"package":"1000"},"allocation":1000,"extra_product_profiles":0,"first_seen_at":"2026-09-28T14:02:00+01:00","requested_at":"2026-09-30T09:15:00+01:00","decided_at":"2026-09-30T16:40:00+01:00","decision_note":null,"linked_at":"2026-10-01T10:00:00+01:00","cancelled_at":null,"partner_domains":{"active":42,"removed":3,"by_scan":{"queued":30,"held":12},"last_posted_at":"2026-10-07T06:00:00+01:00"}}],"next_cursor":null,"notes":[]}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"clients_decide","summary":"Approve, decline, cancel or change a client","description":"Your decision on a client's request for a personalised feed, if you bill your own clients, a change to its monthly scan credits or extra product profiles, or the end of a client's feed. Approving returns the setup link the client finishes setup at.\n\nWhen to use it: When a client.requested webhook arrives, or a client appears in GET /v1/clients?status=requested, and you have agreed terms with that client. Cancel when a client stops paying you.\n\nCost: free within your daily allowance. Permission: clients.\n\nFreshness: Immediate. The webhook for the decision is sent before the response.\n\nNotes: Keep setup_url private to that client: whoever opens it sets up the account. It stops working once setup is finished, after 30 days, or if you cancel the client.","tags":["Network"],"responses":{"200":{"description":"Success. Check ok before reading the rest.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":["boolean","null"],"description":"True on success, false on failure. Check this before anything else - an empty result and a failure are not the same thing."},"error":{"type":["string","null"],"description":"Human-readable message. Present only on failure."},"error_code":{"type":["string","null"],"description":"Stable code to branch on. Match on this, not on the message text."},"status":{"type":["integer","null"],"description":"HTTP status, repeated in the body for clients that cannot see it."},"request":{"type":"object","properties":{"queried_at":{"type":["string","null"],"format":"date-time","description":"When we answered."},"took_ms":{"type":["integer","null"],"description":"How long it took us."},"key_source":{"type":["string","null"],"description":"header or query - where your key was read from."},"rate_limit":{"type":"object","properties":{"requests_per_day":{"type":["integer","null"],"description":"Your daily allowance."},"used_today":{"type":["integer","null"],"description":"Requests used today."},"remaining":{"type":["integer","null"],"description":"What is left."},"resets_at":{"type":["string","null"],"format":"date-time","description":"When it resets. 00:00 UTC."}}},"credits_charged":{"type":["integer","null"],"description":"Credits taken by this request. Present only when it cost something."}}},"client":{"type":"object","properties":{"status":{"type":["string","null"],"description":"approved, declined, active or cancelled."},"allocation":{"type":["integer","null"],"description":"Scan credits a month, after an approval or a change that applies now."},"extra_product_profiles":{"type":["integer","null"],"description":"Extra product profiles, after an approval or a change that applies now."},"allocation_pending":{"type":"object","description":"change only: fewer credits or profiles and the date they take effect. Null otherwise."}}},"effective_from":{"type":["string","null"],"format":"date","description":"When the change applies: today for more credits or profiles, the 1st of next month for fewer. Null for other actions."},"setup_url":{"type":["string","null"],"description":"Where the client finishes setup. Send it to the client. Null for decline and cancel."},"notes":{"type":"array","items":{"type":"array","items":{},"description":"Short sentences."},"description":"Short sentences."}}},"examples":{"clients_decide":{"summary":"Approve, decline, cancel or change a client","value":{"ok":true,"request":{"endpoint":"clients","method":"POST","action":"approve","client_ref":"C-1042"},"client":{"client_ref":"C-1042","status":"approved","personalised":false,"billing":"network","allocation":1000,"extra_product_profiles":1},"setup_url":"https://aw1.rightlander.com/intelv2/partnerIntelNetworkSetup.php?nt=4f2a...","effective_from":null,"notes":["Send the client setup_url to finish setup. It works for 30 days and opens in your branding."]}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["approve","decline","cancel","change"],"description":"approve and decline need a requested client and a network that bills its own clients. change needs an approved or active client and a network that bills its own clients: more credits or profiles apply now, fewer from the 1st of next month. cancel works on a requested, approved or active client."},"client_ref":{"type":"string","examples":["C-1042"],"description":"Your ID for the client."},"uid":{"type":"string","description":"One user of the client: the action is on that user's subscription (networks that personalise per user)."},"allocation":{"type":"integer","description":"Scan credits a month: a multiple of 1000, from 1000 to 500000. approve: omit to use what the client chose, or its estimate rounded up to the next 1,000. change: the new amount; omit to change only extra_product_profiles."},"extra_product_profiles":{"type":"integer","description":"Extra product profiles on top of those included, 0 to 50. approve: omit to use what the client chose. change: the new number; omit to keep it."},"note":{"type":"string","description":"Optional. Kept with the decision and sent in the webhook."}},"required":["action","client_ref"]}}}}}},"/apis/rightlander/v1/network.php":{"get":{"operationId":"network_get","summary":"Your network settings, signing secret and request link","description":"Your billing route (subscription or network), the package your clients get, your prices per scan credit and per extra product profile, your webhook URL and branding, and what you need to build the \"Personalise my feed\" button: the request link and your signing secret.\n\nWhen to use it: Once, when you build the button, and again after rotating your secret.\n\nCost: free within your daily allowance. Permission: clients.\n\nFreshness: Live.\n\nNotes: Billing and package are agreed with Rightlander; contact us to change them. The signing secret is returned only to keys with the clients permission.","tags":["Network settings"],"responses":{"200":{"description":"Success. Check ok before reading the rest.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":["boolean","null"],"description":"True on success, false on failure. Check this before anything else - an empty result and a failure are not the same thing."},"error":{"type":["string","null"],"description":"Human-readable message. Present only on failure."},"error_code":{"type":["string","null"],"description":"Stable code to branch on. Match on this, not on the message text."},"status":{"type":["integer","null"],"description":"HTTP status, repeated in the body for clients that cannot see it."},"request":{"type":"object","properties":{"queried_at":{"type":["string","null"],"format":"date-time","description":"When we answered."},"took_ms":{"type":["integer","null"],"description":"How long it took us."},"key_source":{"type":["string","null"],"description":"header or query - where your key was read from."},"rate_limit":{"type":"object","properties":{"requests_per_day":{"type":["integer","null"],"description":"Your daily allowance."},"used_today":{"type":["integer","null"],"description":"Requests used today."},"remaining":{"type":["integer","null"],"description":"What is left."},"resets_at":{"type":["string","null"],"format":"date-time","description":"When it resets. 00:00 UTC."}}},"credits_charged":{"type":["integer","null"],"description":"Credits taken by this request. Present only when it cost something."}}},"network":{"type":"object","properties":{"account":{"type":["string","null"],"description":"Your account code."},"display_name":{"type":["string","null"],"description":"Your name as your clients see it, or null. Set by Rightlander."},"billing":{"type":["string","null"],"description":"subscription or network. Set by Rightlander."},"package":{"type":"object","description":"markets, partner_domains, health_checks (your own scan credits a month), product_profiles (included per client, per market) and calls_day (the API calls you can make a day: 1,000 unless agreed otherwise) - your package with us. Null until agreed."},"client_packages":{"type":"array","items":{},"description":"Suggested amounts of scan credits a month. Any multiple of 1,000 up to 500,000 is allowed."},"pricing":{"type":"object","description":"What Rightlander bills you, if you bill your own clients: currency, credit_unit (1000), credit_price (per scan credit, a decimal string), per_1000, extra_profile_price (a month), profiles_included and max_extra_profiles. You set your own price to your clients."},"webhook_url":{"type":["string","null"],"description":"Where we post client events, or null."},"branding":{"type":"object","properties":{"logo_url":{"type":["string","null"],"description":"Shown to your clients on our pages, or null."},"brand_colour":{"type":["string","null"],"description":"Header and button colour on our pages, or null."},"item_branding":{"type":["string","null"],"description":"network or neutral - how the page behind each item link looks."}}},"item_links":{"type":"object","properties":{"valid_for_days":{"type":["integer","null"],"description":"How long an item link works after the feed last returned the item."}}},"feed_style":{"type":"object","description":"The look of GET /v1/activity?render=html - see feed_style on POST /v1/network."},"feed_categories":{"type":"array","items":{},"description":"The categories your feed carries - see feed_categories on POST /v1/network."},"personalise":{"type":"object","properties":{"level":{"type":["string","null"],"description":"client or user: whether your feeds are personalised per client or per user (send uid). Set by Rightlander."}}},"show_username":{"type":["boolean","null"],"description":"Whether your clients choose and see a Rightlander username at setup."},"examples":{"type":"object","properties":{"verticals":{"type":"array","items":{"type":"array","items":{},"description":"The verticals our generic product profiles on your account cover."},"description":"The verticals our generic product profiles on your account cover."},"categories":{"type":"array","items":{"type":"array","items":{},"description":"The categories that are examples in your feed."},"description":"The categories that are examples in your feed."},"per_category_per_day":{"type":["integer","null"],"description":"The most example items per category per day."},"note":{"type":["string","null"],"description":"The label example items carry."}}}}},"request_link":{"type":"object","properties":{"base":{"type":["string","null"],"description":"The page the button opens."},"signing_secret":{"type":["string","null"],"description":"Signs the button link and our webhooks. Keep it on your server."},"valid_for_hours":{"type":["integer","null"],"description":"How long a signed link works after its ts."},"signed_params":{"type":"array","items":{"type":"array","items":{},"description":"The parameters the signature covers."},"description":"The parameters the signature covers."},"how_to_sign":{"type":["string","null"],"description":"The signing rule in words."},"example":{"type":["string","null"],"description":"A link with your account code filled in."}}}}},"examples":{"network_get":{"summary":"Your network settings, signing secret and request link","value":{"ok":true,"network":{"account":"NET123","display_name":"Example Network","billing":"network","package":{"markets":3,"partner_domains":1000,"health_checks":5000,"product_profiles":3},"client_packages":[1000,2000,3000,5000,10000,25000,50000,100000],"pricing":{"currency":"GBP","credit_unit":1000,"credit_price":"0.35","per_1000":350,"extra_profile_price":100,"profiles_included":3,"max_extra_profiles":50},"webhook_url":"https://network.example.com/hooks/rightlander","branding":{"logo_url":"https://network.example.com/logo.png","brand_colour":"#1A4B8C","item_branding":"network"},"item_links":{"valid_for_days":30}},"request_link":{"base":"https://aw1.rightlander.com/intelv2/networkRequest.php","signing_secret":"9c1e...","valid_for_hours":24,"signed_params":["network","client_ref","ts","email (optional)","name (optional)","company (optional)"],"how_to_sign":"Take every parameter except sig, sort by name, join as name=value with &, ..."},"notes":[]}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"network_post","summary":"Change your webhook, branding or signing secret","description":"Set the URL we post client events to, the logo and colour your clients see on the pages they reach from your site, or replace your signing secret. Your display name is set by Rightlander.\n\nWhen to use it: When you first set up, and whenever your webhook endpoint or branding changes.\n\nCost: free within your daily allowance. Permission: clients.\n\nFreshness: Immediate.\n\nNotes: billing, package and display_name are set by Rightlander and are refused by name.","tags":["Network settings"],"responses":{"200":{"description":"Success. Check ok before reading the rest.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":["boolean","null"],"description":"True on success, false on failure. Check this before anything else - an empty result and a failure are not the same thing."},"error":{"type":["string","null"],"description":"Human-readable message. Present only on failure."},"error_code":{"type":["string","null"],"description":"Stable code to branch on. Match on this, not on the message text."},"status":{"type":["integer","null"],"description":"HTTP status, repeated in the body for clients that cannot see it."},"request":{"type":"object","properties":{"queried_at":{"type":["string","null"],"format":"date-time","description":"When we answered."},"took_ms":{"type":["integer","null"],"description":"How long it took us."},"key_source":{"type":["string","null"],"description":"header or query - where your key was read from."},"rate_limit":{"type":"object","properties":{"requests_per_day":{"type":["integer","null"],"description":"Your daily allowance."},"used_today":{"type":["integer","null"],"description":"Requests used today."},"remaining":{"type":["integer","null"],"description":"What is left."},"resets_at":{"type":["string","null"],"format":"date-time","description":"When it resets. 00:00 UTC."}}},"credits_charged":{"type":["integer","null"],"description":"Credits taken by this request. Present only when it cost something."}}},"network":{"type":"object","properties":{"account":{"type":["string","null"],"description":"Your account code."},"display_name":{"type":["string","null"],"description":"Your name as your clients see it, or null. Set by Rightlander."},"billing":{"type":["string","null"],"description":"subscription or network. Set by Rightlander."},"package":{"type":"object","description":"markets, partner_domains, health_checks (your own scan credits a month), product_profiles (included per client, per market) and calls_day (the API calls you can make a day: 1,000 unless agreed otherwise) - your package with us. Null until agreed."},"client_packages":{"type":"array","items":{},"description":"Suggested amounts of scan credits a month. Any multiple of 1,000 up to 500,000 is allowed."},"pricing":{"type":"object","description":"What Rightlander bills you, if you bill your own clients: currency, credit_unit (1000), credit_price (per scan credit, a decimal string), per_1000, extra_profile_price (a month), profiles_included and max_extra_profiles. You set your own price to your clients."},"webhook_url":{"type":["string","null"],"description":"Where we post client events, or null."},"branding":{"type":"object","properties":{"logo_url":{"type":["string","null"],"description":"Shown to your clients on our pages, or null."},"brand_colour":{"type":["string","null"],"description":"Header and button colour on our pages, or null."},"item_branding":{"type":["string","null"],"description":"network or neutral - how the page behind each item link looks."}}},"item_links":{"type":"object","properties":{"valid_for_days":{"type":["integer","null"],"description":"How long an item link works after the feed last returned the item."}}},"feed_style":{"type":"object","description":"The look of GET /v1/activity?render=html - see feed_style on POST /v1/network."},"feed_categories":{"type":"array","items":{},"description":"The categories your feed carries - see feed_categories on POST /v1/network."},"personalise":{"type":"object","properties":{"level":{"type":["string","null"],"description":"client or user: whether your feeds are personalised per client or per user (send uid). Set by Rightlander."}}},"show_username":{"type":["boolean","null"],"description":"Whether your clients choose and see a Rightlander username at setup."},"examples":{"type":"object","properties":{"verticals":{"type":"array","items":{"type":"array","items":{},"description":"The verticals our generic product profiles on your account cover."},"description":"The verticals our generic product profiles on your account cover."},"categories":{"type":"array","items":{"type":"array","items":{},"description":"The categories that are examples in your feed."},"description":"The categories that are examples in your feed."},"per_category_per_day":{"type":["integer","null"],"description":"The most example items per category per day."},"note":{"type":["string","null"],"description":"The label example items carry."}}}}},"request_link":{"type":"object","properties":{"base":{"type":["string","null"],"description":"The page the button opens."},"signing_secret":{"type":["string","null"],"description":"Signs the button link and our webhooks. Keep it on your server."},"valid_for_hours":{"type":["integer","null"],"description":"How long a signed link works after its ts."},"signed_params":{"type":"array","items":{"type":"array","items":{},"description":"The parameters the signature covers."},"description":"The parameters the signature covers."},"how_to_sign":{"type":["string","null"],"description":"The signing rule in words."},"example":{"type":["string","null"],"description":"A link with your account code filled in."}}}}},"examples":{"network_post":{"summary":"Change your webhook, branding or signing secret","value":{"ok":true,"network":{"account":"NET123","webhook_url":"https://network.example.com/hooks/rightlander"},"request_link":{"signing_secret":"9c1e..."},"notes":[]}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"webhook_url":{"type":"string","description":"https only. Send an empty value to stop webhooks."},"logo_url":{"type":"string","description":"An https image URL, shown at the top of our pages for your clients."},"brand_colour":{"type":"string","description":"A hex colour like #1A4B8C for the header and buttons."},"feed_style":{"type":"object","description":"The look of GET /v1/activity?render=html. Any of: layout (cards, list), theme (light, dark), density (comfortable, compact), category_colours (ours, accent), accent (hex), radius (0 to 16), font (inherit, system), show_partner, show_markets, show_date, show_audience, show_evidence (true or false), button_text. Items always open in a new window. Only the settings you send change."},"feed_categories":{"type":"array","items":{"type":"string"},"description":"What GET /v1/activity carries: any of risk_domain, risk_social, ppc, offers, anomalies, growth, llm, social_brand, social_comp, social_topic, as an array or a comma list. risk_domain and risk_social are always kept. Also set in the Network feed step of the guided setup."},"show_username":{"type":"string","enum":["0","1"],"default":"0","description":"1 lets your clients choose and see a Rightlander username at setup. 0 (the default): they only choose a password and are never shown one."},"item_branding":{"type":"string","enum":["network","neutral"],"default":"network","description":"How the page behind each item's link looks: network shows your name, logo and colour; neutral shows no name or logo."},"rotate_secret":{"type":"string","enum":["1"],"description":"1 replaces your signing secret at once. Links signed with the old one stop working."}}}}}}}},"/apis/rightlander/domain.php":{"get":{"operationId":"domain_get","summary":"Everything we hold on one domain","description":"The full picture behind the Domain Profile screen, as data. Traffic and audience, the partner and how to reach them, connected domains and social profiles, the risk score and the evidence for it, compliance findings, PPC brand bidding, growth target pages, offers and AI influence.\n\nWhen to use it: Use this for a single domain you already know about. Use ?sets= to keep the response to what you actually need - the full payload is large.\n\nCost: free within your daily allowance. Permission: read.\n\nFreshness: Domain scans run to your subscription cycle, typically monthly. scan.scanned_at dates the evidence.\n\nNotes: Every social profile row carries assessed_for, including rows whose state is unassessed or link_only - those are exactly the ones where somebody else may hold an assessment you could inherit by requesting a refresh. In the summary, assessed_for_you and generic do not add up to assessed: assessed counts the rows this endpoint could fill in, which has always been the ones assessed for you.","tags":["Domains"],"parameters":[{"name":"action","in":"query","required":true,"description":"Set this to choose the request: action=intel for everything we hold on one domain.","schema":{"type":"string","enum":["intel"],"default":"intel"}},{"name":"domain","in":"query","required":true,"description":"The domain, without scheme or path.","schema":{"type":"string","examples":["example.com"]}},{"name":"iso","in":"query","required":false,"description":"Market to report against. Affects which scan and which compliance findings are used.","schema":{"type":"string","default":"GB","examples":["GB"]}},{"name":"sets","in":"query","required":false,"description":"Comma separated. Omit for everything. See Data sets.","schema":{"type":"string","enum":["core","intel","risk","growth","intel,risk"]}},{"name":"pagelimit","in":"query","required":false,"description":"Cap on URL lists inside the response. 0 or all lifts it. Counts alongside the lists are never capped.","schema":{"type":"string","default":"10"}},{"name":"exclude","in":"query","required":false,"description":"Turns off blocks that are on by default.","schema":{"type":"string","enum":["posts","bios","posts,bios"]}},{"name":"include","in":"query","required":false,"description":"raw attaches the underlying scan payloads. Large.","schema":{"type":"string","enum":["raw"]}}],"responses":{"200":{"description":"Success. Check ok before reading the rest.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":["boolean","null"],"description":"True on success, false on failure. Check this before anything else - an empty result and a failure are not the same thing."},"error":{"type":["string","null"],"description":"Human-readable message. Present only on failure."},"error_code":{"type":["string","null"],"description":"Stable code to branch on. Match on this, not on the message text."},"status":{"type":["integer","null"],"description":"HTTP status, repeated in the body for clients that cannot see it."},"request":{"type":"object","properties":{"queried_at":{"type":["string","null"],"format":"date-time","description":"When we answered."},"took_ms":{"type":["integer","null"],"description":"How long it took us."},"key_source":{"type":["string","null"],"description":"header or query - where your key was read from."},"rate_limit":{"type":"object","properties":{"requests_per_day":{"type":["integer","null"],"description":"Your daily allowance."},"used_today":{"type":["integer","null"],"description":"Requests used today."},"remaining":{"type":["integer","null"],"description":"What is left."},"resets_at":{"type":["string","null"],"format":"date-time","description":"When it resets. 00:00 UTC."}}},"credits_charged":{"type":["integer","null"],"description":"Credits taken by this request. Present only when it cost something."}}},"identity":{"type":"object","properties":{"domain":{"type":["string","null"],"description":"The domain, normalised."},"iso":{"type":["string","null"],"description":"Market the response is scoped to."},"site_id":{"type":["string","null"],"description":"Our internal site id."},"domain_id":{"type":["string","null"],"description":"Our internal domain id."},"is_disclosed":{"type":["boolean","null"],"description":"Whether the domain has been disclosed to you by the partner."},"company":{"type":["string","null"],"description":"Company we hold against the domain."},"affids":{"type":"array","items":{"type":"array","items":{},"description":"Every affiliate id seen on the domain."},"description":"Every affiliate id seen on the domain."},"subnetworks":{"type":"array","items":{"type":"array","items":{},"description":"Sub-networks the domain is associated with."},"description":"Sub-networks the domain is associated with."},"is_subnetwork":{"type":["boolean","null"],"description":"Whether the domain itself is a sub-network property."},"subnetwork_label":{"type":["string","null"],"description":"Readable reason for the sub-network call."}}},"scan":{"type":"object","properties":{"scanned_at":{"type":["string","null"],"format":"date-time","description":"When the scan ran."},"updated_at":{"type":["string","null"],"format":"date-time","description":"When the record last changed."},"content_status":{"type":["string","null"],"description":"Outcome of the content fetch."},"pagehash":{"type":["string","null"],"description":"Content hash, for change detection between calls."},"final_url":{"type":["string","null"],"description":"Where the scan ended up after redirects."},"final_http_status":{"type":["integer","null"],"description":"HTTP status of that final URL."},"is_cloaked":{"type":["boolean","null"],"description":"Whether the site served us different content than a normal visitor."},"primary_role":{"type":["string","null"],"description":"What the site principally is."},"scan_status_pill":{"type":["string","null"],"description":"The short status the workbench displays."},"pages_scanned":{"type":"object","properties":{"pages":{"type":["integer","null"],"description":"Pages covered by the current run. Zero is a fact about the domain, not a missing value."},"last_scanned":{"type":["string","null"],"format":"date","description":"Date of that coverage."},"isos_counted":{"type":"array","items":{"type":"array","items":{},"description":"Markets the page count sums across."},"description":"Markets the page count sums across."},"iso_scoped":{"type":["boolean","null"],"description":"Whether the count was limited to the requested market."}}}}},"scores":{"type":"object","properties":{"risk_score_0_100":{"type":["integer","null"],"description":"Risk. Higher is worse. See risk_score_evidence for why."},"quality_score_0_100":{"type":["integer","null"],"description":"Content quality. Higher is better."},"ai_content_likelihood_0_100":{"type":["integer","null"],"description":"How likely the content is machine generated."},"ai_content_band":{"type":["string","null"],"description":"That likelihood as a band."},"ai_content_evidence":{"type":"array","items":{"type":"array","items":{},"description":"What drove the AI content call."},"description":"What drove the AI content call."}}},"content_categories":{"type":"object","properties":{"domain_type":{"type":["string","null"],"description":"Kind of site, e.g. review, coupon, news."},"domain_type_subtype":{"type":["string","null"],"description":"Finer classification."},"site_category_label":{"type":["string","null"],"description":"Readable category."},"verticals":{"type":"array","items":{"type":"array","items":{},"description":"Every sector detected on the site."},"description":"Every sector detected on the site."},"primary_vertical":{"type":["string","null"],"description":"The dominant one."},"client_vertical":{"type":["string","null"],"description":"Your own sector, for comparison."},"profile_categories":{"type":"array","items":{"type":"array","items":{},"description":"Categories from the site profile."},"description":"Categories from the site profile."},"page_topic_categories":{"type":"array","items":{"type":"array","items":{},"description":"Topics across every scored page. Not filtered by the growth rules."},"description":"Topics across every scored page. Not filtered by the growth rules."}}},"traffic":{"type":"object","properties":{"data_month":{"type":["string","null"],"description":"Month the traffic estimate covers."},"iso_traffic_tier":{"type":["string","null"],"description":"Traffic band within the requested market."},"global_traffic_tier":{"type":["string","null"],"description":"Traffic band worldwide."},"global_traffic_approx":{"type":["number","null"],"description":"One significant figure approximation of global visits."},"global_traffic_display":{"type":["string","null"],"description":"That approximation as text, e.g. ~10m visits."},"top_countries":{"type":"array","items":{"type":"object","properties":{"iso":{"type":["string","null"],"description":"Market code."},"country":{"type":["string","null"],"description":"Market name."},"share_pct":{"description":"Whole-number share, or the string \"<1\". Never 0 - a market is listed because it has traffic."}}}},"history":{"type":"object","properties":{"first_month":{"type":["string","null"],"description":"Earliest month we hold."},"last_month":{"type":["string","null"],"description":"Most recent month."},"pct_variance":{"type":["string","null"],"description":"Change between the two, e.g. -22%."}}}}},"domain_reputation":{"type":"object","properties":{"domain_created":{"type":["string","null"],"format":"date","description":"Registration date."},"domain_expires":{"type":["string","null"],"format":"date","description":"Expiry date."},"domain_age_days":{"type":["integer","null"],"description":"Age in days. A very young domain is worth a second look."},"expires_in_days":{"type":["integer","null"],"description":"Days until expiry."},"registrant":{"type":["string","null"],"description":"Registrant, where the record is public."},"registrant_org":{"type":["string","null"],"description":"Registrant organisation."}}},"partner":{"type":"object","properties":{"name":{"type":["string","null"],"description":"Partner name."},"name_shared_estate":{"type":["boolean","null"],"description":"True when the name came from the shared table rather than your own data."},"partner_id":{"type":["string","null"],"description":"Affiliate or partner id."},"is_client_partner":{"type":["boolean","null"],"description":"Whether this partner is on your programme."},"partner_status_known":{"type":["boolean","null"],"description":"False means we could not establish the relationship either way."},"signals":{"type":"array","items":{"type":"array","items":{},"description":"What established the partner, e.g. curated list, tracking link, affiliate id."},"description":"What established the partner, e.g. curated list, tracking link, affiliate id."},"priority":{"type":["string","null"],"description":"Any priority you have set against them."},"is_subnetwork_entity":{"type":["boolean","null"],"description":"Whether the partner is a network rather than a publisher."},"generic_assessment":{"type":["boolean","null"],"description":"True when nothing tied the domain to your programme, so the read is generic."}}},"owner_contact":{"type":"object","properties":{"from_site":{"type":["string","null"],"description":"Contact address found on the site itself."},"best_social_route":{"type":"object","properties":{"platform":{"type":["string","null"],"description":"Platform of the best social route to the owner."},"handle":{"type":["string","null"],"description":"Handle on that platform."},"url":{"type":["string","null"],"description":"Profile URL."},"followers":{"type":["integer","null"],"description":"Audience, so you can judge whether it is worth using."}}},"sources":{"type":"array","items":{"type":"array","items":{},"description":"Where each contact route came from."},"description":"Where each contact route came from."}}},"connected_domains":{"type":"object","properties":{"count":{"type":["integer","null"],"description":"How many were found."},"resolved_aff_id":{"type":["string","null"],"description":"The affiliate id the group resolved to."},"resolved_company":{"type":["string","null"],"description":"The company the group resolved to."},"name_tie_is_foreign":{"type":["boolean","null"],"description":"True when the tie is only a name match, which is weaker evidence."},"domains":{"type":"array","items":{"type":"array","items":{},"description":"Each connected domain and why it is connected."},"description":"Each connected domain and why it is connected."}}},"social":{"type":"object","properties":{"<platform>":{"type":["string","null"],"description":"Profile URL. Keys include facebook, instagram, twitter, youtube, linkedin, pinterest, tiktok and linktree."}}},"social_profiles":{"type":"object","properties":{"available":{"type":["boolean","null"],"description":"False when social assessment is not available on your account."},"note":{"type":["string","null"],"description":"Why, when available is false."},"summary":{"type":"object","properties":{"total_assets":{"type":["integer","null"],"description":"Profiles connected to the domain."},"assessed":{"type":["integer","null"],"description":"Profiles we have scored."},"requested":{"type":["integer","null"],"description":"Profiles queued but not yet assessed."},"not_retrievable_or_gated":{"type":["integer","null"],"description":"Profiles we ran and could not read - private, gated or gone. Deliberately separate from requested."},"unassessed":{"type":["integer","null"],"description":"Profiles never queued."},"link_only":{"type":["integer","null"],"description":"Links found on the site with no profile behind them yet."},"assessed_followers":{"type":["integer","null"],"description":"Total audience across assessed profiles."},"client_context":{"type":["string","null"],"description":"Whether you have a product profile configured. Without one the brand filter cannot run."},"brand_filter":{"type":["string","null"],"description":"applied, or not applied with the reason."},"client_sectors":{"type":"object","properties":{"same":{"type":"array","items":{"type":"array","items":{},"description":"Your sectors. A brand in one of these counts as relevant."},"description":"Your sectors. A brand in one of these counts as relevant."},"adjacent":{"type":"array","items":{"type":"array","items":{},"description":"Adjacent sectors, also counted."},"description":"Adjacent sectors, also counted."}}},"platforms_scannable":{"type":"array","items":{"type":"array","items":{},"description":"Platforms we can assess in full."},"description":"Platforms we can assess in full."}}}}},"platform":{"type":["string","null"],"description":"Platform key."},"platform_label":{"type":["string","null"],"description":"Readable platform name."},"handle":{"type":["string","null"],"description":"Account handle."},"url":{"type":["string","null"],"description":"Profile URL."},"scannable":{"type":["boolean","null"],"description":"Whether we can assess this platform."},"state":{"type":["string","null"],"description":"assessed, requested, not_retrievable_or_gated, unassessed or link_only."},"profile_id":{"type":["string","null"],"description":"Our id for the profile. Use it with the refresh endpoint."},"display_name":{"type":["string","null"],"description":"Account display name."},"followers":{"type":["integer","null"],"description":"Audience size."},"posts_total":{"type":["integer","null"],"description":"Posts on the account."},"language":{"type":["string","null"],"description":"Detected language."},"location":{"type":["string","null"],"description":"Stated location."},"scanned_at":{"type":["string","null"],"format":"date-time","description":"When the profile was last assessed."},"scan_id":{"type":["string","null"],"description":"Assessment run id."},"scan_status":{"type":["string","null"],"description":"Outcome of that run. A bad status explains a posting chart that looks out of date."},"limited_information":{"type":["boolean","null"],"description":"True when every score came back zero or null - a private or gated account, not a clean one."},"risk_score_0_100":{"type":["integer","null"],"description":"Risk score for the profile."},"risk_band":{"type":["string","null"],"description":"That score as a band."},"quality_score_0_100":{"type":["integer","null"],"description":"Content quality."},"audience_fit_score_0_100":{"type":["integer","null"],"description":"How well the audience fits your market."},"professionalism_score_0_100":{"type":["integer","null"],"description":"Presentation and professionalism."},"posts_assessed":{"type":["integer","null"],"description":"Posts the assessment looked at."},"engagement":{"type":"object","description":"Totals and per-post averages. Averages matter: a profile with two posts cannot be ranked against one with fifty on totals."},"partner_signals":{"type":"object","description":"Evidence tying the profile to the partner."},"sector_fit":{"type":"object","description":"in_sector, adjacent, unrelated, share_pct, matched_verticals and unknown_reason."},"profile_verticals":{"type":"array","items":{"type":"array","items":{},"description":"Sectors detected on the profile."},"description":"Sectors detected on the profile."},"brands":{"type":"object","properties":{"detected":{"type":"array","items":{"type":"array","items":{},"description":"Brands found in recent posts that are relevant to you."},"description":"Brands found in recent posts that are relevant to you."},"relevant_count":{"type":["integer","null"],"description":"How many were kept."},"filtered_out":{"type":["integer","null"],"description":"How many were seen and dropped as irrelevant."},"basis":{"type":["string","null"],"description":"What the relevance filter matched on. none means it could not run."},"own_brand_excluded":{"type":["integer","null"],"description":"Mentions of the publisher's own brand, removed so they do not crowd out the ones that matter."}}},"bio":{"type":"object","properties":{"label":{"type":["string","null"],"description":"Bio field name on this platform. Empty means the platform has no readable bio, not that the account has none."},"text":{"type":["string","null"],"description":"Bio text."},"links":{"type":"array","items":{"type":"array","items":{},"description":"Links in the bio. Often the most actionable single field on the row."},"description":"Links in the bio. Often the most actionable single field on the row."},"link_count":{"type":["integer","null"],"description":"How many."}}},"assessment":{"type":"object","properties":{"recommendation":{"type":["string","null"],"description":"Our read on the profile."},"confidence":{"type":["string","null"],"description":"How confident that read is."},"summary":{"type":["string","null"],"description":"One paragraph."},"rationale":{"type":["string","null"],"description":"The reasoning behind that recommendation."}}},"risk_and_compliance":{"type":"object","description":"Compliance findings against the profile."},"profile_overview":{"type":"object","description":"Header facts about the account."},"quality_metrics":{"type":"object","description":"The measures behind the quality score."},"posts_referenced":{"type":"array","items":{"type":"array","items":{},"description":"Lookup table of every post cited anywhere on this row: post_id, url, posted_at, engagement, available. Post ids are STRINGS - they exceed what JavaScript can hold as a number."},"description":"Lookup table of every post cited anywhere on this row: post_id, url, posted_at, engagement, available. Post ids are STRINGS - they exceed what JavaScript can hold as a number."},"brands_found":{"type":"object","properties":{"count":{"type":["integer","null"],"description":"How many distinct brands."},"brands":{"type":"array","items":{"type":"array","items":{},"description":"Brand names. Names only, no page counts."},"description":"Brand names. Names only, no page counts."}}},"exposure":{"type":"object","properties":{"summary":{"type":"object","properties":{"total_pages":{"type":["integer","null"],"description":"Distinct pages with any exposure signal."},"linked_pages_count":{"type":["integer","null"],"description":"Pages carrying a link to you."},"mention_pages_count":{"type":["integer","null"],"description":"Pages mentioning you without linking."},"topic_pages_count":{"type":["integer","null"],"description":"Pages matching your topics."},"outbound_link_count":{"type":["integer","null"],"description":"Outbound links counted."},"priority_pages_active":{"type":["integer","null"],"description":"Pages you have marked priority."},"has_client_mention":{"type":["boolean","null"],"description":"Whether you are mentioned anywhere."},"all_visible_brands":{"type":"array","items":{"type":"array","items":{},"description":"Every brand visible across those pages, yours and others."},"description":"Every brand visible across those pages, yours and others."}}},"pages":{"type":"array","items":{"type":"object","properties":{"url":{"type":["string","null"],"description":"Canonical page URL."},"display_url":{"type":["string","null"],"description":"The same URL for display."},"page_title":{"type":["string","null"],"description":"Page title."},"has_link":{"type":["boolean","null"],"description":"Carries a link to you."},"has_mention":{"type":["boolean","null"],"description":"Mentions you."},"has_topic_signal":{"type":["boolean","null"],"description":"Matches one of your topics."},"aff_id":{"type":["string","null"],"description":"Affiliate id on the link."},"anchor_text":{"type":["string","null"],"description":"Anchor text used."},"external_link":{"type":["string","null"],"description":"Where the link points."},"brands":{"type":"array","items":{"type":"array","items":{},"description":"Brands linked from the page."},"description":"Brands linked from the page."},"visible_brands":{"type":"array","items":{"type":"array","items":{},"description":"Brands visible on the page."},"description":"Brands visible on the page."},"added_date":{"type":["string","null"],"format":"date","description":"When we first saw it."},"is_priority":{"type":["boolean","null"],"description":"Whether it is one of your priority pages."}}}}}},"commercial_signals":{"type":"object","properties":{"has_app":{"type":["boolean","null"],"description":"The site advertises an app."},"has_browser_extension":{"type":["boolean","null"],"description":"The site advertises a browser extension."},"has_coupon_focus":{"type":["boolean","null"],"description":"The site is coupon led."},"has_ads":{"type":["boolean","null"],"description":"The site carries display advertising."}}},"commercial_viability":{"type":"object","properties":{"score_0_100":{"type":["integer","null"],"description":"The score, or null."},"base_score_0_100":{"type":["integer","null"],"description":"Before penalties."},"band":{"type":["string","null"],"description":"The score as a band."},"confidence":{"type":["string","null"],"description":"How much evidence sits behind it."},"foundation_signals":{"type":"array","items":{"type":"array","items":{},"description":"The signals that let a score be produced at all."},"description":"The signals that let a score be produced at all."},"foundation_possible":{"type":["boolean","null"],"description":"Whether a score could be produced."},"traffic_source_penalty":{"type":["number","null"],"description":"Deduction for low quality traffic sources."},"signals":{"type":"array","items":{"type":"array","items":{},"description":"Everything that moved the score."},"description":"Everything that moved the score."}}},"apps_and_extensions":{"type":"object","properties":{"included":{"type":["boolean","null"],"description":"False means we could not look."},"app_advertised":{"type":["boolean","null"],"description":"The scan flagged an app."},"extension_advertised":{"type":["boolean","null"],"description":"The scan flagged an extension."},"item_count":{"type":["integer","null"],"description":"Store URLs captured."},"items":{"type":"array","items":{"type":"object","properties":{"kind":{"type":["string","null"],"description":"app or extension."},"store":{"type":["string","null"],"description":"Which store."},"url":{"type":["string","null"],"description":"Store listing URL."},"found_in":{"type":["string","null"],"description":"Where on the site it was found."}}}}}},"scanned_jurisdictions":{"type":"array","items":{"type":"object","properties":{"iso":{"type":["string","null"],"description":"Market code."},"country":{"type":["string","null"],"description":"Market name."},"last_scan":{"type":["string","null"],"format":"date","description":"Most recent scan in that market."},"scans":{"type":["integer","null"],"description":"How many runs we have done there."}}}},"trackback":{"type":"object","properties":{"is_trackback_user":{"type":["boolean","null"],"description":"Whether Trackback is on your account. False means the clicks figure is absent, not zero."},"clicks":{"type":["integer","null"],"description":"Clicks attributed to the domain, summed across every mapped account."}}},"job_log":{"type":"object","properties":{"rundate":{"type":["string","null"],"format":"date","description":"When the run happened."},"status":{"type":["string","null"],"description":"Run status."},"googlepages":{"type":["integer","null"],"description":"Pages indexed for the domain."},"rows":{"type":["integer","null"],"description":"Rows the run produced."}}},"compliance":{"type":"object","properties":{"has_affiliate_disclosure":{"type":["boolean","null"],"description":"An affiliate disclosure is present."},"has_disclaimer":{"type":["boolean","null"],"description":"A disclaimer is present."},"has_privacy_policy":{"type":["boolean","null"],"description":"A privacy policy is present."},"has_cookie_banner":{"type":["boolean","null"],"description":"A cookie banner is present."},"age_restriction_present":{"type":["boolean","null"],"description":"Age gating is present."},"age_restriction_min_age":{"type":["integer","null"],"description":"Minimum age stated."},"claims_regulated":{"type":["boolean","null"],"description":"The site claims to be regulated."},"regulator_names":{"type":"array","items":{"type":"array","items":{},"description":"Regulators named."},"description":"Regulators named."},"claims_regulated_evidence":{"type":["string","null"],"description":"The phrase and any licence numbers found."},"endorsement_allusions":{"type":["boolean","null"],"description":"The site implies an endorsement."},"trustpilot_mentioned":{"type":["boolean","null"],"description":"Trustpilot is referenced."},"has_responsible_gambling_message":{"type":["boolean","null"],"description":"A responsible gambling message is present."},"has_self_exclusion":{"type":["boolean","null"],"description":"Self-exclusion information is present."}}},"risk_flags":{"type":"object","properties":{"unidentified_scripts":{"type":["boolean","null"],"description":"Scripts we could not identify. Not a malware finding on its own."},"auto_generated_pages":{"type":["boolean","null"],"description":"Pages appear machine generated."},"thin_or_spun_content":{"type":["boolean","null"],"description":"Content is thin or spun."},"dead_links_detected":{"type":["boolean","null"],"description":"Dead links found."},"placeholder_or_demo_content":{"type":["boolean","null"],"description":"Placeholder or template content left in place."},"low_effort_templating":{"type":["boolean","null"],"description":"Low effort templating."},"low_effort_templating_evidence":{"type":["string","null"],"description":"What was found."},"previous_abuse_reports":{"type":["boolean","null"],"description":"Prior abuse reports against the domain."},"browser_warnings":{"type":["boolean","null"],"description":"Browsers warn on the site."},"suspicious_popups":{"type":["boolean","null"],"description":"Suspicious popups."},"adult_content":{"type":["boolean","null"],"description":"Adult content."},"explicit_sexual_language":{"type":["boolean","null"],"description":"Explicit sexual language."},"hate_speech":{"type":["boolean","null"],"description":"Hate speech."},"harassment":{"type":["boolean","null"],"description":"Harassment."},"illegal_activity_references":{"type":["boolean","null"],"description":"References to illegal activity."},"violence_or_weapons_references":{"type":["boolean","null"],"description":"Violence or weapons references."},"excessive_swearing":{"type":["boolean","null"],"description":"Excessive swearing."},"impersonates_known_brand":{"type":["boolean","null"],"description":"The site impersonates a known brand."},"impersonated_brand_candidates":{"type":"array","items":{"type":"array","items":{},"description":"Which brands."},"description":"Which brands."},"unlicensed_gambling_signals":{"type":["boolean","null"],"description":"Signals of unlicensed gambling."}}},"risk_score_evidence":{"type":"object","properties":{"included":{"type":["boolean","null"],"description":"False when there is no score to explain."},"risk_score_0_100":{"type":["integer","null"],"description":"The score being explained."},"band":{"type":["string","null"],"description":"The band."},"what_fired":{"type":"array","items":{"type":"array","items":{},"description":"Every rule that contributed."},"description":"Every rule that contributed."},"verdicts":{"type":"array","items":{"type":"array","items":{},"description":"The judgements behind them."},"description":"The judgements behind them."},"checks_clear":{"type":"array","items":{"type":"array","items":{},"description":"Checks that passed. Useful for proving what was tested."},"description":"Checks that passed. Useful for proving what was tested."},"checks_clear_count":{"type":["integer","null"],"description":"How many passed."},"flagged":{"type":["boolean","null"],"description":"Whether compliance or brand bidding findings forced an override."},"flagged_by":{"type":"array","items":{"type":"array","items":{},"description":"Which of the two."},"description":"Which of the two."},"score_held_at_minimum":{"type":["boolean","null"],"description":"True when the score was floored by the override rather than earned by the scan."},"flag_reasons":{"type":"array","items":{"type":"array","items":{},"description":"One sentence per trigger."},"description":"One sentence per trigger."},"note":{"type":["string","null"],"description":"Anything else worth saying."}}},"compliance_reviews":{"type":"object","properties":{"flagged_count":{"type":["integer","null"],"description":"Items currently flagged."},"priority_count":{"type":["integer","null"],"description":"Of those, how many are priority."},"total_count":{"type":["integer","null"],"description":"Items of any state."},"isos_checked":{"type":"array","items":{"type":"array","items":{},"description":"Markets searched for findings."},"description":"Markets searched for findings."},"items":{"type":"array","items":{"type":"array","items":{},"description":"Each finding, with its state, market and evidence."},"description":"Each finding, with its state, market and evidence."}}},"ppc_brand_bidding":{"type":"object","properties":{"included":{"type":["boolean","null"],"description":"False means brand bidding checks are not available on this deployment - not that the domain is clean."},"monitoring_active":{"type":["boolean","null"],"description":"READ THIS BEFORE ad_count. False means we never looked, so zero ads is not an all clear."},"ad_count":{"type":["integer","null"],"description":"Ads found."},"isos_checked":{"type":"array","items":{"type":"array","items":{},"description":"Markets checked."},"description":"Markets checked."},"cycle":{"type":["string","null"],"description":"The window the check covers."},"ads":{"type":"array","items":{"type":"object","properties":{"iso":{"type":["string","null"],"description":"Market the ad ran in."},"search_terms":{"type":"array","items":{"type":"array","items":{},"description":"Terms that surfaced it."},"description":"Terms that surfaced it."},"ad_title":{"type":["string","null"],"description":"Ad headline."},"ad_text":{"type":["string","null"],"description":"Ad body."},"display_url":{"type":["string","null"],"description":"URL as shown."},"landing_url":{"type":["string","null"],"description":"Where it actually goes."},"advertiser_host":{"type":["string","null"],"description":"Host running the ad."},"position":{"type":["integer","null"],"description":"Position on the results page."},"first_seen":{"type":["string","null"],"format":"date","description":"First seen."},"last_seen":{"type":["string","null"],"format":"date","description":"Last seen."}}}},"other_advertisers":{"type":"object","properties":{"seen":{"type":["boolean","null"],"description":"Whether anyone else was bidding. Only populated when our own count is zero."},"ad_count":{"type":["integer","null"],"description":"How many ads. Count and markets only - never who they were."},"isos":{"type":"array","items":{"type":"array","items":{},"description":"Markets they ran in."},"description":"Markets they ran in."}}}}},"healthcheck_requests":{"type":"object","properties":{"this_month_count":{"type":["integer","null"],"description":"Requests this calendar month, against your allowance."},"latest_request_at":{"type":["string","null"],"format":"date-time","description":"When the last one was made."}}},"growth_target_pages":{"type":"object","properties":{"summary":{"type":"object","properties":{"page_count":{"type":["integer","null"],"description":"Pages after the growth filters."},"scored_pages_total":{"type":["integer","null"],"description":"Pages scored before filtering. The gap between the two is explained by filtered_out."},"highest_topic_score":{"type":["number","null"],"description":"Best topic score in the filtered set."},"average_topic_score":{"type":["number","null"],"description":"Average across it."},"total_adjusted_aar":{"type":["number","null"],"description":"Adjusted addressable audience reach."},"total_original_aar":{"type":["number","null"],"description":"Before adjustment."},"competitor_count":{"type":["integer","null"],"description":"Competitors present on those pages."},"client_brand_mentions":{"type":["integer","null"],"description":"Times you are mentioned."},"client_brand_links":{"type":["integer","null"],"description":"Times you are linked."},"priority_band_counts":{"type":"object","description":"Pages in each priority band, priority_1 to priority_4."},"filtered_out":{"type":"object","description":"How many pages each rule removed, so the drop is reconcilable."},"filter":{"type":"object","description":"The rules themselves: admin_accepted_only, opportunity_types, scan_window_days, suppression_months, workflow_hidden."}}},"pages":{"type":"array","items":{"type":"object","properties":{"url":{"type":["string","null"],"description":"Canonical page URL."},"opportunity_type":{"type":["string","null"],"description":"new or improve. Pages where you already outrank the competitor are excluded."}}}}}},"offers":{"type":"object","properties":{"monitored":{"type":["boolean","null"],"description":"Whether offers are monitored here."},"page_count":{"type":["integer","null"],"description":"Pages with monitored offers."},"oldest_scan_at":{"type":["string","null"],"format":"date-time","description":"Oldest offer scan in the set."},"is_fresh":{"type":["boolean","null"],"description":"Whether offer data postdates the last domain scan."}}},"ai_influence":{"type":"object","properties":{"available":{"type":["boolean","null"],"description":"False when AI influence is not on your account."},"cited":{"type":["boolean","null"],"description":"Whether the domain is cited at all."},"citations":{"type":["integer","null"],"description":"Citations for your product profiles."},"citations_all_clients":{"type":["integer","null"],"description":"Citations across every profile we track. Context for the number above."},"cited_urls":{"type":["integer","null"],"description":"Distinct URLs cited for you."},"cited_urls_all":{"type":["integer","null"],"description":"Distinct URLs cited for anyone."},"profiles_citing":{"type":["integer","null"],"description":"How many profiles cite the domain."},"verticals":{"type":"array","items":{"type":"array","items":{},"description":"Sectors the citations sit in."},"description":"Sectors the citations sit in."},"example_phrases":{"type":"array","items":{"type":"array","items":{},"description":"Searches that produced a citation."},"description":"Searches that produced a citation."},"stability":{"type":["string","null"],"description":"Whether the citation pattern is holding."},"as_of":{"type":["string","null"],"format":"date","description":"Date the evidence carries."},"cited_pages":{"type":"array","items":{"type":"object","properties":{"url":{"type":["string","null"],"description":"A cited page."},"citations":{"type":["integer","null"],"description":"Citations for that page, summed across searches."},"last_seen":{"type":["string","null"],"format":"date","description":"Most recent citation."},"cited_for":{"type":"array","items":{"type":"array","items":{},"description":"Up to ten searches it was cited for."},"description":"Up to ten searches it was cited for."}}}},"cited_pages_total":{"type":["integer","null"],"description":"Cited pages before any page limit."},"your_profiles":{"type":"array","items":{"type":"array","items":{},"description":"Your product profiles the citations belong to."},"description":"Your product profiles the citations belong to."},"ownership_verified":{"type":["boolean","null"],"description":"False means we could not confirm the profiles are yours, so they are withheld."}}},"diagnostics":{"type":"object","properties":{"tables_used":{"type":"array","items":{"type":"array","items":{},"description":"Data sources that answered."},"description":"Data sources that answered."},"failures":{"type":"array","items":{"type":"array","items":{},"description":"Blocks that could not be built, and why."},"description":"Blocks that could not be built, and why."},"cwb_estate":{"type":["string","null"],"description":"Which compliance estate answered."}}}}},"examples":{"domain_get":{"summary":"Everything we hold on one domain","value":{"ok":true,"domain":{"domain":"example.com","iso":"GB","vertical":"ecommerce"},"traffic":{"approx":"~1m visits","top_countries":[{"iso":"GB","share_pct":62}]},"exposure":{"total_pages":37,"linked_pages_count":12},"risk_score_evidence":{"included":true,"score":20,"band":"low"},"social_profiles":{"summary":{"total_assets":3,"assessed":1,"assessed_for_you":1,"generic":2},"profiles":[{"platform":"tiktok","handle":"examplemedia","state":"assessed","assessed_for":{"basis":"your_account","assessed_for_you":true,"last_assessed":"2026-08-01 04:20:00"}},{"platform":"instagram","handle":"examplemedia","state":"unassessed","assessed_for":{"basis":"generic","assessed_for_you":false,"last_assessed":"2026-07-12 09:00:00","rescan_recommended":true}}]},"growth_target_pages":{"summary":{"page_count":4}},"ai_influence":{"available":true,"cited":true}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/apis/rightlander/social.php":{"get":{"operationId":"social_get","summary":"Everything we hold on one social profile","description":"Profile header and audience, posting cadence and engagement, the bio and the links inside it, the brands appearing in recent posts and how relevant each is to you, compliance findings with the posts that evidence them, and whether there is a gap worth approaching the account about.\n\nWhen to use it: Use this after /v1/assets has given you the platform and handle. You can pass the handle bare, with an @, or as a full profile URL.\n\nCost: free within your daily allowance. Permission: read.\n\nFreshness: Social profiles are assessed on a monthly cycle, or whenever a refresh is requested. status.last_scanned dates the evidence, and assessed_for.last_assessed_for_you dates the last one made against your own brands.\n\nNotes: Read assessed_for before acting on the brand and sector fields. A handle nobody has assessed returns 404; CHANGED 10 AUG, that used to also cover handles assessed for another account, which now return 200 marked generic. A handle with an assessment queued returns 200 with state \"requested\" - waiting and nothing-there are different answers.","tags":["Social profiles"],"parameters":[{"name":"platform","in":"query","required":true,"description":"Platform the profile is on. x is treated as twitter.","schema":{"type":"string","enum":["instagram","tiktok","youtube","pinterest","twitter"],"examples":["tiktok"]}},{"name":"handle","in":"query","required":true,"description":"Account handle. The @ and a full profile URL are both accepted.","schema":{"type":"string","examples":["examplemedia"]}},{"name":"sets","in":"query","required":false,"description":"Comma separated. Omit for everything. core is always returned.","schema":{"type":"string","enum":["core","intel","risk","growth","intel,risk"]}},{"name":"iso","in":"query","required":false,"description":"Market. Decides which product profile the brand relevance filter reads from.","schema":{"type":"string","examples":["GB"]}},{"name":"exclude","in":"query","required":false,"description":"Turns off blocks that are on by default. Each costs an extra lookup.","schema":{"type":"string","enum":["posts","bios","posts,bios"]}},{"name":"include","in":"query","required":false,"description":"raw attaches the underlying assessment payload. Large.","schema":{"type":"string","enum":["raw"]}},{"name":"usercode","in":"query","required":false,"description":"Only needed where product profiles are keyed per user. Defaults to the account.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success. Check ok before reading the rest.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":["boolean","null"],"description":"True on success, false on failure. Check this before anything else - an empty result and a failure are not the same thing."},"error":{"type":["string","null"],"description":"Human-readable message. Present only on failure."},"error_code":{"type":["string","null"],"description":"Stable code to branch on. Match on this, not on the message text."},"status":{"type":"object","properties":{"state":{"type":["string","null"],"description":"assessed or requested. A handle we hold nothing for returns 404 rather than an empty row."},"last_scanned":{"type":["string","null"],"format":"date-time","description":"When we last assessed it."},"scan_id":{"type":["integer","null"],"description":"Assessment run id."},"scan_status":{"type":["string","null"],"description":"Outcome of that run. A bad status is what explains a posting chart that looks out of date."},"limited_information":{"type":["boolean","null"],"description":"True when every score came back zero or null - a private or gated account, not a clean one."},"refreshable":{"type":["boolean","null"],"description":"Whether a refresh can be requested right now."},"cooldown_until":{"type":["string","null"],"format":"date-time","description":"When the seven-day cooldown lifts, if one is in force."},"request_status":{"type":["string","null"],"description":"Only when state is requested. Where the queued assessment has got to."}},"description":"HTTP status, repeated in the body for clients that cannot see it."},"request":{"type":"object","properties":{"queried_at":{"type":["string","null"],"format":"date-time","description":"When we answered."},"took_ms":{"type":["integer","null"],"description":"How long it took us."},"key_source":{"type":["string","null"],"description":"header or query - where your key was read from."},"rate_limit":{"type":"object","properties":{"requests_per_day":{"type":["integer","null"],"description":"Your daily allowance."},"used_today":{"type":["integer","null"],"description":"Requests used today."},"remaining":{"type":["integer","null"],"description":"What is left."},"resets_at":{"type":["string","null"],"format":"date-time","description":"When it resets. 00:00 UTC."}}},"credits_charged":{"type":["integer","null"],"description":"Credits taken by this request. Present only when it cost something."}}},"profile":{"type":"object","properties":{"platform":{"type":["string","null"],"description":"Platform key. x is normalised to twitter, so one account never looks like two."},"platform_label":{"type":["string","null"],"description":"Readable platform name."},"handle":{"type":["string","null"],"description":"Account handle, normalised - you may send it bare, with an @, or as a full profile URL."},"profile_id":{"type":["string","null"],"description":"Our id for the profile. Null when we hold no assessment."},"url":{"type":["string","null"],"description":"Profile URL."},"display_name":{"type":["string","null"],"description":"Display name."},"followers":{"type":["integer","null"],"description":"Audience size."},"posts_total":{"type":["integer","null"],"description":"Posts on the account."},"language":{"type":["string","null"],"description":"Detected language."},"location":{"type":["string","null"],"description":"Stated location."},"linked_domain":{"type":["string","null"],"description":"Domain the profile is connected to, where we have established one."}}},"refresh":{"type":"object","properties":{"available":{"type":["boolean","null"],"description":"Whether a refresh would be accepted."},"endpoint":{"type":["string","null"],"description":"Where to request one. Null on a platform we do not assess."},"credits":{"type":["integer","null"],"description":"What it would cost."},"reason":{"type":["string","null"],"description":"Why it is unavailable, when it is."}}},"sector_fit":{"type":"object","properties":{"verdict":{"type":["string","null"],"description":"core, adjacent, off or unknown."},"basis":{"type":["string","null"],"description":"brands or verticals - what the verdict was reached on."},"in_sector":{"type":["integer","null"],"description":"Brands in your sectors."},"adjacent":{"type":["integer","null"],"description":"Brands in adjacent sectors."},"unrelated":{"type":["integer","null"],"description":"Brands in neither."},"share_pct":{"type":["number","null"],"description":"Share of detected brands that are in or adjacent to your sectors."},"matched_verticals":{"type":"array","items":{"type":"array","items":{},"description":"Which of your sectors matched."},"description":"Which of your sectors matched."},"unknown_reason":{"type":["string","null"],"description":"Why the verdict is unknown. UNKNOWN IS NOT \"not relevant\" - it means we had nothing to judge on."}}},"brands":{"type":"object","properties":{"relevant":{"type":"array","items":{"type":"object","properties":{"brand":{"type":["string","null"],"description":"Brand name."},"vertical":{"type":["string","null"],"description":"The brand's own sector. This is what relevance is judged on, not the scan's relevance tag."},"entity_type":{"type":["string","null"],"description":"What kind of entity it is."},"client_relevance":{"type":["string","null"],"description":"own_brand, competitor, same_sector, adjacent_sector or unrelated."},"client_relevance_label":{"type":["string","null"],"description":"That tag in plain English."},"mention_count":{"type":["integer","null"],"description":"Posts mentioning it. Most-mentioned first."},"commercial_post_count":{"type":["integer","null"],"description":"Of those, how many were commercial."},"post_ids":{"type":"array","items":{"type":"array","items":{},"description":"Post ids, as STRINGS. Resolve them against posts_referenced."},"description":"Post ids, as STRINGS. Resolve them against posts_referenced."}}}},"relevant_count":{"type":["integer","null"],"description":"How many brands were kept."},"filtered_out":{"type":["integer","null"],"description":"How many were seen and dropped as irrelevant. This is what tells an empty list apart from a profile that mentioned no brands at all."},"basis":{"type":["string","null"],"description":"verticals, tokens, both, or none. none means the filter could not run, so nothing is claimed relevant."},"own_brand_excluded":{"type":["integer","null"],"description":"Mentions of the publisher's own brand, removed before filtering so they do not crowd out the ones that matter."},"client_sectors":{"type":"object","properties":{"same":{"type":"array","items":{"type":"array","items":{},"description":"Your sectors. Returned because \"why is my brand list empty\" is otherwise unanswerable from the response."},"description":"Your sectors. Returned because \"why is my brand list empty\" is otherwise unanswerable from the response."},"adjacent":{"type":"array","items":{"type":"array","items":{},"description":"Adjacent sectors, also counted."},"description":"Adjacent sectors, also counted."}}}}},"bio":{"type":"object","properties":{"label":{"type":["string","null"],"description":"What the platform calls the field. EMPTY MEANS THE PLATFORM HAS NO READABLE BIO, not that the account has none."},"links_label":{"type":["string","null"],"description":"links everywhere except TikTok, where they are the other accounts the creator connected - a different claim."},"text":{"type":["string","null"],"description":"Bio text."},"links":{"type":"array","items":{"type":"object","properties":{"url":{"type":["string","null"],"description":"Where it goes. On Twitter this is the expanded URL, not the t.co shortlink."},"title":{"type":["string","null"],"description":"Link title."},"type":{"type":["string","null"],"description":"Link type."}}}},"link_count":{"type":["integer","null"],"description":"How many, after de-duplication on the URL."}}},"posting_activity":{"type":"object","properties":{"window_days":{"type":["integer","null"],"description":"Days covered. Thirty, unless a brand mention older than that pulled the window back."},"window_widened_for_brands":{"type":["boolean","null"],"description":"Whether it was widened."},"window_end":{"type":["string","null"],"format":"date-time","description":"The end of the window. Dated when it has slid back to the last post we hold."},"window_is_stale":{"type":["boolean","null"],"description":"True when the window is not recent."},"posts":{"type":["integer","null"],"description":"Posts in the window."},"posts_per_week":{"type":["number","null"],"description":"Cadence."},"engagement_metric":{"type":["string","null"],"description":"What the platform measures - plays, likes and views are not interchangeable."},"engagement_total":{"type":["integer","null"],"description":"Total across the window."},"note":{"type":["string","null"],"description":"An empty window is NOT \"dormant\" - it means we hold nothing recent. window_end is what tells you which."}}},"engagement":{"type":"object","properties":{"metric":{"type":["string","null"],"description":"The metric, repeated on the headline block."},"total":{"type":["integer","null"],"description":"Total engagement."},"average_per_post":{"type":["integer","null"],"description":"Per post. Use this to compare accounts - a profile that posted twice cannot be ranked against one that posted fifty times on totals."},"posts_counted":{"type":["integer","null"],"description":"Posts behind the average."}},"description":"NULL rather than zero when we hold no posts: no data and no engagement are different answers."},"profile_overview":{"type":"object","properties":{"primary_geography":{"type":["string","null"],"description":"Where the audience mostly is."},"primary_geography_evidence":{"type":"array","items":{"type":"array","items":{},"description":"What that was inferred from."},"description":"What that was inferred from."},"audience_age_band":{"type":["string","null"],"description":"Inferred audience age."},"audience_age_confidence":{"type":["integer","null"],"description":"How confident that is."},"content_tone":{"type":"array","items":{"type":"array","items":{},"description":"Tone of the content."},"description":"Tone of the content."},"cta_intensity_0_100":{"type":["integer","null"],"description":"How hard the account sells."},"monetisation_intent":{"type":["string","null"],"description":"How the account makes money."},"monetisation_intent_confidence":{"type":["integer","null"],"description":"How confident that is."},"primary_language":{"type":["string","null"],"description":"Language of the content."},"language_quality_0_100":{"type":["integer","null"],"description":"How well written it is."}}},"profile_verticals":{"type":"array","items":{"type":"array","items":{},"description":"Sectors detected on the profile."},"description":"Sectors detected on the profile."},"scores":{"type":"object","properties":{"risk_score_0_100":{"type":["integer","null"],"description":"Risk. Higher is worse."},"risk_band":{"type":["string","null"],"description":"That score as a band."},"quality_score_0_100":{"type":["integer","null"],"description":"Content quality."},"audience_fit_score_0_100":{"type":["integer","null"],"description":"Fit with your market."},"professionalism_score_0_100":{"type":["integer","null"],"description":"Presentation."},"posts_assessed":{"type":["integer","null"],"description":"Posts the assessment looked at."},"limited_information":{"type":["boolean","null"],"description":"READ THIS BEFORE THE SCORES. True means every one came back zero or null, so they describe what we could see rather than the account."}}},"partner_signals":{"type":"object","properties":{"score":{"type":["integer","null"],"description":"Partner quality out of 4. Client-INDEPENDENT: it says the account is well run, not that it suits you. sector_fit answers that."},"matched":{"type":"array","items":{"type":"array","items":{},"description":"Which signals it scored on."},"description":"Which signals it scored on."}}},"risk_and_compliance":{"type":"object","properties":{"overall_risk_score_0_100":{"type":["integer","null"],"description":"The assessment's own risk figure."},"regulated_verticals":{"type":"array","items":{"type":"array","items":{},"description":"Regulated sectors the account posts in."},"description":"Regulated sectors the account posts in."},"age_restricted_risk":{"type":"object","properties":{"risk_level":{"type":["string","null"],"description":"Age-restricted content risk."},"audience_under_25_likely":{"type":["boolean","null"],"description":"Whether the audience skews young."},"evidence":{"type":"array","items":{"type":"array","items":{},"description":"What that was based on."},"description":"What that was based on."},"post_ids":{"type":"array","items":{"type":"array","items":{},"description":"Posts involved, as strings."},"description":"Posts involved, as strings."}}},"compliance_issues":{"type":"array","items":{"type":"object","properties":{"risk_type":{"type":["string","null"],"description":"What kind of issue."},"severity_score":{"type":["integer","null"],"description":"How serious."},"why_it_matters":{"type":["string","null"],"description":"Why it matters."},"evidence":{"type":"array","items":{"type":"array","items":{},"description":"The evidence."},"description":"The evidence."},"post_ids":{"type":"array","items":{"type":"array","items":{},"description":"Posts involved, as strings."},"description":"Posts involved, as strings."}}}},"compliance_issue_count":{"type":["integer","null"],"description":"How many issues."}}},"quality_metrics":{"type":"object","properties":{"overall_quality_0_100":{"type":["integer","null"],"description":"Overall."},"content_consistency_0_100":{"type":["integer","null"],"description":"How consistent the output is."},"brand_coherence_0_100":{"type":["integer","null"],"description":"How coherent the account is as a brand."},"audience_fit_0_100":{"type":["integer","null"],"description":"Fit between content and audience."},"authenticity_0_100":{"type":["integer","null"],"description":"Authenticity signals."},"professionalism_0_100":{"type":["integer","null"],"description":"Presentation."},"conversion_style_0_100":{"type":["integer","null"],"description":"How the account drives action."},"strengths":{"type":"array","items":{"type":"array","items":{},"description":"What it does well."},"description":"What it does well."},"weaknesses":{"type":"array","items":{"type":"array","items":{},"description":"What it does badly."},"description":"What it does badly."},"best_fit_brand_types":{"type":"array","items":{"type":"array","items":{},"description":"Brands it would suit."},"description":"Brands it would suit."},"avoid_if_sensitive":{"type":"array","items":{"type":"array","items":{},"description":"Reasons to steer clear if you are sensitive to them."},"description":"Reasons to steer clear if you are sensitive to them."}}},"assessment":{"type":"object","properties":{"recommendation":{"type":["string","null"],"description":"Our read on the account."},"confidence":{"type":["integer","null"],"description":"How confident that read is."},"summary":{"type":["string","null"],"description":"One paragraph."},"rationale":{"type":"array","items":{"type":"array","items":{},"description":"The reasoning, up to eight points."},"description":"The reasoning, up to eight points."}}},"growth":{"type":"object","properties":{"competitor_brands":{"type":"array","items":{"type":"object","properties":{"brand":{"type":["string","null"],"description":"A competitor the account already promotes."},"mention_count":{"type":["integer","null"],"description":"How often."}}}},"your_brand_mentions":{"type":["integer","null"],"description":"Times you appear."},"opportunity":{"type":["string","null"],"description":"A plain reading of the two counts, e.g. \"competitors are present and you are not\". Says \"not assessed\" when the relevance filter could not run."},"window_days":{"type":["integer","null"],"description":"The window those counts cover."}}},"posts_referenced":{"type":"array","items":{"type":"object","properties":{"post_id":{"type":["string","null"],"description":"The id, ALWAYS A STRING - a TikTok post id is past the point where JavaScript can hold it as a number without rounding."},"url":{"type":["string","null"],"description":"The post. Null when it has aged out of our posts table."},"posted_at":{"type":["string","null"],"format":"date-time","description":"When it was posted."},"engagement":{"type":"object","description":"Every engagement column the platform holds, keyed by what it measures."},"available":{"type":["boolean","null"],"description":"False for an id we can no longer resolve. It is still listed - omitting it would make a cited id look like an error."}}}}}},"examples":{"social_get":{"summary":"Everything we hold on one social profile","value":{"ok":true,"profile":{"platform":"tiktok","handle":"examplemedia","followers":84000},"assessed_for":{"basis":"generic","assessed_for_you":false,"last_assessed_for_you":null,"last_assessed":"2026-07-12 09:00:00","client_context_applied":false,"rescan_recommended":true,"note":"This profile has not been assessed against your brands and products..."},"status":{"state":"assessed","last_scanned":"2026-07-12 09:00:00","limited_information":false,"refreshable":true},"refresh":{"available":true,"endpoint":"/v1/social/tiktok/examplemedia/refresh","credits":10},"sector_fit":{"verdict":"core","in_sector":5,"share_pct":62},"brands":{"relevant_count":3,"filtered_out":8,"basis":"verticals","own_brand_excluded":10},"posting_activity":{"window_days":30,"posts":21,"engagement_metric":"plays"},"scores":{"risk_score_0_100":15,"risk_band":"low"},"growth":{"your_brand_mentions":0,"opportunity":"competitors are present and you are not"}}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Your Rightlander API key, created on the API Access page."},"apiKeyQuery":{"type":"apiKey","in":"query","name":"apikey","description":"The same key on the query string, for tools that cannot set a header. Prefer the header."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"type":["boolean","null"],"description":"True on success, false on failure. Check this before anything else - an empty result and a failure are not the same thing."},"error":{"type":["string","null"],"description":"Human-readable message. Present only on failure."},"error_code":{"type":["string","null"],"description":"Stable code to branch on. Match on this, not on the message text."},"status":{"type":["integer","null"],"description":"HTTP status, repeated in the body for clients that cannot see it."},"request":{"type":"object","properties":{"rate_limit":{"type":"object","properties":{"requests_per_day":{"type":["integer","null"],"description":"Your daily allowance."},"used_today":{"type":["integer","null"],"description":"Requests used today."},"remaining":{"type":["integer","null"],"description":"What is left."},"resets_at":{"type":["string","null"],"format":"date-time","description":"When it resets. 00:00 UTC."}}}}}}}},"responses":{"Error":{"description":"Failure. ok is false and error_code says why (see the Errors guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}