Use cases

Adding a resource

To add a resource, use the POST/{resource-id} request.

Request:

curl -v -H "Accept: application/vnd.api+json" \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: token ac3b42lp-89ls-..." \
-X POST 
--data \
  '{
     "data":{
       "type":"context_on_site_campaign",
       "attributes":{
         "domain_id":115505,
         "caption":"Test"
       }
     }
   }' \
 'https://jsonapi.partner2.yandex.com/v1/context_on_site_campaign' | json_pp

Response:

HTTP/1.1 201 Created
Content-Length: 2014
Content-Type: application/vnd.api+json
Date: Fri, 13 Nov 2020 11:14:52 GMT
Location: https://jsonapi.partner2.yandex.com:443/v1/context_on_site_campaign/672422
Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff{
   "data" :{
      "attributes" :{},
      "id" : "672422",
      "links" :{
         "self" : "https://jsonapi.partner2.yandex.com:443/v1/context_on_site_campaign/672422"
      },
      "relationships" :{
         "blocks" :{
            "links" :{
               "related" : "https://jsonapi.partner2.yandex.com:443/v1/context_on_site_campaign/672422/blocks",
               "self" : "https://jsonapi.partner2.yandex.com:443/v1/context_on_site_campaign/672422/relationships/blocks"
            }
         },
         "context_on_site_adblock" :{
            "links" :{
               "related" : "https://jsonapi.partner2.yandex.com:443/v1/context_on_site_campaign/672422/context_on_site_adblock",
               "self" : "https://jsonapi.partner2.yandex.com:443/v1/context_on_site_campaign/672422/relationships/context_on_site_adblock"
            }
         },
         "context_on_site_content" :{
            "links" :{
               "related" : "https://jsonapi.partner2.yandex.com:443/v1/context_on_site_campaign/672422/context_on_site_content",
               "self" : "https://jsonapi.partner2.yandex.com:443/v1/context_on_site_campaign/672422/relationships/context_on_site_content"
            }
         },
         "context_on_site_direct" :{
            "links" :{
               "related" : "https://jsonapi.partner2.yandex.com:443/v1/context_on_site_campaign/672422/context_on_site_direct",
               "self" : "https://jsonapi.partner2.yandex.com:443/v1/context_on_site_campaign/672422/relationships/context_on_site_direct"
            }
         },
         "context_on_site_natural" :{
            "links" :{
               "related" : "https://jsonapi.partner2.yandex.com:443/v1/context_on_site_campaign/672422/context_on_site_natural",
               "self" : "https://jsonapi.partner2.yandex.com:443/v1/context_on_site_campaign/672422/relationships/context_on_site_natural"
            }
         },
         "context_on_site_rtb" :{
            "links" :{
               "related" : "https://jsonapi.partner2.yandex.com:443/v1/context_on_site_campaign/672422/context_on_site_rtb",
               "self" : "https://jsonapi.partner2.yandex.com:443/v1/context_on_site_campaign/672422/relationships/context_on_site_rtb"
            }
         },
         "context_on_site_stripe" :{
            "links" :{
               "related" : "https://jsonapi.partner2.yandex.com:443/v1/context_on_site_campaign/672422/context_on_site_stripe",
               "self" : "https://jsonapi.partner2.yandex.com:443/v1/context_on_site_campaign/672422/relationships/context_on_site_stripe"
            }
         }
      },
      "type" : "context_on_site_campaign"
   }
}

Adding a domain

To add a domain, use the POST/{resource-id} request.

Request:

curl -v -H "Accept: application/vnd.api+json" \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: token ac3b42lp-89ls-..." \
-X POST \
--data \
  '{
     "data":{
       "type":"site",
       "attributes":{
         "domain":"mysite.com"
       }
     }
   }' \
'https://jsonapi.partner2.yandex.com/v1/site' | json_pp

Response:

HTTP/1.1 201 Created
Content-Length: 147
Content-Type: application/vnd.api+json
Date: Fri, 13 Nov 2020 11:26:47 GMT
Location: https://jsonapi.partner2.yandex.com/v1/site/184480
Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff{
   "data" :{
      "attributes" :{},
      "id" : "184480",
      "links" :{
         "self" : "https://jsonapi.partner2.yandex.com/v1/site/184480"
      },
      "relationships" :{},
      "type" : "site"
   }
}

Verifying domain ownership

Get the SITE_OWNER_ID of the object that stores the ownership verification status using the PAGE_ID. To do this, send a GET/{resource-id}/{object-id} request with the include=site_owner parameter.

The response returns SITE_OWNER_ID in the id field of the site_owner object inside the included array.
Request:
```
curl -s https://jsonapi.partner2.yandex.com/v1/context_on_site_campaign/{PAGE_ID}?include=site_owner \
-H "Authorization: $TOKEN"
```
Response:
```
{
  "included": [{
      "id": "123",
      "type": "site_owner",
      ...
    }
  ],
  ...
}
```
Fetch available verification methods using the GET/{resource-id}/{object-id} request.
```
curl -s https://jsonapi.partner2.yandex.com/v1/site_owner/{SITE_OWNER_ID}?fields[site_owner]=actions \
-H "Authorization: $TOKEN"
```
Ownership verification actions:
- confirm_ownership_via_file: Verify using an ads.txt file.
- confirm_ownership_via_webmaster: Verify using Yandex Webmaster.
Verify ownership using one of the following methods:
Ads.txt file

