Code examples

Adding users to a LinkedIn Ads audience

Before getting started make sure to set your Polytomic API key as an environment variable:

$export POLYTOMIC_API_KEY=YOUR-API-TOKEN

This tutorial will cover 6 steps:

  1. Connecting to Snowflake.
  2. Connecting to LinkedIn Ads.
  3. Creating a model using a Snowflake query.
  4. Inspecting available audiences in LinkedIn Ads.
  5. Syncing data into an existing LinkedIn Ads audience.
  6. Creating a new audience and populating it with data from Snowflake.

1. Create an Snowflake Connection

The Snowflake instance must be network-accessible from Polytomic. For more information, see our Snowflake connection guide.

$     curl --request POST \
>     --url https://app.polytomic.com/api/connections \
>     --header "accept: application/json" \
>     --header "content-type: application/json" \
>     --header "X-Polytomic-Version: 2024-02-08"  \
>     --header "Authorization: Bearer ${POLYTOMIC_API_KEY}" \
>     -d '{
>     "name": "Snowflake Connection",
>     "type": "snowflake",
>     "configuration": {
>        "account": "uc193736182",
>        "username": "user",
>        "password": "secret",
>        "dbname": "database"
>        }
>    }'

2. Create a LinkedIn Ads connection and select accounts

The following request will create a LinkedIn Ads connection. The configuration for each type of connection can be found at the connection configuration page.

$curl --request POST  \
>     --url https://app.polytomic.com/api/connections \
>     --header "accept: application/json"  \
>     --header "content-type: application/json"  \
>     --header "X-Polytomic-Version: 2024-02-08"   \
>     --header "Authorization: Bearer ${POLYTOMIC_API_KEY}"  \
>     -d '{"type":"linkedinads", "name":"LinkedIn Ads","configuration":{}}'
1{
2  "data": {
3    "organization_id": "d63a93bd-dfbd-4431-9006-63eb445d30a4",
4    "id": "34c27eb9-ec01-45d0-93f8-5b1deb1344c1",
5    "name": "Ads Test",
6    "configuration": {},
7    "auth_url": "https://www.linkedin.com/oauth/v2/authorization?access_type=offline..."
8  }
9}

LinkedIn Ads connections use OAuth for authentication, so the user needs to follow the link returned in auth_url in order to complete the connection.

OAuth Redirection

By default, the API expects the auth_url to be opened in a new browser window. If you’d like to modify the redirect behavior, there is an optional redirect_url parameter that can be added to the request body.

LinkedIn Ads connections support multiple accounts. To configure the accounts enabled for the connection, you fetch the available connection parameters, and then update the account.

$curl --request GET  \
>     --url https://app.polytomic.com/api/connections/YOUR-LINKEDIN-CONNECTION-ID/parameter_values \
>     --header "accept: application/json"  \
>     --header "content-type: application/json"  \
>     --header "X-Polytomic-Version: 2024-02-08"   \
>     --header "Authorization: Bearer ${POLYTOMIC_API_KEY}"
1{
2  "data": {
3 ...
4  }
5}

The values returned can be used to update the connection.

$curl --request POST  \
>     --url https://app.polytomic.com/api/connections/YOUR-LINKEDIN-CONNECTION-ID \
>     --header "accept: application/json"  \
>     --header "content-type: application/json"  \
>     --header "X-Polytomic-Version: 2024-02-08"   \
>     --header "Authorization: Bearer ${POLYTOMIC_API_KEY}"  \
>     -d '{"type":"linkedinads", "name":"LinkedIn Ads","configuration":{"accounts":[]}}'
1{
2  "data": {
3    "organization_id": "d63a93bd-dfbd-4431-9006-63eb445d30a4",
4    "id": "34c27eb9-ec01-45d0-93f8-5b1deb1344c1",
5    "name": "Ads Test",
6    "configuration": {},
7    "auth_url": "https://www.linkedin.com/oauth/v2/authorization?access_type=offline..."
8  }
9}

3. Create a Snowflake data model

$curl --request POST  \
>     --url https://app.polytomic.com/api/models \
>     --header "accept: application/json"  \
>     --header "content-type: application/json"  \
>     --header "X-Polytomic-Version: 2024-02-08"  \
>     --header "Authorization: Bearer ${POLYTOMIC_API_KEY}"  \
>     -d '{
>           "name": "Active Users",
>            "configuration": {
>               "query": "SELECT first_name, last_name, email FROM users",
>            },
>            "connection_id": "YOUR-SNOWFLAKE-CONNECTION-ID"
>          }'
Enumerating model sources

For information about how to enumerate sources, see this example.

4. Inspecting available audiences in LinkedIn Ads

You can retrieve the available audiences for a LinkedIn Ads connection by listing the target objects (destinations) for the connection.

$curl --request GET  \
>     --url https://app.polytomic.com/api/connections/YOUR-LINKEDIN-CONNECTION-ID/modelsync/targetobjects \
>     --header "accept: application/json"  \
>     --header "content-type: application/json"  \
>     --header "X-Polytomic-Version: 2024-02-08"   \
>     --header "Authorization: Bearer ${POLYTOMIC_API_KEY}"
1{
2	"target_creation": {
3		"supported": true,
4		"properties": [
5			{
6				"id": "account",
7				"title": "LinkedIn Ads account ID",
8				"enum": true
9			},
10			{
11				"id": "type",
12				"title": "Audience type",
13				"enum": true
14			},
15			{
16				"id": "name",
17				"title": "Audience name",
18				"enum": false
19			}
20		]
21	},
22	"data": [
23		{
24			"id": "512630692::urn:li:organization:28818517~company_audience.29728356",
25			"name": "Company Audience: Polytomic-Created Company List",
26			"modes": [
27				{
28					"id": "create",
29					"requires_identity": false,
30					"supports_target_filters": false,
31					"supports_per_field_mode": false
32				},
33				{
34					"id": "remove",
35					"requires_identity": false,
36					"supports_target_filters": false,
37					"supports_per_field_mode": false
38				}
39			]
40		}
41	]
42}

