DataDocs is a feature for storing relational data regarding your contacts, this can for example be purchase history, upcoming events or other services.
Visit our API documentation to learn more about using DataDocs.
Terminology
-
Document type
In your DataDocs central you can store one or more Document Types. A Document Type gathers DataDocs with the same content and defines the two mandatory fields (originalId and externalId) in your JSON. You will always map a DataDoc to a type.
Multiple types can be used if you, let's say, want to separate different markets or brands due to different setups or data sources.
When viewing a contact's DataDocs you first select the document type and all rows connected to that contact within the selected type will appear.
You must create a type before you can start creating docs for your contacts.
It is recommended to add a JSON Schema to your types. Read more about this below.
-
DataDoc
A row of data connected to a contact by original id. Must belong to a Document type. The data for a contact can be updated and/or deleted.
-
OriginalId
The originalId is your unique identifier for a contact in Symplify.
What field in your JSON that correspond to originalId is defined by the Document Type.
-
ExternalId
The external Id is your own identifier for a specific DataDoc row, for example an order or booking number. It must be a unique string for that specific event. The externalId can be used for updating or deleting a row.
What field in your JSON that correspond to externalId is defined by the Document Type.
Preparations
DataDocs is a blank sheet when you first start so begin with defining your content.
There are only two mandatory fields for each row; one field containing the original Id and one field containing the external id, the rest of the headers are mapped according to what you include in your file/call.
The mandatory fields are mapped when creating the Document Type.
Consider if you want to include a transaction date and/or a date for when a document was last updated.
Important! Document headers are case sensitive and must be alphanumeric (A–Z, a–z and 0–9) and not contain any whitespaces. Underscore (_) and dash (-) is allowed.
Document headers are used for visualization of data (when using placeholders) and when creating segments.
You can add more document headers over time but please note that already existing ones can not be edited (while the values within can).
No column mapping is needed for visualization within the Symplify interface. When looking at a contact, all DataDoc row headers found on the specific contact (for the selected type) are included automatically.
DataDocs within a selected Document Type on a contact
The field values can be text, dates or numbers (decimals separated with a period (.)) that can be used for segmentation and placeholders in sendouts.
A value field can also contain JSON.
You can include as many headers you like but have in mind that everything should be there for a reason, unnecessary data means unnecessary work for the marketers.
Technical setup
You can import data with a file or as single rows using the API. Learn more on apidocs.symplify.com.
A DataDoc is a text string with JSON. When importing a DataDoc file, each line in the import will contain a JSON row:
{"originalid":"F3","bookingnumber":"F3-2","transactionDate":"2024-06-02","category":"sport","eventDate":"2024-09-01","event":"Team A - Team B","eventDetails":{"location":"Tiny Stadium","startTime":"15.00"},"orderItems":[{"ticketType":"adult","quantity":1,"price":15},{"ticketType":"student","quantity":2,"price":10}]}
{"originalid":"F3", "bookingnumber":"F3-3", "transactionDate": "2024-05-30", "category": "music", "eventDate": "2024-07-22","event":"The musical","eventDetails": {"location": "Big Arena", "Entrance": "F", "startTime": "20.00"},"orderItems":[{"ticketType":"adult","quantity":2,"price":20},{"ticketType":"kid","quantity":1,"price":10},{"ticketType":"student","quantity":1,"price":15}]}
When updating, you must always provide the Document Type id for which the DataDocs belongs.
After a successful import, when selecting the specific Document Type, the rows will be visible on the contacts.
JSON Schema
It is recommended to add a JSON Schema for each Document type. The schema will help you editing segments and using placeholders since this will automatically generate the correct options based on the schema.
If you add a new header to your documents, you should also update the schema.
If your documents include arrays, the array must have the type=array in order to be able to create segments on. Please view "orderItems" in below example schema.
Example schema:
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"category": {
"type": "string"
},
"transactionDate": {
"type": "string",
"format": "date-time"
},
"eventDetails": {
"type": "object",
"properties": {
"location": {
"type": "string"
},
"Entrance": {
"type": "string"
},
"Event": {
"type": "string"
},
"startTime": {
"type": "string"
},
"section": {
"type": "integer"
}
}
},
"orderItems": {
"type": "array",
"items": {
"type": "object",
"properties": {
"ticketType": {
"type": "string"
},
"quantity": {
"type": "integer"
},
"price": {
"type": "number"
}
}
}
}
}
}
Please note! Updating a name or the type of a key that already is in use within a segment may cause the segment to fail (depending on how you stated the condition).
Therefore, make sure your schema is reflecting your data before setting up segments and if you need to make changes, always verify your segments using updated parameters.