Starting September 8, 2025 , every new line item will need to declare whether or not they will serve Eurpoean Union (EU) political ads. Display & Video 360 API and SDF uploads that don't provide declarations will fail. See our deprecations page for more details on how to update your integration to make this declaration.

Retrieve a user

The user resource includes both user-specific information, such as the user display name and unique ID, as well as permissions information, or assigned user roles .

This page describes how to retrieve a user resource using an email address.

Retrieve a user from filtered list

Display & Video 360 API user resources have a unique ID assigned by the system upon creation. This ID can be used to retrieve a user resource through the users.get method. However, if you do not have the userId for a user, you can still retrieve the user resource using the users.list method with the filter parameter to filter by email address.

Here's an example of how to retrieve your user resource using this method:

Java

 // Create a variable to store the desired user once found. 
 User 
  
 retrievedUser 
  
 = 
  
 new 
  
 User 
 (); 
 // Create the filter string for list call. Using this filter will return all 
 // users with an email address containing the specified value. 
 String 
  
 emailFilter 
  
 = 
  
 String 
 . 
 format 
 ( 
 "email:\"%s\"" 
 , 
  
  email 
 - 
 address 
 
 ); 
 // Configure the list request. 
 Users 
 . 
 List 
  
 request 
  
 = 
  
 service 
  
 . 
 users 
 () 
  
 . 
 list 
 (); 
 // Set the filter for the request. 
 request 
 . 
 setFilter 
 ( 
 emailFilter 
 ); 
 // Create the response and nextPageToken variables. 
 ListUsersResponse 
  
 response 
 ; 
 String 
  
 nextPageToken 
  
 = 
  
 null 
 ; 
 do 
  
 { 
  
 // Create and execute the list request. 
  
 response 
  
 = 
  
 request 
 . 
 setPageToken 
 ( 
 nextPageToken 
 ). 
 execute 
 (); 
  
 // Check if response is empty. 
  
 if 
  
 ( 
 response 
 . 
 isEmpty 
 ()) 
  
 { 
  
 break 
 ; 
  
 } 
  
 // Iterate over retrieved line items and add to total list. 
  
 for 
  
 ( 
 User 
  
 user 
  
 : 
  
 response 
 . 
 getUsers 
 ()) 
  
 { 
  
 if 
  
 ( 
 user 
 . 
 getEmail 
 () 
  
 == 
  
  email 
 - 
 address 
 
 ) 
  
 { 
  
 retrievedUser 
  
 = 
  
 user 
 ; 
  
 break 
 ; 
  
 } 
  
 } 
  
 // Update the next page token. 
  
 nextPageToken 
  
 = 
  
 response 
 . 
 getNextPageToken 
 (); 
 } 
  
 while 
  
 ( 
 ! 
 Strings 
 . 
 isNullOrEmpty 
 ( 
 nextPageToken 
 ) 
 && 
 retrievedUser 
 . 
 isEmpty 
 ()); 
 // Print user information if a user was found. 
 if 
  
 ( 
 ! 
 retrievedUser 
 . 
 isEmpty 
 ()) 
  
 { 
  
 System 
 . 
 out 
 . 
 printf 
 ( 
 "User %s was found.\n" 
 , 
  
 retrievedUser 
 . 
 getName 
 ()); 
  
 System 
 . 
 out 
 . 
 printf 
 ( 
 "User: %s, Display Name: %s, Email: %s\n" 
 , 
  
 retrievedUser 
 . 
 getUserId 
 (), 
  
 retrievedUser 
 . 
 getDisplayName 
 (), 
  
 retrievedUser 
 . 
 getEmail 
 ()); 
  
 AssignedUserRole 
  
 userRole 
 ; 
  
 for 
  
 ( 
 int 
  
 i 
  
 = 
  
 0 
 ; 
  
 i 
 < 
 retrievedUser 
 . 
 getAssignedUserRoles 
 (). 
 size 
 (); 
  
 i 
 ++ 
 ) 
  
 { 
  
 userRole 
  
 = 
  
 retrievedUser 
 . 
 getAssignedUserRoles 
 (). 
 get 
 ( 
 i 
 ); 
  
 System 
 . 
 out 
 . 
 printf 
 ( 
 "Assigned User Role %s:\n" 
 , 
  
 i 
 + 
 1 
 ); 
  
 if 
  
 ( 
 userRole 
 . 
 getPartnerId 
 () 
  
 != 
  
 null 
 ) 
  
 { 
  
 System 
 . 
 out 
 . 
 printf 
 ( 
 "Partner ID: %s\n" 
 , 
  
 userRole 
 . 
 getPartnerId 
 ()); 
  
 } 
  
 else 
  
 { 
  
 System 
 . 
 out 
 . 
 printf 
 ( 
 "Advertiser ID: %s\n" 
 , 
  
 userRole 
 . 
 getAdvertiserId 
 ()); 
  
 } 
  
 System 
 . 
 out 
 . 
 printf 
 ( 
 "User Role: %s\n" 
 , 
  
 userRole 
 . 
 getUserRole 
 ()); 
  
 } 
 } 
  
 else 
  
 { 
  
 System 
 . 
 out 
 . 
 printf 
 ( 
 "No user was found with email address %s" 
 , 
  
  email 
 - 
 address 
 
 ); 
 }

