Version 5.0
AdvertServe User Manual :: v5.0

Advertisers :: Query API Module

Query

Description

Allows you to query for a list of advertisers using search criteria. A complete list of all existing advertisers will be returned if no search criteria is specified. Multiple search criteria may be specified together in the same query.

Module URI

Hyperlink /servlet/control/api/advertisers/query

Parameters

Parameter NameParameter TypeRequired?Example ValueValidation Rules (If Applicable)
secretStringYesa78bf24c5a23581aceba1c5f51ac4cad Must be a String containing no more than 32 characters
outputStringNoxml Must be a String equal to either json or xml
Parameter NameParameter TypeRequired?Example ValueValidation Rules (If Applicable)
idIntegerNo123 Must be the ID# of an existing advertiser
nameStringNoACME Company Must be a String containing no more than 80 characters
usernameStringNoacme Must be a String containing no more than 16 alphanumeric characters
statusbooleanNotrue Must be a boolean value equal to either true or false
remindersbooleanNotrue Must be a boolean value equal to either true or false
recyclebooleanNofalse Must be a boolean value equal to either true or false
notesStringNoN/A Must be a String containing no more than 65,535 characters
Parameter NameParameter TypeRequired?Example ValueValidation Rules (If Applicable)
info_companyStringNoACME Must be a String containing no more than 48 characters
info_nameStringNoJohn Doe Must be a String containing no more than 48 characters
info_titleStringNoOwner Must be a String containing no more than 48 characters
info_emailEmailNojohn@acme.com Must be an e-mail address containing no more than 64 characters
info_websiteURLNohttp://www.acme.com/ Must be a HTTP or HTTPS URL containing no more than 64 characters
info_addressStringNo123 Acme Street
New York, NY 10001
Must be a String containing no more than 65,535 characters
info_phoneStringNo123-456-7890 Must be a String containing no more than 48 characters
info_mobileStringNo123-456-7890 Must be a String containing no more than 48 characters
info_faxStringNo123-456-7890 Must be a String containing no more than 48 characters
info_notesStringNoN/A Must be a String containing no more than 65,535 characters
Parameter NameParameter TypeRequired?Example ValueValidation Rules (If Applicable)
competitorIntegerNo123 Must be the ID# of an existing advertiser
Parameter NameParameter TypeRequired?Example ValueValidation Rules (If Applicable)
gabooleanNofalse Must be a boolean value equal to either true or false
ga_sourceStringNoacme Must be a String containing no more than 80 characters
ga_mediumStringNobanner Must be a String containing no more than 80 characters
Parameter NameParameter TypeRequired?Example ValueValidation Rules (If Applicable)
optoutIntegerNo123 Must be the ID# of an existing publisher

XML Response

Hyperlink /servlet/control/api/advertisers/query?secret=(key)&name=acme


