openapi: 3.1.0
info:
title: LinkedIn Compliance Events Access Control Conversion Events Streaming Workflow API
description: LinkedIn provides Compliance API Guides for monitoring, archiving, and management of communications for enterprises in regulated industries. The Compliance Events API allows applications to archive all LinkedIn activities from the past 30 days of a regulated, authenticated member.
version: 1.0.0
contact:
name: LinkedIn API Support
url: https://docs.microsoft.com/en-us/linkedin/compliance/
servers:
- url: https://api.linkedin.com
description: LinkedIn Production API Server
security:
- OAuth2Auth:
- r_compliance
tags:
- name: Conversion Events Streaming Workflow
description: "1. Obtain user authorization with consent to create and manage conversions using `rw_conversions`, `r_ads` permissions in the scope.\n2. Retrieve authenticated user's sponsored Ad Accounts where user has a non-viewer user role.\n3. Ask the user to select one of their Ad Account where conversion events would be streamed.\n4. Fetch existing Conversion Rules for CAPI in the selected Ad Account\n5. Allow the user to choose if they want to create a new Conversion Rule or update an existing one\n6. Create a new Conversion Rule (skip this step if the user chose to update an existing Conversion Rule)\n7. Fetch active campaign URNs to associate with conversion rule\n8. Associate campaigns to conversion rule for campaign attribution and optimization\n9. Stream conversion event to the conversion rule\n \n10. Stream multiple conversion events to the conversion rule"
paths:
/adAccountUsers:
get:
tags:
- Conversion Events Streaming Workflow
summary: LinkedIn 2. Retrieve Authenticated User's Sponsored Ad Accounts
parameters:
- name: LinkedIn-Version
in: header
schema:
type: string
example: '{{insert_version}}'
- name: X-Restli-Protocol-Version
in: header
schema:
type: string
example: 2.0.0
- name: q
in: query
schema:
type: string
example: authenticatedUser
- name: fields
in: query
schema:
type: string
example: role,account,user
responses:
'200':
description: OK
headers:
Content-Type:
schema:
type: string
example: application/json
X-RestLi-Protocol-Version:
schema:
type: string
example: 1.0.0
Date:
schema:
type: string
example: Wed, 14 Jun 2023 18:36:33 GMT
X-Li-Fabric:
schema:
type: string
example: prod-lor1
Transfer-Encoding:
schema:
type: string
example: chunked
Connection:
schema:
type: string
example: keep-alive
X-Li-Source-Fabric:
schema:
type: string
example: prod-lva1
X-Li-Pop:
schema:
type: string
example: prod-lva1-x
X-LI-Proto:
schema:
type: string
example: http/1.1
X-LI-UUID:
schema:
type: string
example: AAX+GzsjqgSHmQZ8fFBRbA==
Set-Cookie:
schema:
type: string
example: lidc="b=OB52:s=O:r=O:a=O:p=O:g=3380:u=1682:x=1:i=1686767793:t=1686813748:v=2:sig=AQFd2BBoXo4jGhMI0VSlCcsx5Q-0dR64"
X-LI-Route-Key:
schema:
type: string
example: '"b=OB52:s=O:r=O:a=O:p=O:g=3380:u=1682:x=1:i=1686767793:t=1686813748:v=2:sig=AQFd2BBoXo4jGhMI0VSlCcsx5Q-0dR64"'
content:
application/json:
schema:
$ref: '#/components/schemas/RetrieveAuthenticatedUsersSponsoredResponse200'
examples:
default:
$ref: '#/components/examples/RetrieveAuthenticatedUsersSponsoredResponse200Example'
operationId: getRetrieveAuthenticatedUsersSponsored
x-microcks-operation:
dispatcher: FALLBACK
dispatcherRules: '{}'
delay: 0
/conversions:
get:
tags:
- Conversion Events Streaming Workflow
summary: LinkedIn 4. Fetch Existing Conversion Rules for CAPI in the Selected Ad Account
description: Fetch existing conversion rules in the selected ad account with this endpoint and parse the response to filter elements with `conversionMethod` to `CONVERSIONS_API` for streaming conversions through API.
parameters:
- name: LinkedIn-Version
in: header
schema:
type: string
example: '{{insert_version}}'
- name: X-Restli-Protocol-Version
in: header
schema:
type: string
example: 2.0.0
- name: q
in: query
schema:
type: string
example: account
- name: account
in: query
schema:
type: string
example: urn%3Ali%3AsponsoredAccount%3A{{sponsoredaccount_id}}
- name: fields
in: query
schema:
type: string
example: conversionMethod,enabled,type,name,id,campaigns,attributionType
responses:
'200':
description: OK
headers:
Content-Type:
schema:
type: string
example: application/json
X-RestLi-Protocol-Version:
schema:
type: string
example: 2.0.0
Date:
schema:
type: string
example: Thu, 15 Jun 2023 08:51:41 GMT
X-Li-Fabric:
schema:
type: string
example: prod-lor1
Transfer-Encoding:
schema:
type: string
example: chunked
Connection:
schema:
type: string
example: keep-alive
X-Li-Source-Fabric:
schema:
type: string
example: prod-lva1
X-Li-Pop:
schema:
type: string
example: prod-lva1-x
X-LI-Proto:
schema:
type: string
example: http/1.1
X-LI-UUID:
schema:
type: string
example: AAX+Jy1X+zsm945WHNt5HQ==
Set-Cookie:
schema:
type: string
example: lidc="b=OB52:s=O:r=O:a=O:p=O:g=3380:u=1684:x=1:i=1686819101:t=1686883294:v=2:sig=AQG9PJifKDndXPzy7_WniIlif5-4vsdz"
X-LI-Route-Key:
schema:
type: string
example: '"b=OB52:s=O:r=O:a=O:p=O:g=3380:u=1684:x=1:i=1686819101:t=1686883294:v=2:sig=AQG9PJifKDndXPzy7_WniIlif5-4vsdz"'
content:
application/json:
schema:
$ref: '#/components/schemas/FetchExistingConversionRulesResponse200'
examples:
default:
$ref: '#/components/examples/FetchExistingConversionRulesResponse200Example'
operationId: getFetchExistingConversionRules
x-microcks-operation:
dispatcher: FALLBACK
dispatcherRules: '{}'
delay: 0
post:
tags:
- Conversion Events Streaming Workflow
summary: LinkedIn 6. Create a New Conversion Rule
description: Create one or more conversion rules with this endpoint and set `conversionMethod` to `CONVERSIONS_API` for streaming conversions through API.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateANewConversionRequest'
parameters:
- name: LinkedIn-Version
in: header
schema:
type: string
example: '{{insert_version}}'
- name: X-Restli-Protocol-Version
in: header
schema:
type: string
example: 2.0.0
responses:
'201':
description: Created
headers:
Content-Type:
schema:
type: string
example: application/json
Location:
schema:
type: string
example: /conversions/14488340
x-restli-id:
schema:
type: integer
example: '14488340'
X-RestLi-Protocol-Version:
schema:
type: string
example: 2.0.0
Date:
schema:
type: string
example: Tue, 24 Oct 2023 02:47:51 GMT
X-Li-Fabric:
schema:
type: string
example: prod-lor1
Report-To:
schema:
type: string
example: '{"group":"network-errors","max_age":2592000,"endpoints":[{"url":"https://www.linkedin.com/li/rep"}],"include_subdomains":true}'
NEL:
schema:
type: string
example: '{"report_to":"network-errors","max_age":1296000,"success_fraction":0.00066,"failure_fraction":1,"include_subdomains":true}'
Transfer-Encoding:
schema:
type: string
example: chunked
Connection:
schema:
type: string
example: keep-alive
X-Li-Source-Fabric:
schema:
type: string
example: prod-lva1
X-Li-Pop:
schema:
type: string
example: prod-lva1-x
X-LI-Proto:
schema:
type: string
example: http/1.1
X-LI-UUID:
schema:
type: string
example: AAYIbV1fUy9lNvosbDYsmQ==
Set-Cookie:
schema:
type: string
example: lidc="b=OB52:s=O:r=O:a=O:p=O:g=3500:u=1754:x=1:i=1698115671:t=1698121131:v=2:sig=AQH9Ek4NjI_HRcW2-y6FXmJ_MnU6czll"
X-LI-Route-Key:
schema:
type: string
example: '"b=OB52:s=O:r=O:a=O:p=O:g=3500:u=1754:x=1:i=1698115671:t=1698121131:v=2:sig=AQH9Ek4NjI_HRcW2-y6FXmJ_MnU6czll"'
content:
application/json:
schema:
$ref: '#/components/schemas/CreateANewConversionResponse201'
examples:
default:
$ref: '#/components/examples/CreateANewConversionResponse201Example'
operationId: postCreateANewConversion
x-microcks-operation:
dispatcher: FALLBACK
dispatcherRules: '{}'
delay: 0
/adAccounts/{sponsoredaccount_id}/adCampaigns:
get:
tags:
- Conversion Events Streaming Workflow
summary: LinkedIn 7. Fetch Active Campaigns
description: Fetch existing conversion rules in the selected ad account with this endpoint and parse the response to filter elements with `conversionMethod` to `CONVERSIONS_API` for streaming conversions through API.
parameters:
- name: LinkedIn-Version
in: header
schema:
type: string
example: '{{insert_version}}'
- name: X-Restli-Protocol-Version
in: header
schema:
type: string
example: 2.0.0
- name: q
in: query
schema:
type: string
example: search
- name: search
in: query
schema:
type: string
example: (status:(values:List(ACTIVE,DRAFT)))
- name: fields
in: query
schema:
type: string
example: id,name
- name: sponsoredaccount_id
in: path
schema:
type: string
required: true
example: '123456'
responses:
'200':
description: OK
headers:
Content-Type:
schema:
type: string
example: application/json
X-RestLi-Protocol-Version:
schema:
type: string
example: 2.0.0
Date:
schema:
type: string
example: Tue, 17 Oct 2023 01:50:46 GMT
Transfer-Encoding:
schema:
type: string
example: chunked
Connection:
schema:
type: string
example: keep-alive
X-Li-Fabric:
schema:
type: string
example: prod-lva1
Report-To:
schema:
type: string
example: '{"group":"network-errors","max_age":2592000,"endpoints":[{"url":"https://www.linkedin.com/li/rep"}],"include_subdomains":true}'
NEL:
schema:
type: string
example: '{"report_to":"network-errors","max_age":1296000,"success_fraction":0.00066,"failure_fraction":1,"include_subdomains":true}'
X-Li-Pop:
schema:
type: string
example: prod-lva1-x
X-LI-Proto:
schema:
type: string
example: http/1.1
X-LI-UUID:
schema:
type: string
example: AAYH38BSGn+zS5gvrvSuEg==
Set-Cookie:
schema:
type: string
example: lidc="b=VB52:s=V:r=V:a=V:p=V:g=3877:u=1748:x=1:i=1697507446:t=1697509914:v=2:sig=AQG1F5DDw_-Cvyww_R4RWc8KPvLXx2sz"
X-LI-Route-Key:
schema:
type: string
example: '"b=VB52:s=V:r=V:a=V:p=V:g=3877:u=1748:x=1:i=1697507446:t=1697509914:v=2:sig=AQG1F5DDw_-Cvyww_R4RWc8KPvLXx2sz"'
content:
application/json:
schema:
$ref: '#/components/schemas/FetchActiveCampaignsResponse200'
examples:
default:
$ref: '#/components/examples/FetchActiveCampaignsResponse200Example'
operationId: getFetchActiveCampaigns
x-microcks-operation:
dispatcher: FALLBACK
dispatcherRules: '{}'
delay: 0
? /campaignConversions/(campaign:urn:li:sponsoredCampaign:{campaign_id},conversion:urn:lla:llaPartnerConversion:{conversion_id})
: put:
tags:
- Conversion Events Streaming Workflow
summary: LinkedIn 8. Associate Campaigns to Conversion Rule
description: Create one or more conversion rules with this endpoint and set `conversionMethod` to `CONVERSIONS_API` for streaming conversions through API.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AssociateCampaignsToConversionRequest'
parameters:
- name: LinkedIn-Version
in: header
schema:
type: string
example: '{{insert_version}}'
- name: X-Restli-Protocol-Version
in: header
schema:
type: string
example: 2.0.0
- name: campaign_id
in: path
schema:
type: string
required: true
example: '123456'
- name: conversion_id
in: path
schema:
type: string
required: true
example: '123456'
responses:
'204':
description: No Content
headers:
X-RestLi-Protocol-Version:
schema:
type: string
example: 2.0.0
Date:
schema:
type: string
example: Tue, 17 Oct 2023 02:01:02 GMT
Connection:
schema:
type: string
example: keep-alive
X-Li-Fabric:
schema:
type: string
example: prod-lva1
Report-To:
schema:
type: string
example: '{"group":"network-errors","max_age":2592000,"endpoints":[{"url":"https://www.linkedin.com/li/rep"}],"include_subdomains":true}'
NEL:
schema:
type: string
example: '{"report_to":"network-errors","max_age":1296000,"success_fraction":0.00066,"failure_fraction":1,"include_subdomains":true}'
X-Li-Pop:
schema:
type: string
example: prod-lva1-x
X-LI-Proto:
schema:
type: string
example: http/1.1
X-LI-UUID:
schema:
type: string
example: AAYH3+UKX//t+2JU8QjBgg==
Set-Cookie:
schema:
type: string
example: lidc="b=VB52:s=V:r=V:a=V:p=V:g=3877:u=1748:x=1:i=1697508062:t=1697509914:v=2:sig=AQEuCMMAxhHSzyZlkupPJUKXiy1LEjWz"
X-LI-Route-Key:
schema:
type: string
example: '"b=VB52:s=V:r=V:a=V:p=V:g=3877:u=1748:x=1:i=1697508062:t=1697509914:v=2:sig=AQEuCMMAxhHSzyZlkupPJUKXiy1LEjWz"'
content:
text/plain:
examples:
default:
$ref: '#/components/examples/AssociateCampaignsToConversionResponse204Example'
schema:
$ref: '#/components/schemas/AssociateCampaignsToConversionResponse204'
operationId: putAssociateCampaignsToConversion
x-microcks-operation:
dispatcher: FALLBACK
dispatcherRules: '{}'
delay: 0
/conversionEvents:
post:
tags:
- Conversion Events Streaming Workflow
summary: LinkedIn 10. Stream Multiple Conversion Events to the Conversion Rule
description: Create one or more conversion rules with this endpoint and set `conversionMethod` to `CONVERSIONS_API` for streaming conversions through API.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/StreamMultipleConversionEventsRequest'
parameters:
- name: LinkedIn-Version
in: header
schema:
type: string
example: '{{insert_version}}'
- name: X-Restli-Protocol-Version
in: header
schema:
type: string
example: 2.0.0
- name: X-RestLi-Method
in: header
schema:
type: string
example: BATCH_CREATE
responses:
'200':
description: OK
headers:
Content-Type:
schema:
type: string
example: application/json
x-restli-protocol-version:
schema:
type: string
example: 2.0.0
Date:
schema:
type: string
example: Tue, 24 Oct 2023 02:51:55 GMT
X-Li-Fabric:
schema:
type: string
example: prod-lor1
Report-To:
schema:
type: string
example: '{"group":"network-errors","max_age":2592000,"endpoints":[{"url":"https://www.linkedin.com/li/rep"}],"include_subdomains":true}'
NEL:
schema:
type: string
example: '{"report_to":"network-errors","max_age":1296000,"success_fraction":0.00066,"failure_fraction":1,"include_subdomains":true}'
Transfer-Encoding:
schema:
type: string
example: chunked
Connection:
schema:
type: string
example: keep-alive
X-Li-Source-Fabric:
schema:
type: string
example: prod-lva1
X-Li-Pop:
schema:
type: string
example: prod-lva1-x
X-LI-Proto:
schema:
type: string
example: http/1.1
X-LI-UUID:
schema:
type: string
example: AAYIbWvmBmkoHhcx9SVCSA==
Set-Cookie:
schema:
type: string
example: lidc="b=OB52:s=O:r=O:a=O:p=O:g=3500:u=1754:x=1:i=1698115914:t=1698121131:v=2:sig=AQHzEIPucPFVAH_DkGU-T6ZaVmFk6Mxe"
X-LI-Route-Key:
schema:
type: string
example: '"b=OB52:s=O:r=O:a=O:p=O:g=3500:u=1754:x=1:i=1698115914:t=1698121131:v=2:sig=AQHzEIPucPFVAH_DkGU-T6ZaVmFk6Mxe"'
content:
application/json:
schema:
$ref: '#/components/schemas/StreamMultipleConversionEventsResponse200'
examples:
default:
$ref: '#/components/examples/StreamMultipleConversionEventsResponse200Example'
operationId: postStreamMultipleConversionEvents
x-microcks-operation:
dispatcher: FALLBACK
dispatcherRules: '{}'
delay: 0
components:
schemas:
AssociateCampaignsToConversionResponse204:
type: string
CreateANewConversionRequest:
type: object
example:
name: Conversion API Segment 5
account: urn:li:sponsoredAccount:{{sponsoredaccount_id}}
conversionMethod: CONVERSIONS_API
postClickAttributionWindowSize: 90
viewThroughAttributionWindowSize: 30
attributionType: LAST_TOUCH_BY_CAMPAIGN
type: LEAD
RetrieveAuthenticatedUsersSponsoredResponse200:
type: object
properties:
paging:
type: object
properties:
start:
type: integer
count:
type: integer
links:
type: array
items: {}
total:
type: integer
elements:
type: array
items:
type: object
properties:
user:
type: string
account:
type: string
role:
type: string
StreamMultipleConversionEventsResponse200:
type: object
properties:
elements:
type: array
items:
type: object
properties:
status:
type: integer
CreateANewConversionResponse201:
type: object
properties:
postClickAttributionWindowSize:
type: integer
example: 42
conversionMethod:
type: string
example: example_value
viewThroughAttributionWindowSize:
type: integer
example: 42
created:
type: integer
example: 42
type:
type: string
example: example_value
enabled:
type: boolean
example: true
associatedCampaigns:
type: array
items: {}
campaigns:
type: array
items: {}
name:
type: string
example: Example Name
id:
type: integer
example: 42
lastModified:
type: integer
example: 42
attributionType:
type: string
example: example_value
urlRules:
type: array
items: {}
account:
type: string
example: example_value
AssociateCampaignsToConversionRequest:
type: object
example:
campaign: urn:li:sponsoredCampaign:{{campaign_id}}
conversion: urn:lla:llaPartnerConversion:{{conversion_id}}
StreamMultipleConversionEventsRequest:
type: object
example:
elements:
- conversion: urn:lla:llaPartnerConversion:{{conversion_id}}
conversionHappenedAt: 1695739275000
conversionValue:
currencyCode: USD
amount: '1500.0'
user:
userIds:
- idType: SHA256_EMAIL
idValue: bad8677b6c86f5d308ee82786c183482a5995f066694246c58c4df37b0cc41f1
- idType: LINKEDIN_FIRST_PARTY_ADS_TRACKING_UUID
idValue: df5gf5-gh6t7-ph4j7h-fgf6n1
userInfo:
firstName: mike
lastName: smith
title: software engineer
companyName: microsoft
countryCode: US
eventId: abc12345
- conversion: urn:lla:llaPartnerConversion:{{conversion_id}}
conversionHappenedAt: 1695950057000
conversionValue:
currencyCode: USD
amount: '2000.0'
user:
userIds:
- idType: SHA256_EMAIL
idValue: dsfgrtg56u767ujy982fgnbmcsdocl46c58c56b650cik230bb9
- idType: LINKEDIN_FIRST_PARTY_ADS_TRACKING_UUID
idValue: ufh8h5-gh6t7-ph4j7h-mkl86n1
userInfo:
firstName: jason
lastName: bourne
title: tech lead
companyName: linkedin
countryCode: US
eventId: xyz345
FetchActiveCampaignsResponse200:
type: object
properties:
paging:
type: object
properties:
start:
type: integer
count:
type: integer
links:
type: array
items:
type: object
properties:
type:
type: string
rel:
type: string
href:
type: string
total:
type: integer
elements:
type: array
items:
type: object
properties:
name:
type: string
id:
type: integer
FetchExistingConversionRulesResponse200:
type: object
properties:
paging:
type: object
properties:
start:
type: integer
count:
type: integer
links:
type: array
items: {}
total:
type: integer
elements:
type: array
items:
type: object
properties:
name:
type: string
conversionMethod:
type: string
id:
type: integer
type:
type: string
campaigns:
type: array
items: {}
enabled:
type: boolean
examples:
FetchActiveCampaignsResponse200Example:
summary: Example 200 response for FetchActiveCampaigns
value:
paging:
start: 0
count: 10
links:
- type: application/json
rel: next
href: /rest/adAccounts/5012345/adCampaigns?q=search&search=(status:(values:List(ACTIVE,DRAFT)))&start=10&count=10&fields=name,id
total: 4
elements:
- name: Website visits - May 4, 2021
id: 12345
- name: Brand awareness - Jul 14, 2022
id: 14567
- name: Lead generation - Dec 5, 2022
id: 789090
- name: Website conversions - Dec 6, 2022
id: 899887
AssociateCampaignsToConversionResponse204Example:
summary: Example 204 response for AssociateCampaignsToConversion
value: null
CreateANewConversionResponse201Example:
summary: Example 201 response for CreateANewConversion
value:
postClickAttributionWindowSize: 90
conversionMethod: CONVERSIONS_API
viewThroughAttributionWindowSize: 30
created: 1698115671440
type: LEAD
enabled: true
associatedCampaigns: []
campaigns: []
name: Conversion API Segment 5
id: 14488340
lastModified: 1698115671440
attributionType: LAST_TOUCH_BY_CAMPAIGN
urlRules: []
account: urn:li:sponsoredAccount:5012345
StreamMultipleConversionEventsResponse200Example:
summary: Example 200 response for StreamMultipleConversionEvents
value:
elements:
- status: 201
- status: 201
FetchExistingConversionRulesResponse200Example:
summary: Example 200 response for FetchExistingConversionRules
value:
paging:
start: 0
count: 10
links: []
total: -1
elements:
- name: Conversion API Segment 1
conversionMethod: CONVERSIONS_API
id: 1403456
type: LEAD
campaigns: []
enabled: true
- name: Conversion API Segment 4
conversionMethod: CONVERSIONS_API
id: 1103890
type: LEAD
campaigns:
- urn:li:sponsoredCampaign:435
- urn:li:sponsoredCampaign:675
- urn:li:sponsoredCampaign:342
enabled: true
- name: Online Test
conversionMethod: INSIGHT_TAG_URL_MATCH_RULES
id: 10991460
type: BOOK_APPOINTMENT
campaigns:
- urn:li:sponsoredCampaign:876786
- urn:li:sponsoredCampaign:536478
enabled: true
- name: Demo requests
conversionMethod: INSIGHT_TAG_JAVASCRIPT_EVENT
id: 4886884
type: REQUEST_QUOTE
campaigns: []
enabled: false
RetrieveAuthenticatedUsersSponsoredResponse200Example:
summary: Example 200 response for RetrieveAuthenticatedUsersSponsored
value:
paging:
start: 0
count: 2147483647
links: []
total: 3
elements:
- user: urn:li:person:abcd
account: urn:li:sponsoredAccount:5000123
role: VIEWER
- user: urn:li:person:abcd
account: urn:li:sponsoredAccount:5000234
role: ACCOUNT_BILLING_ADMIN
- user: urn:li:person:abcd
account: urn:li:sponsoredAccount:5000345
role: ACCOUNT_BILLING_ADMIN
securitySchemes:
OAuth2Auth:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://www.linkedin.com/oauth/v2/authorization
tokenUrl: https://www.linkedin.com/oauth/v2/accessToken
scopes:
r_compliance: Read compliance data