HostTracker help - api REST ads operations

  1. Throttling
  2. GET /api/web/v1/adwords/delays- array of accepted delays for campaigns. Delay defines time in minutes which system should wait after task becomes DOWN and before campaign suspension. Currently [0;5;10;15;30;60]
  3. GET /api/web/v1/adwords - get all AdWords campaigns, possible filltered by url query string
  4. GET /api/web/v1/adwords/{id:guid} - get campaign by id (GUID)
  5. POST /api/web/v1/adwords - create AdWords cmpaign in HostTracker (note: AdWords system should already have specified campaign)
  6. PUT /api/web/v1/adwords - update general campaign parameters (delay, enabled, taskId, contactIds)
  7. PUT /api/web/v1/adwords/{id:guid} - update campaign fields (including accountId and/or campaign name)
  8. DELETE /api/web/v1/adwords/{id:guid} - delete campaign by id (GUID)
  9. DELETE /api/web/v1/adwords - delete campaign by filter (query string) or all campaigns
  10. PATCH /api/web/v1/adwords/{id:guid} - sync states of AdWords campaign, AdWords account in HostTracker and AdWords systems
Throttling

Usual throtling policy per account: 1 request per 1 second, 30 requests per minute
Next API requests are protected via separate throttling policy:

Separate throttling policy checks take place when request is verified (passed other possible errors like BadRequest)
and just before to AdWords API calls. Thus, throttling here plays role of CAPTCHA for UI.
Separate throttling policy parameters: 5 requests per 1 minute. All 3 API share same "throttling space" - act like one endpoint.

GET /api/web/v1/adwords/delays - array of accepted delays for campaigns. Delay defines time in minutes which system should wait after task becomes DOWN and before campaign suspension. Currently [0;5;10;15;30;60]
Request. GET /api/web/v1/adwords/delays
  • Authorization: bearer <your auth.token here> (how to get token see user operations)
  • Accept or Content-Type specifies response content format: application/json, text/xml.
Response. GET /api/web/v1/adwords/delays
  • Content-Type: application/json [0,5,10,15,30,60]
  • Content-Type: text/xml <ArrayOfInt xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
       <int>0</int>
       <int>5</int>
       <int>10</int>
       <int>15</int>
       <int>30</int>
       <int>60</int>
    </ArrayOfInt>
GET /api/web/v1/adwords - get all AdWords campaigns, possible filltered by url query string
Request. GET /api/web/v1/adwords Headers:
  • Authorization: bearer <your auth.token here> (how to get token see user operations)
  • Accept or Content-Type specifies response content format: application/json, text/xml.
