To use the Enterprise Web Services (EWS), you make service requests to the EWS web server and then process the responses that are returned. Requests in EWS are constructed in XML format using the SOAP protocol. This page provides information about constructing EWS requests.
An EWS SOAP request contains an Envelope element with a Header element and a Body element.
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/07/secext"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://marketing.ews.yahooapis.com/V4">
<soapenv:Header>
...
</soapenv:Header>
<soapenv:Body>
...
</soapenv:Body>
</soapenv:Envelope>
To create an EWS request, first choose the Marketing API service and operation. Then create the SOAP header and the SOAP body. The next three sections will walk you through this process.
To create an EWS request, the first step is to choose the Marketing API service and operation.
The Marketing API services are described in the Service Overviews. Each service defines a number of operations. You may include exactly one operation in each request, as explained in the Marketing API Reference.
To build the request, you will need to know the name of the service (for example, AdService), the name of the operation (for example, addAd) and the parameters that define the operation (for example, ad). As you build your request, keep in mind that the names of services, operations, data objects, elements, and constants are case sensitive.
Note: Restrictions apply to all elements. If a required element is missing from any data object that is a part of an operation, the entire request is considered invalid and the operation will fail. This applies to operations with one object (for example, addAd) as well as list-based operations that include multiple objects (for example, addAds).
After you have selected the service and operation, the second step is to create the SOAP header.
The SOAP header contains metadata about the request, such as authentication information. The elements included in the SOAP header will vary depending on who is making the request. There are two scenarios:
(1) User Requests: If you are a user making a request (for example, you are the advertiser), the SOAP header includes these elements:
| Element | Description | Required |
|---|---|---|
| username | Your username. | Yes |
| password | Your password. | Yes |
| license | Your license key. | Yes |
| masterAccountID | Your master account ID. | Yes |
| accountID | Your account ID. | Required for these services: AdGroupService, AdService, BidInformationService, BudgetingService, CampaignService, ExcludedWordsService, KeywordResearchService, KeywordService |
(2) On-Behalf-Of Requests: If you are a third party (for example, an agency, reseller, or search engine marketer) making a request on behalf of another user (the advertiser) the SOAP header includes these elements:
| Element | Description | Required |
|---|---|---|
| username | Your username. | Yes |
| password | Your password. | Yes |
| license | Your license key. | Yes |
| masterAccountID | The advertiser's master account ID. | Yes |
| accountID | The advertiser's account ID. | Required for these services: AdGroupService, AdService, BidInformationService, BudgetingService, CampaignService, ExcludedWordsService, KeywordResearchService, KeywordService |
| onBehalfOfUsername | The advertiser's "on-behalf-of" username. | Yes |
| onBehalfOfPassword | The advertiser's "on-behalf-of" password. | Yes |
For a third party to make requests on behalf of another user, the proper authorizations must be in place (see On-Behalf-Of Authorizations).
The username and password can be defined in the header in one of two ways:
The preferred method is through the WS-Security extension, where both the Username and Password elements are wrapped in the Security and UsernameToken elements, as shown below. To use WS-Security you must also include the secext schema in the SOAP envelope (here defined as wsse):
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/07/secext"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://marketing.ews.yahooapis.com/V4">
<soapenv:Header>
<wsse:Security>
<wsse:UsernameToken>
<wsse:Username>user</wsse:Username>
<wsse:Password>password</wsse:Password>
</wsse:UsernameToken>
</wsse:Security>
...
</soapenv:Header>
<soapenv:Body>
...
</soapenv:Body>
</soapenv:Envelope>
If your SOAP toolkit does not support WS-Security, use the username and password elements in the header:
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/07/secext"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://marketing.ews.yahooapis.com/V4">
<soapenv:Header>
<username>user</username>
<password>password</password>
...
</soapenv:Header>
<soapenv:Body>
...
</soapenv:Body>
</soapenv:Envelope>
If you are making the request yourself, specify your license key, your master account ID, and your account ID.
The account ID is required only for certain services (AdGroupService, AdService, BidInformationService, BudgetingService, CampaignService, ExcludedWordService, KeywordResearchService, KeywordService).
The license, masterAccountID, and accountID elements are specified in the SOAP header, outside the Security element (if used).
See User Requests.
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/07/secext"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://marketing.ews.yahooapis.com/V4">
<soapenv:Header>
<wsse:Security>
<wsse:UsernameToken>
<wsse:Username>user</wsse:Username>
<wsse:Password>password</wsse:Password>
</wsse:UsernameToken>
</wsse:Security>
<license>35cf33e7-5ad1-3aa9-0593-346681f64eb0</license>
<masterAccountID>9901672</masterAccountID>
<accountID>9901673</accountID>
</soapenv:Header>
<soapenv:Body>
...
</soapenv:Body>
</soapenv:Envelope>
If you are making the request on behalf of another user, specify your license key, the advertiser’s master account ID, and the advertiser’s account ID. You must also specify two additional elements: the advertiser's user name (on-behalf-of user name) and the advertiser's password (on-behalf-of password).
Again, the account ID is required only for certain services (AdGroupService, AdService, BidInformationService, BudgetingService, CampaignService, ExcludedWordService, KeywordResearchService, KeywordService).
The license, masterAccountID, accountID, onBehalfOfUsername, and onBehalfOfPassword elements are specified in the SOAP header, outside the Security element (if used).
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/07/secext"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://marketing.ews.yahooapis.com/V4">
<soapenv:Header>
<wsse:Security>
<wsse:UsernameToken>
<wsse:Username>user</wsse:Username>
<wsse:Password>password</wsse:Password>
</wsse:UsernameToken>
</wsse:Security>
<license>35cf33e7-5ad1-3aa9-0593-346681f64eb0</license>
<masterAccountID>9901672</masterAccountID>
<accountID>9901673</accountID>
<onBehalfOfUsername>advertiser_user</onBehalfOfUsername>
<onBehalfOfPassword>advertiser_password</onBehalfOfPassword>
</soapenv:Header>
<soapenv:Body>
...
</soapenv:Body>
</soapenv:Envelope>
After you have defined the SOAP header, the third step is to create the SOAP body.
The SOAP body contains the service operation and its parameters, and any data. The service, itself, is declared when you post the request (see EWS Locations and Requests and HTTP). Only one operation is allowed per request. Parameters must be specified in order.
For example, this is a request to the CampaignService to get campaigns (specified by the campaign IDs) using the getCampaigns operation.
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/07/secext"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://marketing.ews.yahooapis.com/V4">
<soapenv:Header>
...
</soapenv:Header>
<soapenv:Body>
<getCampaigns >
<campaignIDs>
<long>5354501</long>
<long>5355001</long>
</campaignIDs>
</getCampaigns>
</soapenv:Body>
</soapenv:Envelope>
Your EWS license specifies your command groups and quota (see Command Groups and Quota). Each EWS request includes either an operation or list-based operation that counts against your quota. Each EWS response includes elements in the SOAP header that you can use to track your quota consumption (see Tracking Quota for EWS Responses).
List-based operations allow you to add, get, update, or delete multiple objects. The objects can be simple data types or complex data types.
When you set up a list-based operation, you list the objects in a specific order. EWS guarantees that the operation's response will maintain this order when the response objects are returned (see List-Based Operations for EWS Responses).
List-based "add" operations, such as addAds and addKeywords, may allow you to add up to 1,000 new objects in a single operation. However, the actual number of objects you can declare per operation is determined by your account configuration. Please contact your Technical Account Management Team for more information about the number of campaigns, ad groups, ads, keywords, and excluded words that are allowed for your accounts.
To indicate a list of simple data types (long, int, string), use an enclosing element named for the parameter. Then enclose each individual parameter in an element named for the data type itself.
For example, for the CampaignService, the getCampaigns operation takes a list of campaignID elements as parameters. The parameter name is campaignIDs and the data type is long. The parameter list for this operation looks like this:
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/07/secext"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://marketing.ews.yahooapis.com/V4">
<soapenv:Header>
...
</soapenv:Header>
<soapenv:Body>
<getCampaigns>
<campaignIDs>
<long>5354501</long>
<long>5355001</long>
</campaignIDs>
</getCampaigns>
</soapenv:Body>
</soapenv:Envelope>
To indicate a list of complex data types (Campaign, AdGroup, Keyword, and so on), use an enclosing element named for the parameter, and then include each data type as its own element (with subelements).
For example, for the CampaignService, the addCampaigns operation takes a list of Campaign elements as parameters. In this case the parameter name is campaigns and the data type is Campaign. The parameter list looks like this:
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/07/secext"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://marketing.ews.yahooapis.com/V4">
<soapenv:Header>
...
</soapenv:Header>
<soapenv:Body>
<addCampaigns>
<campaigns>
<Campaign>
<accountID>9901673</accountID>
<advancedMatchON>true</advancedMatchON>
<campaignOptimizationON>false</campaignOptimizationON>
...
</Campaign>
<Campaign>
<accountID>9901673</accountID>
<advancedMatchON>true</advancedMatchON>
<campaignOptimizationON>false</campaignOptimizationON>
...
</Campaign>
</campaigns>
</addCampaigns>
</soapenv:Body>
</soapenv:Envelope>
A complete example of a SOAP request for the CampaignService is shown here. See EWS Locations and Requests and HTTP for more information about how to send the request to EWS.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/07/secext"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://marketing.ews.yahooapis.com/V4">
<soapenv:Header>
<wsse:Security>
<wsse:UsernameToken>
<wsse:Username>user</wsse:Username>
<wsse:Password>password</wsse:Password>
</wsse:UsernameToken>
</wsse:Security>
<license>35cf33e7-5ad1-3aa9-0593-346681f64eb0</license>
<masterAccountID>9901672</masterAccountID>
<accountID>9901673</accountID>
</soapenv:Header>
<soapenv:Body>
<getCampaigns>
<campaignIDs>
<long>5354501</long>
<long>5355001</long>
</campaignIDs>
</getCampaigns>
</soapenv:Body>
</soapenv:Envelope>