5. Syncing data into an existing LinkedIn Ads audience.

To sync data into an existing LinkedIn Ads audience, you need to specify the audience ID as the target object in your sync.

This sync maps the email field in the data model to the email field of Salesforce Contacts. It additionally maps the FirstName and LastName fields. You can augment the list of field mappings to sync additional fields.

$curl --request POST  \
>     --url https://app.polytomic.com/api/syncs \
>     --header "accept: application/json"  \
>     --header "content-type: application/json"  \
>     --header "X-Polytomic-Version: 2024-02-08"  \
>     --header "Authorization: Bearer ${POLYTOMIC_API_KEY}"  \
>     -d '{
>          "name": "Snowflake to LinkedIn AdsSync",
>          "mode": "create",
>          "identity": {
>               "source": {
>                    "field": "email",
>                    "model_id": "YOUR-MODEL-ID"
>               },
>               "target": "Email",
>               "function": "equality"
>           },
>          "fields": [
>               {
>                    "source": {
>                         "field": "first_name",
>                         "model_id": "YOUR-MODEL-ID"
>                    },
>                    "target": "FirstName"
>               },
>               {
>                    "source": {
>                         "field": "last_name",
>                         "model_id": "YOUR-MODEL-ID"
>                    },
>                    "target": "LastName"
>               }
>          ],
>          "schedule": {
>               "frequency": "continuous"
>          },
>          "target": {
>               "connection_id": "YOUR-LINKEDIN-CONNECTION-ID",
>               "object": "YOUR-AUDIENCE-ID"
>          }
>     }'

6. Creating a new audience and populating it with data from Snowflake.

To create a sync that writes to a new audience, you need to provide the properties needed to create the audience in the target object of the sync request.

The properties needed to create the audience can be found in target_creation details included in the target objects list response.

1 "target_creation": {
2		"supported": true,
3		"properties": [
4			{
5				"id": "account",
6				"title": "LinkedIn Ads account ID",
7				"enum": true
8			},
9			{
10				"id": "type",
11				"title": "Audience type",
12				"enum": true
13			},
14			{
15				"id": "name",
16				"title": "Audience name",
17				"enum": false
18			}
19		]
20	}

From the response in step 4, we can see that LinkedIn Ads supports creating destinations, and that 3 properties are needed:

  • account
  • type
  • name

The acount and type properties both specify "enum": true, so the available values can be fetched using the property values endpoint.

Fetching the account property values returns the Ad Accounts enabled for the connection.

$curl --request GET  \
>     --url https://app.polytomic.com/api/connections/YOUR-LINKEDIN-CONNECTION-ID/modelsync/targetobjects/properties/account \
>     --header "accept: application/json"  \
>     --header "content-type: application/json"  \
>     --header "X-Polytomic-Version: 2024-02-08"   \
>     --header "Authorization: Bearer ${POLYTOMIC_API_KEY}"
1{
2	"data": {
3		"enum": false,
4		"values": [
5			{
6				"value": "512630692::urn:li:organization:28818517",
7				"label": "Polytomic Inc. (512630692)"
8			}
9		]
10	}
11}

Fetching the type property values returns the audience types supported.

$curl --request GET  \
>     --url https://app.polytomic.com/api/connections/YOUR-LINKEDIN-CONNECTION-ID/modelsync/targetobjects/properties/type \
>     --header "accept: application/json"  \
>     --header "content-type: application/json"  \
>     --header "X-Polytomic-Version: 2024-02-08"   \
>     --header "Authorization: Bearer ${POLYTOMIC_API_KEY}"
1{
2	"data": {
3		"enum": false,
4		"values": [
5			{
6				"value": "company_audience",
7				"label": "Company Audience"
8			},
9			{
10				"value": "user_audience",
11				"label": "User Audience"
12			}
13		]
14	}
15}

Rather than specifying a target object in the sync request, these properties are passed as a create object. For example,

1"target": {
2    "connection_id": "248df4b7-aa70-47b8-a036-33ac447e668d",
3    "create": {
4        "name": "New audience",
5        "type": "user_audience",
6        "account": "512630692::urn:li:organization:28818517"
7    }
8}
$curl --request POST  \
>     --url https://app.polytomic.com/api/syncs \
>     --header "accept: application/json"  \
>     --header "content-type: application/json"  \
>     --header "X-Polytomic-Version: 2024-02-08"  \
>     --header "Authorization: Bearer ${POLYTOMIC_API_KEY}"  \
>     -d '{
>          "name": "Snowflake to LinkedIn AdsSync",
>          "mode": "create",
>          "identity": {
>               "source": {
>                    "field": "email",
>                    "model_id": "YOUR-MODEL-ID"
>               },
>               "target": "Email",
>               "function": "equality"
>           },
>          "fields": [
>               {
>                    "source": {
>                         "field": "first_name",
>                         "model_id": "YOUR-MODEL-ID"
>                    },
>                    "target": "FirstName"
>               },
>               {
>                    "source": {
>                         "field": "last_name",
>                         "model_id": "YOUR-MODEL-ID"
>                    },
>                    "target": "LastName"
>               }
>          ],
>          "schedule": {
>               "frequency": "continuous"
>          },
>          "target": {
>              "connection_id": "YOUR-LINKEDIN-CONNECTION-ID",
>              "create": {
>                  "name": "New audience",
>                  "type": "user_audience",
>                  "account": "512630692::urn:li:organization:28818517"
>              }
>          }
>     }'