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

[Legacy] Offline Conversions

  • Статья

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.

Offline Conversions allow you to onboard your offline conversion events to better measure your campaign performance. You achieve this by attributing offline conversions in addition to online conversions to provide a more accurate view of your return on ad spend and optimize campaign performance.

Note

This API has been sunset since November 2023, and last available version was 202310. We are not accepting new applications. To learn more, see the FAQ. If eligible, you may apply for access to the new Conversions API.

Permissions

There are two conditions for successful calls:

  • Scope permissions:

    • rw_offlineConversions for streaming conversion events
    • rw_ads for associating conversions to campaigns

  • User assigning permission holding one of the following roles in the Ad Account:

    • ACCOUNT_BILLING_ADMIN
    • ACCOUNT_MANAGER
    • CAMPAIGN_MANAGER
    • CREATIVE_MANAGER

For more information on Ad Account roles and permissions:

Create a new Offline Conversion DMP Segment

To create a new offline events source, offline conversion segment must be created via DMP, a platform for you to upload and create audiences that you collect offsite. Alternatively, any existing offline conversion DMP Segment can be reused to stream offline conversion events.

POST /dmpSegments

Schema

Field Name Type Description
accessPolicy PRIVATE The default access policy of this DMP segment. Currently, the only accepted value is PRIVATE.
account urn The sponsored account urn that this DMP segment belongs to. Refer here to search for sponsored accounts that can be used.
description string (optional) A description for this DMP segment.
destinations LINKEDIN The destinations and various metadata that the content of this segment will be onboarded to. See DMP Segment Destinations. Currently, the only accepted value is LINKEDIN.
name string The name of this DMP segment. 
sourcePlatform string The source platform from where users profiles are being imported. A dedicated ENUM will be provided to approved partners when they are granted access to these APIs. 
sourceSegmentId string (optional) The foreign key on the source platform. This is an optional field that will be indexed and can be used by the source platform to find their segments.
type USER The content type of the profiles being imported into this DMP segment. Possible value is USER
sourceType CONVERSION Source type is an additional type for the segment's input data that is independent from DMPSegmentType. It is used to filter for offline conversion segments from other audiences and apply additional input validations. Currently, the only accepted value is CONVERSION.

Sample Request

POST https://api.linkedin.com/rest/dmpSegments

{
  "name":"Offline Conversion Events",
  "sourcePlatform":"DMP_PARTNER_PLATFORM", // Name will be provided.
  "account":"urn:li:sponsoredAccount:516848833",
  "accessPolicy":"PRIVATE",
  "type":"USER",
  "sourceType": "CONVERSION",
  "destinations":[
    {
      "destination":"LINKEDIN"
    }
  ]
}'

POST https://api.linkedin.com/v2/dmpSegments

{
  "name":"Offline Conversion Events",
  "sourcePlatform":"DMP_PARTNER_PLATFORM", // Name will be provided.
  "account":"urn:li:sponsoredAccount:516848833",
  "accessPolicy":"PRIVATE",
  "type":"USER",
  "sourceType": "CONVERSION",
  "destinations":[
    {
      "destination":"LINKEDIN"
    }
  ]
}'

Sample Response

A successful response returns a 201 Created HTTP status code and the segment ID in the x-linkedin-id response header.

Note

Once this Offline Conversion DMP Segment is created, it will be an empty segment, and we recommend inserting a timer to wait for at least 5 seconds after it is first created. It can then be used to stream any offline conversion events.

For more information including GET, UPDATE and DELETE methods, see DMP Segments - LinkedIn

Find Offline Conversion DMP Segments by Ad Account

Use the q=account query parameter and pass the sponsored ad account URN to find DMP segments by the associated sponsored ad account and use the sourceType=CONVERSION query parameter to filter on the offline conversion segments. For more granular results, you can add optional sourcePlatform and sourceSegmentId query parameters to the query.

GET /dmpSegments?q=account&account={sponsoredAdAccountURN}&sourceType=CONVERSION