Optional filters (via URL query string, URL filter keywords are case sensitive!):
  • id - GUID, optional - the id of campaign in HostTracker system (becomes known after campaign creation) GET https://www.host-tracker.com/api/web/v1/adwords?id=37073ead-
    f9f8-4e45-9aaf-e3d02b9d7521     HTTP/1.1
    User-Agent: Fiddler
    Content-Type: application/json
    Host: www.host-tracker.com
    Authorization: bearer <your token here>
  • ids - search campaigns by ids. GET https://www.host-tracker.com/api/web/v1/adwords?ids=092a2bc9-58d1-e411-80c3
    -00155d36955e    &ids=695dc35a-59d1-e411-80c3-00155d36955e HTTP/1.1
    User-Agent: Fiddler
    Content-Type: application/json
    Host: www.host-tracker.com
    Authorization: bearer <your token here>
  • excludeIds - if true then exclude specified ids
  • accountIds - AdWords account ids to search by GET https://www.host-tracker.com/api/web/v1/adwords?accountIds=123-456-7890&accountIds=
    123-456-7891 HTTP/1.1
    User-Agent: Fiddler
    Content-Type: application/json
    Host: www.host-tracker.com
    Authorization: bearer <your token here>
  • names - search campaigns by names. Do not forget to URL encode each name GET https://www.host-tracker.com/api/web/v1/adwords?names=Product+1&names=Product+2 HTTP/1.1
    User-Agent: Fiddler
    Content-Type: application/json
    Host: www.host-tracker.com
    Authorization: bearer <your token here>
  • nameLike - if True - each campaign name specified by names will be searched using LIKE clause. GET https://www.host-tracker.com/api/web/v1/adwords?nameLike=True HTTP/1.1
    User-Agent: Fiddler
    Content-Type: application/json
    Host: www.host-tracker.com
    Authorization: bearer <your token here>
  • excludeName - if True - search for campaigns which does not have specified names via names parameter (or NOT LIKE if nameLike is True). GET https://www.host-tracker.com/api/web/v1/adwords?excludeName=True HTTP/1.1
    User-Agent: Fiddler
    Content-Type: application/json
    Host: www.host-tracker.com
    Authorization: bearer <your token here>
  • enabled - True - search for enabled campaigns, False - search for disabled, null (default) - retrieve all. GET https://www.host-tracker.com/api/web/v1/adwords?enabled=False HTTP/1.1
    User-Agent: Fiddler
    Content-Type: application/json
    Host: www.host-tracker.com
    Authorization: bearer <your token here>
  • manageable - if True - select only those campaigns state of which could be controled by HostTracker.
    Campaign is not manageable if it does not exist or till the moment when it is confirmed that campaign's account could be managed by HostTracker. GET https://www.host-tracker.com/api/web/v1/adwords?manageable=False HTTP/1.1
    User-Agent: Fiddler
    Content-Type: application/json
    Host: www.host-tracker.com
    Authorization: bearer <your token here>
  • taskIds - GUID array - array of task ids by which to perform search.
    For example, taskIds=37073ead-f9f8-4e45-9aaf-e3d02b9d7521 filter will return all campaigns that are controlled by state of specified task. GET https://www.host-tracker.com/api/web/v1/adwords?taskIds=15f82382-81d7-428f-a8a0-
    3f9ef3fb965b    &taskIds=5d8070c1-262d-4242-8702-928240ad56a4 HTTP/1.1
    User-Agent: Fiddler
    Content-Type: application/json
    Host: www.host-tracker.com
    Authorization: bearer <your token here>
  • includeTaskRef - if True - in addition to taskId response will contact task property with TaskReference object (only id and name of the task)
  • includeTask - if True - in addition to taskId response will contact task property with Task object (see tasks operations)
  • includeContacts - if True - in addition to contactIds response will contact contacts array with Contact objects (see contact operations)
