Skip to content

Upsert targetings

PUT
/targetings
curl --request PUT \
--url https://portal.staging.arago-tech.com/targetings \
--header 'Authorization: <Authorization>' \
--header 'Content-Type: application/json' \
--data '{ "targetings": [ { "id": "63e2d42a27ad5f2b345ca123", "geo_area_id": "63e2d42a27ad5f2b345ca123", "distribution_channel_whitelist_urls": "https://cdn.example.com/bucket/owner_user_id/<hash>/whitelist.txt", "distribution_channel_blacklist_urls": "https://cdn.example.com/bucket/owner_user_id/<hash>/blacklist.txt", "frequency_cap": { "max_impressions": 10, "duration_days": 7 }, "ifa_whitelists": [ { "format": "IFA_FORMAT_TYPE_MD5", "url": "https://cdn.example.com/bucket/owner_user_id/<hash>/whitelist.txt" } ], "ifa_blacklists": [ { "format": "IFA_FORMAT_TYPE_MD5", "url": "https://cdn.example.com/bucket/owner_user_id/<hash>/blacklist.txt" } ], "deal_ids": [ "[PHONE]", "ABCDEFGHIJ" ], "device_types": [ "DEVICE_TYPE_PERSONAL_COMPUTER", "DEVICE_TYPE_PHONE", "DEVICE_TYPE_TABLET" ], "distribution_channel_types": [ "DISTRIBUTION_CHANNEL_TYPE_WEBSITE", "DISTRIBUTION_CHANNEL_TYPE_MOBILE_APP", "DISTRIBUTION_CHANNEL_TYPE_DOOH" ], "device_languages": [ "LANGUAGE_EN" ], "brand_safety_enabled": true, "retargeting": { "line_item_ids": [ "63e2d42a27ad5f2b345ca123", "63e2d42a27ad5f2b345ca124" ], "event_types": [ "EVENT_TYPE_IMPRESSION", "EVENT_TYPE_CLICK" ] } } ] }'

Creates or updates multiple targetings. Portal does not accept list file uploads; partners host .txt files in their own S3-compatible object storage and provide URLs. The platform downloads them server-to-server via S3. For generic HTTP(S) URLs fetched browser-side, a CORS rule on the partner server is required.

Request to upsert targetings

Media typeapplication/json
UpsertTargetingsRequest

Request to upsert targetings

object
targetings
required
Targetings

List of targetings to upsert

Array<object>
>= 1 items <= 3000 items
Targeting

Targeting details for upsert

object
id
Targeting ID

The targeting unique identifier. If not provided, a new targeting will be created.

string
Example
63e2d42a27ad5f2b345ca123
geo_area_id
Geo area ID

The geographical area unique identifier in hexadecimal format

string
Example
63e2d42a27ad5f2b345ca123
distribution_channel_whitelist_urls
Distribution channel whitelist URLs

Publicly readable S3-compatible object storage URL(s) of the partner-hosted .txt distribution channel whitelist file(s). Portal does not provide list file uploads; the platform downloads the file server-to-server via S3. For generic HTTP(S) URLs fetched browser-side, a CORS rule on the partner server is required.

Array<string>
Example
https://cdn.example.com/bucket/owner_user_id/<hash>/whitelist.txt
distribution_channel_blacklist_urls
Distribution channel blacklist URLs

Publicly readable S3-compatible object storage URL(s) of the partner-hosted .txt distribution channel blacklist file(s). Portal does not provide list file uploads; the platform downloads the file server-to-server via S3. For generic HTTP(S) URLs fetched browser-side, a CORS rule on the partner server is required.

Array<string>
Example
https://cdn.example.com/bucket/owner_user_id/<hash>/blacklist.txt
frequency_cap
Frequency cap

Frequency cap targeting settings limiting the number of impressions per user within a number of days

object
max_impressions
required

Maximum number of impressions per user within the duration

integer format: integer
>= 1 <= 100
Example
10
duration_days
required

Number of days over which the impression limit applies

integer format: integer
>= 1 <= 90
Example
7
ifa_whitelists
IFAs whitelist entries

Publicly readable S3-compatible object storage URL(s) of the partner-hosted .txt IFA whitelist file(s), paired with the hash format used by their entries. Portal does not provide list file uploads; the platform downloads the file server-to-server via S3. For generic HTTP(S) URLs fetched browser-side, a CORS rule on the partner server is required.

Array<object>

IFAList pairs an uploaded IFA list URL with the hash format used by its entries.