Yandex Webmaster
1. Add an ads.txt file to your site:
  1. Download the ads.txt file in the verification form or under Settings → General.
  2. If you already have an ads.txt file on your site, copy the lines from the downloaded file into it. If you don't have one yet, use the downloaded file as is.
  3. Upload the file to your site so it can be accessed at example.com/ads.txt.
2. Run verification using the POST/{resource-id}/{object-id}/action/{action-name} request:
  curl -s -X POST \ "https://jsonapi.partner2.yandex.com/v1/site_owner/{SITE_OWNER_ID}/action/confirm_ownership_via_file" \ -H "Authorization: $TOKEN"
1. Verify site ownership in Yandex Webmaster using one of the following methods:
  - HTML file in the root directory of your site.
  - Meta tag on your home page.
  - TXT record in your DNS settings.
  - Tag manager (YTM or GTM).
  For instructions, see Verifying the site rights in Yandex Webmaster Help.
2. Run verification using the POST/{resource-id}/{object-id}/action/{action-name} request:
  curl -s -X POST \ "https://jsonapi.partner2.yandex.com/v1/site_owner/{SITE_OWNER_ID}/action/confirm_ownership_via_webmaster" \ -H "Authorization: $TOKEN"

To check the verification status and see when you can try again, use the GET/{resource-id}/{object-id} request:

curl -s "https://jsonapi.partner2.yandex.com/v1/site_owner/{SITE_OWNER_ID}?fields[site_owner]=ownership_successfully_confirmed,file_verification_status,file_verification_not_available_until,webmaster_verification_status,webmaster_verification_not_available_until,actions" \
-H "Authorization: $TOKEN"

Adding an RTB unit with a strategy

To add an RTB unit with the “Maximize revenue” strategy, use the POST/{resource-id} request.

$PI_TOKEN must contain the token value for the partner interface API. For example, the value can start with “a7b8e0-”. Make sure to set a custom value for page_id.

Request:

curl -v -H "Accept: application/vnd.api+json" \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: token $PI_TOKEN" \
-X POST \
--data \
  '{
    "data":{
      "type":"context_on_site_rtb",
      "attributes":{
        "caption":"API-created block",
        "page_id": "636326",
        
        "block_type": "banner",
        "design_templates":[{
            "caption":"Media design",
            "type":"media",
            "design_settings":{
              "filterSizes":false,
              "horizontalAlign":true
            }
          },{
            "caption":"Standard design",
            "type":"tga",
            "filter_tags":["adaptive","vertical"],
            "is_custom_format_direct": false, 
            "design_settings":{
              "name":"adaptive0418",
              "limit":1
            }                    
          }
        ],
        "dsp_blocks":["300x300","300x500","300x600","336x280","100%x250"],
        "blind":0,
        "strategy":1
      }
    }
  }' \
'https://jsonapi.partner2.yandex.com/v1/context_on_site_rtb' | json_pp

Response:

HTTP/1.1 201 Created
Content-Length: 683
Content-Type: application/vnd.api+json
Date: Fri, 13 Nov 2020 11:32:18 GMT
Location: https://jsonapi.partner2.yandex.com/v1/context_on_site_rtb/R-A-636326-3
Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff{
   "data" :{
      "attributes" :{},
      "id" : "R-A-636326-4",
      "links" :{
         "self" : "https://jsonapi.partner2.yandex.com/v1/context_on_site_rtb/R-A-636326-4"
      },
      "relationships" :{
         "context_on_site_campaign" :{
            "links" :{
               "related" : "https://jsonapi.partner2.yandex.com/v1/context_on_site_rtb/R-A-636326-4/context_on_site_campaign",
               "self" : "https://jsonapi.partner2.yandex.com/v1/context_on_site_rtb/R-A-636326-4/relationships/context_on_site_campaign"
            }
         },
         "pages" :{
            "links" :{
               "related" : "https://jsonapi.partner2.yandex.com/v1/context_on_site_rtb/R-A-636326-4/pages",
               "self" : "https://jsonapi.partner2.yandex.com/v1/context_on_site_rtb/R-A-636326-4/relationships/pages"
            }
         }
      },
      "type" : "context_on_site_rtb"
   }
}

Set a CPM floor for the ad unit:


         "attributes": {
            "strategy":"0",
            "mincpm":"123"
        }

Editing RTB unit parameters

To rename an RTB unit, use the PATCH/{resource-id}/{object-id} request.

Request:

curl -v -H "Accept: application/vnd.api+json" \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: token ac3b42lp-89ls-..." \
-X PATCH \
--data \
  '{
     "data":{
       "type":"context_on_site_rtb",
       "id":"R-A-636326-1",
       "attributes":{
         "caption":"MyBlock"
       }
     }
   }' \
'https://jsonapi.partner2.yandex.com/v1/context_on_site_rtb/R-A-636326-1' | json_pp

