The Trade Desk User Management API Guide

Auth method: Token-based authentication. Clients POST credentials to obtain a bearer token, which is then passed in the Authorization header for subsequent requests.

Setup steps

1. Obtain API login credentials (username and password) from your Trade Desk account manager or partner portal.
2. POST to https://api.thetradedesk.com/v3/authentication with your login and password to receive an auth token.
3. Include the token in the Authorization header as 'TTD {token}' for all subsequent API requests.
4. Tokens expire; re-authenticate by repeating the POST to /authentication when a 401 is returned.

Authenticate

• Method: POST
• URL: https://api.thetradedesk.com/v3/authentication
• Watch out for: Token expiration is time-bound; cache and refresh proactively to avoid mid-session 401 errors.

Request example

{
  "Login": "user@example.com",
  "Password": "s3cr3t"
}

Response example

{
  "Token": "TTD abc123...",
  "ExpirationDateUtc": "2024-12-31T23:59:59Z"
}

Create User

• Method: POST
• URL: https://api.thetradedesk.com/v3/user
• Watch out for: UserName must be unique; duplicate submissions return a 400 error.

Request example

{
  "UserName": "newuser@example.com",
  "FirstName": "Jane",
  "LastName": "Doe",
  "EmailAddress": "newuser@example.com",
  "PartnerId": "partner123",
  "UserRole": "Standard"
}

Response example

{
  "UserId": "usr_abc456",
  "UserName": "newuser@example.com",
  "IsActive": true
}

Get User

• Method: GET
• URL: https://api.thetradedesk.com/v3/user/{userId}
• Watch out for: Requesting a userId that does not belong to your partner scope returns 403, not 404.

Request example

GET /v3/user/usr_abc456
Authorization: TTD abc123...

Response example

{
  "UserId": "usr_abc456",
  "UserName": "newuser@example.com",
  "FirstName": "Jane",
  "IsActive": true
}

Update User

• Method: PUT
• URL: https://api.thetradedesk.com/v3/user
• Watch out for: PUT replaces the full user object; omitting optional fields may reset them to defaults.

Request example

{
  "UserId": "usr_abc456",
  "FirstName": "Janet",
  "IsActive": true
}

Response example

{
  "UserId": "usr_abc456",
  "FirstName": "Janet",
  "IsActive": true
}

Query Users

• Method: POST
• URL: https://api.thetradedesk.com/v3/user/query
• Watch out for: Pagination uses PageStartIndex (zero-based offset) and PageSize; max PageSize is 100.

Request example

{
  "PartnerId": "partner123",
  "PageStartIndex": 0,
  "PageSize": 100
}

Response example

{
  "Result": [{"UserId": "usr_abc456", "UserName": "newuser@example.com"}],
  "TotalFilteredCount": 1
}

Deactivate User

• Method: PUT
• URL: https://api.thetradedesk.com/v3/user
• Watch out for: There is no dedicated DELETE endpoint for users; deactivation is achieved by setting IsActive=false via PUT.

Request example

{
  "UserId": "usr_abc456",
  "IsActive": false
}

Response example

{
  "UserId": "usr_abc456",
  "IsActive": false
}

• Rate limits: The Trade Desk API enforces rate limits but does not publicly document specific numeric thresholds in its developer portal. Limits are enforced per partner/advertiser account.

• Rate-limit headers: Unknown

• Retry-After header: Unknown

• Rate-limit notes: Official docs do not specify rate-limit headers or Retry-After behavior. Contact your TTD account manager for partner-specific limits.

• Pagination method: offset

• Default page size: 100

• Max page size: 100

• Pagination pointer: PageStartIndex / PageSize

• Webhooks available: No

• Webhook notes: The Trade Desk API does not document a webhook or event-subscription system for user management events in its public developer portal.

• Alternative event strategy: Poll the /user/query endpoint periodically to detect user state changes.

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Custom (enterprise-tier contract required; contact Trade Desk account management)

• Endpoint: Not documented

• Supported operations: Create User, Update User, Deactivate User, List Users

Limitations:

• SCIM endpoint URL is provisioned per-customer and not publicly documented; it is provided by The Trade Desk during enterprise onboarding.
• No publicly documented IdP-specific connector pages for Okta, Entra ID, Google Workspace, or OneLogin.
• Plan gating requires a custom enterprise agreement; not available on self-serve tiers.
• Specific SCIM attribute mappings and supported schema extensions are not publicly disclosed.

Three primary automation scenarios are supported by the documented endpoints.

First, provisioning: POST to /v3/user with UserName, PartnerId, UserRole, and an explicit AdvertiserIds array-omitting AdvertiserIds creates a user with no advertiser-level access regardless of role.

Second, bulk auditing: POST to /v3/user/query with PageStartIndex and PageSize (max 100);

loop by incrementing PageStartIndex until TotalFilteredCount is exhausted, then filter client-side for IsActive=true since no server-side active/inactive filter is documented.

Third, offboarding: retrieve the full user object via GET /v3/user/{userId} first, then PUT the full object back with IsActive=false-skipping the GET risks silently clearing AdvertiserIds or other fields because PUT is a full replacement, not a partial update.

No DELETE endpoint exists;

deactivation via IsActive=false is the only supported removal mechanism.

Provision a new platform user for an advertiser

1. POST to /v3/authentication with admin credentials to obtain a TTD token.
2. POST to /v3/user with UserName, FirstName, LastName, EmailAddress, PartnerId, UserRole, and the target AdvertiserIds array.
3. Store the returned UserId for future update or deactivation operations.
4. Verify creation by GET /v3/user/{userId}.

Watch out for: AdvertiserIds must be explicitly set; omitting the field may result in a user with no advertiser-level access even if UserRole is Standard.

Bulk-list and audit all active users under a partner

1. POST to /v3/authentication to obtain a token.
2. POST to /v3/user/query with PartnerId, PageStartIndex=0, PageSize=100.
3. Check TotalFilteredCount; if greater than 100, loop incrementing PageStartIndex by 100 until all pages are retrieved.
4. Filter results client-side for IsActive=true to identify active accounts.

Watch out for: Max PageSize is 100; large partner accounts require multiple paginated requests. There is no server-side active/inactive filter documented in the query body.

Offboard a departing employee

1. POST to /v3/authentication to obtain a token.
2. GET /v3/user/{userId} to retrieve the current full user object.
3. PUT to /v3/user with the full user object, setting IsActive=false.
4. Confirm deactivation by GET /v3/user/{userId} and verifying IsActive=false in the response.

Watch out for: Because PUT is a full replacement, retrieve the existing object first to avoid accidentally clearing AdvertiserIds or other fields during the deactivation update.

Several non-obvious behaviors create integration risk. PUT semantics apply to all user updates with no PATCH support, so any automation that constructs a partial payload will overwrite unspecified fields with defaults. Cross-partner user lookups return 403, not 404, which can cause incorrect error-handling logic if partner scope isolation is not accounted for in the client.

Rate limits are enforced per partner/advertiser account but numeric thresholds and retry headers are not publicly documented; contact your TTD account manager for partner-specific limits before building high-frequency polling. Webhooks are not available for user management events, making periodic polling of /v3/user/query the only mechanism for detecting state changes.

SCIM endpoint URLs are not self-service and must be requested during enterprise onboarding, meaning SCIM cannot be activated without account manager involvement even if the contract tier supports it.