Code examples

Syncing audiences from Snowflake to LinkedIn Ads

Set your Polytomic API key as an environment variable:

$export POLYTOMIC_API_KEY=YOUR-API-TOKEN

This example covers six steps:

  1. Create a Snowflake Connection.
  2. Create a LinkedIn Ads Connection.
  3. Create a model from a Snowflake query.
  4. Inspect the available audiences in LinkedIn Ads.
  5. Sync data into an existing LinkedIn Ads audience.
  6. Create a new audience and populate it from Snowflake.

1. Create a Snowflake connection

The Snowflake instance must be reachable from Polytomic over the network. For details, see the 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 creates a LinkedIn Ads Connection. See the LinkedIn Ads connection configuration for the required fields.

$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 authenticate with OAuth. Open the URL returned in the auth_url field of the response to complete the flow.

OAuth redirection

By default, the API expects auth_url to open in a new browser window. Set the optional redirect_url parameter in the request body to change the redirect target.

A LinkedIn Ads Connection can pull data from multiple ad accounts. To choose which ones, fetch the available connection parameters, then update the account list on the Connection.

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

Use those values 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 model

Create a model backed by a Snowflake query:

$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. Inspect the available audiences

Retrieve the audiences available on a LinkedIn Ads Connection by listing the target objects for that 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. Sync into an existing audience

To write to an existing LinkedIn Ads audience, set the audience ID as the target object on the sync.

The following sync maps email, first_name, and last_name from the Snowflake model to the corresponding LinkedIn Ads fields. Add more entries to the fields array to sync additional columns.

$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. Create a new audience and populate it

To write to a new audience, pass the audience’s creation properties in the target object of the sync request.

The required properties come from the target_creation section of 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	}

The Step 4 response shows that LinkedIn Ads supports creating destinations and requires three properties:

  • account
  • type
  • name

Both account and type are marked "enum": true, so you can fetch their allowed values from the property values endpoint.

Fetching account returns the ad accounts enabled on 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 type returns the supported audience types:

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

Instead of setting a target object, pass these properties as a create object on the target. 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"
>              }
>          }
>     }'