Sample Request

GET https://api.linkedin.com/rest/dmpSegments?q=account&account=urn:li:sponsoredAccount:1234&sourceType=CONVERSION

Stream Offline Conversion Event to the DMP Segment

Use the DMP segment ID created or retrieved in the previous step to stream offline conversion events to that DMP segment.

POST /dmpSegments/{dmpSegmentId}/conversions

Note

Below are the available fields for an offline conversion streaming upload. Note that although firstName and lastName are marked as optional*, at least one userIds or {firstName and lastName} must be added for the event to be valid and accepted.

Schema

Field Name Type Description
dmpSegmentId int The ID of the DMP segment where the input conversion event will be added to or removed from.
action string ADD or REMOVE the input conversion event

User

user object containing attributes of the user who performed the conversion.

Field Name Type Description
userIds string Array of user ids with idValue and their type idType. The following idType values are currently supported:
  • SHA256_EMAIL: A HEX encoded string of email address with a maximum length of 64 characters. For example, 692682111bc191d915ac7009d118a78bc496cf7a2ba8c2d0134ade012ac1234
  • SHA512_EMAIL: A HEX encoded string of email address with a maximum length of 128 characters. For example, 09d118a78b692682111bc15ac70c496cf7a9e0502ba8c2d016f2f496cf7a2ba8c1
    		•
    firstName string(optional*) A plain text string with max length 35 characters representing the first name of the contact to match the conversion to. e.g. Mike
    lastName string(optional*) A plain text string with max length 35 characters representing the last name of the contact to match. e.g. Smith
    company string(optional) A plain text string with max length 50 characters representing the company of the contact to match. e.g. Microsoft
    title string(optional) A plain text string with max length 50 characters representing the title name of the contact to match. e.g. Software Engineer
    country string(optional) An ISO standardized two letter country code representing the country of the contact to match e.g. Smith

    Conversion

    conversion object containing attributes of the conversion event.

    Field Name Type Description
    conversionHappenedAt long Epoch timestamp in milliseconds at which the conversion event happened (e.g. 1665392484000). Note: If your source records conversion timestamp in seconds, please insert 000 at the end to transform it to milliseconds.
    conversionType string Type of the conversion (e.g. “LEAD”). Supported conversion types are:
  • "ADD_TO_CART" : The user added one or more things to their shopping cart.
  • "DOWNLOAD" : The user downloaded a file.
  • "INSTALL" : The user installed a plugin or an app.
  • "KEY_PAGE_VIEW" : The user viewed an important web page / app screen.
  • "LEAD" : The user filled out a lead generation form.
  • "PURCHASE" : The user made a purchase.
  • "SIGN_UP" : The user signed up for a web site / app service."
  • "OTHER" : Something that's not listed.
  • "TALENT_MEDIA_ENGAGEMENT" : User interacted with LinkedIn Talent Media or Organization page. Deprecated, replaced by more specific actions such as TALENT_LEAD or JOB_APPLY.
  • "TALENT_LEAD" : User submitted their information as a lead on LinkedIn Talent Media's Pipeline Builder Page.
  • "JOB_APPLY" : User clicked apply to a job on LinkedIn.
  • "SAVE": Saves a form or state in the flow.
  • "START_CHECKOUT": Begins the checkout process.
  • "SCHEDULE": Schedule a service or appointment.
  • "VIEW_CONTENT": The user viewed an section of the page or app screen(webview).
  • "VIEW_VIDEO": The user played a video.
  • "ADD_BILLING_INFO": The user added credit card or purchase details.
  • "BOOK_APPOINTMENT": The user reserved an appointment.
  • "REQUEST_QUOTE": The user requested a quote.
  • "SEARCH": The user searched within the app. Can also track using KEY_PAGE_VIEW that will fire from a search results page.
  • "SUBSCRIBE": The user subscribed to a service.
  • "AD_CLICK": The user clicked a 3rd party ad. (first party ads are tracked from LinkedIn)
  • "AD_VIEW": The user viewed an ad.
  • "COMPLETE_SIGNUP": The user completed registration process.
  • "SUBMIT_APPLICATION": The user submitted an application, same as COMPLETE_SIGNUP.
  • "PHONE_CALL": The user started a call, or performed phone-call specific event or submission.
  • "INVITE": The user sent/shared an invite.
  • "LOGIN": The user logged in to advertiser's service account.
  • "SHARE": The user shared content.
  • "DONATE": The user performed a donation
  • "ADD_TO_LIST": The user added a product to a wishlist.
  • "RATE": The user rated a service or a product.
  • "START_TRIAL": The user started a trial subscription. Overlaps with SUBSCRIBE.
  • "OUTBOUND_CLICK": The user left the app or page by clicking a link. (we won't capture the link).
  • "CONTACT": The user attempted to contact, by filling a form or PHONE_CALL
    		•
    moneyAmount object Object with the monetary value for this conversion. It contains “currencyCode” in ISO format (e.g. “USD”) and the “amount” value of the conversion in decimal string. (e.g. “100.05”)

    Sample Request

    POST https://api.linkedin.com/rest/dmpSegments/10804/conversions

    {
   "action": "ADD",
   "user":{
       "userIds": [
           {
               "idType": "SHA256_EMAIL",
               "idValue": "bad8677b6c86f5d308ee82786c183482a5995f066694246c58c4df37b0cc41f1"
           }
           ],
       "firstName": "mike",
       "lastName": "smith",
       "title": "software engineer",
       "company": "microsoft",
       "country": "us"
   },
   "conversion":{
       "conversionType": "LEAD",
       "moneyAmount": {
           "currencyCode": "USD",
           "amount": "50.0"
       },
       "conversionHappenedAt": 1617658551000
   }
}'

    POST https://api.linkedin.com/v2/dmpSegments/10804/conversions

    {
   "action": "ADD",
   "user":{
       "userIds": [
           {
               "idType": "SHA256_EMAIL",
               "idValue": "bad8677b6c86f5d308ee82786c183482a5995f066694246c58c4df37b0cc41f1"
           }
           ],
       "firstName": "mike",
       "lastName": "smith",
       "title": "software engineer",
       "company": "microsoft",
       "country": "us"
   },
   "conversion":{
       "conversionType": "LEAD",
       "moneyAmount": {
           "currencyCode": "USD",
           "amount": "50.0"
       },
       "conversionHappenedAt": 1617658551000
   }
}'

    Sample Response

    A 201 Created HTTP status code is returned if the request is successful. A 400 Bad Request is returned if the request does not pass the validation check. Please check the error message to further analyze the error.

    Batch Stream Multiple Conversion Events to the DMP Segment

    Tip

    • We recommend using the BATCH_CREATE request header to avoid hitting rate limits on POST by streaming multiple conversion events on the same POST request.
    • We support request payload size of 2 MB, so you should be able to send up to 5000 conversion events in a single batch request.

    Sample Request

    POST https://api.linkedin.com/rest/dmpSegments/{dmpSegmentId}/conversions
X-RestLi-Method: BATCH_CREATE

    {
 "elements":
[
 {
  "action": "ADD",
  "user": {
    "userIds": [
    {
      "idType": "SHA256_EMAIL",
      "idValue": "bad8677b6c86f5d308ee82786c183482a5995f066694246c58c4df37b0cc41f1"
    }
    ],
    "firstName": "mike",
    "lastName": "smith",
    "title": "software engineer",
    "company": "microsoft",
    "country": "us"
  },
  "conversion": {
       "conversionType": "LEAD",
       "moneyAmount": {
           "currencyCode": "USD",
           "amount": "50.0"
       },
       "conversionHappenedAt": 1617658551000
   }
 },
{
 "action": "ADD",
 "user": {
    "userIds": [
    {
      "idType": "SHA256_EMAIL",
      "idValue": "bad8677b6c86f5d308ee82786c183482a5995f066694246c58c4df37b0cc412"
    }
    ],
    "firstName": "john",
    "lastName": "russell",
    "title": "software engineer",
    "company": "linkedin",
    "country": "us"
  },
 "conversion": {
       "conversionType": "LEAD",
       "moneyAmount": {
           "currencyCode": "USD",
           "amount": "100.0"
       },
       "conversionHappenedAt": 1618258551000
   }
 }
]
}

    Sample Response

    {
"elements": [
{
 "status": 201
},
{
"status": 201
}
]
}

    A 400 Bad Request error is returned if the request is incorrect. The error message contains a reference to batchIndex, with the index of the element that caused the error.

    If there is any invalid value in the request body like missing required field or invalid hash value in email, all records will fail and you'll need to resubmit the entire payload after correcting the data as indicated in the response body "message".

    Create Conversion Rules and Associate them to Campaigns

    To measure offline conversions, you must create a conversion rule for each conversion type passed in streaming conversion events in previous step for each conversion segment, and associate them to campaigns for attribution. Advertisers can also Set up Offline Conversion tracking in LinkedIn Campaign Manager.

    Create a Conversion Rule

    Similar to online conversion tracking, instead of defining URL match rules that are applicable for online conversions, advertisers will associate the offline conversion DMP segment created, where the offline conversion events are streamed for a specific conversion type.

    POST /conversions

    Schema

    Field Type Description
    account URN The Sponsored Account URN that this Conversion resides under. This can be either specified in URL query parameter or in the request JSON body.
    name string A short name for this rule, which will be shown in the UI and in reports.
    type string Type of the offline conversion to track for this conversion rule as used in streamed offline conversion event. Eg. PURCHASE, LEAD, SIGNUP etc. Complete list can be found here.
    dmpSegment URN DMP Segment URN that contains the offline events.
    associatedCampaigns Read only. Array of campaign URNs associated with this conversion. default=[ ] Campaign association needs to be done separately as shown in the next step.
    conversionMethod string For offline conversions, the only supported value here is OFFLINE_CONVERSIONS_UPLOAD
    postClickAttributionWindowSize int Conversion window timeframe (in days) of a member clicking on a LinkedIn Ad (a post-click conversion) within which conversions will be attributed to a LinkedIn ad. Allowed values are 1, 7, 30 or 90. Default is 30. Learn more
    viewThroughAttributionWindowSize int Conversion window timeframe (in days) of a member seeing a LinkedIn Ad (a view-through conversion) within which conversions will be attributed to a LinkedIn ad. Allowed values are 1, 7, 30 or 90. Default is 7. Learn more
    attributionType string The model that describes how conversion actions are to be counted. Acceptable values are: LAST_TOUCH_BY_CAMPAIGN and LAST_TOUCH_BY_CONVERSION
  • LAST_TOUCH_BY_CAMPAIGN (Each campaign): conversion actions are counted once for each campaign to which they can be attributed. (Default)
  • LAST_TOUCH_BY_CONVERSION (Single Campaign): conversion actions are counted once for each Conversion with at least one associated campaign. [Learn more] (https://www.linkedin.com/help/lms/answer/a426349)
    		•

    Sample Request

    POST https://api.linkedin.com/rest/conversions

    {
  "postClickAttributionWindowSize": 30,
  "viewThroughAttributionWindowSize": 7,
  "type": "LEAD",
  "name": "Offline Conversion ID",
  "attributionType": "LAST_TOUCH_BY_CAMPAIGN",
  "account": "urn:li:sponsoredAccount:519072844",
  "dmpSegment": "urn:li:dmpSegment:123",
  "conversionMethod": "OFFLINE_CONVERSIONS_UPLOAD"
}'

    POST https://api.linkedin.com/v2/conversions

    {
  "postClickAttributionWindowSize": 30,
  "viewThroughAttributionWindowSize": 7,
  "type": "LEAD",
  "name": "Offline Conversion ID",
  "attributionType": "LAST_TOUCH_BY_CAMPAIGN",
  "account": "urn:li:sponsoredAccount:519072844",
  "dmpSegment": "urn:li:dmpSegment:123",
  "conversionMethod": "OFFLINE_CONVERSIONS_UPLOAD"
}'

    Sample Response

    • A 201 Created HTTP status code is returned if the request is successful and conversion rule ID in the X-LinkedIn-Id response header.
    • A 400 Bad Request is returned if the request does not pass the validation check. Please check the error message to understand what validation failed.

    For more information, see Conversion Tracking.

    Associate Campaigns to Conversion

    Campaign Conversions API is used to associate campaigns to a Conversion ID. Only the campaigns associated with the conversion are eligible for attributing tracked offline Conversions.

    PUT  /campaignConversions/(campaign:{sponsoredCampaignURN},conversion:{conversionURN})

    Sample Request

    PUT https://api.linkedin.com/rest/campaignConversions/(campaign:urn%3Ali%3AsponsoredCampaign%3A337643194,conversion:urn%3Alla%3AllaPartnerConversion%3A70203)

    {
  "campaign": "urn:li:sponsoredCampaign:337643194",
  "conversion": "urn:lla:llaPartnerConversion:70203"
}'

    PUT https://api.linkedin.com/v2/campaignConversions/(campaign:urn%3Ali%3AsponsoredCampaign%3A337643194,conversion:urn%3Alla%3AllaPartnerConversion%3A70203)

    {
  "campaign": "urn:li:sponsoredCampaign:337643194",
  "conversion": "urn:lla:llaPartnerConversion:70203"
}'

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

    Note

    • PartnerConversionURN is of the format urn:lla:llaPartnerConversion:ID where you need to replace ID with the conversion ID extracted from X-LinkedIn-Id response header when creating the conversion rule in this step.
    • Make sure to include X-Restli-Protocol-Version: 2.0.0 in the request header.

    For more information, see Campaign Conversions.

    Batch Create Campaign Conversions

    Multiple campaign conversions can be created with a Batch Create that accepts IDs parameter each with a campaign URN and conversion URN. The campaign and conversion URNs should be passed in a List format and encoded as shown in the examples below.

    PUT https://api.linkedin.com/rest/campaignConversions?ids=List((campaign:urn%3Ali%3AsponsoredCampaign%3A345396555,conversion:urn%3Alla%3AllaPartnerConversion%3A104004))

    {
 "entities":{
  "(campaign:urn%3Ali%3AsponsoredCampaign%3A345396555,conversion:urn%3Alla%3AllaPartnerConversion%3A104004)":{
   "campaign":"urn:li:sponsoredCampaign:345396555",
   "conversion":"urn:lla:llaPartnerConversion:104004"
  }
 }
}

    PUT https://api.linkedin.com/v2/campaignConversions?ids=List((campaign:urn%3Ali%3AsponsoredCampaign%3A345396555,conversion:urn%3Alla%3AllaPartnerConversion%3A104004))

    {
 "entities":{
  "(campaign:urn%3Ali%3AsponsoredCampaign%3A345396555,conversion:urn%3Alla%3AllaPartnerConversion%3A104004)":{
   "campaign":"urn:li:sponsoredCampaign:345396555",
   "conversion":"urn:lla:llaPartnerConversion:104004"
  }
 }
}

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

    Find Conversions Rules by Ad Account

    All conversions associated with an ad account can be retrieved by using the following API which takes in a sponsoredAccount URN in the account parameter, and returns associatedCampaigns for each conversion.

    GET /conversions?q=account&account={sponsoredAdAccountURN}

    Sample Request

    GET https://api.linkedin.com/rest/conversions?q=account&account=urn%3Ali%3AsponsoredAccount%3A519072844

    GET https://api.linkedin.com/v2/conversions?q=account&account=urn%3Ali%3AsponsoredAccount%3A519072844

    For more information, see Find Conversions by Ad Account.

    Reporting Offline Conversions

    Reports for offline conversions are supported via the existing Ad Analytics Reporting API. Use this API and set pivot = CONVERSION to consume offline conversions reporting. Advertisers can also view Conversion Tracking Reporting and Metrics in LinkedIn Campaign Manager.

    Sample Request

    GET  /adAnalytics?q=analytics&pivot=CONVERSION

    GET https://api.linkedin.com/rest/adAnalytics?q=analytics&dateRange=(start:(day:1,month:1,year:2020),end:(day:30,month:3,year:2020))&timeGranularity=ALL&accounts=List(urn%3Ali%3AsponsoredAccount%3A1234)&pivot=CONVERSION&fields=impressions,clicks,totalEngagements,externalWebsiteConversions,externalWebsitePostClickConversions,externalWebsitePostViewConversions,conversionValueInLocalCurrency,costInLocalCurrency,pivotValue,dateRange

    GET https://api.linkedin.com/v2/adAnalytics?q=analytics&dateRange=(start:(day:1,month:1,year:2020),end:(day:30,month:3,year:2020))&timeGranularity=ALL&accounts=List(urn%3Ali%3AsponsoredAccount%3A1234)&pivot=CONVERSION&fields=impressions,clicks,totalEngagements,externalWebsiteConversions,externalWebsitePostClickConversions,externalWebsitePostViewConversions,conversionValueInLocalCurrency,costInLocalCurrency,pivotValue,dateRange

    Sample Response

    {
   "elements": [
       {
           "externalWebsitePostClickConversions": 2,
           "pivotValue": "urn:lla:llaPartnerConversion:12345",
           "externalWebsitePostViewConversions": 5,
           "costInUsd": "0",
           "externalWebsiteConversions": 7,
           "dateRange": {
               "start": {
                   "month": 1,
                   "day": 3,
                   "year": 2020
               },
               "end": {
                   "month": 1,
                   "day": 3,
                   "year": 2020
               }
           },
           "clicks": 3,
           "conversionValueInLocalCurrency": "0.01",
           "totalEngagements": 0,
           "costInLocalCurrency": "0",
           "impressions": 200
       }
   ]
}

    Batch Get Conversions

    In order to expand further details on the partner conversion segment URN retreived as pivotValue in reporting, conversion segment records can be requested with a Batch Get that accepts multiple ids parameters each with a conversion ID. Conversion ids should be passed in List format and encoded as shown in the examples below. For more information, see Conversion Tracking.

    GET  /conversions?account={sponsoredAccountURN}&ids={conversionId}

    Sample Request

    GET 
https://api.linkedin.com/rest/conversions?account=urn%3Ali%3AsponsoredAccount%3A519072844&ids=List(104012,104004)

    GET 
https://api.linkedin.com/v2/conversions?account=urn%3Ali%3AsponsoredAccount%3A519072844&ids=List(104012,104004)

    Sample Response

    {
  "statuses": {},
  "results": {
    "104004": {
      "postClickAttributionWindowSize": 30,
      "created": 1563230255308,
      "viewThroughAttributionWindowSize": 7,
      "type": "ADD_TO_CART",
      "enabled": true,
      "associatedCampaigns": [
        {
          "campaign": "urn:li:sponsoredCampaign:345396555",
          "associatedAt": 1563657869695,
          "conversion": "urn:lla:llaPartnerConversion:104004"
        }
      ],
      "campaigns": [
        "urn:li:sponsoredCampaign:345396555"
      ],
      "name": "test conversion 1",
      "lastModified": 1563230265652,
      "id": 104004,
      "attributionType": "LAST_TOUCH_BY_CAMPAIGN",
      "value": {
        "amount": "10",
        "currencyCode": "USD"
      },
      "account": "urn:li:sponsoredAccount:519072844"
    }
  },
  "errors": {}
}