object
url
string
format
string
default: IFA_FORMAT_TYPE_UNSPECIFIED
Allowed values: IFA_FORMAT_TYPE_UNSPECIFIED IFA_FORMAT_TYPE_UUID IFA_FORMAT_TYPE_SHA256 IFA_FORMAT_TYPE_MD5
Example
[
{
"format": "IFA_FORMAT_TYPE_MD5",
"url": "https://cdn.example.com/bucket/owner_user_id/<hash>/whitelist.txt"
}
]
ifa_blacklists
IFAs blacklist entries

Publicly readable S3-compatible object storage URL(s) of the partner-hosted .txt IFA blacklist file(s), paired with the hash format used by their entries. Portal does not provide list file uploads; the platform downloads the file server-to-server via S3. For generic HTTP(S) URLs fetched browser-side, a CORS rule on the partner server is required.

Array<object>

IFAList pairs an uploaded IFA list URL with the hash format used by its entries.

object
url
string
format
string
default: IFA_FORMAT_TYPE_UNSPECIFIED
Allowed values: IFA_FORMAT_TYPE_UNSPECIFIED IFA_FORMAT_TYPE_UUID IFA_FORMAT_TYPE_SHA256 IFA_FORMAT_TYPE_MD5
Example
[
{
"format": "IFA_FORMAT_TYPE_MD5",
"url": "https://cdn.example.com/bucket/owner_user_id/<hash>/blacklist.txt"
}
]
deal_ids
Deal IDs

The deal IDs for the targeting

Array<string>
Example
[
"[PHONE]",
"ABCDEFGHIJ"
]
device_types
Device types

The device types for the targeting

Array<string>
Allowed values: DEVICE_TYPE_UNSPECIFIED DEVICE_TYPE_MOBILE_TABLET DEVICE_TYPE_PERSONAL_COMPUTER DEVICE_TYPE_CONNECTED_TV DEVICE_TYPE_PHONE DEVICE_TYPE_TABLET DEVICE_TYPE_CONNECTED_DEVICE DEVICE_TYPE_SET_TOP_BOX DEVICE_TYPE_OOH_DEVICE
Example
[
"DEVICE_TYPE_PERSONAL_COMPUTER",
"DEVICE_TYPE_PHONE",
"DEVICE_TYPE_TABLET"
]
distribution_channel_types
Distribution channel types

Allowed distribution channel types (website, mobile app, DOOH)

Array<string>
Allowed values: DISTRIBUTION_CHANNEL_TYPE_UNSPECIFIED DISTRIBUTION_CHANNEL_TYPE_WEBSITE DISTRIBUTION_CHANNEL_TYPE_MOBILE_APP DISTRIBUTION_CHANNEL_TYPE_DOOH
Example
[
"DISTRIBUTION_CHANNEL_TYPE_WEBSITE",
"DISTRIBUTION_CHANNEL_TYPE_MOBILE_APP",
"DISTRIBUTION_CHANNEL_TYPE_DOOH"
]
device_languages
Device languages

The device languages for the targeting

Array<string>
Allowed values: LANGUAGE_UNSPECIFIED AA AB AE AF AK AM AN AR AS AV AY AZ BA BE BG BH BI BM BN BO BR BS CA CE CH CO CR CS CU CV CY DA DE DV DZ EE EL EN EO ES ET EU FA FF FI FJ FO FR FY GA GD GL GN GU GV HA HE HI HR HT HU HY HZ IA ID IE IG II IK IO IS IT IU JA JV KA KG KI KJ KK KL KM KN KO KR KS KU KV KW KY LA LB LG LI LN LO LT LU LV MG MH MI MK ML MN MR MS MT MY NA NB ND NE NG NL NN NO NR NV NY OC OJ OM OR OS PA PI PL PS PT QU RM RN RO RU RW SA SC SD SE SG SI SK SL SM SN SO SQ SR SS ST SU SV SW TA TE TG TH TI TK TL TN TO TR TS TT TW TY UG UK UR UZ VE VI VO WA WO XH YI YO ZA ZH ZU
Example
[
"LANGUAGE_EN"
]
brand_safety_enabled
Brand safety enabled

Enables brand safety targeting

boolean
Example
true
retargeting
Retargeting

Retargeting settings allowing a bid only when the user was already reached by one of the source line items

object
line_item_ids
required
Source line item IDs

The unique identifiers of the line items owned by the account whose previous delivery is retargeted

Array<string>
>= 1 items <= 3000 items unique items
Example
[
"63e2d42a27ad5f2b345ca123",
"63e2d42a27ad5f2b345ca124"
]
event_types
Event types

The events a user must have triggered on the source line items to be retargeted, among EVENT_TYPE_IMPRESSION, EVENT_TYPE_VIEWABLE_MRC_50 and EVENT_TYPE_CLICK; any event when empty