<results>
  <advertiser id="123" name="ACME" username="acme" basis="standard" balance="0.000" status="true" reminders="true" recycle="false">
    <notes/>
    <information company="ACME Company" name="John Doe" title="" email="john@acme.com" website="http://www.acme.com/" phone="123-456-7890" mobile="123-456-7890" fax="123-456-7890">
      <address><![CDATA[123 Acme Street
New York, NY 10001]]></address>
      <notes/>
    </information>
    <contacts>
      <contact name="Jane Doe" title="" email="jane@acme.com" phone="123-456-7890" />
    </contacts>
    <config>
      <setting name="HOME_DATE_RANGE" value="thirty"/>
      <setting name="HOME_MEDIA_FILTER" value=""/>
      <setting name="HOME_COMPARE_BY" value="clickratio"/>
      <setting name="HOME_ITEM_COUNT" value="25"/>
      <setting name="RECENT_EMAIL_FREQUENCY" value="never"/>
      <setting name="RECENT_EMAIL_FORMAT" value="HTML"/>
      <setting name="REPORTS_HIDE_GRAPHS" value="false"/>
      <setting name="REPORTS_HIDE_EMPTY" value="false"/>
      <setting name="REPORTS_INCLUDE_DEFINITIONS" value="true"/>
      <setting name="REPORTS_DATA_ADVERTISER" value="true"/>
      <setting name="REPORTS_DATA_CAMPAIGN" value="true"/>
      <setting name="REPORTS_DATA_CONVERSIONS" value="true"/>
      <setting name="REPORTS_DATA_CUSTOM" value="false"/>
      <setting name="REPORTS_DATA_GROUP" value="true"/>
      <setting name="REPORTS_DATA_MEDIA" value="true"/>
      <setting name="REPORTS_DATA_PUBLISHER" value="true"/>
      <setting name="REPORTS_DATA_ZONE" value="true"/>
      <setting name="REPORTS_DATA_DAILY" value="true"/>
      <setting name="REPORTS_DATA_EVENTS" value="true"/>
      <setting name="REPORTS_DATA_GEOGRAPHY" value="false"/>
      <setting name="REPORTS_DATA_HOURLY" value="true"/>
      <setting name="REPORTS_DATA_INTERACTIVE" value="true"/>
      <setting name="REPORTS_DATA_KEYWORDS" value="false"/>
      <setting name="REPORTS_DATA_LANGUAGES" value="false"/>
      <setting name="REPORTS_DATA_NETWORK" value="false"/>
      <setting name="REPORTS_DATA_REFERRER" value="false"/>
      <setting name="REPORTS_DATA_ROI" value="true"/>
      <setting name="REPORTS_DATA_SIZE" value="true"/>
      <setting name="REPORTS_DATA_SOFTWARE" value="false"/>
      <setting name="REPORTS_DATA_VIDEO" value="true"/>
      <setting name="REPORTS_DATA_VIEWABILITY" value="true"/>
      <setting name="REPORTS_DATA_WEATHER" value="true"/>
    </config>
    <permissions>
      <action>LOGIN</action>
      <action>ACCOUNTS</action>
      <action>ACCOUNTS_VIEW</action>
      <action>ACCOUNTS_EDIT</action>
      <action>MEDIA</action>
      <action>MEDIA_LISTING</action>
      <action>MEDIA_SEARCH</action>
      <action>MEDIA_PREVIEW</action>
      <action>MEDIA_VIEW</action>
      <action>MEDIA_STATUS</action>
      <action>FILES</action>
      <action>CAMPAIGNS</action>
      <action>CAMPAIGNS_LISTING</action>
      <action>CAMPAIGNS_SEARCH</action>
      <action>CAMPAIGNS_VIEW</action>
      <action>CAMPAIGNS_STATUS</action>
      <action>REPORTS</action>
      <action>REPORTS_ACCOUNTING</action>
      <action>REPORTS_GENERAL</action>
      <action>REPORTS_CAMPAIGNS</action>
      <action>REPORTS_GROUPS</action>
      <action>REPORTS_MEDIA</action>
      <action>REPORTS_PUBLISHERS</action>
      <action>REPORTS_ZONES</action>
      <action>REPORTS_CONVERSIONS</action>
      <action>REPORTS_CUSTOM</action>
      <action>REPORTS_DAILY</action>
      <action>REPORTS_ENGAGEMENT</action>
      <action>REPORTS_EVENTS</action>
      <action>REPORTS_GEOGRAPHY</action>
      <action>REPORTS_HOURLY</action>
      <action>REPORTS_INTERACTIVE</action>
      <action>REPORTS_KEYWORDS</action>
      <action>REPORTS_LANGUAGES</action>
      <action>REPORTS_NETWORK</action>
      <action>REPORTS_REFERRER</action>
      <action>REPORTS_ROI</action>
      <action>REPORTS_SOFTWARE</action>
      <action>REPORTS_VIDEO</action>
      <action>REPORTS_VIEWABILITY</action>
      <action>REPORTS_WEATHER</action>
      <action>TOOLS</action>
    </permissions>
    <bidding/>
    <competitors>
      <id>2</id>
      <id>3</id>
      <id>4</id>
      <id>20</id>
    </competitors>
    <googleanalytics source="acme" medium="banner"/>
    <optout>
      <id>7</id>
      <id>8</id>
      <id>9</id>
    </optout>
    <pixels view="123" click="123" action="123" retargeting="123"/>
    <regulations>
      <actions/>
      <countries unknown="false">
        <country id="ca"/>
        <country id="us"/>
      </countries>
      <keywords/>
    </regulations>
    <roadblocks>
      <campaigns>
        <id>1000</id>
        <id>1001</id>
      </campaigns>
      <zones>
        <id>10</id>
        <id>22</id>
        <id>31</id>
      </zones>
    </roadblocks>
  </advertiser>
</results>

JSON Response

Hyperlink /servlet/control/api/advertisers/query?secret=(key)&output=json&name=acme


