Microsoft Advertising User Management API Guide

Auth method: OAuth 2.0 (Microsoft Identity Platform / Azure AD) with developer token

Setup steps

1. Register an application in Azure Active Directory (Azure portal) to obtain a client_id and optionally a client_secret.
2. Request OAuth 2.0 authorization using the Microsoft Identity Platform endpoint: https://login.microsoftonline.com/common/oauth2/v2.0/authorize with scope https://ads.microsoft.com/msads.manage offline_access.
3. Exchange the authorization code for an access token and refresh token via https://login.microsoftonline.com/common/oauth2/v2.0/token.
4. Obtain a Microsoft Advertising developer token from the Microsoft Advertising Developer Portal (https://developers.ads.microsoft.com).
5. Include both the OAuth Bearer access token (Authorization header) and the developer token (DeveloperToken SOAP header) in every API request.

Required scopes

GetUser

• Method: POST
• URL: https://clientcenter.api.bingads.microsoft.com/Api/CustomerManagement/v13/CustomerManagementService.svc
• Watch out for: Passing nil UserId returns the authenticated user's own record. To retrieve another user, you must have Super Admin or Aggregator role.

Request example

<GetUserRequest xmlns="https://bingads.microsoft.com/Customer/v13">
  <UserId i:nil="true" />
</GetUserRequest>

Response example

<GetUserResponse>
  <User><Id>123456</Id><UserName>user@example.com</UserName>
    <Name><FirstName>Jane</FirstName><LastName>Doe</LastName></Name>
    <UserLifeCycleStatus>Active</UserLifeCycleStatus>
  </User>
</GetUserResponse>

GetUsersInfo

• Method: POST
• URL: https://clientcenter.api.bingads.microsoft.com/Api/CustomerManagement/v13/CustomerManagementService.svc
• Watch out for: Returns lightweight UserInfo objects (Id + UserName only), not full User objects. Call GetUser per Id for full details.

Request example

<GetUsersInfoRequest xmlns="https://bingads.microsoft.com/Customer/v13">
  <CustomerId>987654</CustomerId>
  <StatusFilter>Active</StatusFilter>
</GetUsersInfoRequest>

Response example

<GetUsersInfoResponse>
  <UsersInfo>
    <UserInfo><Id>111</Id><UserName>a@example.com</UserName></UserInfo>
    <UserInfo><Id>222</Id><UserName>b@example.com</UserName></UserInfo>
  </UsersInfo>
</GetUsersInfoResponse>

SendUserInvitation

• Method: POST
• URL: https://clientcenter.api.bingads.microsoft.com/Api/CustomerManagement/v13/CustomerManagementService.svc
• Watch out for: User creation is invitation-based; the invitee must accept via email before the account is active. RoleId values: 16=Advertiser Campaign Manager, 41=Super Admin, 100=Viewer, 203=Standard User.

Request example

<SendUserInvitationRequest xmlns="https://bingads.microsoft.com/Customer/v13">
  <UserInvitation>
    <FirstName>John</FirstName><LastName>Smith</LastName>
    <Email>john@example.com</Email>
    <CustomerId>987654</CustomerId>
    <RoleId>16</RoleId>
    <Lcid>1033</Lcid>
  </UserInvitation>
</SendUserInvitationRequest>

Response example

<SendUserInvitationResponse>
  <UserInvitationId>99887766</UserInvitationId>
</SendUserInvitationResponse>

UpdateUser

• Method: POST
• URL: https://clientcenter.api.bingads.microsoft.com/Api/CustomerManagement/v13/CustomerManagementService.svc
• Watch out for: TimeStamp from the prior GetUser call is mandatory; omitting it causes a concurrency fault. UserName cannot be updated.

Request example

<UpdateUserRequest xmlns="https://bingads.microsoft.com/Customer/v13">
  <User>
    <Id>123456</Id>
    <Name><FirstName>Jane</FirstName><LastName>Updated</LastName></Name>
    <TimeStamp>AAAAAAB...</TimeStamp>
  </User>
</UpdateUserRequest>

Response example

<UpdateUserResponse>
  <LastModifiedTime>2024-01-15T10:30:00</LastModifiedTime>
</UpdateUserResponse>

DeleteUser

• Method: POST
• URL: https://clientcenter.api.bingads.microsoft.com/Api/CustomerManagement/v13/CustomerManagementService.svc
• Watch out for: Sets UserLifeCycleStatus to Inactive; does not permanently remove the record. TimeStamp is required.

Request example

<DeleteUserRequest xmlns="https://bingads.microsoft.com/Customer/v13">
  <UserId>123456</UserId>
  <TimeStamp>AAAAAAB...</TimeStamp>
</DeleteUserRequest>

Response example

<DeleteUserResponse xmlns="https://bingads.microsoft.com/Customer/v13" />

GetCustomerPilotFeatures

• Method: POST
• URL: https://clientcenter.api.bingads.microsoft.com/Api/CustomerManagement/v13/CustomerManagementService.svc
• Watch out for: Useful for checking feature availability before calling newer operations; pilot flag integers are not fully documented publicly.

Request example

<GetCustomerPilotFeaturesRequest xmlns="https://bingads.microsoft.com/Customer/v13">
  <CustomerId>987654</CustomerId>
</GetCustomerPilotFeaturesRequest>

Response example

<GetCustomerPilotFeaturesResponse>
  <FeaturePilotFlags><int>78</int><int>212</int></FeaturePilotFlags>
</GetCustomerPilotFeaturesResponse>

UpdateUserRoles

• Method: POST
• URL: https://clientcenter.api.bingads.microsoft.com/Api/CustomerManagement/v13/CustomerManagementService.svc
• Watch out for: Role changes apply at the account level. Passing DeleteRoleId removes the user's role from specified accounts. Super Admin role applies at customer level, not account level.

Request example

<UpdateUserRolesRequest xmlns="https://bingads.microsoft.com/Customer/v13">
  <CustomerId>987654</CustomerId>
  <UserId>123456</UserId>
  <NewRoleId>41</NewRoleId>
  <NewAccountIds><long>111222</long></NewAccountIds>
</UpdateUserRolesRequest>

Response example

<UpdateUserRolesResponse>
  <LastModifiedTime>2024-01-15T11:00:00</LastModifiedTime>
</UpdateUserRolesResponse>

GetUserInvitations

• Method: POST
• URL: https://clientcenter.api.bingads.microsoft.com/Api/CustomerManagement/v13/CustomerManagementService.svc
• Watch out for: Only returns pending (not yet accepted) invitations. Accepted invitations appear as active users via GetUsersInfo.

Request example

<GetUserInvitationsRequest xmlns="https://bingads.microsoft.com/Customer/v13">
  <CustomerId>987654</CustomerId>
  <RoleId i:nil="true" />
</GetUserInvitationsRequest>

Response example

<GetUserInvitationsResponse>
  <UserInvitations>
    <UserInvitation><Id>99887766</Id><Email>john@example.com</Email>
      <RoleId>16</RoleId><ExpirationDate>2024-02-01</ExpirationDate>
    </UserInvitation>
  </UserInvitations>
</GetUserInvitationsResponse>

• Rate limits: Microsoft Advertising API enforces service call limits per developer token and per customer. Limits are documented per service operation but specific numeric thresholds are not publicly published in a single rate-limit table.
• Rate-limit headers: No
• Retry-After header: No
• Rate-limit notes: The API returns SOAP fault codes (e.g., CallRateExceeded) when limits are hit. Microsoft recommends exponential back-off retry logic. Specific numeric limits are not documented publicly.
• Pagination method: offset
• Default page size: 1000
• Max page size: 1000
• Pagination pointer: PageInfo (Index + Size elements in SOAP request)

• Webhooks available: No
• Webhook notes: Microsoft Advertising API does not offer webhooks or push notifications for user management events.
• Alternative event strategy: Poll GetUsersInfo and GetUserInvitations on a schedule to detect user state changes.

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

Limitations:

• Microsoft Advertising does not expose a SCIM 2.0 endpoint.
• User provisioning is managed exclusively through the Customer Management SOAP API via invitation flow.
• No IdP (Okta, Entra, Google Workspace) SCIM connector is officially supported for Microsoft Advertising.

User creation is invitation-only via SendUserInvitation.

There is no direct CreateUser operation;

the invitee must accept the emailed link before their UserLifeCycleStatus transitions to Active and they appear in GetUsersInfo results.

Invitations expire (typically 30 days), and pending invitations are only visible via GetUserInvitations - accepted invitations do not appear there.

Role assignments are a separate operation from profile updates.

UpdateUserRoles handles role and account-scope changes;

UpdateUser handles profile fields (name, contact info).

These cannot be combined in a single call.

Note that UserName (the Microsoft account email) is immutable and cannot be changed via the API after account creation.

DeleteUser does not permanently remove a record - it sets UserLifeCycleStatus to Inactive.

Both UpdateUser and DeleteUser require the TimeStamp concurrency token returned by a prior GetUser call;

a stale or omitted timestamp causes a concurrency fault.

Super Admin (RoleId=41) is scoped at the customer level, while all other roles apply per account.

Invite a new user and assign account-level role

1. Authenticate via OAuth 2.0 and obtain access token with https://ads.microsoft.com/msads.manage scope.
2. Call SendUserInvitation with the user's email, FirstName, LastName, CustomerId, RoleId (e.g., 16 for Campaign Manager), and target AccountIds.
3. Store the returned UserInvitationId for tracking.
4. Poll GetUserInvitations periodically to check if the invitation is still pending.
5. Once accepted, call GetUsersInfo to retrieve the new user's Id, then GetUser for full profile.

Watch out for: Invitations expire (typically 30 days). If the user does not accept, you must re-send the invitation. There is no way to force-create an active user without the invitation acceptance step.

List all active users for a customer

1. Call GetUsersInfo with CustomerId and StatusFilter=Active.
2. Iterate the returned UserInfo list (Id + UserName pairs).
3. For each UserId requiring full details, call GetUser with that UserId.
4. Handle pagination: GetUsersInfo returns up to 1000 records; use PageInfo (Index, Size) if the customer has more than 1000 users.

Watch out for: GetUsersInfo only returns lightweight records. Full profile data requires N additional GetUser calls, which can trigger throttling for large user bases. Implement exponential back-off.

Update a user's role across accounts

1. Call GetUser to retrieve the current user record and TimeStamp.
2. Call UpdateUserRoles with CustomerId, UserId, NewRoleId, and the list of AccountIds to apply the new role.
3. To remove a role from specific accounts, include DeleteRoleId and DeleteAccountIds in the same request.
4. Verify the change by calling GetUser again and inspecting the role assignments.

Watch out for: UpdateUserRoles and UpdateUser are separate operations. Profile field changes (name, contact info) require UpdateUser with TimeStamp; role changes use UpdateUserRoles. Mixing them in one call is not supported.

The two-credential requirement (OAuth Bearer token + developer token) is the most common integration failure point. Developer tokens for production require a separate Microsoft approval process; sandbox tokens use a different base URL (https://clientcenter.api.sandbox.bingads.microsoft.com/...) and are not interchangeable with production.

Teams that test against sandbox and deploy to production without updating the endpoint will receive authentication errors, not a clear environment mismatch signal.

Rate limit thresholds are not publicly documented in a consolidated table. The API returns a CallRateExceeded SOAP fault when throttled, with no Retry-After header. Fetching full user profiles at scale compounds this: GetUsersInfo returns lightweight Id + UserName pairs only, requiring a separate GetUser call per user for full profile data.

On large MCC hierarchies, this N+1 call pattern can trigger throttling quickly. Implement exponential back-off from the start, not as a retrofit.