Config API Version 2 PPC

Introduction

Infinity integrates with several paid search (PPC or pay-per-click) ad-serving networks.

To do so, we need to authenticate against the network’s own APIs with credentials and account references.

Each network has its own network code to identify it within Infinity, i.e.:

Each account has a reference that identifies it within the network. They should also have a default time zone and currency defined within the network.

Authentication

Each account requires credentials in order to access its data. Those credentials can be either basic auth (a username and password) or oAuth2 (a refresh token).

For basic auth, the username and password can be submitted directly to the “add account” or “update account” routes.

For oAuth2, you must first create an auth session, use that session key to grant access to Infinity for the given client’s data, then finally submit the session key to the “add account” or “update account” route as appropriate.

The oAuth2 process is more complicated than basic auth but is considered more secure as the password and refresh token are kept private within each system.

Basic auth logins are being phased out by the networks in favour of oAuth2 over the next year or so. Once basic auth is phased out, only oAuth2 logins will be accepted by the paid search networks.

Oauth2 requires an appCode to identify the thirdparty system. Valid appCode’s for PPC network are googleAdwords and bingAds.

Status

This API uses Infinity status codes to show the state of each account within the network. Infinity status codes are mapped to network states as follows:

List Networks

Lists known paid search networks.

Request:

GET /config/v2/ppc/networks

Filter Types

The networks list may be filtered by any of the returned fields.

Sort Types

The networks list may be sorted by any of the returned fields. By default the list is sorted by networkName.

Response:

Returns a list of known networks.

Response example:

HTTP 200 - OK
{"networkCode":"mac","networkName":"Bing Ads","oauth2AppCode":"bingAds"}
{"networkCode":"gaw","networkName":"Google AdWords","oauth2AppCode":"googleAdWords"}
{"networkCode":"ysm","networkName":"Yahoo! Search Marketing","oauth2AppCode":""}

Read Network

Returns the properties for a particular network.

Request:

GET /config/v2/ppc/networks/{networkCode}

URL Path Params

Response:

Returns the requested network details.

Response example:

HTTP 200 - OK
{"networkCode":"gaw","networkName":"Google AdWords","oauth2AppCode":"googleAdWords"}

List Available Accounts

Lists accounts available to add to an IGRP using a set of network credentials. One set of credentials should be provided, as either:

Request:

GET /config/v2/igrps/{IGRP SPECIFIER}/ppc/networks/{networkCode}/accounts/available

URL Path Params

GET Params

Response:

Returns a list of available network accounts using the provided credentials.

Response example:

HTTP 200 - OK
{"networkCode":"gaw","accountRef":1234567890,"accountName":"Some Account"}
{"networkCode":"gaw","accountRef":9876543210,"accountName":"Other Account"}

List Accounts

Lists accounts added to an IGRP for a particular network.

Request:

GET /config/v2/igrps/{IGRP SPECIFIER}/ppc/networks/{networkCode}/accounts

URL Path Params

Filter Types

The accounts list may be filtered by any of the following fields.

Sort Types

The accounts list may be sorted by any of the following fields. By default the list is sorted by accountName.

Response:

Returns a list of accounts within the IGRP and network.

Response example:

HTTP 200 - OK
{"igrp":"1","networkCode":"gaw","accountRef":"1234567890","accountName":"My Account","accountStatus":"410","currencyCode":"GBP","timezone":"Europe\/London"}
{"igrp":"1","networkCode":"gaw","accountRef":"9876543210","accountName":"My Other Account","accountStatus":"200","currencyCode":"GBP","timezone":"Europe\/London","maxBuildDatehour":"2013-12-03 00:00:00","lastSyncDatetime":"2013-12-04 00:24:16"}

Read Account

Returns the properties for a particular account.

Request:

GET /config/v2/igrps/{IGRP SPECIFIER}/ppc/networks/{networkCode}/accounts/{accountRef}

URL Path Params

Response:

Returns the requested account details.

Response example:

HTTP 200 - OK
{"igrp":"1","networkCode":"gaw","accountRef":"9876543210","accountName":"My Other Account","accountStatus":"200","currencyCode":"GBP","timezone":"Europe\/London","maxBuildDatehour":"2013-12-03 00:00:00","lastSyncDatetime":"2013-12-04 00:24:16"}

Add Account

Adds an account to an IGRP using a set of network credentials. One set of credentials should be provided, as either:

Request:

POST /config/v2/igrps/{IGRP SPECIFIER}/ppc/networks/{networkCode}/accounts

URL Path Params

POST Params

Response:

Returns the HTTP 204 (No Content) status code if added successfully.

HTTP 204 - NO CONTENT

Update Account

Updates the config for an existing account within an IGRP. Either the network credentials or the account’s status may be updated.

Request:

POST /config/v2/igrps/{IGRP SPECIFIER}/ppc/networks/{networkCode}/accounts/{accountRef}

URL Path Params

POST Params

Response:

Returns the HTTP 204 (No Content) status code if update successful.

HTTP 204 - NO CONTENT

Delete Account

Deletes a particular account.

Request:

DELETE /config/v2/igrps/{IGRP SPECIFIER}/ppc/networks/{networkCode}/accounts/{accountRef}

URL Path Params

Response:

Returns the HTTP 204 (No Content) status code if delete is successful.

HTTP 204 - NO CONTENT

List Conversion Types

Returns the list of available upload conversion types for a particular account.

Request:

GET /config/v2/igrps/{IGRP SPECIFIER}/ppc/networks/{networkCode}/accounts/{accountRef}/conversionTypes/available

URL Path Params

GET Params

Response:

Returns the conversion types.

Response example:

HTTP 200 - OK
{"ref":14962301,"name":"Infinity Call Pass"}

Schedule account tagging job

Schedules an account tagging job. The account tagging job will analyse your account and send the results of that analysis in a file to the named recipient. The results file will contain suggested changes to ensure that your account is tagged correctly for Infinity. It should be loaded into AdWords Editor or Bing Ads Editor for review before posting.

Request:

POST /config/v2/igrps/{IGRP SPECIFIER}/ppc/networks/{networkCode}/accounts/{accountRef}/checkTagging

URL Path Params

POST Params

Response:

HTTP 202 - ACCEPTED