Service endpoint¶
https://api.targetsmart.com/service/onboarding
Overview¶
This service can be used to create custom audiences for digital ad targeting.
Facebook custom audiences¶
Using platform=facebook
, a request can initiate a workflow that will result in
a Facebook custom audience ready to be used in ad campaigns.
Upon workflow completion the custom audience is available in your Facebook Ad Account ready to be used in your Facebook platform ads.
Facebook Pattern #1: Creating audiences based on TargetSmart voter file records¶
- Follow Getting started with Facebook
- Prepare a CSV file containing Voterbase ID records using the header name
voterbase_id
- Perform a GET request to register a workflow session, specifying an audience name, Facebook ad account id, and status email.
- Perform a PUT request to stream your CSV data, triggering workflow processing.
Facebook Pattern #2: Creating audiences based on your PII independently of TargetSmart data¶
- Contact us to discuss your onboarding infrastructure needs to satisfy prerequisites.
- Prepare a CSV file with identifiers conforming to Facebook’s field name and value formatting standards.
- Perform a GET request to register a workflow session, specifying an audience name, your owner Facebook ad account id, a secondary Facebook ad account id where ads will be placed, and a status email.
- Perform a PUT request to stream your CSV data, triggering workflow processing.
DSPolitical custom audiences¶
Using platform=dspolitical
, a request may target DSPolitical, and you will receive an
email from them when your audience is ready to be used in ads. Please also
review the TargetSmart
Audiences documentation.
Rate limiting¶
Request parameters¶
Key | Required | Optional | Default | Permitted Values |
---|---|---|---|---|
platform |
✓ | facebook , dspolitical |
||
audience |
✓ | name <= 50 alphanumeric or underscore chars | ||
status_email |
✓ | email address to receive status updates | ||
facebook_adid |
if facebook |
A Facebook ad account ID | ||
owner_adid |
if facebook |
A Facebook ad account ID. Only use with Pattern #2 described above. |
Additional Parameter Details¶
facebook_adid
Advertiser’s Facebook Ad Account ID to share the audience with.
owner_adid
Client’s Facebook Ad Account ID that has been approved for direct upload to Facebook. If not provided, we will upload the audience to a TargetSmart ad account and share it with facebook_adid
. Contact client services to request direct upload. This is only used with Facebook Pattern #2 described above.
JSON response¶
Responses are JSON objects with the optional key:
url
: A presigned S3 URL to upload your onboarding records (see below).
PUT to upload file¶
Upon a successful GET
request, target the provided presigned url
to upload your input file using an HTTP PUT
request.
CSV formatting¶
The uploaded input file must meet these requirements:
- A csv file where the first row contains valid header names
- Each subsequent row is a record that follows the data formatting rules of the platform
- Excel compatible CSV using UTF8 encoding without BOM.
Voterbase Id files¶
When platform=dspolitical
or platform=facebook
without owner_id
(Facebook Pattern #1 described above), the CSV file should have one header with name voterbase_id
. Each row should be a valid TargetSmart Voterbase Id. You might acquire a “voterbase_id” list using the ListBuilder API, the SmartMatch API, from analytics install
file records, or other TargetSmart data deliverables.
Contact information PII files¶
When platform = facebook
and specifying owner_id
(Facebook Pattern #2
described above), multiple CSV header fields can be used with exact identifiers supported by Facebook and field values meeting the doc here.
Code Examples¶
🔐 Remember to secure your API key
Never expose your API key in plain text or source control accessible by a third party.
#! /usr/bin/env python3
import os
import requests
api_key = os.environ["TS_API_KEY"]
endpoint = "https://api.targetsmart.com/service/onboarding"
headers = {"x-api-key": api_key}
# request URL to upload data
params = {
"platform": "facebook",
"audience": "my_audience_name",
"status_email": "me@example.com",
"facebook_adid": CLIENT_AD_ACCOUNT_ID,
# Only include `owner_adid` if uploading your PII directly to your Facebook
# ad account.
# "owner_adid": PARTNER_AD_ACCOUNT_ID,
}
# Register with service/onboarding to produce a target url for upload.
response_1 = requests.get(endpoint, params=params, headers=headers)
response_1.raise_for_status()
response_1_info = response_1.json()
if not response_1_info["error"]:
print("Registration request successful")
# Stream your prepared UTF8 CSV input file to the provided pre-signed URL.
# Content-Type should be <empty>.
# This request interacts with AWS S3. Do not include the TargetSmart API key in the request header.
with open("onboarding_input_file.csv", "rb") as reader:
response_2 = requests.put(
response_1_info["url"], data=reader, headers={"Content-Type": ""}
)
response_2.raise_for_status()
print("Execution started")
#! /usr/bin/env node
const fetch = require("node-fetch");
const fs = require("fs");
const filepath = "onboarding_input_file.csv";
const targetSmartApiKey = process.env.TS_API_KEY;
// Register with service/onboarding to produce a target url for upload.
fetch(
"https://api.targetsmart.com/service/onboarding?" +
new URLSearchParams({
platform: "facebook",
audience: "my_audience_name",
status_email: "me@example.com",
facebook_adid: CLIENT_AD_ACCOUNT_ID,
// Only include `owner_adid` if uploading your PII directly to your Facebook
// ad account.
// "owner_adid": PARTNER_AD_ACCOUNT_ID,
}).toString(),
{
method: "GET",
headers: {
"x-api-key": targetSmartApiKey,
},
}
).then((response) => {
if (response.status === 200) {
response.json().then((respdata) => {
if (!respdata.error) {
console.log("Registration request successful");
/* Stream your prepared UTF8 CSV input file to the provided pre-signed
* URL. Content-Type should be <empty>. This request interacts with AWS
* S3. Do not include the TargetSmart API key in the request header. */
const stats = fs.statSync(filepath);
const reader = fs.createReadStream(filepath, { encoding: null });
reader.on("error", console.log);
fetch(respdata.url, {
method: "PUT",
headers: { "Content-Length": stats.size, "Content-Type": "" },
body: fs.createReadStream(filepath),
}).then((response2) => {
if (response2.status === 200) {
console.log("Execution started");
}
});
}
});
}
});
#! /usr/bin/env bash
# Register with service/onboarding to produce a target url for upload.
if result_1=$(curl -XGET \
-H "x-api-key: $TS_API_KEY" \ "https://api.targetsmart.com/service/onboarding?platform=facebook&audience=my_audience_name&status_email=me%40example.com%0A&facebook_adid=CLIENT_AD_ACCOUNT_ID"); then
# Stream your prepared UTF8 CSV input file to the provided pre-signed URL.
# Content-Type should be <empty>.
# This request interacts with AWS S3. Do not include the TargetSmart API key in the request header.
echo "Registration request successful";
aws_url=$(echo $result_1| jq -r '.url');
if result_2=$(curl -L -H 'Content-Type:' --upload-file onboarding_input_file.csv $aws_url); then
echo "Execution started"
fi
fi