Ad Accounts

Try in Postman

LinkedIn allows advertisers to create multiple Ad Accounts, which is useful if you advertise on behalf of multiple organizations.

Advertising accounts can have a maximum of 5,000 campaigns and 15,000 creatives.

To create and manage ad campaigns, you must have an Enterprise or Business Ad Account with one authenticated user assigned as the account administrator.

Permissions

There are two conditions for successful calls: (1) Scope permissions to rw_ads and/or r_ads, and (2) the user assigning permission holding one of the following roles in the Ad Account.

Scope permissions:

  • rw_ads (Read/Write)
  • r_ads (Read-Only)

Ad Account Roles:

  • ACCOUNT_BILLING_ADMIN
  • ACCOUNT_MANAGER
  • CAMPAIGN_MANAGER
  • CREATIVE_MANAGER
  • VIEWER (Read-Only, even with rw_ads scope)

For more information on Ad Account roles and permissions:

Pagination

The adAccountsV2 API implements pagination using the start and count parameters, where max count=1000.

400 Bad Request is returned if:

  1. count value > 1000, or
  2. Response elements > 100 and the request does not have pagination request parameters

For more information, see Pagination.

Schema

Field Name Type Description
currency string, default="USD" The 3 character standard currency code such as 'USD' for United States Dollar. Refer to the list of supported currencies for the full list. Note: Advertisers selecting Brazilian Real (BRL) as a currency will see their account budget, advertising bids, and spend in BRL, but their account will be billed in USD. We recommend communicating this to advertisers in your application if they opt for BRL. Learn more
id long Unique internal ID representing the account.
name string A label for the account.
notifiedOnCampaignOptimization boolean, default="false" Indicates if the campaign contact is notified about campaign optimization opportunities.
notifiedOnCreativeApproval boolean, default="false" Indicates if the creative contact is notified when a creative has been reviewed and approved.
notifiedOnCreativeRejection boolean, default="false" Indicates if the creative contact is notified when a creative has been rejected due to content.
notifiedOnEndOfCampaign boolean, default="false" Indicates if the campaign contact is notified when an associated campaign has been completed.
notifiedOnNewFeaturesEnabled boolean, default="false" Indicates if the account owner is notified about new Campaign Manager features.
reference optional URN The entity on whose behalf the account advertises. Must either be in the format urn:li:person:{id} or urn:li:organization:{id}.
servingStatuses string[], default="[]" An array of enums with information about the account's system serving statuses. If an account is eligible for serving, then this array will have a single element:
  • RUNNABLE
Otherwise, this array will contain one or more reasons why the account is not servable:
  • STOPPED
  • BILLING_HOLD
  • ACCOUNT_TOTAL_BUDGET_HOLD
  • ACCOUNT_END_DATE_HOLD
  • RESTRICTED_HOLD
  • INTERNAL_HOLD
status string, default="ACTIVE"
  • ACTIVE - Account is active; this is the default state
  • CANCELED - Account has been permanently canceled
  • DRAFT - Account is in draft status, meaning it's not yet fully set up and it is not serving
type string
  • BUSINESS – This is the only value allowed when creating accounts through the API.
  • ENTERPRISE – This value cannot be used to create accounts through the API and is reserved for accounts created by LinkedIn's internal ad operations systems.
test boolean, default="false" Flag showing whether this account is marked as a test account. An account can be marked as test only during creation. This is an immutable field.

Create Ad Account

Ad Accounts can be created via the LinkedIn API.

Note

The type field must be set to BUSINESS when creating Ad Accounts.

POST https://api.linkedin.com/v2/adAccountsV2
{
    "currency": "USD", 
    "name": "Company A", 
    "notifiedOnCampaignOptimization": true, 
    "notifiedOnCreativeApproval": true, 
    "notifiedOnCreativeRejection": true, 
    "notifiedOnEndOfCampaign": true, 
    "reference": "urn:li:organization:2414183", 
    "type": "BUSINESS"
}

The Ad Account's ID is returned back in the x-linkedin-id response header if creation is successful.

Search for Accounts

Use the q=search parameter with adAccountsV2 to search for accounts by ID, name, reference, type, and status fields. Search criteria can be chained together for increased granularity. If a search query is omitted, all accounts the caller has access to are returned in the response.

Caution

The Rest.li 2.0.0 syntax is required for most calls to /adAccountsV2. Include the header X-RestLi-Protocol-Version: 2.0.0 in your request.

GET https://api.linkedin.com/v2/adAccountsV2?q=search&search=(field:(values:List(value1,value2,...)))