Array<string>
<= 3 items unique items
Allowed values: EVENT_TYPE_UNSPECIFIED EVENT_TYPE_LOADED EVENT_TYPE_IMPRESSION EVENT_TYPE_VIEWABILITY_MEASURABLE EVENT_TYPE_VIEWABLE_MRC_50 EVENT_TYPE_VIEWABLE_MRC_100 EVENT_TYPE_VIEWABLE_VIDEO_50 EVENT_TYPE_CLICK
Example
[
"EVENT_TYPE_IMPRESSION",
"EVENT_TYPE_CLICK"
]

A successful response.

Media typeapplication/json
UpsertTargetingsResponse

Response containing the upserted targetings

object
targetings
Targetings

List of targetings

Array<object>
Targeting

The targeting information

object
id
Targeting ID

The targeting unique identifier in hexadecimal format

string
geo_area_id
Geo area ID

The geographical area unique identifier in hexadecimal format

string
distribution_channel_whitelist_urls
Distribution channel whitelist URLs

Publicly readable S3-compatible object storage URL(s) of the partner-hosted .txt distribution channel whitelist file(s). Portal does not provide list file uploads; the platform downloads the file server-to-server via S3. For generic HTTP(S) URLs fetched browser-side, a CORS rule on the partner server is required.

Array<string>
distribution_channel_blacklist_urls
Distribution channel blacklist URLs

Publicly readable S3-compatible object storage URL(s) of the partner-hosted .txt distribution channel blacklist file(s). Portal does not provide list file uploads; the platform downloads the file server-to-server via S3. For generic HTTP(S) URLs fetched browser-side, a CORS rule on the partner server is required.

Array<string>
frequency_cap
Frequency cap

Frequency cap targeting settings limiting the number of impressions per user within a number of days

object
max_impressions
required

Maximum number of impressions per user within the duration

integer format: integer
>= 1 <= 100
duration_days
required

Number of days over which the impression limit applies

integer format: integer
>= 1 <= 90
created_at
Created At

The creation date and time of the targeting

string format: date-time
updated_at
Updated At

The last update date and time of the targeting

string format: date-time
ifa_whitelists
IFAs whitelist entries

Publicly readable S3-compatible object storage URL(s) of the partner-hosted .txt IFA whitelist file(s), paired with the hash format used by their entries. Portal does not provide list file uploads; the platform downloads the file server-to-server via S3. For generic HTTP(S) URLs fetched browser-side, a CORS rule on the partner server is required.

Array<object>
Messages for IFA List
object
url
string
format
string
default: IFA_FORMAT_TYPE_UNSPECIFIED
Allowed values: IFA_FORMAT_TYPE_UNSPECIFIED IFA_FORMAT_TYPE_UUID IFA_FORMAT_TYPE_SHA256 IFA_FORMAT_TYPE_MD5
ifa_blacklists
IFAs blacklist entries

Publicly readable S3-compatible object storage URL(s) of the partner-hosted .txt IFA blacklist file(s), paired with the hash format used by their entries. Portal does not provide list file uploads; the platform downloads the file server-to-server via S3. For generic HTTP(S) URLs fetched browser-side, a CORS rule on the partner server is required.

Array<object>
Messages for IFA List
object
url
string
format
string
default: IFA_FORMAT_TYPE_UNSPECIFIED
Allowed values: IFA_FORMAT_TYPE_UNSPECIFIED IFA_FORMAT_TYPE_UUID IFA_FORMAT_TYPE_SHA256 IFA_FORMAT_TYPE_MD5
deal_ids
Deal IDs

The deal IDs for the targeting

Array<string>
device_types
Device types

The device types for the targeting

Array<string>
Allowed values: DEVICE_TYPE_UNSPECIFIED DEVICE_TYPE_MOBILE_TABLET DEVICE_TYPE_PERSONAL_COMPUTER DEVICE_TYPE_CONNECTED_TV DEVICE_TYPE_PHONE DEVICE_TYPE_TABLET DEVICE_TYPE_CONNECTED_DEVICE DEVICE_TYPE_SET_TOP_BOX DEVICE_TYPE_OOH_DEVICE
distribution_channel_types
Distribution channel types

Allowed distribution channel types (website, mobile app, DOOH)

Array<string>
Allowed values: DISTRIBUTION_CHANNEL_TYPE_UNSPECIFIED DISTRIBUTION_CHANNEL_TYPE_WEBSITE DISTRIBUTION_CHANNEL_TYPE_MOBILE_APP DISTRIBUTION_CHANNEL_TYPE_DOOH
device_languages
Device languages

The device languages for the targeting

