Get

Returns data on associations of images with ads.

Restrictions

Attention. The method only supports text and image ads. To work with all types of ads, use the Ads service in version 5 of the API. More about ad types...

The method response may contain no more than 10,000 associations.

The total number of associations that meet the specified criteria is shown in the TotalObjectsCount output parameter. If the total is more than 10,000, you must use the Limit and Offset parameters to set up paged selection in order to get all the associations.

Input data

The input data structure in JSON is shown below.

{
   "method": "AdImageAssociation",
   "param": {
      /* AdImageAssociationRequest */
      "Action": (string),
      "SelectionCriteria": {
         /* AdImageAssociationSelectionCriteria */
         "Logins": [
            (string)
            ...
         ],
         "AdImageHashes": [
            (string)
            ...
         ],
         "StatusAdImageModerate": [
            (string)
            ...
         ],
         "AdIDS": [
            (long)
            ...
         ],
         "CampaignIDS": [
            (int)
            ...
         ],
         "Limit": (int),
         "Offset": (int)
      }
   }
}

Parameters are described below.

Parameter Description Required
AdImageAssociationRequest object
Action Action: Get. Yes
SelectionCriteria The AdImageAssociationSelectionCriteria object, which contains criteria for selecting image associations. For agencies
AdImageAssociationSelectionCriteria object
Logins

For agencies, an array containing usernames of clients (no more than 10) to perform the operation for.

For advertisers, this parameter is ignored.

For agencies
AdImageHashes Array containing the hashes of images (no more than 10,000). No
StatusAdImageModerate

Array of strings containing the moderation status of images:

  • New — Image has not been checked.
  • Pending — Moderation in progress.
  • Yes — Approved.
  • No — Rejected.

Selects images with all the statuses listed in the array.

No
AdIDS Array of IDs (no more than 10,000) for ads that images are associated with. No
CampaignIDS Array of IDs (no more than 10,000) for campaigns that images are associated with. No
Limit

The number of associations in the response. The maximum allowed value is 10,000. If omitted, the limit is 10,000.

When combined with the Offset parameter, this allows you to organize paginated selections from the database.

No
Offset

The number of associations that should be skipped when getting the selection. If omitted, 0 is assumed.

When combined with the Limit parameter, this allows you to organize paginated selections from the database.

No
Notes
  1. For advertisers: If the SelectionCriteria structure is empty, you will get all the associations (up to 10,000).
  2. If the SelectionCriteria structure has more than one criterion set, you will get the associations that simultaneously match all the criteria. For example, if the AdImageHashes and AdIDS parameters are set with the string "Yes", you will get associations if their hashes are in the AdImageHashes array, and their ad IDs are also in the AdIDS array.

Parameter Description Required
AdImageAssociationRequest object
Action Action: Get. Yes
SelectionCriteria The AdImageAssociationSelectionCriteria object, which contains criteria for selecting image associations. For agencies
AdImageAssociationSelectionCriteria object
Logins

For agencies, an array containing usernames of clients (no more than 10) to perform the operation for.

For advertisers, this parameter is ignored.

For agencies
AdImageHashes Array containing the hashes of images (no more than 10,000). No
StatusAdImageModerate

Array of strings containing the moderation status of images:

  • New — Image has not been checked.
  • Pending — Moderation in progress.
  • Yes — Approved.
  • No — Rejected.

Selects images with all the statuses listed in the array.

No
AdIDS Array of IDs (no more than 10,000) for ads that images are associated with. No
CampaignIDS Array of IDs (no more than 10,000) for campaigns that images are associated with. No
Limit

The number of associations in the response. The maximum allowed value is 10,000. If omitted, the limit is 10,000.

When combined with the Offset parameter, this allows you to organize paginated selections from the database.

No
Offset

The number of associations that should be skipped when getting the selection. If omitted, 0 is assumed.

When combined with the Limit parameter, this allows you to organize paginated selections from the database.

No
Notes
  1. For advertisers: If the SelectionCriteria structure is empty, you will get all the associations (up to 10,000).
  2. If the SelectionCriteria structure has more than one criterion set, you will get the associations that simultaneously match all the criteria. For example, if the AdImageHashes and AdIDS parameters are set with the string "Yes", you will get associations if their hashes are in the AdImageHashes array, and their ad IDs are also in the AdIDS array.

Output data

The output data structure in JSON is shown below.

{
   "data": {
      /* AdImageAssociationResponse */
      "AdImageAssociations": [
         {  /* AdImageAssociation */
            "AdID": (long),
            "AdImageHash": (string),
            "Login": (string),
            "CampaignID": (int),
            "StatusAdImageModerate": (string),
            "ModerateRejectionReasons": [
               {  /* RejectReason */
                  "Type": (string),
                  "Text": (string)
               }
               ...
            ]
         }
         ...
      ],
      "TotalObjectsCount": (int)
   }
}

Parameters are described below.

Parameter Description
AdImageAssociationResponse object
AdImageAssociations Array of AdImageAssociation objects containing information about images.
TotalObjectsCount The total number of associations that match the set criteria (without the Limit parameter).
AdImageAssociation object
AdID Identifier of the ad that the image is associated with.
AdImageHash Hash of the image.
Login Username of the image's owner.
CampaignID The campaign ID.
StatusAdImageModerate

The image's moderation status:

  • New — Image has not been checked.
  • Pending — Moderation in progress.
  • Yes — Approved.
  • No — Rejected.
ModerateRejectionReasons Array of RejectReason objects. These objects describe the reasons that caused the image for the ad to be rejected.
RejectReason object
Type The type of object that was rejected during moderation: AdImage.
Text Reason for rejection during moderation.
Parameter Description
AdImageAssociationResponse object
AdImageAssociations Array of AdImageAssociation objects containing information about images.
TotalObjectsCount The total number of associations that match the set criteria (without the Limit parameter).
AdImageAssociation object
AdID Identifier of the ad that the image is associated with.
AdImageHash Hash of the image.
Login Username of the image's owner.
CampaignID The campaign ID.
StatusAdImageModerate

The image's moderation status:

  • New — Image has not been checked.
  • Pending — Moderation in progress.
  • Yes — Approved.
  • No — Rejected.
ModerateRejectionReasons Array of RejectReason objects. These objects describe the reasons that caused the image for the ad to be rejected.
RejectReason object
Type The type of object that was rejected during moderation: AdImage.
Text Reason for rejection during moderation.

Examples of input data

Python

{
   'Action': 'Get',
   'SelectionCriteria': {
      'StatusAdImageModerate': ['Yes'],
      'CampaignIDS': [1327944, 1327974],
      'Limit': 20,
      'Offset': 60
   }
}

PHP

array(
   'Action' => 'Get',
   'SelectionCriteria' => array(
      'StatusAdImageModerate' => array('Yes'),
      'CampaignIDS' => array(1327944, 1327974),
      'Limit' => 20,
      'Offset' => 60
   )
)

Perl

{
   'Action' => 'Get',
   'SelectionCriteria' => {
      'StatusAdImageModerate' => ['Yes'],
      'CampaignIDS' => [1327944, 1327974],
      'Limit' => 20,
      'Offset' => 60
   }
}