Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Insight and transactional data API
description: 'Deprecated v2 endpoints for managing transactional and insight data. Use this
API to add, replace, retrieve, and delete individual records within named
collections; bulk-import records asynchronously; check import status and retrieve
import reports; query all records in a collection at account level; list available
collections; and empty a collection. All endpoints in this spec are deprecated —
new integrations should use the Insight Data Service API instead.'
version: 2.0.1
servers:
- url: https://{region}-api.dotdigital.com
variables:
region:
default: r1
enum:
- r1
- r2
- r3
description: The Dotdigital region id your account belongs to
security:
- basicAuth: []
tags:
- name: Insight and transactional data
paths:
/v2/contacts/transactional-data/{collectionName}:
parameters:
- in: header
name: x-ddg-integration-token
required: false
description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.
schema:
type: string
pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
post:
summary: Add transactional data to contact
deprecated: true
description: Adds a single piece of transactional/insight data to a contact or account
operationId: add-transactional-data-to-contact
tags:
- Insight and transactional data
parameters:
- name: collectionName
in: path
description: The name of the transactional data collection
required: true
example: ''
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
required:
- key
- contactIdentifier
- json
properties:
key:
type: string
description: The key for the piece of data
contactIdentifier:
type: string
description: Either the id or email address of the contact that the transactional data is being added to
json:
type: string
description: The data to be stored against the contact
format: json
examples:
Request Example:
value:
key: Order-123
contactIdentifier: myCustomer@emailsim.io
json:
id: Order-123
currency: GBP
order_status: completed
purchase_date: '2020-11-03 13:03:32+00:00'
order_total: 99
order_subtotal: 99
products:
- name: Product Name
price: 99
sku: '68694'
qty: 1
summary: Request Example
responses:
'201':
description: '201'
content:
application/json:
schema:
type: object
properties:
key:
type: string
examples:
- P00000001
contactIdentifier:
type: string
examples:
- '23'
json:
type: string
examples:
- '{
"id": "Order-123",
"currency": "GBP",
"order_status": "completed",
"PurchaseDate": "2012-11-19T10:01:21Z",
"order_total": 111.2000000000,
"order_subtotal": 133.4400000000,
"Products": [
{
"Name": "Long unlined leather gloves",
"Price": 111.2000000000,
"sku": "24920",
"qty": 2
}
]
}'
examples:
Result:
summary: Result
value:
key: P00000001
contactIdentifier: '23'
json: '{
"id": "Order-123",
"currency": "GBP",
"order_status": "completed",
"PurchaseDate": "2012-11-19T10:01:21Z",
"order_total": 111.2000000000,
"order_subtotal": 133.4400000000,
"Products": [
{
"Name": "Long unlined leather gloves",
"Price": 111.2000000000,
"sku": "24920",
"qty": 2
}
]
}'
/v2/contacts/transactional-data/import/{collectionName}:
parameters:
- in: header
name: x-ddg-integration-token
required: false
description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.
schema:
type: string
pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
post:
summary: Bulk add transactional data to contacts
deprecated: true
description: Adds multiple pieces of transactional/insight data to contacts asynchronously
operationId: bulk-add-transactional-data-to-contacts
tags:
- Insight and transactional data
parameters:
- name: collectionName
in: path
description: The name of the transactional data collection
required: true
example: ''
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
properties:
RAW_BODY:
type: array
description: The insight data items to add
items:
properties:
key:
type: string
description: The unique key to identify this specific insight record
contactIdentifier:
type: string
description: The contact to add the insight data to; use **account** for account level insight data
json:
type: string
description: The insight data to add
format: json
required:
- key
- contactIdentifier
- json
type: object
examples:
Request Example:
value:
- key: Order-123
contactIdentifier: myCustomer@emailsim.io
json:
id: Order-123
currency: GBP
order_status: completed
purchase_date: '2020-11-03 13:03:32+00:00'
order_total: 99
order_subtotal: 99
products:
- name: Big BBQ
price: 99
sku: '68694'
qty: 1
- key: Order-124
contactIdentifier: myOtherCustomer@emailsim.io
json:
id: Order-124
currency: USD
order_status: completed
purchase_date: '2020-11-03 13:03:32+00:00'
order_total: 129
order_subtotal: 129
products:
- name: Baseball bat
price: 99
sku: BB-123
qty: 1
- name: Baseball glove
price: 30
sku: BB-912
qty: 1
summary: Request Example
responses:
'202':
description: '202'
content:
application/json:
schema:
type: object
properties:
id:
type: string
examples:
- 842d81e8-c619-457f-bb77-ab6c4a17da39
status:
type: string
examples:
- NotStarted
examples:
Result:
summary: Result
value:
id: 842d81e8-c619-457f-bb77-ab6c4a17da39
status: NotStarted
/v2/contacts/transactional-data/{collectionName}/{key}:
parameters:
- in: header
name: x-ddg-integration-token
required: false
description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.
schema:
type: string
pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
post:
summary: Replace transactional data by key
deprecated: true
description: Replaces a piece of transactional/insight data by key
operationId: replace-transactional-data-by-key
tags:
- Insight and transactional data
parameters:
- name: collectionName
in: path
description: The name of the transactional data collection
required: true
example: ''
schema:
type: string
- name: key
in: path
description: The key for the piece of data
required: true
example: ''
schema:
type: string
requestBody:
content:
application/json:
schema:
type: object
required:
- json
properties:
json:
type: string
description: The data to be stored against the contact, as an escaped JSON string
examples:
Request Example:
value:
key: P00000001
contactIdentifier: '986710407'
json: '{
"PurchaseDate": "2012-11-19T10:01:21Z",
"TotalExTax": 111.2000000000,
"TotalIncTax": 133.4400000000,
"Product": [
{
"Name": "Long unlined leather gloves",
"Brand": "Dents",
"Department": "Womenswear",
"Category": "Gloves",
"PriceExTax": 111.2000000000,
"ProductID": "24920"
}
],
"SalesChannel": "Online",
"SalesSubChannel": "myshop.com"
}'
summary: Request Example
responses:
'200':
description: '200'
content:
application/json:
schema:
type: object
properties:
key:
type: string
examples:
- P00000001
contactIdentifier:
type: string
examples:
- '23'
json:
type: string
examples:
- '{
"PurchaseDate": "2012-11-19T10:01:21Z",
"TotalExTax": 111.2000000000,
"TotalIncTax": 133.4400000000,
"Product": [
{
"Name": "Long unlined leather gloves",
"Brand": "Dents",
"Department": "Womenswear",
"Category": "Gloves",
"PriceExTax": 111.2000000000,
"ProductID": "24920"
}
],
"SalesChannel": "In store",
"SalesSubChannel": "London - One New Change"
}'
examples:
Result:
summary: Result
value:
key: P00000001
contactIdentifier: '23'
json: '{
"PurchaseDate": "2012-11-19T10:01:21Z",
"TotalExTax": 111.2000000000,
"TotalIncTax": 133.4400000000,
"Product": [
{
"Name": "Long unlined leather gloves",
"Brand": "Dents",
"Department": "Womenswear",
"Category": "Gloves",
"PriceExTax": 111.2000000000,
"ProductID": "24920"
}
],
"SalesChannel": "In store",
"SalesSubChannel": "London - One New Change"
}'
get:
summary: Get transactional data by key
deprecated: true
description: Gets a piece of transactional/insight data by key
operationId: get-transactional-data-by-key
tags:
- Insight and transactional data
parameters:
- name: key
in: path
description: The key for the piece of transactional data
required: true
example: ''
schema:
type: string
- name: collectionName
in: path
description: The name of the transactional data collection
required: true
example: ''
schema:
type: string
responses:
'200':
description: '200'
content:
application/json:
schema:
type: object
properties:
key:
type: string
examples:
- P00000110
contactIdentifier:
type: string
examples:
- '23'
json:
type: string
examples:
- '{
"PurchaseDate": "2020-01-01T09:40:18.527Z",
"TotalExTax": 111.2000000000,
"TotalIncTax": 133.4400000000,
"Product": [
{
"Name": "Long unlined leather gloves",
"Brand": "Dents",
"Department": "Womenswear",
"Category": "Gloves",
"PriceExTax": 111.2000000000,
"ProductID": "24920"
}
],
"SalesChannel": "In store",
"SalesSubChannel": "London - One New Change"
}'
examples:
Result:
summary: Result
value:
key: P00000110
contactIdentifier: '23'
json: '{
"PurchaseDate": "2020-01-01T09:40:18.527Z",
"TotalExTax": 111.2000000000,
"TotalIncTax": 133.4400000000,
"Product": [
{
"Name": "Long unlined leather gloves",
"Brand": "Dents",
"Department": "Womenswear",
"Category": "Gloves",
"PriceExTax": 111.2000000000,
"ProductID": "24920"
}
],
"SalesChannel": "In store",
"SalesSubChannel": "London - One New Change"
}'
delete:
summary: Delete transactional data by key
deprecated: true
description: Deletes a piece of transactional/insight data by key
operationId: delete-transactional-data-by-key
tags:
- Insight and transactional data
parameters:
- name: collectionName
in: path
description: The name of the transactional data collection
required: true
example: ''
schema:
type: string
- name: key
in: path
description: The key for the piece of transactional data
required: true
example: ''
schema:
type: string
responses:
'204':
description: '204'
content:
application/json:
schema:
type: object
properties: {}
examples:
Result:
summary: Result
value: {}
/v2/contacts/transactional-data/import/{id}:
parameters:
- in: header
name: x-ddg-integration-token
required: false
description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.
schema:
type: string
pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
get:
summary: Get transactional data import status
deprecated: true
description: Gets the import status of a previously started transactional/insight data import
operationId: get-transactional-data-import-status
tags:
- Insight and transactional data
parameters:
- name: id
in: path
description: The import ID (GUID) of the transactional data import
required: true
example: ''
schema:
type: string
responses:
'200':
description: '200'
content:
application/json:
schema:
type: object
properties:
id:
type: string
examples:
- 842d81e8-c619-457f-bb77-ab6c4a17da39
status:
type: string
examples:
- Finished
examples:
Result:
summary: Result
value:
id: 842d81e8-c619-457f-bb77-ab6c4a17da39
status: Finished
/v2/contacts/transactional-data/import/{id}/report:
parameters:
- in: header
name: x-ddg-integration-token
required: false
description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.
schema:
type: string
pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
get:
summary: Get transactional data import report
deprecated: true
description: Gets a report with statistics about what transactional/insight data was successfully imported, and what was unable to be imported
operationId: get-transactional-data-import-report
tags:
- Insight and transactional data
parameters:
- name: id
in: path
description: The import ID (GUID) of the transactional data import
required: true
example: ''
schema:
type: string
responses:
'200':
description: '200'
content:
application/json:
schema:
type: object
properties: {}
examples:
Result:
summary: Result
value: '{
"totalItems": 6,
"totalImported": 5,
"totalRejected": 1,
"faults": [
"key": "1234AB",
"reason": "InvalidJson"
]
}'
/v2/contacts/{selector}/transactional-data/{collectionName}:
parameters:
- name: selector
in: path
description: The email address or contact ID of the contact.
required: true
example: contact1@emailsim.io
schema:
oneOf:
- type: string
description: Email address
format: email
- type: string
description: Contact ID
format: regex
pattern: '[0-9]+'
- name: collectionName
in: path
description: The name of the transactional data collection
required: true
example: orders
schema:
type: string
get:
summary: Get transactional data collection for contact by email
deprecated: true
description: Gets a list of up to 100 pieces of transactional data records for a contact in a collection by their email address, sorted by the transactional record key.
operationId: get-transactional-data-collection-for-contact-by-email
tags:
- Insight and transactional data
responses:
'200':
description: '200'
content:
application/json:
schema:
type: array
items:
type: object
properties:
key:
type: string
examples:
- P00000113
contactIdentifier:
type: string
examples:
- '23'
json:
type: string
examples:
- '{
"PurchaseDate": "2020-01-01T09:40:18.527Z",
"TotalExTax": 92.0000000000,
"TotalIncTax": 110.4000000000,
"Product": [
{
"Name": "Cashmere cable-knit beanie",
"Brand": "Paul Smith",
"Department": "Menswear",
"Category": "Hat",
"PriceExTax": 88.0000000000,
"ProductID": "24937"
},
{
"Name": "Armani Jeans beanie hat",
"Brand": "Armani Jeans",
"Department": "Menswear",
"Category": "Hat",
"PriceExTax": 56.0000000000,
"ProductID": "24938"
}
],
"SalesChannel": "Online",
"SalesSubChannel": "myshop.com"
}'
examples:
Result:
summary: Result
value:
- key: P00000113
contactIdentifier: '23'
json: '{
"PurchaseDate": "2020-01-01T09:40:18.527Z",
"TotalExTax": 92.0000000000,
"TotalIncTax": 110.4000000000,
"Product": [
{
"Name": "Cashmere cable-knit beanie",
"Brand": "Paul Smith",
"Department": "Menswear",
"Category": "Hat",
"PriceExTax": 88.0000000000,
"ProductID": "24937"
},
{
"Name": "Armani Jeans beanie hat",
"Brand": "Armani Jeans",
"Department": "Menswear",
"Category": "Hat",
"PriceExTax": 56.0000000000,
"ProductID": "24938"
}
],
"SalesChannel": "Online",
"SalesSubChannel": "myshop.com"
}'
- key: P00000114
contactIdentifier: '23'
json: '{
"PurchaseDate": "2020-01-01T09:40:18.527Z",
"TotalExTax": 56.0000000000,
"TotalIncTax": 67.2000000000,
"Product": [
{
"Name": "Armani Jeans beanie hat",
"Brand": "Armani Jeans",
"Department": "Menswear",
"Category": "Hat",
"PriceExTax": 56.0000000000,
"ProductID": "24938"
}
],
"SalesChannel": "In store",
"SalesSubChannel": "Manchester"
}'
delete:
summary: Delete transactional data collection for contact
deprecated: true
description: Deletes all transactional/insight data for a contact in a collection identified by either their email or contact ID.
operationId: delete-transactional-data-collection-for-contact
tags:
- Insight and transactional data
responses:
'204':
description: '204'
content:
application/json:
schema:
type: object
properties: {}
examples:
Result:
summary: Result
value: {}
/v2/transactional-data/{collectionName}:
parameters:
- in: header
name: x-ddg-integration-token
required: false
description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.
schema:
type: string
pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
get:
summary: Get account scoped transactional data
deprecated: true
description: Gets transactional/insight data in a collection at account level
operationId: get-account-scoped-transactional-data
tags:
- Insight and transactional data
parameters:
- name: collectionName
in: path
description: The name of the transactional data collection
required: true
example: ''
schema:
type: string
- name: select
in: query
description: The number of records to select between 1 and 100
required: false
schema:
type: integer
format: int32
- name: skip
in: query
description: The numbers of records to skip in the result set
required: false
schema:
type: integer
format: int32
responses:
'200':
description: '200'
content:
application/json:
schema:
type: array
items:
type: object
properties:
key:
type: string
examples:
- Resort001
contactIdentifier:
type: string
examples:
- '-1'
json:
type: string
examples:
- '{
"Name": "Playa del Fun",
"Country": "Spain",
"Stars": 3.0000000000,
"Category": "Family beach",
"Image": "https://www.123holidays.com/resorts/1/9/7/9/3/1/files/imagecache/63595/w20_124720_beachresort1.jpg",
"Short_desc": "Close to three water parks and the best beach around, this resort is a favourite with families.",
"From_price": 412.0000000000,
"Link": "https://www.123holidays.com/resorts/playa_del_fun"
}'
examples:
Result:
summary: Result
value:
- key: Resort001
contactIdentifier: '-1'
json: '{
"Name": "Playa del Fun",
"Country": "Spain",
"Stars": 3.0000000000,
"Category": "Family beach",
"Image": "https://www.123holidays.com/resorts/1/9/7/9/3/1/files/imagecache/63595/w20_124720_beachresort1.jpg",
"Short_desc": "Close to three water parks and the best beach around, this resort is a favourite with families.",
"From_price": 412.0000000000,
"Link": "https://www.123holidays.com/resorts/playa_del_fun"
}'
/v2/contacts/transactional-data-collections:
parameters:
- in: header
name: x-ddg-integration-token
required: false
description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.
schema:
type: string
pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
get:
summary: Get transactional data collections
deprecated: true
description: Gets transactional/insight data collections at account and contact level
operationId: get-contact-scoped-transactional-data-collections
tags:
- Insight and transactional data
parameters:
- name: select
in: query
description: The number of records to select between 1 and 1000
required: false
schema:
type: integer
format: int32
- name: skip
in: query
description: The numbers of records to skip in the result set
required: false
schema:
type: integer
format: int32
responses:
'200':
description: '200'
content:
application/json:
schema:
type: object
properties: {}
examples:
Result:
summary: Result
value: '[
{
"Id": "1",
"Name": "Catalog",
},
{
"Id": "2",
"Name": "Orders",
},
{
"Id": "3",
"Name": "Product
# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dotdigital/refs/heads/main/openapi/dotdigital-insight-and-transactional-data-api-openapi.yml