Ad Account Users API
Warning
Deprecation Notice
The Marketing Version 202310 (Marketing October 2023) and earlier versions (excluding 202306 and 202307) have been sunset. Additionally, the unversioned APIs will be sunset soon. We recommend that you migrate to the versioned APIs as well as migrate to the new Content and Community Management APIs to avoid disruptions. See the Migration page for more details.
If you haven’t yet migrated and have questions, submit a request on the LinkedIn Developer Support Portal.
The Ad Account Users API enables advertisers to manage ad account user access. Ad account users are members who have ad account permissions in Campaign Manager. Partners can manage what roles a user has in order to more finely control access.
Permissions
There are two conditions for successful Ad Account Users API calls:
Scope permission accessibility for:
rw_ads
(read/write)r_ads
(read-only)
The Ad Account user assigning permission holding one of the following Ad Account roles:
ACCOUNT_BILLING_ADMIN
ACCOUNT_MANAGER
CAMPAIGN_MANAGER
CREATIVE_MANAGER
VIEWER
(read-only, even withrw_ads
scope)
Ad Account User Role Definitions
The following table describes in detail what each role provides:
Control Name | Description |
---|---|
VIEWER | View campaign data and reports for the account. No ability to create or edit any campaigns or ads |
CREATIVE_MANAGER | View campaign data and reports for the account. Ability to create and edit ads |
CAMPAIGN_MANAGER | View campaign data and reports for the account. Ability to create and edit campaigns and ads |
ACCOUNT_MANAGER | View campaign data and reports for the account. Ability to create and edit campaigns and ads. Edit account data and manage user access to the account. |
ACCOUNT_BILLING_ADMIN | View campaign data and reports for the account. Ability to create and edit campaigns and ads. Edit account data and manage user access to the account. Can also access billing data and will be billed for this account. |
Note
There should be ONLY ONE USER with the ACCOUNT_BILLING_ADMIN
role in an account.
Schema
Field Name | Type | Description |
---|---|---|
account | SponsoredAccountUrn | Associated advertiser account URN |
campaignContact | boolean | Marked as campaign contact to receive emails on campaign-related events such as whether the campaign is completed. An account can have one or more campaign contacts. |
createdAt | long | Timestamp corresponding to the creation of this record. Number of milliseconds since midnight, January 1, 1970 UTC. |
lastModifiedAt | long | Timestamp corresponding to the last modification of the record. If no modification has happened since creation, lastModified should be the same as created. Number of milliseconds since midnight, January 1, 1970 UTC. |
role | AccountUserRole | Enum of user's role in this account. See the following Account User Roles table for the possible values. |
user | PersonUrn | Associated user URN. |
Create Ad Account User
Sample Request
A successful response returns a 204 No Content
HTTP status code.
Note
A failure can occur if:
- The
account
anduser
URL params do not match the values in the request body. - Either the specified
account
oruser
does not exist.
Update Existing Ad Account User
Sample Request
The following example updates a user's role to CREATIVE_MANAGER
:
A successful response returns a 200 OK
HTTP status code.
A failure can occur when you update a member role which has no access to the specified account. In this case, you create the endpoint to grant member access to an ad account.
Get Ad Account User
Fetching an ad account user requires both account
and user
params to look up an existing ad account user.
Sample Request
Sample Response
{
"account": "urn:li:sponsoredAccount:516986977",
"changeAuditStamps": {
"created": {
"actor": "urn:li:unknown:0",
"time": 1509484800000
},
"lastModified": {
"actor": "urn:li:unknown:0",
"time": 1509484800000
}
},
"role": "CAMPAIGN_MANAGER",
"user": "urn:li:person:_mVMF2Kp8p",
"version": {
"versionTag": "1"
}
}
Find Ad Accounts by Authenticated User
All ad accounts that an authenticated user has access to can be retrieved with the following Find Ad Account endpoint. The only required param is q=authenticatedUser
. This will return all of the ad accounts associated with the member whose access token is being used in the call.
Sample Request
Sample Response
{
"elements": [
{
"account": "urn:li:sponsoredAccount:516413367",
"changeAuditStamps": {
"created": {
"actor": "urn:li:unknown:0",
"time": 1500331577000
},
"lastModified": {
"actor": "urn:li:unknown:0",
"time": 1505328748000
}
},
"role": "ACCOUNT_BILLING_ADMIN",
"user": "urn:li:person:K1RwyVNukt",
"version": {
"versionTag": "89"
}
},
{
"account": "urn:li:sponsoredAccount:516880883",
"changeAuditStamps": {
"created": {
"actor": "urn:li:unknown:0",
"time": 1505326590000
},
"lastModified": {
"actor": "urn:li:unknown:0",
"time": 1505326615000
}
},
"role": "ACCOUNT_BILLING_ADMIN",
"user": "urn:li:person:K1RwyVNukt",
"version": {
"versionTag": "3"
}
}
],
"paging": {
"count": 2,
"links": [],
"start": 0,
"total": 2
}
}
Find Ad Account Users by Accounts
The inverse of the prior endpoint is to fetch all users associated with a specific ad account. This endpoint requires the q=accounts
parameter. It requires at least one accounts
param with a sponsoredAccount
URN. Multiple ad accounts can be requested by chaining together multiple accounts
parameters.
Sample Request
Sample Response
{
"elements": [
{
"account": "urn:li:sponsoredAccount:516986977",
"changeAuditStamps": {
"created": {
"time": 1509484815000
},
"lastModified": {
"time": 1509484815000
}
},
"role": "CAMPAIGN_MANAGER",
"user": "urn:li:person:AeioYvX34u"
},
{
"account": "urn:li:sponsoredAccount:516986977",
"changeAuditStamps": {
"created": {
"time": 1505858342000
},
"lastModified": {
"time": 1509750585000
}
},
"role": "ACCOUNT_BILLING_ADMIN",
"user": "urn:li:person:K1RwyVNukt"
}
],
"paging": {
"count": 2,
"links": [],
"start": 0,
"total": 2
}
}
Delete an Ad Account User
You can remove member access to an ad account by using the DELETE Ad Account User endpoint. Deletion requires both account
and user
params to find the subject ad account user.
Sample Request
Error Codes/Messages
The following table details potential errors that may generate when working with test Ad Account Users.
Scenario | Message | Reason | Type |
---|---|---|---|
Updating Ad Account User | The account id account in the query parameters does not match the account id account in the body. |
ACCOUNT_ID_MISMATCH_IN_PARAM_AND_BODY | INVALID_VALUE |
Creating Ad Account User | A confirmed, primary email is required but is not present for account account . Please set a primary email and make sure it is confirmed. |
MEMBER_HAD_UNCONFIRMED_EMAIL | INVALID_VALUE |
Updating Ad Account User | This request has multiple accounts associated with it, but batch request only supports operations on a single account. Separate the requests by account URN. | MULTIPLE_ACCOUNTS_UNSUPPORTED | INVALID_VALUE |
Updating Ad Account User | The user id user in the query parameters does not match the user id user in the body. |
USER_MISMATCH_IN_PARAM_AND_BODY | INVALID_VALUE |