Service endpoint

https://api.targetsmart.com/service/onboarding

Overview

This service can be used to create custom audience segments for digital ad targeting. The request can target one of your Facebook Ad Accounts.

The ad audience records are defined by specifying a list of Voterbase record identifiers (voterbase_id) in your request. For example you might acquire a set of voterbase_id identifiers using the ListBuilder API, the SmartMatch API, from analytics install file records, or other TargetSmart data deliverables.

Upon Facebook onboarding workflow completion, the custom audience is ready to be used in your Facebook platform ads.

The Onboarding API is limited to one request per minute.

Please also review the TargetSmart Audiences documentation.

Request parameters

Key Required Optional Default Permitted Values
platform facebook
audience string with max 50 characters


Additional platforms may be supported in the future.

Additional parameter details

audience

This parameter is your desired audience name. Accepts a string of up to 50 characters, including spaces. This is the “Audience Name” that will be used to create a custom audience.

JSON response

Responses are JSON objects with the following keys:

  • url: URL to upload data

Use the url returned from the service to upload your onboarding request.

Your request needs to be a JSON document with the following fields:

  • status_email: An email address to receive status updates on your request
  • ids: A sorted comma separated list (without spaces) of valid Voterbase IDs
  • facebook_adid: Your Ad Account ID (required if platform=facebook)

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 json
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"}

# 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")
    # PUT the onboarding request body to the returned pre-signed url to initiate asynchronous audience creation.
    # This request interacts with AWS S3. Do not include the TargetSmart API key in the request header.
    execution_payload = {
        "facebook_adid": "2075824559387154",
        "status_email": "bob@example.com",
        "ids": "AR-1882830,AZ-6285654,MD-000002862484",
    }

    response_2 = requests.put(
        response_1_info["url"],
        data=json.dumps(execution_payload),
        headers={"Content-Type": ""},
    )
    response_2.raise_for_status()
    print("🚀 Execution started")
#! /usr/bin/env node

const fetch = require("node-fetch");

const targetSmartApiKey = process.env.TS_API_KEY;

const executionPayload = {
  facebook_adid: "2075824559387154",
  status_email: "bob@example.com",
  ids: "AR-1882830,AZ-6285654,MD-000002862484",
};

// 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",
    }).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");
        /* PUT the onboarding request body to the returned pre-signed url to
         * initiate asynchronous audience creation. This request interacts with AWS
         * S3. Do not include the TargetSmart API key in the request header. */
        fetch(respdata.url, {
          method: "PUT",
          body: JSON.stringify(executionPayload),
          headers: { "Content-Type": "" }, // note Content-Type must be set and <empty>
        }).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"); then
    # PUT the onboarding request body to the returned pre-signed url to initiate asynchronous audience creation.
    # 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 -H 'Content-Type:' -XPUT -d '{"facebook_adid": "2075824559387154", "status_email": "bob@example.com", "ids": "AR-1882830,AZ-6285654,MD-000002862484"}' $aws_url); then
        echo "🚀 Execution started"
    fi
fi