Yelp Conversions API Export Integration

The Yelp Conversions API (CAPI) connector enables server-side tracking and measurement of offline/server-side conversion events for Yelp Ads campaigns. By integrating directly with Yelp's Conversions API, this connector helps multi-location advertisers measure campaign performance, improve ad attribution, and optimize ROAS (Return on Ad Spend) measurement.

Key capabilities:

• Offline Conversions: Track purchases, leads, and other conversion events that happen outside of the Yelp platform
• PII Hashing: Automatic SHA-256 hashing of user identifiers (email, phone, name, etc.) for privacy-compliant matching
• Data Normalization: Automated field normalization to Yelp CAPI specifications

This server-side integration enables advertisers to close the attribution loop between Yelp Ads clicks and downstream conversions, providing more complete ROAS measurement.

• Basic knowledge of Treasure AI, including the TD Toolbelt.
• A Yelp Business account with Yelp Ads enabled.
• A Yelp API key (Bearer token) obtained from Yelp developer app credentials.

• Daily Rate Limit: 50,000 events/day cap may limit large-scale exports. Batching/scheduling across multiple days may be needed.
• Rate Limit: 100 requests/second. The connector implements throttling and exponential backoff.
• Limited Event Types: Custom events must be prefixed with custom_ and contain only alphanumeric characters, underscores, and hyphens.
• Single Value Arrays: For array fields in user data (email, phone, country, state, zip_code, city, external_id), the connector sends these as arrays with a single value.
• No content_category/content_ids support: custom_data.content_category, custom_data.content_ids, custom_data.contents, and custom_data.event_labels are not supported in the initial release.

If your security policy requires IP whitelisting, you must add Treasure Data's IP addresses to your allowlist to ensure a successful connection.

Please find the complete list of static IP addresses, organized by region, at the following document

In Data Workbench, you must create and configure the data connection before running your query. As part of the data connection, you provide authentication to access the integration.

1. Open Data Workbench.
2. Navigate to Integrations Hub > Catalog.
3. Search for and select Yelp Conversions API.
4. Select Create Authentication.
5. Type the credentials to authenticate:

6. Select Continue.
7. Type a name for your connection.
8. Select Done.

1. Navigate to Data Workbench > Queries.
2. Select New Query.
3. Run the query to validate the result set.

SELECT
  transaction_id AS event_id,
  time AS event_time,
  'purchase' AS event_name,
  'website' AS action_source,
  email,
  first_name,
  last_name,
  phone,
  birthday,
  gender,
  country,
  state,
  zip_code,
  city,
  external_id,
  ip_address,
  user_agent,
  lead_id,
  total_amount AS value,
  'USD' AS currency,
  order_id
FROM
  my_database.conversions
WHERE
  TD_TIME_RANGE(time, TD_TIME_ADD(TD_SCHEDULED_TIME(), '-1d'), TD_SCHEDULED_TIME())
  AND email IS NOT NULL

4. You need to define the column mapping in the query. The columns in the query represent data to be sent to Yelp Conversions API.

1. Select Export Results.
2. Select an existing Yelp Conversions API authentication or create a new one as described above.
3. Configure the export parameters:

4. Select Done.

To upload event data to Yelp Conversions API, you need to build a data export query that includes a combination of standard fields that adhere to Yelp CAPI guidelines. Ensure the column names match those listed in the "Field/Column-Level Specifications" section.

The connector automatically normalizes the column names (case-insensitive matching), so you do not need to worry about case sensitivity. For example, for the field "event_name," the column name in your export query can be written as "EVENT_NAME," "event_name," or "Event_Name."

To successfully upload conversion data to Yelp CAPI, you must construct an export query that adheres to specific data specifications. These specifications are divided into two levels:

• Export Query Specifications (Dataset-level data specs): Requirements and rules that apply to your entire query result dataset, such as the presence of required fields and cross-field validation rules.
• Field/Column-Level Specifications: Requirements and rules for individual fields/columns in your dataset, such as data types, formats, and normalization rules.

The following fields are used to identify users for conversion matching. At least one user identifier (email, phone, external_id, or lead_id) is recommended for accurate matching.

