Ad Accounts

Try in Postman

LinkedIn enables you to create Ad Accounts for your organization's advertising campaigns.

An Ad Account 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 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)

For more information on Ad Account roles and permissions, refer to the following:

Pagination

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

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

A 400 Bad Request notification is returned if:

  • count value > 1000, or
  • 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 see their account budget, advertising bids, and spend in BRL, but their account is billed in USD. We recommend communicating this to stakeholders 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 is advertised. 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 the array has a single element:
  • RUNNABLE Otherwise, the array contains 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
  • PENDING_DELETION - Denotes that the account has been requested to be deleted that is currently pending
  • REMOVED - Denotes that the account was deleted, but must remain fetchable due to the existence of performance data.
  • 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

    LinkedIn 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/rest/adAccounts
    
    {
        "currency": "USD", 
        "name": "Company A", 
        "notifiedOnCampaignOptimization": true, 
        "notifiedOnCreativeApproval": true, 
        "notifiedOnCreativeRejection": true, 
        "notifiedOnEndOfCampaign": true, 
        "reference": "urn:li:organization:2414183", 
        "type": "BUSINESS"
    }
    
    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 ID is returned back in the x-linkedin-id response header if creation is successful.

    Search for Accounts

    Use the q=search parameter with adAccounts 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 /adAccounts. Include the header X-RestLi-Protocol-Version: 2.0.0 in your request.

    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/rest/adAccounts?q=search&search=(field:(values:List(value1,value2,...)))
    
    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
  • PENDING_DELETION
  • REMOVED
  • 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 account
  • false: for non-test account 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 following call 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/rest/adAccounts?q=search&search=(type:(values:List(BUSINESS)),status:(values:List(ACTIVE,CANCELED)))&sort=(field:ID,order:DESCENDING)
    

    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/rest/adAccounts/{adAccountID}
    
    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/rest/adAccounts/{adAccountID}
    
    {
        "patch": {
            "$set": {
                "name": "This is a new account name."
            }
        }
    }
    
    POST https://api.linkedin.com/v2/adAccountsV2/{adAccountID}
    
    {
        "patch": {
            "$set": {
                "name": "This is a new account name."
            }
        }
    }
    

    Delete Ad Account

    Ad Account can be deleted. Use DELETE method to delete a DRAFT account. To start the process of deleting non DRAFT account, update the status to PENDING_DELETION.

    To delete DRAFT account: 
    DELETE https://api.linkedin.com/rest/adAccounts/{adAccountID}
    
    To delete non DRAFT account:
    POST https://api.linkedin.com/rest/adAccounts/{adAccountID}
    {
        "patch": {
            "$set": {
                "status": "PENDING_DELETION"
            }
        }
    }
    
    
    To delete DRAFT account: 
    DELETE https://api.linkedin.com/v2/adAccountsV2/{adAccountID}
    
    To delete non DRAFT account:
    POST https://api.linkedin.com/v2/adAccountsV2/{adAccountID}
    {
        "patch": {
            "$set": {
                "status": "PENDING_DELETION"
            }
        }
    }
    
    

    Note

    Only the billing admin can delete the Ad Accounts.

    Batch Create Ad Accounts

    Multiple Ad Accounts can be created in a single API call. The endpoint 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/rest/adAccounts
    
    {
        "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": "/adAccounts/123456",
                "status": 201,
                "id": "123456"
            },
            {
                "location": "/adAccounts/987654",
                "status": 201,
                "id": "987654"
            }
        ]
    }
    
    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": "/adAccounts/123456",
                "status": 201,
                "id": "123456"
            },
            {
                "location": "/adAccountsV2/987654",
                "status": 201,
                "id": "987654"
            }
        ]
    }
    

    Working with Test Ad Accounts

    LinkedIn enables you to create a test Ad Account so you can develop and demo your integration. A test Ad Account provides several benefits, including the ability to create test ads via the API which are not served and not billed.

    You can use a test Ad Account to:

    • Integrate with new ads API features (e.g., new formats).
    • Test or demo your integration with the LinkedIn marketing platform.

    Follow these steps to set up your test Ad Account:

    • Create a test Ad Account using the /adAccounts 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.
    • 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.

    • Note these behaviors in test Ad Accounts:

      • All creatives created under a test Ad Account are never served in production.
      • Creatives under the test Ad Account are auto-rejected in the review process.
      • Test campaigns do not require billing details or incur any costs.
      • No reporting data is available from /adAnalytics for test campaigns as they do not get served.
      • 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 has 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 are not 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 adAccounts API by including an additional boolean test flag to true on the payload.

    Sample Request

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

    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

    GET https://api.linkedin.com/rest/adAccounts/{adAccountID}
    
    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/rest/adCampaigns
    
    {
        "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", ...
    }
    
    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/rest/adCampaigns/{adCampaignID}
    
    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 returns 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/rest/adAccounts?q=search&search.status.values[0]=DRAFT&search.test=true
    
    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/rest/adAccounts?q=search&search.status.values[0]=DRAFT&search.test=false
    
    GET https://api.linkedin.com/v2/adAccountsV2?q=search&search.status.values[0]=DRAFT&search.test=false
    

    Similarly, CampaignGroupSearch, CampaignSearch, CreativeSearch have 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/rest/adCampaignGroups?q=search&search.status.values[0]=ACTIVE&search.test=true
    
    GET https://api.linkedin.com/v2/adCampaignGroupsV2?q=search&search.status.values[0]=ACTIVE&search.test=true
    

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

    GET https://api.linkedin.com/rest/adCampaignGroups?q=search&search.status.values[0]=ACTIVE&search.test=false
    
    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/rest/adCampaigns?q=search&search.status.values[0]=ACTIVE&search.test=true&count=5
    
    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, specify search.test=false

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

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

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

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

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

    Creative Search

    To search for test creatives, 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, 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