Search Parameters

Field Name Required Description
status no Searches for accounts with the provided status. The possible values include:
  • DRAFT
  • CANCELED
  • ACTIVE
As with most of the other parameters, this field is associated with a document containing a list field named values, so that multiple values may be specified
reference no Searches for accounts by reference.
name. no Searches for an account by name.
id no Searches for an account by ID.
type no Searches for accounts by type. Possible values include:
  • BUSINESS
  • ENTERPRISE
test no Searches for accounts based on test or non-test.
  • true: for test accounts
  • false: for non-test accounts
If not specified, searches for both test and non-test accounts. Note that this parameter is unique in being associated with a single scalar boolean (true or false) rather than a document containing a list field named values

These parameters are encoded within the search parameter as (field1:(values:List(value1,value2,...)), field2:(values:List(value1,value2,...))) -- all as the value of the parameter search. Substitute the appropriate field name (status type) for field1, field2, and so forth.

There is one exception to the above: the test field. This is associated with a scalar value of either true or false, rather than a list within a sub-document. For this, test:true or test:false would be appropriate -- do not use test:(values:List((true))).

Sort Parameters

Field Name Description
field Specifies sort criterion: ID (default)
order Sort order: ASCENDING (default) or DESCENDING

It is optional to specify a sort for the account finder.

Sample Request

The following sample request searches for Ad Accounts where type is BUSINESS and status is either ACTIVE or CANCELED. It also sorts by ID in descending order.

Note

The call shown below may return both test and non-test accounts.
To search only non-test accounts, filter test accounts by specifying search.test=false.
To search only test accounts, specify search.test=true.

Include request header: X-Restli-Protocol-Version: 2.0.0

GET https://api.linkedin.com/v2/adAccountsV2?q=search&search=(type:(values:List(BUSINESS)),status:(values:List(ACTIVE,CANCELED)))&sort=(field:ID,order:DESCENDING)

Sample Response

{
    "elements": [
        {
            "test": false,
            "changeAuditStamps": {
                "created": {
                    "time": 1479402003000
                }, 
                "lastModified": {
                    "time": 1479402004534
                }
            }, 
            "currency": "USD", 
            "id": 507404993, 
            "name": "Dunder Mifflin Account", 
            "notifiedOnCampaignOptimization": true, 
            "notifiedOnCreativeApproval": true, 
            "notifiedOnCreativeRejection": true, 
            "notifiedOnEndOfCampaign": true, 
            "reference": "urn:li:organization:2414183", 
            "servingStatuses": [
                "BILLING_HOLD"
            ], 
            "status": "ACTIVE",
            "type": "BUSINESS", 
            "version": {
                "versionTag": "4"
            }
        }
    ], 
    "paging": {
        "count": 2147483647, 
        "links": [], 
        "start": 0, 
        "total": 56
    }
}

Fetch Ad Account

Individual Ad Accounts can be fetched with the following endpoint taking in an adAccount ID.

GET https://api.linkedin.com/v2/adAccountsV2/{adAccountID}

Sample Response

{
    "test": false,
    "changeAuditStamps": {
        "created": {
            "actor": "urn:li:person:fGcyYDdglZ", 
            "time": 1449768717000
        }, 
        "lastModified": {
            "actor": "urn:li:unknown:0", 
            "time": 1477941718075
        }
    }, 
    "currency": "USD", 
    "id": 123456, 
    "name": "Company A", 
    "notifiedOnCampaignOptimization": true, 
    "notifiedOnCreativeApproval": true, 
    "notifiedOnCreativeRejection": true, 
    "notifiedOnEndOfCampaign": true, 
    "reference": "urn:li:organization:2414183", 
    "servingStatuses": [
        "RUNNABLE"
    ], 
    "status": "ACTIVE",
    "type": "BUSINESS", 
    "version": {
        "versionTag": "10"
    }
}

Update Ad Account

Ad Accounts can be updated through a partial update by patching the fields you want to change. A successful response returns a 204 No Content HTTP status code.

The following example changes the name field only.

POST https://api.linkedin.com/v2/adAccountsV2/{adAccountID}
{
    "patch": {
        "$set": {
            "name": "This is a new account name."
        }
    }
}

Batch Create Ad Accounts

Multiple Ad Accounts can be created in a single API call. This endpoint's request body requires an elements array that contains each Ad Account you would like to create.

Note that the X-RestLi-Method header must be included in the request and set to BATCH_CREATE.

