Skip to content
RallyHere Docs

Find Opportunities

POST
/ad/v1/opportunity

Find ad opportunities for the user given optional screen sizes. This will generate a new ad api token that is returned in the response header.

Authorizations

Parameters

Header Parameters

x-hz-ad-api-token

Optional header to make calling the endpoint faster by not requiring a new token to be generated.

string

Optional header to make calling the endpoint faster by not requiring a new token to be generated.

Request Body required

object
screen_pixel_width

Width of the screen in pixels

integer
screen_pixel_height

Height of the screen in pixels

integer
country_code
required

ISO 3166-1 alpha-2 country code for the user

string
>= 2 characters <= 2 characters
language_code
required

ISO 639-2 language code

string
>= 2 characters <= 3 characters
device_id

Unique Identifier for the device a session is started on. E.g should be the same for multiple users on the same device.

string
>= 1 characters <= 256 characters

Responses

200

Successful Response

object
opportunities
required
Array<object>
object
ad_url
required

The URL to the ad

string
seconds
required

The number of seconds the ad is

integer
opportunity_id
required

The ID of the ad opportunity

string
>= 1 characters

Headers

x-hz-ad-api-token
string

Provide this token to future requests for the same user to make their requests faster (as a new token doesn't need to be generated)

403

Error Codes:

  • auth_invalid_key_id - Invalid Authorization - Invalid Key ID in Access Token
  • auth_invalid_version - Invalid Authorization - version
  • auth_malformed_access - Invalid Authorization - malformed access token
  • auth_not_jwt - Invalid Authorization
  • auth_token_expired - Token is expired
  • auth_token_format - Invalid Authorization - {}
  • auth_token_invalid_claim - Token contained invalid claim value: {}
  • auth_token_invalid_type - Invalid Authorization - Invalid Token Type
  • auth_token_sig_invalid - Token Signature is invalid
  • auth_token_unknown - Failed to parse token
  • insufficient_permissions - Insufficient Permissions
object
auth_success
boolean
default: true
error_code
required
string
desc
required
string

422

Validation Error

object
detail
Array<object>
object
loc
required
Array
msg
required
string
type
required
string

500

Internal Server Error

Headers

x-hz-ad-api-token
string

Provide this token to future requests for the same user to make their requests faster (as a new token doesn't need to be generated)