Python

 # Create a variable to store the desired user once found. 
 retrieved_user 
 = 
 None 
 # Create the filter string for list call. Using this filter will return all 
 # users with an email address containing the specified value. 
 email_filter 
 = 
 'email:" 
 %s 
 "' 
 % 
  email 
 - 
 address 
 
 # Create the page token variable. 
 next_page_token 
 = 
 '' 
 while 
 True 
 : 
 # Request the users list. 
 response 
 = 
 service 
 . 
 users 
 () 
 . 
 list 
 ( 
 filter 
 = 
 email_filter 
 , 
 pageToken 
 = 
 next_page_token 
 ) 
 . 
 execute 
 () 
 # Check if the response is empty. 
 if 
 not 
 response 
 : 
 break 
 # Iterate over retrieved users. 
 for 
 user 
 in 
 response 
 [ 
 'users' 
 ]: 
 # Break from the loop if the user is found. 
 if 
 user 
 [ 
 'email' 
 ] 
 == 
  email 
 - 
 address 
 
 retrieved_user 
 = 
 user 
 break 
 # Break out of the loop if there is no next page or if the user has been 
 # found. 
 if 
 'nextPageToken' 
 not 
 in 
 response 
 or 
 user 
 is 
 not 
 None 
 : 
 break 
 # Update the next page token. 
 next_page_token 
 = 
 response 
 [ 
 'nextPageToken' 
 ] 
 # Print user information if a user was found. 
 if 
 retrieved_user 
 : 
 print 
 ( 
 'User 
 %s 
 was found.' 
 % 
 retrieved_user 
 [ 
 'name' 
 ]) 
 print 
 ( 
 'User: 
 %s 
 , Display Name: 
 %s 
 , Email: 
 %s 
 ' 
 % 
 ( 
 retrieved_user 
 [ 
 'userId' 
 ], 
 retrieved_user 
 [ 
 'displayName' 
 ], 
 retrieved_user 
 [ 
 'email' 
 ])) 
 for 
 index 
 in 
 range 
 ( 
 len 
 ( 
 retrieved_user 
 [ 
 'assignedUserRoles' 
 ])): 
 print 
 ( 
 'Assigned User Role 
 %s 
 :' 
 % 
 index 
 ) 
 if 
 'partnerId' 
 in 
 retrieved_user 
 [ 
 'assignedUserRoles' 
 ][ 
 0 
 ]: 
 print 
 ( 
 'Partner ID: 
 %s 
 ' 
 % 
 retrieved_user 
 [ 
 'assignedUserRoles' 
 ][ 
 0 
 ][ 
 'partnerId' 
 ]) 
 else 
 : 
 print 
 ( 
 'Advertiser ID: 
 %s 
 ' 
 % 
 retrieved_user 
 [ 
 'assignedUserRoles' 
 ][ 
 0 
 ][ 
 'advertiserId' 
 ]) 
 print 
 ( 
 'User Role: 
 %s 
 ' 
 % 
 retrieved_user 
 [ 
 'assignedUserRoles' 
 ][ 
 0 
 ][ 
 'userRole' 
 ]) 
 else 
 : 
 print 
 ( 
 'No user was found with email address 
 %s 
 ' 
 % 
  email 
 - 
 address 
 
 )

PHP

 // Create a variable to store the desired user once found. 
 $retrievedUser = null; 
 // Create the filter string with the desired user email. 
 $emailFilter = 'email:"' . email-address 
. '"'; 
 # Create the page token variable. 
 $nextPageToken = ''; 
 do { 
 // Build argument parameters for list call. 
 $optParams = array( 
 'filter' => $emailFilter, 
 'pageToken' => $nextPageToken 
 ); 
 // Call the API, getting the line items with flights ending before the 
 // given date. 
 $response = $this->service->users->listUsers($optParams); 
 // If no line items are returned, break loop. 
 if (!empty($response->getUsers())) { 
 break; 
 } 
 foreach ($response->getUsers() as $user) { 
 if ($user->getEmail() == email-address 
) { 
 $retrievedUser = $user; 
 break; 
 } 
 } 
 $nextPageToken = $response->getNextPageToken(); 
 } while (is_null($retrievedUser) && $nextPageToken); 
 // Print user information if a user was found. 
 if (!is_null($retrievedUser)) { 
 printf( 
 'User %s was found.\nUser: %s, Display Name: %s, Email: %s\n', 
 $retrievedUser->getName(), 
 $retrievedUser->getUserId(), 
 $retrievedUser->getDisplayName(), 
 $retrievedUser->getEmail() 
 ); 
 // Print each assigned user role for user. 
 foreach ($retrievedUser->getAssignedUserRoles() as $userRole) { 
 print("Assigned User Role:\n"); 
 if ($userRole->getPartnerId()) { 
 printf("\tPartner ID: %s\n", $userRole->getPartnerId()); 
 } else { 
 printf("\tAdvertiser ID: %s\n", $userRole->getAdvertiserId()); 
 } 
 printf("\tUser Role: %s\n", $userRole->getUserRole()); 
 } 
 } else { 
 printf( 
 "No user was found with email address %s", 
  email-address 
 
 ); 
 }

Overview

Create a user

Retrieve a user Stay organized with collections Save and categorize content based on your preferences.

Retrieve a user from filtered list

Java

Python

PHP

Retrieve a user