Knowledge Base

Getting Started with the Yahoo DSP Connector Through the API

This guide explains how to organize and publish datasets to Yahoo DSP using Narrative’s Yahoo DSP Connector. The workflow is similar to the Trade Desk integration:

1. Retrieve existing taxonomies
2. Create or update folders (taxonomy elements)
3. Create or update buyable segments
4. Synchronize to make segments discoverable in Yahoo DSP
5. Delete or retire elements if needed

1. Introduction

Narrative’s Yahoo DSP Connector allows you to create and manage your segments (audiences) so that advertisers can discover and use them in Yahoo DSP. Proper organization of folders and segments, along with accurate data rates, is crucial to maintaining a coherent taxonomy and monetizing your data effectively.

2. Retrieve Existing Taxonomies

Endpoint

GET https://yahoo-dev.narrativeconnectors.com/taxonomies

Sample Response (truncated for brevity):

{
  "children": [
    {
      "element_id": "123223-1769-4f25-947c-3190e8bc3eb4",
      "display_name": "My Audience",
      "buyable": false,
      "children": [
        {
          "element_id": "165faa1f-bc2a-4d50-ba76-1c2f2a8fd679",
          "display_name": "Delivery dataset",
          "buyable": true,
          "data_rates": [
            {
              "display_rate_usd": 5.0,
              "video_rate_usd": 5.0,
              "rate_type": "cpm",
              "type": "yahoo_data_rate"
            }
          ]
        },
        ...
      ]
    },
    ...
  ]
}

• element_id: Unique identifier for each folder or segment.
• display_name: User-friendly name (visible in Yahoo DSP).
• buyable: Indicates whether the audience is purchasable or just a folder.
• data_rates: Defines CPM rates for display (display_rate_usd) and video (video_rate_usd) inventory.

3. Create a Folder

Folders organize your data segments under a hierarchical taxonomy. Typically, folders are not buyable (set "buyable": false). If you don’t need additional hierarchy, you can skip creating a folder.

4. Create a Buyable Element (Segment)

Endpoint

POST https://yahoo-dev.narrativeconnectors.com/taxonomies/elements

Sample Request Body

{
    "parent_element_id": "324232-efcd-4649-aa5e-901167bf871a",
    "buyable": true,
    "data_rates": [
        {
            "rate_type": "cpm",
            "type": "create_data_rate_system",
            "display_rate_usd": 2,
            "video_rate_usd": 1
        }
    ],
    "datasets": [1232],
    "display_name": "Delivery dataset"
}

• parent_element_id: The folder or node under which this new segment will reside.
• buyable: Marks the segment as purchasable.
• data_rates: Defines CPM rates for display (display_rate_usd) and video (video_rate_usd).
• datasets: The underlying dataset IDs from Narrative that build your audience.
• display_name: Segment name shown to advertisers.

A successful response returns a 201 Created status and the new element’s details.

5. Synchronize Segments

After creating or updating segments, they may initially be in a “draft” or “internal” state. To publish them so advertisers can actually see and buy these segments:

Endpoint

POST https://yahoo-dev.narrativeconnectors.com/taxonomies/synchronization-requests

Once synchronized, the segments appear in Yahoo DSP. If you check the taxonomy again, the relevant segments typically reflect a connection_synchronized status.

6. Update or Delete Elements

• Update

  PUT https://yahoo-dev.narrativeconnectors.com/taxonomies/elements/{element_id}
  

  
  Use this to rename a segment, adjust rates, move it under a different parent folder, or associate a new dataset.
• Delete

  DELETE https://yahoo-dev.narrativeconnectors.com/taxonomies/elements/{element_id}
  

  
  Removes a folder or segment entirely (ensure it’s not needed by active campaigns).

7. Conclusion

The main steps to start using Narrative’s Yahoo DSP Connector are:

1. Retrieve your current taxonomy to see existing folders/segments.
2. Create or update folders and buyable segments with your preferred data rates.
3. Synchronize segments to make them live in Yahoo DSP.
4. Delete any outdated segments when needed.

By following these steps, you can easily structure your data in Yahoo DSP and streamline how advertisers discover and purchase your audiences. For further assistance, contact Narrative Support.