POST https://api.linkedin.com/v2/adAccountsV2
{
    "elements": [
        {
            "currency": "USD", 
            "name": "MyTestAccount 1", 
            "notifiedOnCampaignOptimization": true, 
            "notifiedOnCreativeApproval": true, 
            "notifiedOnCreativeRejection": true, 
            "notifiedOnEndOfCampaign": true, 
            "type": "BUSINESS"
        }, 
        {
            "currency": "USD", 
            "name": "MyTestAccount2", 
            "notifiedOnCampaignOptimization": true, 
            "notifiedOnCreativeApproval": true, 
            "notifiedOnCreativeRejection": true, 
            "notifiedOnEndOfCampaign": true, 
            "type": "BUSINESS"
        }
    ]
}

Sample Response

{
    "elements": [
        {
            "location": "/adAccountsV2/123456",
            "status": 201,
            "id": "123456"
        },
        {
            "location": "/adAccountsV2/987654",
            "status": 201,
            "id": "987654"
        }
    ]
}

Working with Test Ad Accounts

LinkedIn provides the ability to create a test ad account for you to develop, test, and demo your integration. A test ad account provides several benefits, including the ability to create test ads via the API which will never be served and will not require billing.

We recommend you use a test ad account in these cases:

  • Integrating with a new ads API feature, i.e., a new format.
  • Testing or demoing your integration with LinkedIn's marketing platform.

Follow these steps to set up your test ad account:

  • Create a test ad account using the /adAccountsV2 endpoint. Include an additional boolean parameter test to indicate this is a test ad account. Note that you can only create one test ad account per developer application.
  • Using the test ad account, perform other actions like creating and updating ads and creatives as you normally would.
  • Please note these behaviors in test ad accounts:
    • All creatives created under a test ad account will never be served in production.
    • Creatives under the test ad account will be auto-rejected in the review process.
    • Test campaigns do not require billing details or incur any costs.
    • No reporting data is available from /adAnalyticsV2 for test campaigns as they do not get served.
  • Reporting data is not available because impressions do not occur under a test account and no social actions can be measured.
  • Test accounts do not support Audience segment upload.
  • Only business accounts support test ad accounts. Test enterprise ad accounts are not available.
  • You cannot create a test ad account in Campaign Manager. You must create a test ad account using an API endpoint.

Other Test Ad Account Attributes

The following list details other attributes for test ad accounts:

  • You cannot change the status of an existing ad account to be a test account. The only way an ad account can be a test ad account is if you establish it as a test account when you initially create it.
  • Any object you create in a test ad account will have the test flag enabled, indicating the test status of the account is true. All child objects within the test account inherit the test flag.
  • When you set up a test account, the account does not require any credit card or payment information.
  • Campaigns set up under a test account will not be available publicly.
  • You cannot duplicate a campaign within a test account under a production account.

Creating a Test Ad Account

Create a test ad account using the adAccountsV2 API by including an additional boolean test flag to true on the payload.

Sample Request

POST https://api.linkedin.com/v2/adAccountsV2 
{
        "currency": "USD",
        "name": "NAME_OF_T_ACCOUNT",
        "notifiedOnCampaignOptimization": true,
        "notifiedOnCreativeApproval": true,
        "notifiedOnCreativeRejection": true,
        "notifiedOnEndOfCampaign": true,
        "reference": "urn:li:organization:2414183",
        "type": "BUSINESS",
        "test": true
}

Retrieving a Test Ad Account

Sample Request

The following request is a retrieval of a test ad account.

GET https://api.linkedin.com/v2/adAccountsV2/{adAccountID}

Sample Response

Note

/test cannot be set to true if /type is set to ENTERPRISE

{
        "currency": "USD",
        "name": "bizTestAccount",
        "notifiedOnCampaignOptimization": true,
        "notifiedOnCreativeApproval": true,
        "notifiedOnCreativeRejection": true,
        "notifiedOnEndOfCampaign": true,
        "reference": "urn:li:organization:2414183",
        "type": "BUSINESS",
        "test": true
}

Creating a Campaign Under the Test Ad Account

The approach to creating campaigns, campaign groups, and creatives under a test ad account each require the same steps. As an example of creating a test account entity, the following request creates a campaign under test ad account "XXX213".

Sample Request

The following example methods create a test ad campaign under test ad account "XXX213", and a retrieval shows that the test flag has been set.

