Signing up for an adBrite API Account

Before using the adBrite API, an API customer (developer) should create an adBrite account. Following the sign-up process, the adBrite advertiser will be authorized by adBrite to use their user id and password for initiating API calls.

Getting Started using the adBrite API Web Services

To use the adBrite API, the API developer can write a client program in a language of their choice (such as Java, Perl, Python, C, C++, PHP). The client program needs to send a request to one of the adBrite Web Services such as CampaignService or AdGroupService. The relevant service will process the request and send back a response for the client program to parse.

Developers need to install the software for the language and toolkit that they choose to write their own programs in. For example, if a developer chooses to write their client programs in Java, they need to install Java and a SOAP toolkit such as Axis 2.

adBrite has internally tested the APIs using Java and The SOAP toolkit r 1.5 for Axis 2, available at the Apache Axis2 site.

adBrite provides a wsdl-generated Java client library with convenience classes for each service that simplify management of header information with example console programs using them. <add link to java package here>

Web Service URLs

The operations provided by a web service are defined in a Web Service Definition Language (WSDL) file. Before connecting to a web service, the developer would need to know the URL of the service. Each API web service has its own WSDL. The URL for each WSDL has the following form, where SERVICE_NAME is the service name:

https://api.adbrite.com/v1/SERVICE_NAME.wsdl

For example, this is the URL for the CampaignService WSDL:

https://api.adbrite.com/v1/CampaignService.wsdl

Logging in to the AdWords API Web Services

Once a developer is authorized to use APIs, they can login to their API account where they view the list of clients they manage. Then, when making an API request, the API  developer must include in the request header their email and password. Optionally they may include the login id of a client account. Once the client email address is provided, the developer can operate on behalf of the client’s account without any additional authorization needed.

<Adding a client to a developer account>

Request Header

The following header elements are required for requests sent to the API web services:

• email
  Email address for the API account being accessed.
• password
  Password for the API account being accessed

The following header elements are optional.

• clientEmail
  An Email address that uniquely identifies an adBrite client. If this element is provided, adBrite would validate all API calls to ensure that the API request is valid for this client account.
• clientCustomerId
  If the developer already has a value set to operate with another vendor, adBrite will accept this field but will ignore it.
• useragent
  If the developer already this field set, adBrite will accept this field but will ignore it.
• developerToken
  If the developer already has a token set to operate with another vendor, adBrite will accept this field but will ignore it.
• applicationToken
  If the developer already has a token defined to operate with another vendor, adBrite will accept this field but will ignore it.

For an example of XML code for setting a request header, see the section SOAP Request Example further down this page.

Response Header

All responses returned from the API web services include the following header elements. As a best practice, we recommend that you log these values.

• requestId
  Uniquely identifies this request.
• operations
  Currently, always set to 1.
• units
  Currently, always set to 1.
• responseTime
  Elapsed time between the web service receiving the request and sending the response.

For an example of XML code for a response header, see the section SOAP Response Example below.

Request Example

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Header>
    <ns1:useragent xmlns:ns1="https://api.adbrite.com/v1/common" soapenv:mustUnderstand="0">adBrite: API Test</ns1:useragent>
    <ns1:password xmlns:ns1="https://api.adbrite.com/v1/common" soapenv:mustUnderstand="0">xxxxxx</ns1:password>
    <ns1:email xmlns:ns1="https://api.adbrite.com/v1/common" soapenv:mustUnderstand="0">dev_user@adbrite.com</ns1:email>
    <ns1:clientEmail xmlns:ns1="https://api.adbrite.com/v1/common" soapenv:mustUnderstand="0">clnt_user@adbrite.com</ns1:clientEmail>
    <ns1:clientCustomerId xmlns:ns1="https://api.adbrite.com/v1/common" soapenv:mustUnderstand="0">clntcustid</ns1:clientCustomerId>
    <ns1:developerToken xmlns:ns1="https://api.adbrite.com/v1/common" soapenv:mustUnderstand="0">develToken</ns1:developerToken>
    <ns1:applicationToken xmlns:ns1="https://api.adbrite.com/v1/common" soapenv:mustUnderstand="0">appToken</ns1:applicationToken>
  </soapenv:Header>
  <soapenv:Body>
    <ns1:addCampaign xmlns:ns1="https://api.adbrite.com/v1/common">
      <ns1:campaign>
        <ns1:budgetAmount>100000000</ns1:budgetAmount>
        <ns1:budgetOptimizerSettings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="1"/>
        <ns1:budgetPeriod>Daily</ns1:budgetPeriod>
        <ns1:contentTargeting xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="1"/>
        <ns1:geoTargeting xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="1"/>
        <ns1:id>0</ns1:id>
        <ns1:languageTargeting xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="1"/>
        <ns1:name xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="1"/>
        <ns1:networkTargeting xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="1"/>
        <ns1:schedule xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="1"/>
        <ns1:status xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="1"/>
      </ns1:campaign>
    </ns1:addCampaign>
  </soapenv:Body></soapenv:Envelope>

Response Example

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
  <soapenv:Body>    <ns1:addCampaignResponse xmlns:ns1="https://api.adbrite.com/v1/common">
      <ns1:addCampaignReturn>
        <ns1:budgetAmount>100000000</ns1:budgetAmount>
        <ns1:budgetOptimizerSettings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="1"/>
        <ns1:budgetPeriod>Daily</ns1:budgetPeriod>
        <ns1:contentTargeting>AllPlacements</ns1:contentTargeting>
        <ns1:endDay>2037-12-30-05:00</ns1:endDay>
        <ns1:geoTargeting>
          <ns1:targetAll>true</ns1:targetAll>
        </ns1:geoTargeting>
        <ns1:id>11804796</ns1:id>
        <ns1:languageTargeting xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="1"/>
        <ns1:name>Campaign #11804796</ns1:name>
        <ns1:networkTargeting>
          <ns1:networkTypes>ContentNetwork</ns1:networkTypes>
        </ns1:networkTargeting>
        <ns1:schedule xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="1"/>
        <ns1:startDay>2009-11-16-05:00</ns1:startDay>
        <ns1:status>Active</ns1:status>
      </ns1:addCampaignReturn>
    </ns1:addCampaignResponse>
  </soapenv:Body></soapenv:Envelope>