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.

Request

Header Parameters

x-hz-ad-api-token X-Hz-Ad-Api-Token

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

application/json

Body

required

screen_pixel_width Screen Pixel Width (integer)

Width of the screen in pixels

screen_pixel_height Screen Pixel Height (integer)

Height of the screen in pixels

country_code Country Code (string)required

Possible values: >= 2 characters and <= 2 characters

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

language_code Language Code (string)required

Possible values: >= 2 characters and <= 3 characters

ISO 639-2 language code

device_id Device Id (string)

Possible values: non-empty and <= 256 characters

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

Responses

200

Successful Response

Response 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)

application/json

Schema

Schema

opportunities

object[]

required

Array [

ad_url Ad Url (string)required

The URL to the ad

seconds Seconds (integer)required

The number of seconds the ad is

opportunity_id Opportunity Id (string)required

Possible values: non-empty

The ID of the ad opportunity

]

Example (from schema)

{
  "opportunities": [
    {
      "ad_url": "string",
      "seconds": 0,
      "opportunity_id": "string"
    }
  ]
}

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

application/json

Schema

Schema

auth_success Auth Success (boolean)

Default value: true

error_code Error Code (string)required
desc Desc (string)required

Example (from schema)

{
  "auth_success": true,
  "error_code": "string",
  "desc": "string"
}

422

Validation Error

application/json

Schema

Schema

detail

object[]

Array [

loc

object[]

required

Array [

anyOf

MOD1

string

MOD2

integer

]

msg Message (string)required

type Error Type (string)required

]

Example (from schema)

{
  "detail": [
    {
      "loc": [
        "string",
        0
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

500

Internal Server Error

Response 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)

Loading...