The User Data API enables you to update your user data on demand, including partial updates.
With the User Data API, you can use data that was collected outside of Dynamic Yield for segmentation and targeting, in real time, and with reduced load compared to the file-based feed. Also, you can run updates, view results, and monitor activity with no need for assistance from your account manager.
When should you choose the API rather than the CSV method?
You can experiment with calling the API, checking the status in the log and fine-tuning it to match your business needs.
Prefer this method when:
- User data is needed in real time (for personalizing the user's experience, for example. Say, letting a user know that they have loyalty points that are about to expire).
- Only a small number of users need an update (with the CSV method, the entire data set is uploaded. With the API, you can update only specific new data).
User-data onboarding flow
Setting up and using the API includes the following steps. Some preparation is done on your side (by either a business user or a developer), and some are done in the Dynamic Yield console, as indicated.
Follow these instructions if you are setting up user-data onboarding for the first time. If you are migrating from CSV upload to API, see Existing accounts: Moving from CSV to API.
Preparation:
- Decide which attributes (columns) to pass in the API (including the attribute name, type, and so on). Note: For privacy reasons, do not include any attributes that are considered PII (such as name, date of birth, address, and so on).
Pro tip:
All user attributes must be sent in each API call. You can streamline the process by grouping the columns into User Data feeds based on use cases, for example, based on:
- Frequency: Group together fields that you plan to update with the same frequency (eliminates needless updates).
- Attribute availability: All attributes that are updated in the feed must be available for each API call, so separate those that change infrequently from those that change often.
- Number of users to update: For a small number of user updates, the API is best-suited. If you need to do a full update, use the API load or a CSV file method.
- Generate an API key (if you haven't already done so).
Setup in the Dynamic Yield console (developer):
-
Set up the feed:
- Create a new feed with the required settings.
- Create the JSON schema. You can build the schema from scratch, or start with the sample file provided in the console, and edit it as needed.
- Set the sections that share the data, and save the draft. The schema is available within 5 minutes, and the API can now be tested.
- Set up the code for your API calls.
Test the feed:
Note: This is an important step, because after activation, the schema can be changed only in limited ways. The test user data is not committed, and campaigns do not yet work.
- Call the API you coded in the previous step.
- The API call returns a transaction ID in a field called dy_trace_id. Using this ID, go to the API log and search for the API call status.
- In the log, ensure that the API request status is correct (202). Then, check that no errors exist for the nested objects – the API call status that is returned doesn't include them.
When the API is called, a status is returned. This status indicates the call is received. In the log, you can see the details of any errors for each action, relating to specific objects they include.
Onboard user data:
- Activate the feed (developer).
- Call APIs in accordance with your business flow.
- Monitor the feed (business user and developer). Use:
- Alerts: Provide information about issues with the API call and its included objects.
- Logs: See Experience APIs Logs for more information. The User Data API logs behave the same.
Schema guidelines
The schema is a table that determines where and how the information is stored in Dynamic Yield. This information is provided in JSON syntax, and copied into the Dynamic Yield console.
We've created a tool to make creating and modifying your JSON schema easier:
- Access the schema creator tool
- Learn more about the User Data Schema Creator
Goal
The purpose of the schema is:- Define the table where the data is stored, so values can be validated when they are sent via the API or CSV.
- Define how the Dynamic Yield console shows the condition (when defining an audience based on criteria).
Size limitation
The JSON definition schema cannot exceed 64K.Fields
Each field is stored as an object within the fields array. The JSON schema must include at least 1 object in the field array, with the following parameters, as shown in this example:"fields": [
{
"name": "purchase_count",→ field name, sent in the API or column name in the CSV
"display": "Purchase Count", → the condition name, that appears in DY admin
"type": [
"null", → is the object nullable or not
"int" → nature of the field passed
],
"uiType": "number" → nature of the field that appears in DY admin
}
]
Additional values in the layout
If you want create display values in the Dynamic Yield console in addition to those set in the schema:
- Create a UI object that contains its definition (for example, map “true” to “t”).
- Parallel to the “field” array, add a "uiTypes" object.
- Map that UI object using the existing field object.
- Verify that each UI object in the field arrays is defined.
Example of what this can look like:
Sample code:
"fields": [
{
"name": "has_offer",
"display": "Has Offer",
"type": [
"null",
"boolean"
],
"uiType": "ref",
"uiTypeRef": "UIhas_offer"
}
],
"uiTypes": {
"UIhas_offer": {
"uiType": "select",
"validation": {
"values": [
{
"name": "Yes",
"value": "true"
},
{
"name": "No",
"value": "false"
}
]
}
}
You can:
- Add or remove values, as long as they are not in use in an audience conditions
- Change display names of fields
- Add new fields:
- Add only at the end of the existing schema.
- Fields must be nullable (non-mandatory) (must be of type “null”).
- Must include "default": null parameter.
You can't:
- Delete fields.
Pro tip: Instead, change a field to non-mandatory and stop updating it. - Change the order of fields.
- Change field types.
- Remove “null” from a field type, as it will make the field mandatory.
{
"fields": [
{
"//":"Field with values example - Referenced in uiType with the possible values",
"name": "VIPPersona",
"display": "VIP Persona",
"type": ["null", "int"],
"uiType": "ref",
"uiTypeRef": "UIMetalVIP"
},
{
"//":"Number example - no need to reference in uiType",
"name": "CustomerScore",
"display": "Customer Score",
"type": ["null", "int"],
"default": null,
"uiType": "number"
},
{
"//":"string example - no need to reference in uiType",
"display": "Account Manager",
"name": "AccountManager",
"type": [
"null",
"string"
],
"uiType": "input"
},{
"//":"Boolean example - no need to reference in uiType",
"name": "IsSubscribedTo",
"display": "Is Subscribed To Emails",
"type": [
"null",
"boolean"
],
"uiType": "ref",
"uiTypeRef": "UIIsSubscribed"
},
{
"//":"Date example - no need to reference in uiType",
"name": "AnniversaryGiftExpires",
"display": "Anniversary Gift Expires",
"type": [
"null",
"long"
],
"uiType": "date"
}
],
"uiTypes": {
"UIMetalVIP": {
"//":"Example how to represent different display values in the Dynamic Yield console",
"uiType": "select",
"validation": {
"values": [{
"name": "VIP Gold",
"value": 0,
"source": "goldVIP"
}, {
"name": "Other",
"value": 1,
"source": "otherVip"
}, {
"name": "VIP Silver",
"value": 4,
"source": "vipSilver"
}
]
}
},
"UIIsSubscribed": {
"//":"Admin vallues: boolean",
"uiType": "select",
"validation": {
"values": [
{
"name": "No",
"value": "false"
},
{
"name": "Yes",
"value": "true"
}
]
}
}
}
}
Use our User Data Schema Generator tool to create or edit your schemas.
Setup
Generate an API key
An API Key is used to identify the source of API calls that are sent to Dynamic Yield. You must include the API Key in all of the API calls specified below. To generate an API Key:
- Go to Settings › API Keys and click New Key.
- Specify User Feed for the ACL value and click Save.
- Copy the value of the key to a secure location.
- The new key now appears in your list.
Create a new feed
- Go to Assets › Data Feeds and create a new User Data feed.
- For the Feed Source, select Sync via API.
- Enter the schema for the feed.
- Define the CUID type. Default is email, so you need to change this value only if you want to use a different ID type.
- Click Save as Draft.
Existing accounts: Moving from CSV to API
If you are already onboarding user data using the CSV upload method and want to move to the User Data API:
- Open the User Data feed.
- Change the feed settings to Sync via API. Note that schema changes are not supported at this time.
- Call APIs in accordance with your business flow.
- Monitor the feed (business user and developer). Use:
- Alerts: Provide information about issues with the API call and its included objects.
- Logs: See Experience APIs Logs for more information. The User Data API logs behave the same.
- Activate
Note: Existing user attributes is retained when switched to API.
Important: Once you switch to the API sync, you cannot go back to the CSV method without assistance from technical support, so make sure this is what you want to do.
Creating API calls
For details, see the API reference on our Developers site.
Creating audiences based on user data
When your data is onboarded, you can immediately use the Audience Explorer to explore these valuable segments and analyze their performance in comparison to your entire online user base, complemented by users’ behavioral data captured by Dynamic Yield. The new condition appears under User Properties using the User-Data feed name, and it can be coupled with any other Dynamic Yield condition available in your account and used to create and save micro-targetable segments (audiences) that can be incorporated into your Dynamic Yield Site Personalization experiences and Recommendations.
Troubleshooting response errors
API error messages
Possible errors that can be returned include:
- 202: request accepted - trace ID returned
- 400: bad request/error parsing request
- 401: invalid or missing API key
- 403: access denied for a valid API key (wrong section, wrong feed id, illegal operation)
- 405: wrong HTTP method (not POST)
- 422: exceeded feed size limitation/exceeded number of actions per batch
- 429: too many requests received
- 451: wrong key type used (server-side key from client side, or client-side key from server-side)
- 500: unspecified internal error
Prerequisites and limitations
- API-based feed cannot be changed to CSV method.
- Each site must have a unique API key.
- API request limit:
- Ability to update up to 100 users in 1 API call
- Up to 100 API calls in 1 second, adding up to 600K updates per minute