Response:

HTTP/1.1 200 OK
Content-Length: 732
Content-Type: application/vnd.api+json
Date: Fri, 13 Nov 2020 11:40:50 GMT
Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff{
   "data" :{
      "attributes" :{
         "caption" : "MyBlock"
      },
      "id" : "R-A-636326-1",
      "relationships" :{
         "context_on_site_campaign" :{
            "links" :{
               "related" : "https://jsonapi.partner2.yandex.com/v1/context_on_site_rtb/R-A-636326-1/context_on_site_campaign",
               "self" : "https://jsonapi.partner2.yandex.com/v1/context_on_site_rtb/R-A-636326-1/relationships/context_on_site_campaign"
            }
         },
         "pages" :{
            "links" :{
               "related" : "https://jsonapi.partner2.yandex.com/v1/context_on_site_rtb/R-A-636326-1/pages",
               "self" : "https://jsonapi.partner2.yandex.com/v1/context_on_site_rtb/R-A-636326-1/relationships/pages"
            }
         }
      },
      "type" : "context_on_site_rtb"
   },
   "links" :{
      "self" : "https://jsonapi.partner2.yandex.com/v1/context_on_site_rtb/R-A-636326-1"
   },
   "meta" :{
      "fields" : [
         "caption"
      ]
   }
}

Creating a universal banner

Request:


curl 'https://jsonapi.partner2.yandex.com/v1/context_on_site_rtb' \
-X 'POST' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Accept: application/vnd.api+json' \
-H "Authorization: $PI_TOKEN" \
-d '{
    "data" :{
        "attributes" :{
            "block_type" : "banner",
            "formats_setup_mode" : "standard",
            "strategy" : 1,
            "caption" : "Unit",
            "page_id" : 12345,
            "tech_type" : "none"
        },
    "type" : "context_on_site_rtb"
    }
}'

Request:


curl 'https://jsonapi.partner2.yandex.com/v1/context_on_site_rtb' \
-X 'POST' \
-H 'Content-Type: application/vnd.api+json' \
-H 'Accept: application/vnd.api+json' \
-H "Authorization: $PI_TOKEN" \
-d '{
    "data" :{
        "attributes" :{
            "block_type" : "banner",
            "formats_setup_mode" : "standard",
            "strategy" : 1,
            "caption" : "Ad unit",
            "page_id" : 12345,
            "tech_type" : "turbo"
        },
    "type" : "context_on_site_rtb"
    }
}'

Ad unit settings

You can configure rendering parameters at the ad unit level.

For example, set a dark theme:


"attributes":{
   "pcode_settings":{
         "themeIndicator":"dark",
         "bgColorLight":"A387FF",
         "bgColorDark":"FF6279"
   }
}

Blocking an ad format

To block an ad format, remove it from design_templates.

You can exclude specific brands or ad categories at the site level.

Block video ads:


"attributes" : {
            "formats_setup_mode" : "manual",
            "design_templates" : [{
                    ...,
                    "caption" : "Display ad design",
                    "type" : "media",
                    ...,
                },{
                    ...,
                    "caption" : "Text & Image ad design",
                    "type" : "tga",
                    ...,
                }
            ]
        },

Block display ads:


"attributes" : {
   "formats_setup_mode" : "manual",
   "design_templates" : [{
                    ...,
                    "caption" : "Video design",
                    "type" : "video",
                    ...,
                },{
                    ...,
                    "caption" : "Text & Image ad design",
                    "type" : "tga",
                    ...,
                }
            ]
        },

Brand and ad category exclusions

Excluding brands at the site level


curl 'https://jsonapi.partner2.yandex.com/v1/context_on_site_campaign/12345' \
-X PATCH \
-H 'Accept: application/vnd.api+json' \
-H 'content-type: application/vnd.api+json' \
-H "Authorization: $TOKEN" \
-d '{
    "data":{
        "attributes":{
            "brands":[{"bid":"189","blocked":true}]
        },
        "type":"context_on_site_campaign",
        "id":"12345"
    }
}'

Excluding ad categories at the site level


curl 'https://jsonapi.partner2.yandex.com/v1/context_on_site_campaign/12345' \
-X PATCH \
-H 'Accept: application/vnd.api+json' \
-H 'content-type: application/vnd.api+json' \
-H "Authorization: $TOKEN" \
-d '{
    "data":{
        "attributes":{
            "picategories":[{"id":"2","cpm":9999}]
        },
        "type":"context_on_site_campaign",
        "id":"12345"
    }
}'

Was the article helpful?

Filtering data

Operations with API resources

Use cases

Adding a resource

Adding a domain

Verifying domain ownership

Adding an RTB unit with a strategy

Editing RTB unit parameters

Creating a universal banner

Creating a Turbo banner

Ad unit settings

Blocking an ad format

Brand and ad category exclusions

Was the article helpful?