1. Phone Number Format: Phone numbers should include country code, area code, and number. The connector strips allowed characters (+, -, parentheses, spaces), validates digits only, and applies the following rules:
   • 10 digits: leading "1" is prepended automatically
   • Starts with "1": must be exactly 11 digits
   • Other country codes: maximum 15 digits
2. Automatic Processing: The connector automatically handles field normalization (lowercase, trim, punctuation removal) and SHA-256 hashing for all PII fields.
3. Error Collection: All validation errors for a record are collected and reported together, making it easier to diagnose data issues.

You can use Scheduled Jobs with Result Export to periodically write the output result to a target destination that you specify.

Treasure Data's scheduler feature supports periodic query execution to achieve high availability.

When two specifications provide conflicting schedule specifications, the specification requesting to execute more often is followed while the other schedule specification is ignored.

For example, if the cron schedule is '0 0 1 * 1', then the 'day of month' specification and 'day of week' are discordant because the former specification requires it to run every first day of each month at midnight (00:00), while the latter specification requires it to run every Monday at midnight (00:00). The latter specification is followed.

1. Navigate to Data Workbench > Queries

2. Create a new query or select an existing query.

3. Next to Schedule, select None.

4. In the drop-down, select one of the following schedule options:

   Drop-down Value	Description
   Custom cron...	Review Custom cron... details.
   @daily (midnight)	Run once a day at midnight (00:00 am) in the specified time zone.
   @hourly (:00)	Run every hour at 00 minutes.
   None	No schedule.

 *    *    *    *    *
 -    -    -    -    -
 |    |    |    |    |
 |    |    |    |    +----- day of week (0 - 6) (Sunday=0)
 |    |    |    +---------- month (1 - 12)
 |    |    +--------------- day of month (1 - 31)
 |    +-------------------- hour (0 - 23)
 +------------------------- min (0 - 59)

The following named entries can be used:

• Day of Week: sun, mon, tue, wed, thu, fri, sat.
• Month: jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, dec.

A single space is required between each field. The values for each field can be composed of:

1. (Optional) You can delay the start time of a query by enabling the Delay execution.

You can also send segment data to the target platform by creating an activation in the Audience Studio.

1. Navigate to Audience Studio.
2. Select a parent segment.
3. Open the target segment, right-mouse click, and then select Create Activation.
4. In the Details panel, enter an Activation name and configure the activation according to the previous section on Configuration Parameters.
5. Customize the activation output in the Output Mapping panel.

• Attribute Columns
  • Select Export All Columns to export all columns without making any changes.
  • Select + Add Columns to add specific columns for the export. The Output Column Name pre-populates with the same Source column name. You can update the Output Column Name. Continue to select + Add Columnsto add new columns for your activation output.
• String Builder
  • + Add string to create strings for export. Select from the following values:
    • String: Choose any value; use text to create a custom value.
    • Timestamp: The date and time of the export.
    • Segment Id: The segment ID number.
    • Segment Name: The segment name.
    • Audience Id: The parent segment number.

6. Set a Schedule.

• Select the values to define your schedule and optionally include email notifications.

7. Select Create.

Within Treasure Workflow, you can specify the use of this integration to export data.

Learn more at Using Workflows to Export Data with the TD Toolbelt.

_export:
  td:
    database: my_database

+yelp_conversions_export:
  td>: export_yelp_conversions.sql
  database: ${td.database}
  result_connection: {your_connection_name}
  result_settings:
    upload_mode: single_event
    skip_invalid_records: false
    test_event: false

You can also use CLI (Toolbelt) for Result Export to Yelp Conversions API.

You need to specify the information for export to Yelp Conversions as --result option of td query command. About td query command, you can refer to this article.

The format of the option is JSON and the general structure is as follows.

{
  "type": "yelp_conversion",
  "api_key": "your-yelp-api-key-here",
  "upload_mode": "single_event",
  "skip_invalid_records": false,
  "test_event": false
}

td query --result '{"type":"yelp_conversion","api_key":"your-api-key","upload_mode":"single_event","skip_invalid_records":false,"test_event":false}' -d my_database "SELECT transaction_id AS event_id, time AS event_time, 'purchase' AS event_name, 'website' AS action_source, email, total_amount AS value, 'USD' AS currency FROM conversions" -T presto

• Yelp Conversions API Documentation
• Yelp Conversions API Hashing Guide
• Yelp Conversions API Normalization Guide