Adform API documentation

General Specification

Adform API is published through a SOAP Web Services over https. Services are described using Web Service Description Language (WSDL). You can find a link to WSDL document in documentation page of each service. WSDL documents can be used to generate a source code for client applications which communicate with Adform API services.

To start using Adfrom API services please contact us in order to enable access for you. Also we want you to know that your feedback is important for us, so please share your ideas and opinions what can be improved. This is early version of Adform API and we consider to have a lot of improvements and new services in near future.

Overview of Adform API services:

Security

  • Security service - allows users to authenticate and access Adform API by issuing security tokens.

Media Plan and Campaign management

Ads and Tags management

  • Tag service - dedicated to Tags management. Allows creating tags for existing ads for all supported ads in the system.
  • Quick Tag service - allows to create Rotators, Schedules and Tags for them in a one single call!
  • Ad service - dedicated to Ads management. Allows users to list existing ads and create link ads at the moment.
  • Rotator service - dedicated to Rotators management. Allows creating rotators for existing ads at the moment.
  • Rotator service (v20120913) - Updated version of Rotator service.
  • Schedule service - dedicated to Schedule management. Allows creating schedules for existing ads and rotators at the moment.

Product and Custom feed management

  • Product service - allows to setup product feed update from external source. Two modes are supported at the moment: Custom and Product feed.

Authentication

Every SOAP request made to Adform API must include a SOAP Ticket header, containing the value of authentication ticket issued by Security service Login operation. So, before making calls to any operation of Adform API services you should call Security service Login operation first. Issued authentication ticket is valid for some period of time and can be used in subsequent calls until it expires. It is not necessary (and not recommended) to call Login operation on every request. For an example, see examples section.

Errors

Any Adform API service error is returned as SOAP fault message, containing error code in faultcode tag and error message in faultstring tag. For a list of all error codes, error messages and descriptions, see errors page.

In the following service response example error code is: SecurityError, and error message is Incorrect user name or password: 

                        <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
                           <s:Body>
                              <s:Fault>
                                 <faultcode>s:SecurityError</faultcode>
                                 <faultstring xml:lang="en-US">Incorrect user name or password</faultstring>
                              </s:Fault>
                           </s:Body>
                        </s:Envelope>

Examples

In case you want to create a tag for existing banner through Adform API services, you can make a request to a SaveTag operation of Quick Tag service.

First, you need to get authentication ticket. For this purpose you should make the following request using HTTP POST method to Security service Login operation (for Security service location address, see service documentation page): 

                        Content-Type: text/xml;charset=UTF-8
                        SOAPAction: "http://www.adform.com/api/2010/06/ISecurityService/Login"
                        Host: api.adform.com
                        Content-Length: 325

                        <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.adform.com/api/2010/06">
                            <soapenv:Body>
                                <ns:LoginData>
                                    <ns:UserName>YOUR_USERNAME</ns:UserName>
                                    <ns:Password>YOUR_PASSWORD</ns:Password>
                                </ns:LoginData>
                            </soapenv:Body>
                        </soapenv:Envelope>

Security service should return the following response: 

                        <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
                            <s:Body>
                                <Ticket xmlns="http://www.adform.com/api/2010/06">D0C46D1D70814D388214654D0FE893D49A3FF155</Ticket>
                            </s:Body>
                        </s:Envelope>

Next, you will need to make a request to Quick Tag service SaveTag operation using HTTP POST method (for Quick Tag service location address, see service documentation page). Note, that authentication ticket is included in SOAP Ticket header: 

                        Content-Type: text/xml;charset=UTF-8
                        SOAPAction: "http://www.adform.com/api/2010/06/IQuickTagService/SaveTag"
                        Host: api.adform.com
                        Content-Length: 540

                        <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.adform.com/api/2010/06">
                            <soapenv:Header>
                                <ns:Ticket>Dz02gYmsWnlWF1-hNCVC58jP7QF0idTYi9r9VkjOCIMzpwQ63uZiK4N46NsGs4gX7dryU5nt-FMqRbfs-x2WPg__</ns:Ticket>
                            </soapenv:Header>
                            <soapenv:Body>
                                <ns:SaveTagData>
                                    <ns:CampaignCode>CAMPAIGN_CODE</ns:CampaignCode>
                                    <ns:MediaSiteName>MEDIA_NAME</ns:MediaSiteName>
                                    <ns:PlacementName>PLACEMENT_NAME</ns:PlacementName>
                                    <ns:BannerName>BANNER_NAME</ns:BannerName>
                                </ns:SaveTagData>
                            </soapenv:Body>
                        </soapenv:Envelope>

Tag service should return the following response: 

                        <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
                            <s:Body>
                                <TagId xmlns="http://www.adform.com/api/2010/06">12345</TagId>
                            </s:Body>
                        </s:Envelope>