Поделиться через

Ad Account Users API

Warning

Deprecation Notice
The Marketing Version 202406 (Marketing June 2024) has been sunset. We recommend that you migrate to the latest versioned 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

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 user roles to more precisely 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 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 for 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 for the account. Can also access billing data and is 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
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, lastModifiedAt 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 Account User Roles table above for the possible values.
user PersonUrn Associated user URN for your developer app in the format urn:li:person:{PersonID}. You can retrieve PersonID by sending a GET /me request for the authenticated member from your developer application.

Create Ad Account User

PUT https://api.linkedin.com/rest/adAccountUsers/(account:{sponsoredAccountURN},user:{personURN})

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"
}

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"
        }
    }
}

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 the account and user keys 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)

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 parameter is q=authenticatedUser. This returns all 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

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 previous endpoint is to fetch all users associated with a specific ad account. This endpoint requires the q=accounts parameter and supports searching users by only a single ad account. It only returns matching results of the first account ID in the accounts query parameter even if there are multiple account IDs in the accounts query parameter.

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

Sample Request

GET https://api.linkedin.com/rest/adAccountUsers?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 a member's access to an ad account by using the DELETE Ad Account User endpoint. Deletion requires both the account and user keys to identify the ad account user.

Sample Request

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

Error Codes/Messages

The following table details potential errors that may occur 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