Dynamic Yield User Data API

openapi: 3.2.0
info:
  version: '2.2'
  title: Dynamic Yield Experience User Data API
  description: API definitions for all Dynamic Yield public endpoints.
  contact:
    name: API Support
    email: apisupport@mastercard.com
    url: https://developer.mastercard.com/support
servers:
- url: https://dy-api.com/v2
  description: US data center
- url: https://direct.dy-api.com/v2
  description: US data center, direct endpoint
- url: https://dy-api.eu/v2
  description: EU data center
- url: https://direct.dy-api.eu/v2
  description: EU data center, direct endpoint
security:
- ApiKeyAuth: []
tags:
- name: User Data API
  description: Update user data.
paths:
  /userdata/channels/{channel}/opt-in:
    summary: Update Reconnect Opt-In
    post:
      summary: Update Reconnect Opt-In
      description: Update a user's opt-in status to a specific channel in real time.
      operationId: updateReconnectOptIn
      tags:
      - User Data API
      parameters:
      - $ref: '#/components/parameters/UserDataChannel'
      requestBody:
        $ref: '#/components/requestBodies/UpdateReconnectOptInBody'
      responses:
        '202':
          $ref: '#/components/responses/SuccessUserData'
        '400':
          $ref: '#/components/responses/InvalidUserData'
  /userdata/channels/{channel}/opt-out:
    summary: Update Reconnect Opt-Out
    post:
      summary: Update Reconnect Opt-Out
      description: Update a user's opt-out status to a specific channel in real time.
      operationId: updateReconnectOptOut
      tags:
      - User Data API
      parameters:
      - $ref: '#/components/parameters/UserDataChannel'
      requestBody:
        $ref: '#/components/requestBodies/UpdateReconnectOptInBody'
      responses:
        '202':
          $ref: '#/components/responses/SuccessUserData'
        '400':
          $ref: '#/components/responses/InvalidUserData'
  /userdata/events:
    summary: External Events
    post:
      summary: External Events
      description: Track user interaction event using the user's `cuid`. Use in cases where the user's `dyid` is unavailable (e.g. offline activity).
      operationId: externalEvents
      tags:
      - User Data API
      requestBody:
        $ref: '#/components/requestBodies/ExternalEventsBody'
      responses:
        '202':
          $ref: '#/components/responses/SuccessUserData'
        '400':
          $ref: '#/components/responses/InvalidUserData'
  /userdata/{feedKey}/bulk:
    summary: User Data API
    post:
      summary: User Data API
      description: 'The User Data API enables you to update your user data on demand, including partial updates.

        **Support site article:** User Data Feed'
      operationId: userDataApi
      tags:
      - User Data API
      parameters:
      - $ref: '#/components/parameters/UserDataFeedKey'
      requestBody:
        $ref: '#/components/requestBodies/UserDataBody'
      responses:
        '202':
          $ref: '#/components/responses/SuccessUserData'
        '400':
          $ref: '#/components/responses/InvalidUserData'
