Ad Accounts

Article
10/15/2024

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.

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 for non-search APIs

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

Pagination

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

Pagination

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

Note

Starting 202211, response decoration is no longer supported and has been replaced by Additional Info Fields. These new field(s) provide additional information for a field that is present in a schema. Learn more about the Additional Info Fields here.

Field Name	Type	Description	Required	Additional Info Field
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	False	False
id	long	Unique internal ID representing the account	False	False
name	string	A label for the account	True	False
notifiedOnCampaignOptimization	boolean, default="false"	Indicates if the campaign contact is notified about campaign optimization opportunities	False	False
notifiedOnCreativeApproval	boolean, default="false"	Indicates if the creative contact is notified when a creative has been reviewed and approved	False	False
notifiedOnCreativeRejection	boolean, default="false"	Indicates if the creative contact is notified when a creative has been rejected due to content	False	False
notifiedOnEndOfCampaign	boolean, default="false"	Indicates if the campaign contact is notified when an associated campaign has been completed	False	False
notifiedOnNewFeaturesEnabled	boolean, default="false"	Indicates if the account owner is notified about new Campaign Manager features	False	False
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}	False	False
referenceInfo	Union	Information about the entity associated with the reference. If the entity is an organization, an Organizationinfo object is returned. If the entity is a person, a Personinfo object is returned. For all other entity types an empty record will be returned. This is a read only field. Please refer to Additional Info Fields to learn how to access this field.	False	True
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	False	False
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.	False	False
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.	True	False
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.	False	False

OrganizationInfo

Field Name	Type	Description
id	long	Unique ID representing the organization.
name	MultiLocaleString	Name of the organization.
vanityName	string	Name of the organization present in the URLs.
localizedName	string	Locale specific name of the organization.
logo	CroppedImage	The organization’s logo. The sizes may vary greatly, i.e., 50x50, 100x60, 400x400, so clients should handle the given height and width accordingly.

PersonInfo

Field Name	Type	Description
id	Urn	Unique ID representing the member
vanityName	String	Name of the member present in the URLs.

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.

http
curl

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

curl -X POST 'https://api.linkedin.com/rest/adAccounts' \
--H 'Authorization: Bearer {INSERT_TOKEN}' \
--H 'LinkedIn-Version: {version number in the format YYYYMM}' \
--H 'X-Restli-Protocol-Version: 2.0.0' \
--H 'Content-Type: application/json' \
--data '{
    "currency": "USD", 
    "name": "Company A", 
    "notifiedOnCampaignOptimization": true, 
    "notifiedOnCreativeApproval": true, 
    "notifiedOnCreativeRejection": true, 
    "notifiedOnEndOfCampaign": true, 
    "reference": "urn:li:organization:2414183", 
    "type": "BUSINESS"
}'

http
curl

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

curl -X POST 'https://api.linkedin.com/v2/adAccountsV2' \
-H 'Authorization: Bearer {INSERT_TOKEN}' \
-H 'Content-Type: application/json' \
--data '{
    "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

Note

From 202401 version and above, we have moved from index based pagination to cursor based pagination for our search APIs.

Cursor based Pagination for search APIs

The adAccounts API implements cursor based pagination using the pageSize and pageToken parameters for search method. The max allowed pageSize is 1000.

pageSize governs the number of requested entities.
pageToken is used to get the next set of results.
nextPageToken is returned in metadata field of the search response.
This should be passed in pageToken query parameter in the request to get the next page of results.

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.

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.

http
curl

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

curl -X GET 'https://api.linkedin.com/rest/adAccounts?q=search&search=(field:(values:List(value1,value2,...)))' \
--H 'X-Restli-Protocol-Version: 2.0.0' \
--H 'LinkedIn-Version: {version number in the format YYYYMM}' \
--H 'Authorization: Bearer {INSERT_TOKEN}'

http
curl

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

