Ad Account Users API

  • Article

Warning

Deprecation Notice
The Marketing version 202304 (Marketing April 2023) and below has been sunset and the unversioned APIs are going to 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.

Try in Postman

Try in Postman

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 with rw_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

PUT https://api.linkedin.com/rest/adAccountUsers/account=urn:li:sponsoredAccount:516986977&user=urn:li:person:_mVMF2Kp8p

{
    "account": "urn:li:sponsoredAccount:516986977",
    "role": "VIEWER",
    "user": "urn:li:person:_mVMF2Kp8p"
}

PUT https://api.linkedin.com/v2/adAccountUsersV2/account=urn:li:sponsoredAccount:516986977&user=urn:li:person:_mVMF2Kp8p

{
    "account": "urn:li:sponsoredAccount:516986977",
    "role": "VIEWER",
    "user": "urn:li:person:_mVMF2Kp8p"
}

A successful response returns a 204 No Content HTTP status code.

Note

A failure can occur if:

  • The account and user URL params do not match the values in the request body.
  • Either the specified account or user does not exist.

Update Existing Ad Account User

Sample Request

The following example updates a user's role to CREATIVE_MANAGER:

POST https://api.linkedin.com/rest/adAccountUsers/account=urn:li:sponsoredAccount:516986977&user=urn:li:person:_mVMF2Kp8p

{
    "patch": {
        "$set": {
            "account": "urn:li:sponsoredAccount:516986977",
            "role": "CREATIVE_MANAGER",
            "user": "urn:li:person:_mVMF2Kp8p"
        }
    }
}

POST https://api.linkedin.com/v2/adAccountUsersV2/account=urn:li:sponsoredAccount:516986977&user=urn:li:person:_mVMF2Kp8p

{
    "patch": {
        "$set": {
            "account": "urn:li:sponsoredAccount:516986977",
            "role": "CREATIVE_MANAGER",
            "user": "urn:li:person:_mVMF2Kp8p"
        }
    }
}

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

GET https://api.linkedin.com/rest/adAccountUsers/account=urn:li:sponsoredAccount:516986977&user=urn:li:person:_mVMF2Kp8p


GET https://api.linkedin.com/v2/adAccountUsersV2/account=urn:li:sponsoredAccount:516986977&user=urn:li:person:_mVMF2Kp8p

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

GET https://api.linkedin.com/rest/adAccountUsers?q=authenticatedUser

GET https://api.linkedin.com/v2/adAccountUsersV2?q=authenticatedUser

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.

GET https://api.linkedin.com/rest/adAccountUsers?q=accounts&accounts={sponsoredAccountUrn}

GET https://api.linkedin.com/v2/adAccountUsersV2?q=accounts&accounts={sponsoredAccountUrn}

Sample Request

GET https://api.linkedin.com/rest/adAccountUsers?q=accounts&accounts=urn:li:sponsoredAccount:516986977

GET https://api.linkedin.com/v2/adAccountUsersV2?q=accounts&accounts=urn:li:sponsoredAccount:516986977

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

DELETE https://api.linkedin.com/rest/adAccountUsers/account=urn:li:sponsoredAccount:516986977&user=urn:li:person:_mVMF2Kp8p

DELETE https://api.linkedin.com/v2/adAccountUsersV2/account=urn:li:sponsoredAccount:516986977&user=urn:li:person:_mVMF2Kp8p

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