POST https://api.linkedin.com/v2/adCampaignsV2
{
    "locale": {...},
    "targetingCriteria": {...},
    "dailyBudget": { "amount": "25", "currencyCode": "USD" }, 
    "audienceExpansionEnabled": true, 
    "type": "TEXT_AD", 
    "status": "ACTIVE", 
    "associatedEntity": "urn:li:organization:2414183",
    "account": "urn:li:sponsoredAccount:XXX213",
    "name": "sample campaign data", 
    "costType": "CPC", ...
}

Retrieving a Test Campaign

Every campaign under a Test Ad Account is a Test Campaign and hence, you will find "test" to be true.

Sample Request

The following request is a retrieval of a campaign under test ad account "XXX213".

GET https://api.linkedin.com/v2/adCampaignsV2/{adCampaignID}

Sample Response

{
    "sponsoringLandingPage": false,
    "targetingCriteria": {...},  
    "type": "TEXT_AD",  "locale": {...}, 
    "costType": "CPC", 
    "id": YYY695,
    "activationTime": 0,
    "audienceExpansionEnabled": true,
    "test": true, 
    "associatedEntity": "urn:li:organization:2414183",
    "dailyBudget": { "currencyCode": "USD", "amount": "25" },    
    "name": "sample campaign data"
    "account": "urn:li:sponsoredAccount:XXX213", ...
}

Finder Support

The finder for each entity must be able to filter out the test and non-test ones. The finder calls for account, campaign group, campaign and creative will return test entities (e.g., test accounts, test campaign group, test campaign and test creative) unless test entities are being explicitly filtered out.

The only change needed to search a test entity is the following: search.test=true

AccountSearch

Search for all test accounts in DRAFT Status by using search.test=true in finder calls.

GET https://api.linkedin.com/v2/adAccountsV2?q=search&search.status.values[0]=DRAFT&search.test=true

Search for all non-test accounts in DRAFT Status by using search.test=false in finder calls.

GET https://api.linkedin.com/v2/adAccountsV2?q=search&search.status.values[0]=DRAFT&search.test=false

Similarly, CampaignGroupSearch, CampaignSearch, CreativeSearch has been modified to enable search based on test account or not.

Find ACTIVE Test Campaign Groups by using search.test=true in finder calls.

GET https://api.linkedin.com/v2/adCampaignGroupsV2?q=search&search.status.values[0]=ACTIVE&search.test=true

To search for non-test campaign groups, please specify search.test=false in finder calls.

GET https://api.linkedin.com/v2/adCampaignGroupsV2?q=search&search.status.values[0]=ACTIVE&search.test=false

Find Five ACTIVE Test Campaigns by using search.test=true in finder calls.

GET https://api.linkedin.com/v2/adCampaignsV2?q=search&search.status.values[0]=ACTIVE&search.test=true&count=5

To search for non-test campaign, please specify search.test=false

GET https://api.linkedin.com/v2/adCampaignsV2?q=search&search.status.values[0]=ACTIVE&search.test=false&count=5

To search for test creatives, please specify search.test=true in finder calls.

GET https://api.linkedin.com/v2/adCreativesV2?q=search&search.status.values[0]=ACTIVE&search.test=true&count=5

To search for non-test creatives, please specify search.test=false in finder calls.

GET https://api.linkedin.com/v2/adCreativesV2?q=search&search.status.values[0]=ACTIVE&search.test=false&count=5

Error Codes/Messages

The following table details potential errors that may generate when working with test ad accounts.

Scenario Message Reason Type
Create a test account Syntax exception in path variables Remove X-Restli-Protocol-Version: 2.0.0 from the request header
Creating Test Enterprise Account /test cannot be set to true if /type is set to ENTERPRISE CONDITIONAL_INVALID_VALUE INVALID_VALUE
Creating More Than One Test Account Per App Cannot create another test account. Each developer application may have a maximum of 1 test account(s) associated with it TEST_ACCOUNT_LIMIT_REACHED INVALID_VALUE
Batch Create More Than One Test Account Per App Batch create request of 2 test accounts failed. Each developer application may have a maximum of 1 test account(s) associated with it BATCH_CREATION_TEST_ACCOUNTS_CROSSING_LIMIT ACTION_NOT_ALLOWED
Uploading Audience Under a Test Account Segment creation is not supported for test accounts SEGMENT_CREATION_NOT_ALLOWED_FOR_TEST_ACCOUNTS ACTION_NOT_ALLOWED
Converting Existing Account to Test Attempted to change the value of an un-editable field. -- FIELD_NOT_EDITABLE
Creating Test Campaign Providing Flag Field is not allowed on creation. -- FIELD_NOT_ALLOWED