curl -X GET 'https://api.linkedin.com/v2/adAccountsV2?q=search&search=(field:(values:List(value1,value2,...)))' \
-H 'Authorization: Bearer {INSERT_TOKEN}'

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. For example, `urn:li:sponsoredAccount:{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
sortOrder	SortOrder default=ASCENDING	Sort mode by account ID for matching records
pageSize	no	Specifies the number of entities to be returned. The default is 100. Max is 1000.
pageToken	no	Unique key representing the last entity of the response. This is to be used to fetch the next set of entities. If less than pageSize entities are returned in the current response, pageToken will be null.

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))).

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.

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

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

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

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

http
curl

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)

curl -X GET 'https://api.linkedin.com/rest/adAccounts?q=search&search=(type:(values:List(BUSINESS)),status:(values:List(ACTIVE,CANCELED)))&sort=(field:ID,order:DESCENDING)' \
--H 'X-Restli-Protocol-Version: 2.0.0' \
--H 'LinkedIn-Version: {version number in the format YYYYMM}' \
--H 'Authorization: Bearer {INSERT_TOKEN}'

http
curl

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)

curl -X GET 'https://api.linkedin.com/v2/adAccountsV2?q=search&search=(type:(values:List(BUSINESS)),status:(values:List(ACTIVE,CANCELED)))&sort=(field:ID,order:DESCENDING)' \
-H 'Authorization: Bearer {INSERT_TOKEN}'

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"
            }
        }
    ],
    "metadata": {
      "nextPageToken": "DgGerr1iVQreCJVjZDOW_grcp63nueBDipsS4DJpvJo"
    }
}

API Call to get the next set of results would use the nextPageToken passed in the response above.

http
curl

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

curl -X GET 'https://api.linkedin.com/rest/adAccounts?q=search&search=(type:(values:List(BUSINESS)),status:(values:List(ACTIVE,CANCELED)))&sort=(field:ID,order:DESCENDING)&pageToken=DgGerr1iVQreCJVjZDOW_grcp63nueBDipsS4DJpvJo' \
--H 'X-Restli-Protocol-Version: 2.0.0' \
--H 'LinkedIn-Version: {version number in the format YYYYMM}' \
--H 'Authorization: Bearer {INSERT_TOKEN}'

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

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.

http
curl

GET https://api.linkedin.com/rest/adAccounts/{adAccountID}

curl -X GET 'https://api.linkedin.com/rest/adAccounts/{adAccountID}' \
--H 'Authorization: Bearer {INSERT_TOKEN}'\
--H 'LinkedIn-Version: {version number in the format YYYYMM}' \
--H 'X-Restli-Protocol-Version: 2.0.0' \

http
curl

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

curl -X GET 'https://api.linkedin.com/v2/adAccountsV2/{adAccountID}' \
-H 'Authorization: Bearer {INSERT_TOKEN}'

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.

http
curl

POST https://api.linkedin.com/rest/adAccounts/{adAccountID}

{
    "patch": {
        "$set": {
            "name": "This is a new account name."
        }
    }
}

curl -X POST 'https://api.linkedin.com/rest/adAccounts/{adAccountID}' \
--H 'Authorization: Bearer {INSERT_TOKEN}' \
--H 'LinkedIn-Version: {version number in the format YYYYMM}' \
--H 'X-Restli-Protocol-Version: 2.0.0' \
--H 'Content-Type: application/json' \
--data '{
    "patch": {
        "$set": {
            "name": "This is a new account name."
        }
    }
}'

http
curl

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

{
    "patch": {
        "$set": {
            "name": "This is a new account name."
        }
    }
}

curl -X POST 'https://api.linkedin.com/v2/adAccountsV2/{adAccountID}' \
-H 'Authorization: Bearer {INSERT_TOKEN}' \
-H 'Content-Type: application/json' \
--data '{
    "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.

http
curl

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:
curl -X DELETE 'https://api.linkedin.com/rest/adAccounts/{adAccountID}' \
--H 'Authorization: Bearer {INSERT_TOKEN}' \
--H 'LinkedIn-Version: {version number in the format YYYYMM}' \
--H 'X-Restli-Protocol-Version: 2.0.0' \

To delete non DRAFT account:
curl -X POST 'https://api.linkedin.com/rest/adAccounts/{adAccountID}' \
--H 'Authorization: Bearer {INSERT_TOKEN}' \
--H 'X-RestLi-Method: PARTIAL_UPDATE' \
--H 'LinkedIn-Version: {version number in the format YYYYMM}' \
--H 'X-Restli-Protocol-Version: 2.0.0' \
--H 'Content-Type: application/json' \
--data '{
    "patch": {
        "$set": {
            "status": "PENDING_DELETION"
        }
    }
}'

http
curl

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

To delete DRAFT account:
curl -X DELETE 'https://api.linkedin.com/v2/adAccountsV2/{adAccountID}' \
-H 'Authorization: Bearer {INSERT_TOKEN}'

To delete non DRAFT account:
curl -X POST 'https://api.linkedin.com/v2/adAccountsV2/{adAccountID}' \
-H 'Authorization: Bearer {INSERT_TOKEN}' \
-H 'X-RestLi-Method: PARTIAL_UPDATE' \
-H 'Content-Type: application/json' \
--data '{
    "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.

http
curl

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

curl -X POST 'https://api.linkedin.com/rest/adAccounts' \
--H 'X-RestLi-Method: BATCH_CREATE' \
--H 'Authorization: Bearer {INSERT_TOKEN}' \
--H 'LinkedIn-Version: {version number in the format YYYYMM}' \
--H 'X-Restli-Protocol-Version: 2.0.0' \
--H 'Content-Type: application/json' \
--data '{
    "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"
        }
    ]
}

http
curl

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

curl -X POST 'https://api.linkedin.com/v2/adAccountsV2' \
--H 'X-RestLi-Method: BATCH_CREATE' \
--H 'Authorization: Bearer {INSERT_TOKEN}' \
--H 'Content-Type: application/json' \
--data '{
    "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.

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
}

curl -X POST 'https://api.linkedin.com/rest/adAccounts ' \
--H 'Authorization: Bearer {INSERT_TOKEN}' \
--H 'LinkedIn-Version: {version number in the format YYYYMM}' \
--H 'X-Restli-Protocol-Version: 2.0.0' \
--H 'Content-Type: application/json' \
--data '{
        "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

http
curl

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
}

curl -X POST 'https://api.linkedin.com/v2/adAccountsV2 ' \
--H 'Authorization: Bearer {INSERT_TOKEN}' \
--H 'Content-Type: application/json' \
--data '{
        "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

http
curl

GET https://api.linkedin.com/rest/adAccounts/{adAccountID}

curl -X GET 'https://api.linkedin.com/rest/adAccounts/{adAccountID}' \
--H 'Authorization: Bearer {INSERT_TOKEN}'\
--H 'X-Restli-Protocol-Version: 2.0.0' \
--H 'LinkedIn-Version: {version number in the format YYYYMM}'

http
curl

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

curl -X GET 'https://api.linkedin.com/v2/adAccountsV2/{adAccountID}' \
-H 'Authorization: Bearer {INSERT_TOKEN}'

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.

http
curl

POST https://api.linkedin.com/rest/adAccounts/{adAccountId}/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", ...
}

curl -X POST 'https://api.linkedin.com/rest/adAccounts/{adAccountId}/adCampaigns' \
-H 'Authorization: Bearer {INSERT_TOKEN}' \
--H 'X-Restli-Protocol-Version: 2.0.0' \
--H 'LinkedIn-Version: {version number in the format YYYYMM}' \
-H 'Content-Type: application/json' \
--data '{
    "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", ...
}'

http
curl

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

curl -X POST 'https://api.linkedin.com/v2/adCampaignsV2' \
--H 'Authorization: Bearer {INSERT_TOKEN}' \
--H 'Content-Type: application/json' \
--data '{
    "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".

http
curl

GET https://api.linkedin.com/rest/adAccounts/{adAccountId}/adCampaigns/{adCampaignID}

curl -X GET 'https://api.linkedin.com/rest/adAccounts/{adAccountId}/adCampaigns/{adCampaignID}' \
-H 'Authorization: Bearer {INSERT_TOKEN}'\
--H 'X-Restli-Protocol-Version: 2.0.0' \
--H 'LinkedIn-Version: {version number in the format YYYYMM}'

http
curl

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

curl -X GET 'https://api.linkedin.com/v2/adCampaignsV2/{adCampaignID}' \
--H 'Authorization: Bearer {INSERT_TOKEN}'

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.

http
curl

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

curl -X GET 'https://api.linkedin.com/rest/adAccounts?q=search&search.status.values[0]=DRAFT&search.test=true' \
--H 'Authorization: Bearer {INSERT_TOKEN}' \
--H 'LinkedIn-Version: {version number in the format YYYYMM}' \
--H 'X-Restli-Protocol-Version: 2.0.0'

http
curl

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

curl -X GET 'https://api.linkedin.com/v2/adAccountsV2?q=search&search.status.values[0]=DRAFT&search.test=true' \
--H 'Authorization: Bearer {INSERT_TOKEN}'

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

http
curl

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

curl -X GET 'https://api.linkedin.com/rest/adAccounts?q=search&search.status.values[0]=DRAFT&search.test=false' \
--H 'Authorization: Bearer {INSERT_TOKEN}' \
--H 'LinkedIn-Version: {version number in the format YYYYMM}' \
--H 'X-Restli-Protocol-Version: 2.0.0' \

http
curl

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

curl -X GET 'https://api.linkedin.com/v2/adAccountsV2?q=search&search.status.values[0]=DRAFT&search.test=false' \
--H 'Authorization: Bearer {INSERT_TOKEN}'

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

Campaign Group Search

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

http
curl

GET https://api.linkedin.com/rest/adAccounts/{adAccountId}/adCampaignGroups?q=search&search.status.values[0]=ACTIVE&search.test=true

curl -X GET 'https://api.linkedin.com/rest/adAccounts/{adAccountId}/adCampaignGroups?q=search&search.status.values[0]=ACTIVE&search.test=true' \
-H 'Authorization: Bearer {INSERT_TOKEN}' \
--H 'X-Restli-Protocol-Version: 2.0.0' \
--H 'LinkedIn-Version: {version number in the format YYYYMM}'

http
curl

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

curl -X GET 'https://api.linkedin.com/v2/adCampaignGroupsV2?q=search&search.status.values[0]=ACTIVE&search.test=true' \
--H 'Authorization: Bearer {INSERT_TOKEN}'

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

http
curl

GET https://api.linkedin.com/rest/adAccounts/{adAccountId}/adCampaignGroups?q=search&search.status.values[0]=ACTIVE&search.test=false

curl -X GET 'https://api.linkedin.com/rest/adAccounts/{adAccountId}/adCampaignGroups?q=search&search.status.values[0]=ACTIVE&search.test=false' \
-H 'Authorization: Bearer {INSERT_TOKEN}' \
--H 'X-Restli-Protocol-Version: 2.0.0' \
--H 'LinkedIn-Version: {version number in the format YYYYMM}'

http
curl

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

curl -X GET 'https://api.linkedin.com/v2/adCampaignGroupsV2?q=search&search.status.values[0]=ACTIVE&search.test=false' \
--H 'Authorization: Bearer {INSERT_TOKEN}' \
--H 'X-Restli-Protocol-Version: 2.0.0' \
--H 'LinkedIn-Version: {version number in the format YYYYMM}'

Campaign Search

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

http
curl

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

curl -X GET 'https://api.linkedin.com/rest/adAccounts/{adAccountId}/adCampaigns?q=search&search.status.values[0]=ACTIVE&search.test=true&count=5' \
-H 'Authorization: Bearer {INSERT_TOKEN}' \
--H 'X-Restli-Protocol-Version: 2.0.0' \
--H 'LinkedIn-Version: {version number in the format YYYYMM}'

http
curl

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

curl -X GET 'https://api.linkedin.com/v2/adCampaignsV2?q=search&search.status.values[0]=ACTIVE&search.test=true&count=5' \
-H 'Authorization: Bearer {INSERT_TOKEN}'

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

http
curl

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

curl -X GET 'https://api.linkedin.com/rest/adAccounts/{adAccountId}/adCampaigns?q=search&search.status.values[0]=ACTIVE&search.test=false&count=5' \
--H 'Authorization: Bearer {INSERT_TOKEN}' \
--H 'X-Restli-Protocol-Version: 2.0.0' \
--H 'LinkedIn-Version: {version number in the format YYYYMM}'

http
curl

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

curl -X GET 'https://api.linkedin.com/v2/adCampaignsV2?q=search&search.status.values[0]=ACTIVE&search.test=false&count=5' \
--H 'Authorization: Bearer {INSERT_TOKEN}'

Creative Search

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

http
curl

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

curl -X GET 'https://api.linkedin.com/rest/adAccounts/{adAccountId}/adCreatives?q=search&search.status.values[0]=ACTIVE&search.test=true&count=5' \
--H 'Authorization: Bearer {INSERT_TOKEN}' \
--H 'X-Restli-Protocol-Version: 2.0.0' \
--H 'LinkedIn-Version: {version number in the format YYYYMM}'

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

http
curl

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

curl -X GET 'https://api.linkedin.com/rest/adAccounts/{adAccountId}/adCreatives?q=search&search.status.values[0]=ACTIVE&search.test=false&count=5' \
--H 'Authorization: Bearer {INSERT_TOKEN}' \
--H 'X-Restli-Protocol-Version: 2.0.0' \
--H 'LinkedIn-Version: {version number in the format YYYYMM}'

Creative Search

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

http
curl

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

curl -X GET 'https://api.linkedin.com/v2/adCreativesV2?q=search&search.status.values[0]=ACTIVE&search.test=true&count=5' \
--H 'Authorization: Bearer {INSERT_TOKEN}'

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

http
curl

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

curl -X GET 'https://api.linkedin.com/v2/adCreativesV2?q=search&search.status.values[0]=ACTIVE&search.test=false&count=5' \
--H 'Authorization: Bearer {INSERT_TOKEN}'

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

Share via

Ad Accounts

Permissions

Pagination for non-search APIs

Pagination

Pagination

Schema

OrganizationInfo

PersonInfo

Create Ad Account

Search for Accounts

Cursor based Pagination for search APIs

Search Parameters

Sample Request

Search Parameters

Sort Parameters

Sample Request

Search Parameters

Sort Parameters

Sample Request

Sample Response

Sample Response

Sample Response

Fetch Ad Account

Sample Response

Update Ad Account

Delete Ad Account

Batch Create Ad Accounts

Sample Response

Sample Response

Working with Test Ad Accounts

Other Test Ad Account Attributes

Creating a Test Ad Account

Sample Request

Sample Request

Retrieving a Test Ad Account

Sample Request

Sample Response

Creating a Campaign Under the Test Ad Account

Sample Request

Retrieving a Test Campaign

Sample Request

Sample Response

Finder Support

AccountSearch

Campaign Group Search

Campaign Search

Creative Search

Creative Search

Error Codes/Messages

Feedback

Additional resources