Google DV360 User Management API Guide

Auth method: OAuth 2.0

Setup steps

1. Create or select a project in Google Cloud Console.
2. Enable the Display & Video 360 API for the project.
3. Create OAuth 2.0 credentials (Service Account for server-to-server, or OAuth client ID for user-delegated flows).
4. Grant the service account or user the appropriate DV360 role (e.g., Admin) within the DV360 UI or via the API.
5. Request an access token using the scope https://www.googleapis.com/auth/display-video.
6. Include the Bearer token in the Authorization header of each API request.

Required scopes

List Users

• Method: GET
• URL: https://displayvideo.googleapis.com/v3/users
• Watch out for: Requires display-video-user-management scope. Results are scoped to entities the caller has access to. Use filter param for server-side filtering.

Request example

GET /v3/users?pageSize=50&filter=displayName%3D%22Jane%22
Authorization: Bearer {token}

Response example

{
  "users": [
    {"userId":"123","email":"jane@example.com","displayName":"Jane"}
  ],
  "nextPageToken": "abc123"
}

Get User

• Method: GET
• URL: https://displayvideo.googleapis.com/v3/users/{userId}
• Watch out for: Returns 403 if the caller does not have visibility into the user's entity scope.

Request example

GET /v3/users/123
Authorization: Bearer {token}

Response example

{
  "userId": "123",
  "email": "jane@example.com",
  "displayName": "Jane",
  "assignedUserRoles": []
}

Create User

• Method: POST
• URL: https://displayvideo.googleapis.com/v3/users
• Watch out for: The email must be a valid Google account. The caller must have ADMIN role on the partner/advertiser being assigned. Creating a user without assignedUserRoles is allowed but the user will have no access.

Request example

POST /v3/users
Authorization: Bearer {token}
{
  "email": "newuser@example.com",
  "displayName": "New User",
  "assignedUserRoles": [{"entityType":"PARTNER","entityId":"456","userRole":"STANDARD"}]
}

Response example

{
  "userId": "789",
  "email": "newuser@example.com",
  "displayName": "New User",
  "assignedUserRoles": [{"assignedUserRoleId":"r1","entityType":"PARTNER","entityId":"456","userRole":"STANDARD"}]
}

Patch (Update) User

• Method: PATCH
• URL: https://displayvideo.googleapis.com/v3/users/{userId}
• Watch out for: updateMask is required and must list only the fields being changed. Patching assignedUserRoles replaces the entire array; use bulkEditAssignedUserRoles for additive/subtractive changes.

Request example

PATCH /v3/users/789?updateMask=displayName
Authorization: Bearer {token}
{"displayName": "Updated Name"}

Response example

{
  "userId": "789",
  "email": "newuser@example.com",
  "displayName": "Updated Name"
}

Delete User

• Method: DELETE
• URL: https://displayvideo.googleapis.com/v3/users/{userId}
• Watch out for: Returns empty body on success (HTTP 200). Caller must have ADMIN access to all entities the user is assigned to, otherwise returns 403.

Request example

DELETE /v3/users/789
Authorization: Bearer {token}

Response example

{}

Bulk Edit Assigned User Roles

• Method: POST
• URL: https://displayvideo.googleapis.com/v3/users/{userId}:bulkEditAssignedUserRoles
• Watch out for: deletedAssignedUserRoles takes assignedUserRoleId strings (not full objects). This is the preferred method for incremental role changes to avoid accidentally removing existing roles.

Request example

POST /v3/users/789:bulkEditAssignedUserRoles
Authorization: Bearer {token}
{
  "deletedAssignedUserRoles": ["r1"],
  "createdAssignedUserRoles": [{"entityType":"ADVERTISER","entityId":"999","userRole":"READ_ONLY"}]
}

Response example

{
  "createdAssignedUserRoles": [{"assignedUserRoleId":"r2","entityType":"ADVERTISER","entityId":"999","userRole":"READ_ONLY"}]
}

List Users (filtered by partner)

• Method: GET
• URL: https://displayvideo.googleapis.com/v3/users
• Watch out for: Filter syntax follows AIP-160. Not all field combinations are supported; unsupported filters return INVALID_ARGUMENT.

Request example

GET /v3/users?filter=assignedUserRoles.entityId%3D%22456%22%20AND%20assignedUserRoles.entityType%3D%22PARTNER%22
Authorization: Bearer {token}

Response example

{
  "users": [{"userId":"789","email":"newuser@example.com"}],
  "nextPageToken": null
}

