Dynamic Yield Developer Documentation

Browse Dynamic Yield's latest developer documentation including API references, articles, and sample code for optimizing, personalizing, and creating consistent digital customer experiences across touchpoints.


Basic Concepts

The Technicalities

At the core, our developer product is based on a secure REST API. We're now hard at work on building a suite of SDKs for web and mobile. These SDKs are aimed at making your life as a developer simpler and minimizing implementation issues.


The API is HTTPS-only. Request and response bodies are JSON-encoded.

Authentication & authorization are based on API keys passed in the request header, which are managed through the Admin UI. You are highly encouraged to only grant the needed permissions for API keys and use dedicated keys when multiple components of your system need to interact with different parts of our API.

Base URLs

Dynamic Yield's SaaS offering is available in two separate data centers to best support both latency and regulatory purposes. The two data centers do not share any data between them, meaning you should only use the API Gateway URL matching your account.

In addition, we ask that you use a slightly different endpoint when calling the API directly from your client side.

For the US:
For server-side keys: https://dy-api.com/v2/, for example: https://dy-api.com/v2/serve/user/choose
For client-side keys: https://direct.dy-api.com/v2/
For client-side collection endpoints: https://direct-collect.dy-api.com/v2/collect

For the EU:
For server-side keys: https://dy-api.eu/v2/
For client-side keys: https://direct.dy-api.eu/v2/
For client-side collection endpoints: https://direct-collect.dy-api.eu/v2/collect

User and Session IDs

Since we're all about personalization here, having well-defined user and session IDs is paramount for segmentation and experimentation to run correctly. The long-term behavior of a user is super useful for targeting recurring users, while the proper session definition is important for session-length tests running the way they're expected to - and for reports to show valid data.

  • In the API-Only implementation mode, generating these IDs is totally up to you, as is storing these IDs for a duration that you control. This means you get complete control for the price of some extra work.

  • With the hybrid approach of using APIs over the Web-based implementation, identifiers and their lifecycle are managed by Dynamic Yield. However, we still need you to pass and set the needed cookies. See the guide to learn more.

Although in hybrid mode you need not generate or consider the right lifetime of IDs, it still pays off to understand the purpose of each identifier:

The User ID

The User ID essentially identifies a single, unique device, whether the actual person using it is anonymous or known (i.e. logged-in / registered). Meaning, you're not expected to always have the ID of a known user account at hand. Rather, you should have a unique identifier value that is allocated once when the device is first seen and stays persistent on that device for as long as feasible.

In an API-Only Implementation, how you actually persist these IDs typically depends on the platform:
on the web, this is usually done via setting a first-party cookie by your server. For mobile apps, you can typically choose between various types of local data storage. In most cases, you should already have such an ID. If not, please refer to the Best Practices section for guidelines.

The Session ID

The Session ID represents a period of activity on a specific device and should always be valid for a limited time. This identifier usually already exists in your client apps. If not, see Best Practices.


Omni-channel user identification

For identifying the same user across devices, you need to have another type of identifier named the Customer ID. Typically, this would be a hashed email or some internal ID coming from your backend systems. To learn more about associating User IDs with a Customer ID, see Reporting Events.

The Core Endpoints

Choosing Variations and Reporting Page Views

If there were one API call to rule them all, it would be the choose endpoint.

Using choose, you receive the chosen variations for one or multiple tests, regardless of the type of campaign. Custom Campaigns, Recommendations, and any other type of test are all served via this method, returning their appropriate payload in the response.

When a user navigates through your app, either if you render full web pages on the server side, or alternatively pass a JSON payload to your SPA or mobile app, it is common to choose variations as part of the page rendering process. Thus, in the API-Only Implementation, the call to choose also implicitly reports a new page view by default. Pageview reporting is critical for many targeting conditions to work correctly, which rely on the browsing history of the user - whether over time, in the current session, or on the currently viewed page. In Hybrid Mode, our client script integrated in your website would report the pageview when loaded.

Of course, choosing a variation need not happen only when rendering the page - and reporting a page view does not necessitate choosing a variation at that time. choose can be called at any point during the lifecycle of a page, and is often called asynchronously for below-the-fold or dynamically loaded content. This helps keep the initial rendering of the page with minimal delay. For more, please see Best Practices.

Reporting Engagement With a Variation

Now that you've got the chosen variations and rendered them (or performed any other relevant action), the next step is reporting engagement with any rendered variation. For the sake of accurate reports, Dynamic Yield needs to record both impressions and clicks on each variation being served to the end-user.

  • Impressions (i.e. the user has been exposed to a variation) are by default implicitly reported by the call to choose (note: changing that behavior to explicitly report impressions is possible - please contact us).

  • Clicks always need to be reported by you: unlike the classic mode of integrating Dynamic Yield, which is mostly based on a client-side script loaded in the browser, in an API-based scenario, Dynamic Yield does not control or monitor the rendered content.
    Instead, the response from choose contains identifiers for each unique decision made in that call. You should store these identifiers, then pass them back when reporting a click. See Reporting Engagement.

Reporting Events

Reporting meaningful user events (e.g. Login, Add to Cart, Purchase, Video Play, etc.) is crucial for both segmentation and experimentation: you typically wish to target users based on their past actions or set an event as a primary or secondary metric for your campaigns. For more on built-in and custom events, see Reporting Events.


Rate Limiting

The /choose endpoint is globally limited to a rate of 11,000 requests per minute by default.
All other endpoints could be used with an unlimited rate of requests.

When you have reached your limit of allowed requests, you will get a status code of "429 - Too many requests" as your response.

Please contact your Technical Account Manager if your use case requires a different rate limiting enforcement configuration.

Validating Your Implementation

Since API calls are typically made server-server, validating a fresh new implementation or debugging something that does not work as expected in production can become tricky. To that end, we've released a logs viewer within the Admin UI. It offers both a high-level view that's useful for getting a bird eye's view of your implementation health, and controls for drilling down up to the level of a single API request and all its details.

If you've previously worked with the ELK stack (Elasticsearch, Logstash & Kibana) Splunk or similar tools, this screen should look really familiar to you.

API Logs screenAPI Logs screen

API Logs screen

Other Endpoints

The documentation for a few features is only available to logged-in customers at this time:

  • To learn more about the Unified Customer Profile API, please head to our Knowledge Base article.

  • To learn more about the Pushing incremental product feed updates via API rather than a through the default periodic file-based sync, please contact your Customer Success Manager.


So few endpoints?

One thing that is certainly surprising to people new to our API is how few endpoints there actually are.

This is by design: we wanted the API to have a small surface area - the choose
endpoint, for example, unlocks a wide variety of campaign types and settings which are all manageable through the Admin UI.

This means radical changes can be made by the Admin UI user, while the developer need not be aware of these changes and any complex reasoning behind them. In particular, setting and editing variation payloads and targeting rules are all made via the UI.

Updated about a year ago

Basic Concepts

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.