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

  1. Follow Getting started with Facebook
  2. Prepare a CSV file containing Voterbase ID records using the header name voterbase_id
  3. Perform a GET request to register a workflow session, specifying an audience name, Facebook ad account id, and status email.
  4. 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

  1. Contact us to discuss your onboarding infrastructure needs to satisfy prerequisites.
  2. Prepare a CSV file with identifiers conforming to Facebook’s field name and value formatting standards.
  3. 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.
  4. 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

The Onboarding API is limited to one request per minute.

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