• Rate limits: DV360 API enforces per-project, per-method quotas. Default quota for users.list and users.get is 1 query per second (QPS) per project. Write operations (create, patch, delete) are also subject to per-project QPS limits.
• Rate-limit headers: No
• Retry-After header: No
• Rate-limit notes: Quota increases can be requested via Google Cloud Console. The API returns HTTP 429 when quota is exceeded. Exponential backoff is recommended. Official docs do not document rate-limit response headers.
• Pagination method: token
• Default page size: 100
• Max page size: 200
• Pagination pointer: pageToken

• Webhooks available: No
• Webhook notes: DV360 API does not offer webhook or push-notification support for user management events.
• Alternative event strategy: Poll users.list periodically to detect changes. For audit events, use Google Cloud Audit Logs (Data Access logs) if enabled for the GCP project linked to DV360.

• SCIM available: No
• SCIM version: Not documented
• Plan required: N/A
• Endpoint: Not documented

Limitations:

• DV360 does not expose a SCIM 2.0 endpoint.
• No native IdP connector (Okta, Entra ID, etc.) for automated provisioning via SCIM.
• User provisioning must be performed via the DV360 REST API or manually in the DV360 UI.

Three automation scenarios cover the majority of lifecycle needs.

For provisioning, POST to /v3/users with the target email, displayName, and an assignedUserRoles array specifying entityType (PARTNER or ADVERTISER), entityId, and userRole

the calling principal must hold ADMIN on every entity being assigned.

For deprovisioning, retrieve the userId via GET /v3/users filtered by email, then call DELETE /v3/users/{userId};

the caller must have ADMIN access to all entities the user is assigned to, or the delete returns 403

use bulkEditAssignedUserRoles to strip individual role assignments first if full ADMIN coverage is unavailable.

For role changes, always use POST /v3/users/{userId}:bulkEditAssignedUserRoles rather than PATCH on assignedUserRoles - PATCH replaces the entire assignedUserRoles array, silently removing any assignments not included in the request body.

Pagination uses a pageToken cursor with a default page size of 100 and a maximum of 200.

The API enforces 1 QPS per method per project by default;

quota is shared across all DV360 accounts tied to the same GCP project, so multi-account setups can exhaust quota faster than expected.

HTTP 429 signals quota exhaustion;

implement exponential backoff - no Retry-After header is returned.

Provision a new analyst with read-only access to a specific advertiser

1. Obtain an OAuth 2.0 access token with scope https://www.googleapis.com/auth/display-video-user-management.
2. POST to /v3/users with the user's email, displayName, and assignedUserRoles containing entityType=ADVERTISER, entityId={advertiserId}, userRole=READ_ONLY.
3. Store the returned userId for future management operations.
4. Verify access by calling GET /v3/users/{userId} and confirming the assignedUserRoles array.

Watch out for: The calling service account or user must hold ADMIN role on the target advertiser. If the advertiser belongs to a partner, partner-level ADMIN also satisfies this requirement.

Deprovision a departing employee across all entities

1. Call GET /v3/users with a filter on the user's email to retrieve their userId.
2. Review the assignedUserRoles array to confirm all entity assignments.
3. Call DELETE /v3/users/{userId}.
4. Confirm HTTP 200 with empty body response.

Watch out for: If the caller lacks ADMIN on any entity the user is assigned to, the delete returns 403. Escalate to a partner-level ADMIN or remove the specific role assignments via bulkEditAssignedUserRoles before deleting.

Promote a user from STANDARD to ADMIN at the partner level

1. Call GET /v3/users/{userId} to retrieve the current assignedUserRoles and find the assignedUserRoleId for the STANDARD partner role.
2. Call POST /v3/users/{userId}:bulkEditAssignedUserRoles with deletedAssignedUserRoles=['{assignedUserRoleId}'] and createdAssignedUserRoles=[{entityType:PARTNER, entityId:'{partnerId}', userRole:ADMIN}].
3. Confirm the response contains the new ADMIN role entry with a new assignedUserRoleId.

Watch out for: Do not use PATCH on assignedUserRoles for this operation - it would overwrite all other role assignments. bulkEditAssignedUserRoles is atomic and preserves unrelated assignments.

Several non-obvious behaviors create integration risk. The userId field is an int64 serialized as a string in JSON - parsing it as a number in JavaScript will cause precision loss for large IDs; always treat it as a string.

The email field is immutable post-creation; a user whose Google account email changes must be deleted and recreated, which also resets all role assignments. Webhooks are not available for user management events;

the only detection mechanism for out-of-band changes is polling users.list and diffing against your identity graph state. For audit coverage, route Google Cloud Audit Logs (Data Access logs) from the linked GCP project - the DV360 API itself exposes no audit trail.

Finally, filter syntax on users.list follows AIP-160 but not all field combinations are supported; unsupported filter expressions return INVALID_ARGUMENT rather than an empty result set, which can break naive polling loops if not explicitly handled.