components:
  schemas:
    UserDataRequests:
      description: A list of user data update requests to be executed.
      type: array
      items:
        oneOf:
        - $ref: '#/components/schemas/UserDataRequestUpsert'
        - $ref: '#/components/schemas/UserDataRequestDelete'
        - $ref: '#/components/schemas/UserDataRequestArray'
    SecondaryIdentifiers:
      type: array
      items:
        type: object
        properties:
          type:
            type: string
            example: hashedPhoneNumber
          value:
            type: string
            example: 49c7b1f6d24121078d8f37997b433586fe9a28e2dc4fbd0803eac237ac82255e
    CartItemPrice:
      description: unit.cents format using the section default currency.
      type: number
      example: 23.99
    InformAffinity:
      title: Inform Affinity
      description: Report an array of product attributes to use in affinity personalization.
      type: object
      properties:
        name:
          $ref: '#/components/schemas/EventName'
        properties:
          allOf:
          - $ref: '#/components/schemas/EventProperties'
          - properties:
              dyType:
                description: Must be `inform-affinity-v1`.
                type: string
                pattern: inform-affinity-v1
              source:
                description: The source of the user data
                type: string
              data:
                description: 'An array of attributes and values.<br><strong>Important:</strong> Reported attributes and values must be an exact match to the product feed<br>Each item in the array includes an attribute and up to 10 values:<br><br>- attribute: "name of attribute"<br>- values: ["value1", "value2"...]'
                type: array
                items:
                  type: object
                  properties:
                    attribute:
                      description: name of attribute
                    values:
                      type: array
                      maxItems: 10
                      items:
                        type: string
            required:
            - dyType
            - data
      example:
        name: Inform Affinity
        properties:
          dyType: inform-affinity-v1
          source: registration-form
          data:
          - attribute: categories
            values:
            - shoes
            - tops
            - accessories
          - attribute: brand
            values:
            - adidas
    OfflinePurchase:
      title: Offline Purchase
      description: Reports that the user completed a purchase.
      type: object
      properties:
        name:
          $ref: '#/components/schemas/EventName'
        properties:
          allOf:
          - $ref: '#/components/schemas/EventProperties'
          - properties:
              dyType:
                description: Must be `offline-purchase-v1`.
                type: string
                pattern: offline-purchase-v1
                default: offline-purchase-v1
                example: offline-purchase-v1
              uniqueTransactionId:
                allOf:
                - $ref: '#/components/schemas/UniqueTransactionId'
                - description: The purchase transaction ID. Each line contains a maximum of one SKU. If multiple items were purchased together, create multiple lines with the same transactionId.<br>The transaction ID must be unique per transaction, including online purchases.<br>A transaction with the same ID as another transaction previously ingested within the past day is ignored.
              transactionSource:
                $ref: '#/components/schemas/TransactionSource'
              transactionDatetime:
                $ref: '#/components/schemas/TransactionDatetime'
              currency:
                $ref: '#/components/schemas/Currency'
              value:
                $ref: '#/components/schemas/Value'
              cart:
                allOf:
                - $ref: '#/components/schemas/CartExternal'
                - description: The cart's absolute current state. Products are ordered from the first added to the cart to the most recent.
            required:
            - dyType
            - uniqueTransactionId
            - transactionDatetime
            - value
            - cart
      required:
      - name
      - properties
    UserDataActionArray:
      description: Use `array_add` and `array_remove` to edit data in existing arrays.
      type: string
      enum:
      - array_add
      - array_remove
      example: array_add
    ExternalIdentify:
      title: Identify
      description: Reports that the user has been identified.
      type: object
      properties:
        name:
          allOf:
          - $ref: '#/components/schemas/EventName'
          - example: CDP Initial Sync
        properties:
          allOf:
          - $ref: '#/components/schemas/EventProperties'
          - properties:
              dyType:
                description: Must be `external-identify-v1`.
                type: string
                pattern: external-identify-v1
                default: external-identify-v1
                example: external-identify-v1
              secondaryIdentifiers:
                type: array
                items:
                  $ref: '#/components/schemas/SecondaryIdentifiers'
            required:
            - dyType
            - secondaryIdentifiers
      required:
      - name
      - properties
    UserDataUpsert:
      description: Add CRM data here. Date values within the CRM Data should be date & time in ISO 8601 format, with or without milliseconds (YYYY-MM-DDThh:mm:ssTZD or YYYY-MM-DDThh:mm:ss.sTZD ), expressed either in UTC or in local time. Alternatively, you can use an epoch timestamp.
      type: object
      additionalProperties: {}
    TransactionSource:
      description: The source where the transaction occurred, usually the physical store ID.
      type: string
      example: f877e8a9dbb
    Ip:
      description: 'The client IP address, for geolocation-based targeting and audience building. If not passed, the caller IP is used. This applies only to client-side API calls when isImplicitClientData: true is set in the Options object.'
      type: string
      example: 54.100.200.255
    ReconnectIdentifierValue:
      description: The identifier value.
      type: string
    Timestamp:
      description: Date & time in ISO 8601 format, with or without milliseconds (YYYY-MM-DDThh:mm:ssTZD or YYYY-MM-DDThh:mm:ss.sTZD ), expressed either in UTC or in local time. Alternatively, you can use an epoch timestamp.
      type: string
      format: date-time
      example: '2021-07-24T13:44:17+02:00'
    EventProperties:
      description: Data for the reported event.
      type: object
    Size:
      description: Product size.
      type: string
      example: L
    UpdateReconnectOptInPayloadWebApp:
      title: Update Opt-In/Out Status – Web-Push/App-Push
      type: object
      properties:
        associatedDevice:
          description: The device associated with the user for web/app push notifications.
          type: object
          properties:
            dyid:
              $ref: '#/components/schemas/Dyid'
        identifier:
          description: The identifier to opt in or out for.
          type: object
          properties:
            type:
              allOf:
              - $ref: '#/components/schemas/ReconnectIdentifierType'
              - enum:
                - pushID
                default: pushID
                example: pushID
            value:
              $ref: '#/components/schemas/ReconnectIdentifierValue'
      required:
      - identifier
    CustomEvent:
      title: Custom Event
      description: Use custom events to report any event that isn't already defined for use in Experience OS, but is significant to your business.<br>**Note:** custom events support only symbols that are encoded with UTF-8 ([Basic Multilingual Plane](https://en.wikipedia.org/wiki/Plane_%28Unicode%29#Basic_Multilingual_Plane)). Some characters with diacritics (additional symbols above or below the letter) are read as the base character. For example, **é** is processed as **e**.
      type: object
      properties:
        name:
          description: Event name for display. Does not have a `dyType` property.
          type: string
          example: VIP Login
        properties:
          description: Properties can be strings, numbers, or Boolean. Note that we don't support nested properties when creating targeting rules over custom events.
          type: object
          properties:
            value:
              description: Indicates the monetary value of the event, with or without the optional currency designation. Use for goals based on events.
              type: number
              example: 98.7
            currency:
              $ref: '#/components/schemas/Currency'
          additionalProperties:
            anyOf:
            - type: string
            - type: number
            - type: boolean
      required:
      - name
      example:
        name: Custom Event Example 1
        properties:
          isVIP: true
    DeviceEngagement:
      description: Data for the served device.
      type: object
      properties:
        ip:
          $ref: '#/components/schemas/Ip'
    CartQuantity:
      description: Number of items.
      type: number
    EventsExternal:
      description: One or more events to report.
      type: array
      items:
        oneOf:
        - $ref: '#/components/schemas/OfflinePurchase'
        - $ref: '#/components/schemas/InformAffinity'
        - $ref: '#/components/schemas/ExternalIdentify'
        - $ref: '#/components/schemas/CustomEvent'
    CartTransactionItemValue:
      description: Value of the line item in actual payment currency.<br>The value is the product of `itemPrice` times `quantity`, after discount and taxes.<br>Negative values are ignored.<br>Required if the `value` property is not defined. Otherwise, it's optional.
      type: number
      example: 23.99
    UserDataUser:
      description: User's identifying details.
      type: object
      properties:
        cuid:
          $ref: '#/components/schemas/Cuid'
        cuidType:
          allOf:
          - $ref: '#/components/schemas/CuidType'
          - description: The type of identifier used to identify the user. The value should be one of the following:<ul><li>`he` - hashed email</li><li>Any custom identifier previously defined</li></ul>
          - example: he
      required:
      - cuidType
      - cuid
    UserDataRequestUpsert:
      title: Upsert Request
      type: object
      properties:
        action:
          $ref: '#/components/schemas/UserDataActionUpsert'
        cuid:
          allOf:
          - $ref: '#/components/schemas/Cuid'
          - example: 531168e71649b840a843bc3c3859c072195866cae634fa65efe2328b5ef54134
        cuidtype:
          allOf:
          - $ref: '#/components/schemas/CuidType'
          - description: Use `he` for hashed email addresses or use your custom identifier type. If importing data based on users' DYID, use `dyid` as the `cuidtype` and enter its value in the `cuid` field.
          - example: he
        timestamp:
          $ref: '#/components/schemas/Timestamp'
        data:
          $ref: '#/components/schemas/UserDataUpsert'
      required:
      - action
      - cuid
      - cuidtype
      - timestamp
      - data
    CuidType:
      description: 'Use this identifier type to identify users across devices (for example, `customer_id`, `account_id`, or `he` for SHA-256 hashed email).<br>**Note: Do not include any personal information in this ID.**'
      type: string
    CartExternal:
      description: Personalize campaigns based on cart state.<br>**Required when basket-based strategies and rules are being used.**
      type: array
      items:
        type: object
        properties:
          productId:
            $ref: '#/components/schemas/CartProductIdEcom'
          quantity:
            $ref: '#/components/schemas/CartQuantity'
          itemPrice:
            allOf:
            - $ref: '#/components/schemas/CartItemPrice'
            - description: List price for each item (quantity of one). This might be different from the `transactionItemValue` due to discounts, taxes, and so on.
          transactionItemValue:
            $ref: '#/components/schemas/CartTransactionItemValue'
          size:
            $ref: '#/components/schemas/Size'
          innerProducts:
            $ref: '#/components/schemas/InnerProductsExternal'
        required:
        - productId
        - quantity
        - itemPrice
        - transactionItemValue
    UserDataArrayNumber:
      title: 'Data: array of numbers'
      description: Add CRM data here. Insert the integer values corresponding to your predefined dropdown array. [Learn more about mapping numeric values to dropdown arrays](https://support.dynamicyield.com/hc/en-us/articles/4409595248017-Update-Your-User-Data-Feed-by-API#h_01FZ58DYM9WMR66N2P3Z4NKF7R).
      type: object
      additionalProperties:
        type: array
        items:
          type: number
    UserDataRequestDelete:
      title: Delete Request
      type: object
      properties:
        action:
          $ref: '#/components/schemas/UserDataActionDelete'
        cuid:
          allOf:
          - $ref: '#/components/schemas/Cuid'
          - example: 531168e71649b840a843bc3c3859c072195866cae634fa65efe2328b5ef54134
        cuidtype:
          allOf:
          - $ref: '#/components/schemas/CuidType'
          - description: Use `he` for hashed email addresses or use your custom identifier type. If importing data based on users' DYID, use `dyid` as the `cuidtype` and enter its value in the `cuid` field.
          - example: he
        timestamp:
          $ref: '#/components/schemas/Timestamp'
      required:
      - action
      - cuid
      - cuidtype
      - timestamp
    Cuid:
      description: User identifier value. Max 250 characters.
      type: string
      enum:
      - demo@email.com
      - '123456789'
    Currency:
      description: The currency used for the value. *Optional, but required for multi-currency sites.*<br>[List of supported currencies](https://support.dynamicyield.com/hc/en-us/articles/360022558254#h_01F248KMJV1VWADRC2H7WYFWCZ)
      type: string
      example: USD
    UserDataArrayString:
      title: 'Data: array of strings'
      description: Add CRM data here.
      type: object
      additionalProperties:
        type: array
        items:
          type: string
    Dyid:
      description: The _dyid cookie value. The user ID assigned to visitors by Dynamic Yield. For a new user, send this param empty. Learn more about the [user ID](https://dy.dev/docs/experience-api-basics#user-id).
      type: string
    UserDataPayload:
      title: User Data Request
      type: object
      properties:
        requests:
          $ref: '#/components/schemas/UserDataRequests'
      required:
      - requests
      example:
        requests:
        - action: upsert
          cuid: 0c907031b7d6515ce8def68a767272d0ec7225e987c3e0ce70b985c265f318f0
          cuidType: ihe
          timestamp: '2023-07-02T10:44:44+02:00'
          data:
            UserSegments:
            - segment 1
            - segment 2
        - action: delete
          cuid: myuser789
          cuidType: ihe
          timestamp: '2022-05-24T12:31:09+02:00'
    ExternalEventsPayload:
      title: External Events Request
      properties:
        user:
          $ref: '#/components/schemas/UserDataUser'
        device:
          $ref: '#/components/schemas/DeviceEngagement'
        events:
          $ref: '#/components/schemas/EventsExternal'
      required:
      - user
      - events
    UserDataActionUpsert:
      description: Use `upsert` to add user data.
      type: string
      enum:
      - upsert
      example: upsert
    UserDataRequestArray:
      title: array_add/array_remove Request
      type: object
      properties:
        action:
          $ref: '#/components/schemas/UserDataActionArray'
        cuid:
          allOf:
          - $ref: '#/components/schemas/Cuid'
          - example: 531168e71649b840a843bc3c3859c072195866cae634fa65efe2328b5ef54134
        cuidtype:
          allOf:
          - $ref: '#/components/schemas/CuidType'
          - description: Use `he` for hashed email addresses or use your custom identifier type. If importing data based on users' DYID, use `dyid` as the `cuidtype` and enter its value in the `cuid` field.
          - example: he
        timestamp:
          $ref: '#/components/schemas/Timestamp'
        data:
          oneOf:
          - $ref: '#/components/schemas/UserDataArrayString'
          - $ref: '#/components/schemas/UserDataArrayNumber'
      required:
      - action
      - cuid
      - cuidtype
      - timestamp
      - data
    Value:
      description: The total monetary value of the event. This is the item or items added that triggered the event only, not necessarily all items in the cart.<br>Numbers are rounded to the nearest 0.01. Numbers smaller than 0.005 are rounded down to 0.
      type: number
      example: 19.9
    EventName:
      description: A human-readable name corresponding to the schema name.
      type: string
    ReconnectIdentifierType:
      description: The identifier type.
      type: string
    CartProductIdEcom:
      description: SKU exactly as it appears in the product feed.
      type: string
    UserDataActionDelete:
      description: Use `delete` to remove data.
      type: string
      enum:
      - delete
      example: delete
    TransactionDatetime:
      description: The date and time of the purchase in **ISO 8601 combined date and time** format.
      type: string
      example: '2018-09-23T07:29:51+00:00'
    UpdateReconnectOptInPayloadEmailSms:
      title: Update Opt-In/Out Status – Email/SMS/WhatsApp
      type: object
      properties:
        identifier:
          description: The identifier opting in or out.
          type: object
          properties:
            type:
              type: string
              description: "identifier type must be one of the following:\n  <ul>\n  <li><code>email</code></li>\n  <li><code>phoneNumber</code></li>\n  <li>Any previously defined custom identifier</li>\n  <li><strong>Note:</strong> For <code>email</code> and <code>phoneNumber</code>, pass the corresponding identifier value in plain text.</li>\n  </ul>\n"
              example: email
            value:
              $ref: '#/components/schemas/ReconnectIdentifierValue'
      required:
      - identifier
    UniqueTransactionId:
      description: When this value is passed it ensures that only one purchase is recorded for the transaction ID, even if duplicate events are reported.<br>Maximum of 64 characters.<br>*Optional, but recommended*
      type: string
      example: '38373991919193830033'
    InnerProductsExternal:
      description: '**For restaurants only.** Indicate any inner products within the main product.'
      type: array
      items:
        type: object
        properties:
          productId:
            $ref: '#/components/schemas/CartProductIdEcom'
          quantity:
            $ref: '#/components/schemas/CartQuantity'
          itemPrice:
            $ref: '#/components/schemas/CartItemPrice'
        required:
        - productId
  examples:
    UserDataUpdateExample01:
      value:
        dy_trace_id: eed3b778281fe4bd435902c8c7f854a3
    UserDataPayloadExample01:
      value:
        requests:
        - action: upsert
          cuid: myuser123
          cuidtype: ihe
          timestamp: '2021-07-24T13:44:17+02:00'
          data:
            VIP: T
            contacts_buyer: T
            premium_score: 0.8
            last_visit: '2020-05-16T05:50:06-05:00'
        - action: upsert
          cuid: myuser456
          cuidtype: ihe
          timestamp: '2021-07-24T13:45:52+02:00'
          data:
            VIP: F
            contacts_buyer: T
            premium_score: 0.3
        - action: upsert
          cuid: 0c907031b7d6515ce8def68a767272d0ec7225e987c3e0ce70b985c265f318f0
          cuidtype: ihe
          timestamp: '2023-07-02T10:44:44+02:00'
          data:
            UserSegments:
            - segment 1
            - segment 2
        - action: delete
          cuid: myuser789
          cuidtype: ihe
          timestamp: '2022-05-24T12:31:09+02:00'
    UserDataUpdateExample02:
      value:
        error:
          message: The feedKey must match the feed key in the feed settings
          type: E019
        dy_trace_id: 74eb317b0a44addc30e765e6b9a83675
  parameters:
    UserDataFeedKey:
      name: feedKey
      description: The data feed key. To get the key of an existing data feed, go to the data feed in Experience OS, click Edit, and copy the key.
      in: path
      required: true
      schema:
        type: string
      example: 114f64059571a124de146311f2256f2
    UserDataChannel:
      name: channel
      description: The channel by which to send the push to the user.
      in: path
      required: true
      schema:
        type: string
        enum:
        - email
        - sms
        - whatsapp
        - web-push
        - app-push
      example: email
  responses:
    SuccessUserData:
      description: User data updated.
      content:
        application/json:
          examples:
            UserDataResponseExample01:
              $ref: '#/components/examples/UserDataUpdateExample01'
    InvalidUserData:
      description: Response with error.
      content:
        application/json:
          examples:
            UserDataResponseExample02:
              $ref: '#/components/examples/UserDataUpdateExample02'
  requestBodies:
    UserDataBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UserDataPayload'
          example:
            $ref: '#/components/examples/UserDataPayloadExample01'
    UpdateReconnectOptInBody:
      required: true
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/UpdateReconnectOptInPayloadEmailSms'
            - $ref: '#/components/schemas/UpdateReconnectOptInPayloadWebApp'
    ExternalEventsBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ExternalEventsPayload'
  securitySchemes:
    ApiKeyAuth:
      description: Your API key
      type: apiKey
      in: header
      name: dy-api-key
      x-default: your-api-key
x-provenance:
  method: searched
  source: https://dy.dev/reference
  harvested: '2026-10-14'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://dy.dev/reference/browse.md
  - https://dy.dev/reference/choose-variations.md
  - https://dy.dev/reference/externalevents.md
  - https://dy.dev/reference/profileanywhere.md
  - https://dy.dev/reference/reportoutages.md
  - https://dy.dev/reference/search.md
  - https://dy.dev/reference/shoppingmuse.md
  - https://dy.dev/reference/suggest.md
  - https://dy.dev/reference/track-engagement.md
  - https://dy.dev/reference/track-pageviews.md
  - https://dy.dev/reference/trackevents.md
  - https://dy.dev/reference/tracktransactionstatusspecificitem.md
  - https://dy.dev/reference/tracktransactionstatuswholetransaction.md
  - https://dy.dev/reference/update-reconnect-opt-in.md
  - https://dy.dev/reference/update-reconnect-opt-out.md
  - https://dy.dev/reference/updateaddonsfeed.md
  - https://dy.dev/reference/updatebranchfeed.md
  - https://dy.dev/reference/updateproductfeed.md
  - https://dy.dev/reference/userdataapi.md
  merge:
    pages: 19
    deduped: 262
    conflicts_kept_first: 0