Response. GET /api/web/v1/adwords - array of campaigns
  • Content-Type: application/json [
     {
       "id":"Campaign id, ex. 967b026c-2c7b-e711-aa68-3085a980e898",
       "accountStringId":"AdWords account id, ex. 123-456-7890",
       "accountLongId":"AdWords account id as long int, ex. 1234567890"
       "name":"Campaign name as it was registered in the AdWords console",
       "delay":int, delay in minutes after task DOWN detection and campaign suspension,
    see delays    ,
       "taskId":"one of your task ids, shows on which task specified campaign will react.
    Ex. 4f8e87a1-a3dd-4da3-9579-c804a9a682fd    ",
       "task":Additional task information.
          If query string has includeTaskRef, it will be in form:
          {
             "id":taskId, GUID, ex. 4f8e87a1-a3dd-4da3-9579-c804a9a682fd
             "name":"The name of the task you specified during creation"
          }
          If query string has includeTask, it will be in form of Task object
       "contactIds":["GUID of first contact", "GUID of second contact", "..."],
       "contacts":
          [
             {
               Contact object
             },
             {
               One more contact object
             }
          ]    ,
       "enabled":true, false - campaign enablance by user,
       "manageable":true, false - can HostTracker manage campaign state or not -
    AdWords account should confirm the access by HostTracker management account before
    campaign could actually be managed    ,
       "lastSeenStatus":"Can be one of:
            Unknown - have not asked AdWords yet;
            NotFound - asked AdWords and it said that campaign (account, name) does not exist;
            Suspended - campaign exists in suspended state - could go to Active when task goes UP;
            Active - campaign is Active, could got to Suspended when task goes DOWN    ",
       "lastSeenStatusDate":"The date when HostTracker has seen last status from AdWords,
    ex. 2017-08-16T23:44:00    ",
       "lastSeenStatusDateUnix":Same as lastSeenStatusDate but in format of number -
    number of seconds from 01.01.1970        "accountLinkStatus":"Can be one of:
            Initial - account was just registered in HostTracker but no AdWords API action took place
            InitFail - AdWords API call for linking user account ot HostTracker management account failed.
    Retry is required
            Pending - invitation was sent, account was linked (via AdWords API) in PENDING state
            Active - account is active, invitation was confirmed - HostTracker can manage campaign now
            Inactive - Inactive link state, HostTracker cannot alter campaigns
            Refused - Invitation was refused, HostTracker cannot alter campaigns
            Canceled - invitation was canceled by HostTracker, or account was deleted
            Unkn - intermediate state, should not be returned by API    ",
       "accountLinkStatusDate":"the date when HostTracker last observed specified accountLinkState.
    To sync link state with AdWords see PATCH request    ",
       "accountLinkStatusDateUnix":Same as accountLinkStatusDate but in format of a number -
    number of seconds from 01.01.1970      },
     ...
    ]
  • Content-Type: text/xml <ArrayOfAdWordsCampaign xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
       <AdWordsCampaign>
         <id>Campaign id, ex. 967b026c-2c7b-e711-aa68-3085a980e898</id>
         <accountStringId>AdWords account id, ex. 123-456-7890</confirmed>
         <accountLongId>AdWords account id as long int, ex. 1234567890</contactType>
         <name>Campaign name as it was registered in the AdWords console</name>
         <delay>int, delay in minutes after task DOWN detection and campaign suspension,
    see delays    </delay>
         <taskId>one of your task ids, shows on which task specified campaign will react.
    Ex. 4f8e87a1-a3dd-4da3-9579-c804a9a682fd    </taskId>
         <task>
          <-- for query string includeTaskRef = True -->
          <id>317cbd8d-420f-e711-a9eb-3085a980e898</id>
          <name>test 1</name>
          <-- for query string includeTask = True there will be additional fields -
    see Task object. xsi:type on task element will contain actual type>
         </task>
        <contactIds>
          <guid>9944e26e-e438-e611-a91d-dc85de1f0bc2</guid>
          <guid>6737041f-c076-44da-9e46-aadc415ad53a</guid>
        </contactIds>
        <-- for query string includeContact = True contacts will contain contact objects.
    Each contact will have xsi:type with type of contact (for ex., SkypeContact) >
         <contacts>
          <contact>
            ...see contact object
          </contact>
         </contacts>
         <enabled>true/false</enabled>
         <manageable>true/false</manageable>
         <lastSeenStatus>Active (see explanation in json section above)<lastSeenStatus>
         <lastSeenStatusDate>2017-09-13T04:51:20</lastSeenStatusDate>
         <lastSeenStatusDateUnix>1505278280</lastSeenStatusDateUnix>
         <accountLinkStatus>Active (see explanation in json section above)<accountLinkStatus>
         <accountLinkStatusDate>2017-09-13T04:51:20</accountLinkStatusDate>
         <accountLinkStatusDateUnix>1505278280</accountLinkStatusDateUnix>
       </AdWordsCampaign>
    </ArrayOfAdWordsCampaign>
GET /api/web/v1/adwords/{id:guid} - get Adwords campaign by id (GUID)
Request. GET /api/web/v1/adwords/{id:guid} Headers:
  • Authorization: bearer <your auth.token here> (how to get token see user operations)
  • Accept or Content-Type specifies response content format: application/json, text/xml.
Response. GET /api/web/v1/adwords/{id:guid} Contact data (see section above)
POST /api/web/v1/adwords - create (register) Adwords campaing. note: AdWords system should already have specified campaign
Throttling - allowed 5 requests per 1 minute per account
Request. POST /api/web/v1/adwords Headers:
  • Authorization: bearer <your auth.token here> (how to get token see user operations)
  • Accept or Content-Type specifies response content format: application/json, text/xml, application/x-www-form-urlencoded
  • Parameters in the body:
    • accountStringId - 123-456-7890 - the AdWords account number,
      if specified then accountLongId is not neccessary
    • accountLongId - 1234567890 - the AdWords account number as long int,
      if specified then accountStringId is not neccessary
    • name - the name of the campaign to be registered in HostTracker (it should exist in AdWords system)
    • delay - one of the delays (optional). Deflault is 5 mins.
    • taskId - GUID, required, id of the task which defines the state of the campaign
    • contactIds - array of contact ids, which will be notified about any campaign status changes that performed by HostTracker.
      Way of supplying array depends from selected MIME type of body. For form-urlencoded use contactIds several times
    • enabled - create campaign in disabled or enabled state.
      HostTracker will do nothing if campaign is disabled and corresponding task changes state
  • Content-Type: application/json {"accountLongId":1234567890,"name":"Product 1",
    "taskId":"6737041f-c076-44da-9e46-aadc415ad53a"}
  • Content-Type: text/xml <AdWordsCampaignEditableData>
       <accountLongId>
          1234567890
       </accountLongId>
       <name>
          Product 1
       </name>
       <taskId>
          6737041f-c076-44da-9e46-aadc415ad53a
       </taskId>
       <contactIds>
          <guid>6737041f-c076-44da-9e46-aadc415ad53b</guid>
          <guid>6737041f-c076-44da-9e46-aadc415ad53c</guid>
       </contactIds>
    </AdWordsCampaignEditableData>
