Receiving API data with JSON Data Pushes
JSON Data Pushes are designed to proactively push audience data for videos and webinars to a customer-controlled endpoint. This makes for a simple data integration point if you're aiming to ensure that contacts and activity data from the TwentyThree product are captured on other systems, such as your marketing automation platform, CRM, or data lake.
It is possible to query the standard API to pull this same data, and the API also supports webhooks for additional data push use cases. However, JSON Data Pushes provide a "pre-chewed," comprehensive, and standardised payload that covers most use cases around syncing contact and activity data from TwentyThree to other data platforms in the stack.
These pushes:
- Are sent to configurable endpoints.
- Endpoints can be secured using OAuth 2 signatures.
- Come in a standardized JSON payload documented below.
- Are sent every time there is an update for a contact related to an object, such as a video or a webinar.
- Are debounced and may arrive within 4 hours of the originating event to avoid race conditions.
- Are only sent for identified contacts.
JSON Data Pushes include:
- Contact details such as email address, name, location, and opt-in status, along with any custom collector fields configured on the platform.
- Total engagement details such as the number of videos watched, time spent on the platform, and video engagement score.
- Detailed information about the video or webinar the push is related to, including type, title, duration, category, timing, and links.
- Detailed viewing and attendance information about the video or webinar the push is related to, such as the total seconds watched and whether the view was live or on-demand.
- Engagement data such as poll responses, handouts downloaded, chat messages, and questions.
Configure JSON Data Pushes
To configure your JSON Data Pushes, go to Video Attribution → Connect → JSON Data Pushes. Here you can configure the HTTP endpoint that should receive data updates.
Using the configuration option, you will also be able to control whether payloads come as POST or PUT bodies, and you can set up OAuth 2 credentials if you need to secure your intake endpoint.
Shape of payloads
All pushes take the same payload shape, while the information contained will vary between objects and states. Payloads are structured like this:
{
<span class="hljs-comment">// Merge ID for data, combining site id, email address and object id</span>
<span class="hljs-string">"eventIdentifier"</span>:<span class="hljs-string">"56718447,peter@ranguinc.com,96672232"</span>,
<span class="hljs-comment">// Time of the triggering event</span>
<span class="hljs-string">"eventTime"</span>:<span class="hljs-string">"2024-04-18T06:14:07.896Z"</span>,
<span class="hljs-comment">// Contact details</span>
<span class="hljs-string">"contact"</span>:{
<span class="hljs-string">"uuid"</span>:<span class="hljs-string">"2b942528-472b-8a38-86a2-9a204f4aadcf"</span>,
<span class="hljs-string">"email"</span>:<span class="hljs-string">"peter@ranguinc.com"</span>,
<span class="hljs-string">"firstName"</span>:<span class="hljs-string">"Peter"</span>,
<span class="hljs-string">"lastName"</span>:<span class="hljs-string">"Cooper"</span>,
...
},
<span class="hljs-comment">// Information about the video or webinar</span>
<span class="hljs-string">"video"</span>:{
<span class="hljs-string">"identifier"</span>:<span class="hljs-string">"96672232"</span>,
<span class="hljs-string">"objectType"</span>:<span class="hljs-string">"live"</span>,
<span class="hljs-string">"title"</span>:<span class="hljs-string">"How Rangu can help you build more sustainable cities"</span>,
...
},
<span class="hljs-comment">// Attendance or viewing details about the video or webinar</span>
<span class="hljs-string">"attendance"</span>:{
...
},
<span class="hljs-comment">// Engagement with the video or webinar</span>
<span class="hljs-string">"engagement"</span>:{
<span class="hljs-comment">// Handouts downloaded</span>
<span class="hljs-string">"handouts"</span>:[
...
],
<span class="hljs-comment">// Chat messages</span>
<span class="hljs-string">"chatMessages"</span>:[
...
],
<span class="hljs-comment">// Questions</span>
<span class="hljs-string">"questions"</span>:[
...
],
<span class="hljs-comment">// Poll answers</span>
<span class="hljs-string">"polls"</span>:[
...
]
}
}
Example payload: Webinar registration
{
<span class="hljs-attr">"eventIdentifier"</span>:<span class="hljs-string">"56718447,peter@ranguinc.com,96672232"</span>,
<span class="hljs-attr">"eventTime"</span>:<span class="hljs-string">"2024-04-18T06:14:07.896Z"</span>,
<span class="hljs-attr">"contact"</span>:{
<span class="hljs-attr">"uuid"</span>:<span class="hljs-string">"2b942528-472b-8a38-86a2-9a204f4aadcf"</span>,
<span class="hljs-attr">"email"</span>:<span class="hljs-string">"peter@ranguinc.com"</span>,
<span class="hljs-attr">"firstName"</span>:<span class="hljs-string">"Peter"</span>,
<span class="hljs-attr">"lastName"</span>:<span class="hljs-string">"Cooper"</span>,
<span class="hljs-attr">"company"</span>:<span class="hljs-string">"Rangu Inc"</span>,
<span class="hljs-attr">"phone"</span>:<span class="hljs-string">""</span>,
<span class="hljs-attr">"jobTitle"</span>:<span class="hljs-string">""</span>,
<span class="hljs-attr">"country"</span>:<span class="hljs-string">""</span>,
<span class="hljs-attr">"countryCode"</span>:<span class="hljs-string">"DK"</span>,
<span class="hljs-attr">"data_optin"</span>:<span class="hljs-string">""</span>,
<span class="hljs-attr">"marketing_optin"</span>:<span class="hljs-number">1</span>,
<span class="hljs-attr">"totalSessions"</span>:<span class="hljs-number">1</span>,
<span class="hljs-attr">"totalVideosPlayed"</span>:<span class="hljs-number">0</span>,
<span class="hljs-attr">"engagementScore"</span>:<span class="hljs-number">22</span>,
<span class="hljs-attr">"recentActivityDate"</span>:<span class="hljs-string">"2024-04-18T06:14:07.896Z"</span>,
<span class="hljs-attr">"industry"</span>:<span class="hljs-string">""</span>,
<span class="hljs-attr">"job_title"</span>:<span class="hljs-string">""</span>,
<span class="hljs-attr">"primary_interest_in_drones"</span>:<span class="hljs-string">""</span>
},
<span class="hljs-attr">"video"</span>:{
<span class="hljs-attr">"identifier"</span>:<span class="hljs-string">"96672232"</span>,
<span class="hljs-attr">"title"</span>:<span class="hljs-string">"How Rangu can help you build more sustainable cities"</span>,
<span class="hljs-attr">"category"</span>:<span class="hljs-string">"Webinars"</span>,
<span class="hljs-attr">"tags"</span>:<span class="hljs-string">"live:96672232"</span>,
<span class="hljs-attr">"link"</span>:<span class="hljs-string">"https://video.ranguinc.com/live/96672232"</span>,
<span class="hljs-attr">"joinLink"</span>:<span class="hljs-string">"https://video.ranguinc.com/jump/payload?url=https%3A%2F%2Fvideo.ranguinc.com%2Flive%2F96672232%2Froom&payload=ezZ7hIYbqKLltrITo7Rf4g9Vz198qkVgJQlz"</span>,
<span class="hljs-attr">"roomLink"</span>:<span class="hljs-string">"https://video.ranguinc.com/live/96672232/room"</span>,
<span class="hljs-attr">"duration"</span>:<span class="hljs-string">""</span>,
<span class="hljs-attr">"status"</span>:<span class="hljs-string">"upcoming"</span>,
<span class="hljs-attr">"objectType"</span>:<span class="hljs-string">"live"</span>
},
<span class="hljs-attr">"attendance"</span>:{
<span class="hljs-attr">"registrationTime"</span>:<span class="hljs-string">"2024-04-18T06:14:07.789"</span>,
<span class="hljs-attr">"watchedSeconds"</span>:<span class="hljs-literal">null</span>,
<span class="hljs-attr">"viewedTime"</span>:<span class="hljs-literal">null</span>,
<span class="hljs-attr">"watchedLiveOrOndemand"</span>:<span class="hljs-literal">null</span>,
<span class="hljs-attr">"engagementRate"</span>:<span class="hljs-literal">null</span>
},
<span class="hljs-attr">"engagement"</span>:{
<span class="hljs-attr">"handouts"</span>:[],
<span class="hljs-attr">"chatMessages"</span>:[],
<span class="hljs-attr">"questions"</span>:[],
<span class="hljs-attr">"polls"</span>:[]
}
}
Example: Webinar attendance
{
<span class="hljs-attr">"eventIdentifier"</span>:<span class="hljs-string">"56718447,ana@ranguinc.com,61442398"</span>,
<span class="hljs-attr">"eventTime"</span>:<span class="hljs-string">"2021-05-19T08:29:05.080Z"</span>,
<span class="hljs-attr">"contact"</span>:{
<span class="hljs-attr">"uuid"</span>:<span class="hljs-string">"b93a831d-c0a6-8a9f-b8d2-842bf003a7f3"</span>,
<span class="hljs-attr">"email"</span>:<span class="hljs-string">"ana@ranguinc.com"</span>,
<span class="hljs-attr">"firstName"</span>:<span class="hljs-string">"Ana"</span>,
<span class="hljs-attr">"lastName"</span>:<span class="hljs-string">"Navi"</span>,
<span class="hljs-attr">"company"</span>:<span class="hljs-string">"TwentyThree"</span>,
<span class="hljs-attr">"phone"</span>:<span class="hljs-string">""</span>,
<span class="hljs-attr">"jobTitle"</span>:<span class="hljs-string">""</span>,
<span class="hljs-attr">"country"</span>:<span class="hljs-string">"Denmark"</span>,
<span class="hljs-attr">"countryCode"</span>:<span class="hljs-string">"DK"</span>,
<span class="hljs-attr">"data_optin"</span>:<span class="hljs-number">1</span>,
<span class="hljs-attr">"marketing_optin"</span>:<span class="hljs-string">""</span>,
<span class="hljs-attr">"totalSessions"</span>:<span class="hljs-number">30</span>,
<span class="hljs-attr">"totalVideosPlayed"</span>:<span class="hljs-number">35</span>,
<span class="hljs-attr">"engagementScore"</span>:<span class="hljs-number">92</span>,
<span class="hljs-attr">"recentActivityDate"</span>:<span class="hljs-string">"2021-05-19T08:29:05.080Z"</span>,
<span class="hljs-attr">"industry"</span>:<span class="hljs-string">""</span>,
<span class="hljs-attr">"job_title"</span>:<span class="hljs-string">""</span>,
<span class="hljs-attr">"primary_interest_in_drones"</span>:<span class="hljs-string">"Surveillance"</span>
},
<span class="hljs-attr">"video"</span>:{
<span class="hljs-attr">"identifier"</span>:<span class="hljs-string">"61442398"</span>,
<span class="hljs-attr">"title"</span>:<span class="hljs-string">"Measuring Heat Loss in the building phase"</span>,
<span class="hljs-attr">"category"</span>:<span class="hljs-string">"Webinars"</span>,
<span class="hljs-attr">"tags"</span>:<span class="hljs-string">"live:61442398"</span>,
<span class="hljs-attr">"link"</span>:<span class="hljs-string">"https://video.ranguinc.com/live/61442398"</span>,
<span class="hljs-attr">"joinLink"</span>:<span class="hljs-string">"https://video.ranguinc.com/jump/payload?url=https%3A%2F%2Fvideo.ranguinc.com%2Flive%2F61442398%2Froom&payload=ICLRY%2B0K9k6FYLOgYmFQNU9OMMLULZiTo"</span>,
<span class="hljs-attr">"roomLink"</span>:<span class="hljs-string">"https://video.ranguinc.com/live/61442398/room"</span>,
<span class="hljs-attr">"duration"</span>:<span class="hljs-number">815</span>,
<span class="hljs-attr">"status"</span>:<span class="hljs-string">"previous"</span>,
<span class="hljs-attr">"objectType"</span>:<span class="hljs-string">"live"</span>
},
<span class="hljs-attr">"attendance"</span>:{
<span class="hljs-attr">"registrationTime"</span>:<span class="hljs-string">"2020-12-01T15:09:51.388761"</span>,
<span class="hljs-attr">"watchedSeconds"</span>:<span class="hljs-number">720</span>,
<span class="hljs-attr">"viewedTime"</span>:<span class="hljs-string">"2020-03-18T12:02:35"</span>,
<span class="hljs-attr">"watchedLiveOrOndemand"</span>:<span class="hljs-string">"live"</span>,
<span class="hljs-attr">"engagementRate"</span>:<span class="hljs-number">0.8834355828220859</span>
},
<span class="hljs-attr">"engagement"</span>:{
<span class="hljs-attr">"handouts"</span>:[
{
<span class="hljs-attr">"filename"</span>:<span class="hljs-string">"2020 Drone Specs.pdf"</span>,
<span class="hljs-attr">"time"</span>:<span class="hljs-string">"2020-08-21T07:12:44.999571"</span>
}
],
<span class="hljs-attr">"chatMessages"</span>:[
{
<span class="hljs-attr">"message"</span>:<span class="hljs-string">"No lags."</span>,
<span class="hljs-attr">"time"</span>:<span class="hljs-string">"2020-03-18T12:10:53.883628"</span>
},
{
<span class="hljs-attr">"message"</span>:<span class="hljs-string">"It's not actually."</span>,
<span class="hljs-attr">"time"</span>:<span class="hljs-string">"2020-03-18T12:10:42.257434"</span>
},
{
<span class="hljs-attr">"message"</span>:<span class="hljs-string">"or are we dancer?"</span>,
<span class="hljs-attr">"time"</span>:<span class="hljs-string">"2020-03-18T12:10:10.403433"</span>
},
{
<span class="hljs-attr">"message"</span>:<span class="hljs-string">"YAY!"</span>,
<span class="hljs-attr">"time"</span>:<span class="hljs-string">"2020-03-18T12:06:02.380561"</span>
},
{
<span class="hljs-attr">"message"</span>:<span class="hljs-string">"Can I get a mention too?"</span>,
<span class="hljs-attr">"time"</span>:<span class="hljs-string">"2020-03-18T12:05:36.335794"</span>
},
{
<span class="hljs-attr">"message"</span>:<span class="hljs-string">"This is a very interesting webinar."</span>,
<span class="hljs-attr">"time"</span>:<span class="hljs-string">"2020-03-18T12:04:27.111328"</span>
}
],
<span class="hljs-attr">"questions"</span>:[
{
<span class="hljs-attr">"question"</span>:<span class="hljs-string">"Are you aliens?"</span>,
<span class="hljs-attr">"time"</span>:<span class="hljs-string">"2020-03-18T12:03:06.842034"</span>
}
],
<span class="hljs-attr">"polls"</span>:[
{
<span class="hljs-attr">"question"</span>:<span class="hljs-string">"How would you rate the information in this webinar?"</span>,
<span class="hljs-attr">"answer"</span>:<span class="hljs-string">"5 - Excellent"</span>,
<span class="hljs-attr">"time"</span>:<span class="hljs-string">"2020-03-18T12:11:43.376333"</span>
},
{
<span class="hljs-attr">"question"</span>:<span class="hljs-string">"Does your 2021 monitoring strategy include drones?"</span>,
<span class="hljs-attr">"answer"</span>:<span class="hljs-string">"No"</span>,
<span class="hljs-attr">"time"</span>:<span class="hljs-string">"2020-03-18T12:02:22.360533"</span>
}
]
}
}
Example: Video view
{
<span class="hljs-attr">"eventIdentifier"</span>:<span class="hljs-string">"56718447,peter@ranguinc.com,8456758"</span>,
<span class="hljs-attr">"eventTime"</span>:<span class="hljs-string">"2024-04-18T14:26:16.000Z"</span>,
<span class="hljs-attr">"contact"</span>:{
<span class="hljs-attr">"uuid"</span>:<span class="hljs-string">"2b942528-472b-8a38-86a2-9a204f4aadcf"</span>,
<span class="hljs-attr">"email"</span>:<span class="hljs-string">"peter@ranguinc.com"</span>,
<span class="hljs-attr">"firstName"</span>:<span class="hljs-string">"Peter"</span>,
<span class="hljs-attr">"lastName"</span>:<span class="hljs-string">"Cooper"</span>,
<span class="hljs-attr">"company"</span>:<span class="hljs-string">"Rangu Inc"</span>,
<span class="hljs-attr">"phone"</span>:<span class="hljs-string">""</span>,
<span class="hljs-attr">"jobTitle"</span>:<span class="hljs-string">""</span>,
<span class="hljs-attr">"country"</span>:<span class="hljs-string">""</span>,
<span class="hljs-attr">"countryCode"</span>:<span class="hljs-string">"DK"</span>,
<span class="hljs-attr">"data_optin"</span>:<span class="hljs-string">""</span>,
<span class="hljs-attr">"marketing_optin"</span>:<span class="hljs-number">1</span>,
<span class="hljs-attr">"totalSessions"</span>:<span class="hljs-number">1</span>,
<span class="hljs-attr">"totalVideosPlayed"</span>:<span class="hljs-number">6</span>,
<span class="hljs-attr">"engagementScore"</span>:<span class="hljs-number">89</span>,
<span class="hljs-attr">"recentActivityDate"</span>:<span class="hljs-string">"2024-04-18T14:26:16.000Z"</span>,
<span class="hljs-attr">"industry"</span>:<span class="hljs-string">""</span>,
<span class="hljs-attr">"job_title"</span>:<span class="hljs-string">""</span>,
<span class="hljs-attr">"primary_interest_in_drones"</span>:<span class="hljs-string">""</span>
},
<span class="hljs-attr">"video"</span>:{
<span class="hljs-attr">"identifier"</span>:<span class="hljs-string">"8456758"</span>,
<span class="hljs-attr">"title"</span>:<span class="hljs-string">"This is a demo video"</span>,
<span class="hljs-attr">"category"</span>:<span class="hljs-string">"Demo Category"</span>,
<span class="hljs-attr">"tags"</span>:<span class="hljs-string">"videotag"</span>,
<span class="hljs-attr">"link"</span>:<span class="hljs-string">"https://preview.ranguinc.com/video/8456758"</span>,
<span class="hljs-attr">"joinLink"</span>:<span class="hljs-literal">null</span>,
<span class="hljs-attr">"roomLink"</span>:<span class="hljs-literal">null</span>,
<span class="hljs-attr">"duration"</span>:<span class="hljs-number">134.933</span>,
<span class="hljs-attr">"status"</span>:<span class="hljs-string">""</span>,
<span class="hljs-attr">"objectType"</span>:<span class="hljs-string">"video"</span>
},
<span class="hljs-attr">"attendance"</span>:{
<span class="hljs-attr">"registrationTime"</span>:<span class="hljs-string">"2024-04-18T14:25:48"</span>,
<span class="hljs-attr">"watchedSeconds"</span>:<span class="hljs-number">41</span>,
<span class="hljs-attr">"viewedTime"</span>:<span class="hljs-string">"2024-04-18T14:25:48"</span>,
<span class="hljs-attr">"watchedLiveOrOndemand"</span>:<span class="hljs-string">"ondemand"</span>,
<span class="hljs-attr">"engagementRate"</span>:<span class="hljs-number">0.3038545055694308</span>
},
<span class="hljs-attr">"engagement"</span>:{
<span class="hljs-attr">"handouts"</span>:[],
<span class="hljs-attr">"chatMessages"</span>:[],
<span class="hljs-attr">"questions"</span>:[],
<span class="hljs-attr">"polls"</span>:[]
}
}