This page provides details on how to perform common tasks using the API.
The UserService allows a user with Administrator rights to create a user directly in their network. Any developer can do this without having the new user sign up first. For example, if you are trying out the API for the first time, instead of performing every API call as an Administrator (the default for your email address), you may want to create a few users with roles such as Salesperson, Trafficker, or Advertiser to test real-world workflows.
- Create some new gmail addresses such as
email@example.com. Alternatively, register an existing non-gmail address as a new Google account.
createUserswith that new address and the chosen
- You can authenticate as that new user, using OAuth 2.0 to generate your access token.
Both the topmost
AdUnit to which you can add child nodes and the permitted depth of your hierarchy depend on your account type (Small Business or Premium). The topmost
AdUnit that supports modifying its child nodes is called the effective root
Note: Different account types support different hierarchy patterns.
You search for objects by search criteria using the
exposed by many services, where Object is a specific object type. This
method takes a PQL query, which is similar to a SQL query in that it lets you specify
fields to search on (where field names map to properties on the object), sort,
limit, and offset your search results. See the PQL
Guide to learn more about PQL, and also to learn which object fields you can
To create an order, simply create an
Order object and set the advertiser,
salesperson, and trafficker IDs to the appropriate users, assign a unique name,
createOrders(). The result will include the newly created
or an error.
See example Java code for creating an order.
Here are the steps for creating a new line item:
- Create a new
Orderobject or use an existing one.
- Create a new
LineItemobject, and set the rotation type, creative size array, start and end dates, and other properties.
- Create a new
InventoryTargetingobject, and specify which
AdUnitobjects to target or exclude.
- Wrap your
InventoryTargetingobject inside a new
Targetingobject, and assign it to your
LineItem's targeting property.
- Call the lineitem service method
createLineItems()with your new object, and examine the result to see whether your object was created.
See example Java code for creating a line item.
Different types of creatives support different components: for example, an image
creative supports a single source file for the image; a flash creative supports
two underlying asset files: a flash file and a backup image file, in case the flash
file cannot be served. For creatives hosted on third-party sites, you will upload
only an HTML snippet that references the file on the third-party server. See your
Creative subclass to learn what assets you'll have to upload in order
to create your creative.
See example Java code for creating an image creative.
To modify an existing object, query for your object by calling
update the values in the returned objects, and then call
Note: Updated objects will completely replace existing objects, so if you neglect to set a property value in the object that you send, the saved object will get the default value for that property, not the previous value.
Object status is changed by calling the
exposed by your service. This method takes two parameters:
- An instance of the action object that describes what you want done. For
instance, the order service exposes several actions including
ArchiveOrders. Action objects all derive from a base action class appropriate for your service.
- A PQL query describing which objects to change. You can change the status of one or more objects at a time by specifying an appropriate PQL statement.
You cannot generate ad tags using the API; instead you must use the DFP website. See the Tagging Help Center section for more information.
You can find many more examples in our client library sample code, in several different programming languages. See the Client Libraries & Example Code page for a link to examples in your programming language.