Array<string>
Allowed values: LANGUAGE_UNSPECIFIED AA AB AE AF AK AM AN AR AS AV AY AZ BA BE BG BH BI BM BN BO BR BS CA CE CH CO CR CS CU CV CY DA DE DV DZ EE EL EN EO ES ET EU FA FF FI FJ FO FR FY GA GD GL GN GU GV HA HE HI HR HT HU HY HZ IA ID IE IG II IK IO IS IT IU JA JV KA KG KI KJ KK KL KM KN KO KR KS KU KV KW KY LA LB LG LI LN LO LT LU LV MG MH MI MK ML MN MR MS MT MY NA NB ND NE NG NL NN NO NR NV NY OC OJ OM OR OS PA PI PL PS PT QU RM RN RO RU RW SA SC SD SE SG SI SK SL SM SN SO SQ SR SS ST SU SV SW TA TE TG TH TI TK TL TN TO TR TS TT TW TY UG UK UR UZ VE VI VO WA WO XH YI YO ZA ZH ZU
brand_safety_enabled
Brand safety enabled

Enables brand safety targeting

boolean
retargeting
Retargeting

Retargeting settings allowing a bid only when the user was already reached by one of the source line items

object
line_item_ids
required
Source line item IDs

The unique identifiers of the line items whose previous delivery is retargeted

Array<string>
>= 1 items <= 3000 items unique items
event_types
Event types

The events a user must have triggered on the source line items to be retargeted, among EVENT_TYPE_IMPRESSION, EVENT_TYPE_VIEWABLE_MRC_50 and EVENT_TYPE_CLICK; any event when empty

Array<string>
<= 3 items unique items
Allowed values: EVENT_TYPE_UNSPECIFIED EVENT_TYPE_LOADED EVENT_TYPE_IMPRESSION EVENT_TYPE_VIEWABILITY_MEASURABLE EVENT_TYPE_VIEWABLE_MRC_50 EVENT_TYPE_VIEWABLE_MRC_100 EVENT_TYPE_VIEWABLE_VIDEO_50 EVENT_TYPE_CLICK
Example
{
"targetings": [
{
"id": "63e2d42a27ad5f2b345ca123",
"geo_area_id": "63e2d42a27ad5f2b345ca123",
"distribution_channel_whitelist_urls": "https://cdn.example.com/bucket/owner_user_id/<hash>/whitelist.txt",
"distribution_channel_blacklist_urls": "https://cdn.example.com/bucket/owner_user_id/<hash>/blacklist.txt",
"frequency_cap": {
"max_impressions": 10,
"duration_days": 7
},
"created_at": "2021-01-01T00:00:00Z",
"updated_at": "2021-01-01T00:00:00Z",
"ifa_whitelists": [
{
"format": "IFA_FORMAT_TYPE_MD5",
"url": "https://cdn.example.com/bucket/owner_user_id/<hash>/whitelist.txt"
}
],
"ifa_blacklists": [
{
"format": "IFA_FORMAT_TYPE_MD5",
"url": "https://cdn.example.com/bucket/owner_user_id/<hash>/blacklist.txt"
}
],
"deal_ids": [
"0123456789",
"ABCDEFGHIJ"
],
"device_types": [
"DEVICE_TYPE_PERSONAL_COMPUTER",
"DEVICE_TYPE_PHONE",
"DEVICE_TYPE_TABLET"
],
"distribution_channel_types": [
"DISTRIBUTION_CHANNEL_TYPE_WEBSITE",
"DISTRIBUTION_CHANNEL_TYPE_MOBILE_APP",
"DISTRIBUTION_CHANNEL_TYPE_DOOH"
],
"device_languages": [
"LANGUAGE_EN"
],
"brand_safety_enabled": true,
"retargeting": {
"line_item_ids": [
"63e2d42a27ad5f2b345ca123",
"63e2d42a27ad5f2b345ca124"
],
"event_types": [
"EVENT_TYPE_IMPRESSION",
"EVENT_TYPE_CLICK"
]
}
}
]
}

Bad request

Media typeapplication/json
object
Example
{
"error": {
"code": "BAD_REQUEST",
"details": [
{
"code": "MAX_ITEMS",
"field": "line_items",
"message": "value must contain no more than 3000 item(s)",
"params": {
"max": "3000"
}
}
],
"message": "Bad request"
}
}

Unauthorized

Media typeapplication/json
object
Example
{
"error": {
"code": "UNAUTHORIZED",
"message": "Unauthorized"
}
}

Internal server error

Media typeapplication/json
object
Example
{
"error": {
"code": "INTERNAL_ERROR",
"message": "Internal server error"
}
}

An unexpected error response.

Media typeapplication/json
object
code
integer format: int32
message
string
details
Array<object>
object
@type
string
key
additional properties
any
Examplegenerated
{
"code": 1,
"message": "example",
"details": [
{
"@type": "example"
}
]
}