{
  "results": [
    {
      "id": 123,
      "name": "ACME",
      "username": "acme",
      "basis": "standard",
      "balance": 0.000,
      "status": true,
      "reminders": true,
      "recycle": false,
      "notes": "",
      "information": {
        "company": "ACME Company",
        "name": "John Doe",
        "title": "",
        "email": "john@acme.com",
        "website": "http://www.acme.com/",
        "phone": "123-456-7890",
        "mobile": "123-456-7890",
        "fax": "123-456-7890",
        "address": "123 Acme Street\r\nNew York, NY 10001",
        "notes": ""
      },
      "contacts": [
        {
          "name": "Jane Doe",
          "title": "",
          "email": "jane@acme.com",
          "phone": "123-456-7890"
        }
      ],
      "config": {
        "HOME_DATE_RANGE": "thirty",
        "HOME_MEDIA_FILTER": "",
        "HOME_COMPARE_BY": "clickratio",
        "HOME_ITEM_COUNT": 25,
        "RECENT_EMAIL_FREQUENCY": "never",
        "RECENT_EMAIL_FORMAT": "HTML",
        "REPORTS_HIDE_GRAPHS": false,
        "REPORTS_HIDE_EMPTY": false,
        "REPORTS_INCLUDE_DEFINITIONS": true,
        "REPORTS_DATA_ADVERTISER": true,
        "REPORTS_DATA_CAMPAIGN": true,
        "REPORTS_DATA_CONVERSIONS": true,
        "REPORTS_DATA_CUSTOM": false,
        "REPORTS_DATA_GROUP": true,
        "REPORTS_DATA_MEDIA": true,
        "REPORTS_DATA_PUBLISHER": true,
        "REPORTS_DATA_ZONE": true,
        "REPORTS_DATA_DAILY": true,
        "REPORTS_DATA_EVENTS": true,
        "REPORTS_DATA_GEOGRAPHY": false,
        "REPORTS_DATA_HOURLY": true,
        "REPORTS_DATA_INTERACTIVE": true,
        "REPORTS_DATA_KEYWORDS": false,
        "REPORTS_DATA_LANGUAGES": false,
        "REPORTS_DATA_NETWORK": false,
        "REPORTS_DATA_REFERRER": false,
        "REPORTS_DATA_ROI": true,
        "REPORTS_DATA_SIZE": true,
        "REPORTS_DATA_SOFTWARE": false,
        "REPORTS_DATA_VIDEO": true,
        "REPORTS_DATA_VIEWABILITY": true,
        "REPORTS_DATA_WEATHER": true
      },
      "permissions": [
        "LOGIN",
        "ACCOUNTS",
        "ACCOUNTS_VIEW",
        "ACCOUNTS_EDIT",
        "MEDIA",
        "MEDIA_LISTING",
        "MEDIA_SEARCH",
        "MEDIA_PREVIEW",
        "MEDIA_VIEW",
        "MEDIA_STATUS",
        "FILES",
        "CAMPAIGNS",
        "CAMPAIGNS_LISTING",
        "CAMPAIGNS_SEARCH",
        "CAMPAIGNS_VIEW",
        "CAMPAIGNS_STATUS",
        "REPORTS",
        "REPORTS_ACCOUNTING",
        "REPORTS_GENERAL",
        "REPORTS_CAMPAIGNS",
        "REPORTS_CONVERSIONS",
        "REPORTS_CUSTOM",
        "REPORTS_GROUPS",
        "REPORTS_MEDIA",
        "REPORTS_PUBLISHERS",
        "REPORTS_ZONES",
        "REPORTS_DAILY",
        "REPORTS_ENGAGEMENT",
        "REPORTS_EVENTS",
        "REPORTS_GEOGRAPHY",
        "REPORTS_HOURLY",
        "REPORTS_INTERACTIVE",
        "REPORTS_KEYWORDS",
        "REPORTS_LANGUAGES",
        "REPORTS_NETWORK",
        "REPORTS_REFERRER",
        "REPORTS_ROI",
        "REPORTS_SOFTWARE",
        "REPORTS_VIDEO",
        "REPORTS_VIEWABILITY",
        "REPORTS_WEATHER",
        "TOOLS"
      ],
      "bidding": {},
      "competitors": [
        2,
        3,
        4,
        20
      ],
      "google_analytics": {
        "source": "acme",
        "medium": "banner"
      }
      "optout": [
        7,
        8,
        9
      ],
      "pixels" : {
        "view": 123,
        "click": 123,
        "action": 123,
        "retargeting": 123
      },
      "regulations": {
        "actions": "",
        "countries": [
          "ca",
          "us"
        ],
        "keywords": []
      },
      "roadblocks": {
        "campaigns": [
          1000,
          1001
        ],
        "zones": [
          10,
          22,
          31
        ]
      }
    }
  ]
}