Yelp Ads

Datafly Signal sends conversions to Yelp Ads server-to-server through the Yelp Conversions API (CAPI), for online and offline attribution of Yelp ads.

Prerequisites

Request access

Ask your Yelp sales or success contact for the Conversions API. Yelp currently offers attribution reporting to businesses with 10 or more locations.

Create a Yelp developer app

At yelp.com/developers create an app, copy its Client ID to your Yelp contact and keep the API Key. Yelp activates the key for CAPI.

Configure in Signal

Configuration Fields

Field	Required	Description
`api_key`	Yes	The API key from your Yelp developer app once the Conversions API has been activated for it. Sent as ‘Authorization: Bearer <api_key>’. Contact your Yelp Sales/CS rep to enable CAPI on your app.
`test_event`	No	When enabled, Yelp validates the payload without recording conversions in production. Set true while verifying your integration, then disable for live traffic.

Management UI Setup

Go to Integrations > Add Integration > Yelp Ads.
Choose a preset: Default (default), Retail (ecommerce), Lead Generation (lead_gen), Insurance (insurance).
Fill in the fields above and click Save.

Request format

POST https://api.yelp.com/v3/conversion/events

{
  "events": [
    {
      "action_source": "website",
      "custom_data": {
        "content_category": "purchase",
        "contents": [
          {
            "id": "SKU_1",
            "item_price": 120,
            "quantity": 2
          },
          {
            "id": "SKU_2",
            "item_price": 19.99,
            "quantity": 1
          }
        ],
        "currency": "GBP",
        "order_id": "ORD-1001",
        "value": 259.99
      },
      "event_id": "ORD-1001",
      "event_name": "purchase",
      "event_time": 1758500000,
      "user_data": {
        "client_ip_address": "203.0.113.9",
        "client_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
        "country": [
          "0b407281768f0e833afef47ed464b6571d01ca4d53c12ce5c51d1462f4ad6677"
        ],
        "em": [
          "86e0b9e56c17cc4d12387e1949b85053fbe73bc3ce5a1188713a9d300cc6133d"
        ],
        "external_id": [
          "d2863329af6d3300c06cca11c621a6854dce32e06c217fe09ae25687dc4573a8"
        ],
        "fn": "81f8f6dde88365f3928796ec7aa53f72820b06db8664f5fe76a7eb13e24546a2",
        "ln": "799ef92a11af918e3fb741df42934f3b568ed2d93ac1df74f1b8d41a27932a6f",
        "ph": [
          "11072303eb5c8cb5c5a1ebb762f11b37b07131265b46fdfe1276196bfbd3ca51"
        ],
        "ylpcid": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6abcd1234"
      }
    }
  ],
  "test_event": true
}

event_time (epoch seconds), event_name (purchase, lead or custom_*), action_source and custom_data are required; custom_data.value is required on purchases. Up to 1,000 events per request (bulk endpoint), 100 requests per second and 50,000 per day. test_event: true validates without recording.

Event Mapping

Signal event	Vendor event	Presets
`purchase`	`purchase`	Default, Retail, Insurance
`generate_lead`	`lead`	Default, Retail, Lead Generation, Insurance
`sign_up`	`custom_sign_up`	Default, Lead Generation
`lead_submitted`	`lead`	Lead Generation
`contact_requested`	`custom_contact`	Lead Generation
`dealer_contacted`	`custom_contact`	Lead Generation
`test_drive_booked`	`custom_booking`	Lead Generation
`quote_requested`	`lead`	Insurance
`quote_completed`	`lead`	Insurance

Signal forwards properties the preset does not map unless the integration’s strict output contract is on. Turn on strict_output_contract for this integration so only the documented fields are sent.

Identity

user_data carries em, ph (country code and digits, no plus), fn, ln, country and external_id (your user ID) as SHA-256, and client_ip_address, client_user_agent, madid and the Yelp click ID ylpcid unhashed. Yelp de-duplicates on event_id with event_name; on purchases event_id is the order ID. Yelp expects names without spaces or punctuation; a hashed multi-part name will not match.

Yelp is an advertising destination and requires marketing consent by default.

Troubleshooting

Problem	Solution
400 about currency	Yelp accepts USD and CAD only.
404	Yelp has not activated the API key for CAPI yet.

Blueprint

The Yelp Ads blueprint version is 0.9.0. It was last reviewed against the vendor’s documentation on 2026-09-22.