openapi: 3.0.0
info:
title: Sovrn Commerce Bid Check API
version: 1.0.0
description: Harvested verbatim from the OpenAPI definitions Sovrn publishes inside its Sovrn Developer
Center reference pages at https://developer.sovrn.com/. Operations sharing this info/servers block
were merged into one document by API Evangelist; operation content is unmodified.
x-source-title: Bid Check
servers:
- url: https://api.viglink.com
description: Production
components:
schemas:
BidWin:
type: object
description: Returned when Sovrn returns a bid or offer for the click.
required:
- affiliated
- pricing
- eepc
- url
properties:
affiliated:
type: boolean
description: '`true` when Sovrn returns a bid or offer for the click.'
example: true
pricing:
type: string
description: 'Pricing model of the winning bid or offer. `CPC` is a real-time bid win. `CPA`
is returned when `includeCpa=true` and a CPA offer wins.
'
enum:
- CPC
- CPA
example: CPC
eepc:
type: number
format: float
description: 'Expected earnings per click, in USD. This value is returned after Sovrn''s revenue
share is deducted. For CPC bids, this is the rate you can earn by routing the click through
Sovrn before the bid expires. For CPA offers, this is the average amount Sovrn expects you
to earn per click and is not guaranteed for an individual click.
'
example: 0.05725
url:
type: string
format: uri
description: 'Sovrn redirect URL to use if you route the click through Sovrn. Visiting this
URL tracks the click and forwards the user to the destination URL.
'
example: https://redirect.viglink.com?u=https%3A%2F%2Fexample-merchant.com&key=YOUR_API_KEY
expireInMs:
type: integer
description: 'Length of time the returned bid is valid, in milliseconds. Returned for CPC wins
only. If you redirect the user after the bid expires, the click is still tracked and affiliated
through standard link optimization at the current market rate.
'
example: 250
BidNoFill:
type: object
description: 'Returned when there is no eligible bid, the destination URL is not monetizable, or
the available bid is below the submitted bid floor.
'
required:
- affiliated
properties:
affiliated:
type: boolean
description: '`false` when there is no eligible bid, the destination URL is not monetizable,
or the available bid is below the submitted `bidFloor`.
'
example: false
paths:
/api/bid:
get:
summary: Bid Check
description: Get a real-time Sovrn bid on your click traffic.
operationId: getBid
parameters:
- name: key
in: query
required: true
description: 'Site Commerce API Key for the site or traffic source where the click originated.
Use the API Key that corresponds to the site, app, or traffic source sending the click so the
bid is evaluated and attributed correctly.
'
schema:
type: string
example: YOUR_API_KEY
- name: out
in: query
required: true
description: 'Destination URL for the click. This value must be URL-encoded when placed in the
query string.
'
schema:
type: string
format: uri
example: https://example-merchant.com
- name: ip
in: query
required: true
description: 'The real end user''s IP address. IPv4 and IPv6 are supported. Pass the end user''s
actual IP address, not the IP address of your server. This value must match the user who is
redirected through Sovrn for the bid to be valid.
'
schema:
type: string
example: 192.0.2.1
- name: userAgent
in: query
required: true
description: 'The real end user''s browser User-Agent string. Pass the end user''s actual User-Agent,
not the User-Agent of your server. This value must match the user who is redirected through
Sovrn for the bid to be valid. This value must be URL-encoded when placed in the query string.
'
schema:
type: string
example: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko)
Chrome/120.0.0.0 Safari/537.36
- name: referrerUrl
in: query
required: false
description: 'Page URL where the click originated. This value must be URL-encoded when placed
in the query string.
'
schema:
type: string
format: uri
example: https://example-publisher.com/article
- name: subId
in: query
required: false
description: 'Fully qualified SubID URL used to associate the click with a child campaign, placement,
domain, or publisher under the parent API Key. If the SubID does not already exist, Sovrn will
create it. This value must be URL-encoded when placed in the query string.
'
schema:
type: string
format: uri
example: https://example-publisher.com/placement/homepage
- name: bidFloor
in: query
required: false
description: 'Minimum acceptable bid, in USD, expressed as a decimal. For example, `0.01` means
one cent. When provided, bids below this value return `affiliated: false`. If omitted, no minimum
bid floor is applied.
'
schema:
type: number
format: float
example: 0.01
- name: includeCpa
in: query
required: false
description: 'When `true`, CPA offers are considered alongside CPC bids. If a CPA offer wins,
the response `pricing` will be `CPA`. If omitted, only CPC bids are considered.
'
schema:
type: boolean
example: false
- name: cuid
in: query
required: false
description: An identifier of your choosing used to associate the click with a user, page, campaign,
or event. Use only letters, numbers, hyphens, and underscores. Maximum 2048 characters.
schema:
type: string
maxLength: 2048
pattern: ^[A-Za-z0-9_-]+$
example: user_12345
- name: utm_source
in: query
required: false
description: Identifies the source of the traffic, such as a website, newsletter, or social platform.
Use only letters, numbers, hyphens, and underscores.
schema:
type: string
pattern: ^[A-Za-z0-9_-]+$
example: newsletter
- name: utm_medium
in: query
required: false
description: Identifies the marketing medium, such as email, social, or banner. Use only letters,
numbers, hyphens, and underscores.
schema:
type: string
pattern: ^[A-Za-z0-9_-]+$
example: email
- name: utm_campaign
in: query
required: false
description: Identifies the campaign name, promotion, or initiative. Use only letters, numbers,
hyphens, and underscores.
schema:
type: string
pattern: ^[A-Za-z0-9_-]+$
example: black_friday_2025
- name: utm_term
in: query
required: false
description: Identifies paid search keywords or targeting terms. Use only letters, numbers, hyphens,
and underscores.
schema:
type: string
pattern: ^[A-Za-z0-9_-]+$
example: running_shoes
- name: utm_content
in: query
required: false
description: Differentiates similar links or placements on the same page. Use only letters, numbers,
hyphens, and underscores.
schema:
type: string
pattern: ^[A-Za-z0-9_-]+$
example: header
- name: gdprApplies
in: query
required: false
description: 'Indicates whether GDPR applies to the user. If omitted, Sovrn determines whether
GDPR applies based on the user''s IP address.
'
schema:
type: boolean
example: false
- name: gdprConsent
in: query
required: false
description: 'Raw GDPR consent string for the user, when applicable.
'
schema:
type: string
example: COwK7daOwK7daABABBENAPCgAAAAAAAAAAYgAAAAAAAA
- name: ccpaConsent
in: query
required: false
description: 'Raw CCPA consent string for the user, when applicable.
'
schema:
type: string
example: 1YNN
- name: gppConsent
in: query
required: false
description: 'Raw GPP consent string for the user, when applicable.
'
schema:
type: string
example: DBABMA~CPXxRfAPXxRfAAfKABENB-CgAAAAAAAAAAYgAAAAAAAA
responses:
'200':
description: Success — bid response returned.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BidWin'
- $ref: '#/components/schemas/BidNoFill'
examples:
cpcWin:
summary: CPC win
value:
affiliated: true
pricing: CPC
eepc: 0.05725
url: https://redirect.viglink.com?u=https%3A%2F%2Fexample-merchant.com&key=YOUR_API_KEY&prodOvrd=PRE&fbu=https%3A%2F%2Fexample-merchant.com&bf=0.01&redirClientIp=192.0.2.1&userAgent=Mozilla%2F5.0+%28Macintosh%3B+Intel+Mac+OS+X+10_15_7%29+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%29+Chrome%2F120.0.0.0+Safari%2F537.36&sid=EXAMPLE_SID
expireInMs: 250
cpaWin:
summary: CPA win (includeCpa=true)
value:
affiliated: true
pricing: CPA
eepc: 0.016875
url: https://redirect.viglink.com?u=https%3A%2F%2Fexample-merchant.com&key=YOUR_API_KEY&prodOvrd=PRE&fbu=https%3A%2F%2Fexample-merchant.com&bf=0.01&redirClientIp=192.0.2.1&userAgent=Mozilla%2F5.0+%28Macintosh%3B+Intel+Mac+OS+X+10_15_7%29+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%29+Chrome%2F120.0.0.0+Safari%2F537.36
noFill:
summary: No bid or not monetizable
value:
affiliated: false
'400':
description: 'Bad Request — one or more required fields are missing or malformed.
'
'401':
description: 'Unauthorized — the provided `key` is not a valid Commerce API Key.
'
'500':
description: Internal Server Error.