Response. POST /api/web/v1/adwords Response will contact AdWords created campaign information (see GET for details). Normal HTTP status is 201
PUT /api/web/v1/adwords - Update Adwords campaign by filter. Only next parameters can be updated by this method (but for many campaigns):
delay, enabled, taskId, contactIds
NOTE: Currently update of taskId is not recommended but possible.
Known issue - system will not resume campaign when user changes taskId from down task to up task.
System reacts only at moments of Down and Up detection.
Request. api/web/v1/adwords Headers:
  • Authorization: bearer <your auth.token here> (how to get token see user operations)
  • Accept or Content-Type specifies response content format: application/json, text/xml.
  • Query string defines which campaigns will be updates. See GET for more info about query filter
HTTP Body (examples):
  • Content-Type: application/json
    {"delay":10,"enabled":true}
    {"taskId":"6737041f-c076-44da-9e46-aadc415ad53a"}
  • Content-Type: text/xml
    <AdWordsCampaignEditableData>
       <taskId>
          6737041f-c076-44da-9e46-aadc415ad53a
       </taskId>
       <contactIds>
          <guid>6737041f-c076-44da-9e46-aadc415ad53b</guid>
          <guid>6737041f-c076-44da-9e46-aadc415ad53c</guid>
       </contactIds>
    </AdWordsCampaignEditableData>
    {"taskId":"6737041f-c076-44da-9e46-aadc415ad53a"}
Response. api/web/v1/adwords Array of updated campaigns - see GET result
PUT /api/web/v1/adwords/{id:guid} - Update selected (by id) Adwords campaign
Throttling - 1 update per 1 minute per account is allowed.
All editable fields could be updated (see POST for available editable fields)
Request. api/web/v1/adwords/{id:guid} Headers:
  • Authorization: bearer <your auth.token here> (how to get token see user operations)
  • Accept or Content-Type specifies response content format: application/json, text/xml.
HTTP Body (examples):
  • Content-Type: application/json
    {"name":"New campaign name","delay":10,"enabled":true}
    {"taskId":"6737041f-c076-44da-9e46-aadc415ad53a","accountLongId":1234567891}
  • Content-Type: text/xml
    <AdWordsCampaignEditableData>
       <taskId>
          6737041f-c076-44da-9e46-aadc415ad53a
       </taskId>
       <contactIds>
          <guid>6737041f-c076-44da-9e46-aadc415ad53b</guid>
          <guid>6737041f-c076-44da-9e46-aadc415ad53c</guid>
       </contactIds>
    </AdWordsCampaignEditableData>
    {"taskId":"6737041f-c076-44da-9e46-aadc415ad53a"}
Response. api/web/v1/adwords Updated campaign - see GET with id result
DELETE /api/web/v1/adwords - delete AdWords campaigns by specified filter in query string.
WARN: empty query string - delete of all campaigns
Response. Deleted AdWords cmapaigns - see GET result
DELETE /api/web/v1/adwords/{id:guid} - delete specified by id AdWords campaign
Response. Deleted AdWords cmapaign - see GET with id
PATCH /api/web/v1/adwords/{id:guid} - sync account and campaign states in HostTracker from AdWords
Throttling - 5 requests per 1 minute per account
You DO NOT need to call this method after you create campaign or when you update campaign name and/or account id.
In such cases this method will be called automatically.

Help pages by categories