Skip to Content

TwentyThree

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:

{
    // Merge ID for data, combining site id, email address and object id
    "eventIdentifier":"56718447,peter@ranguinc.com,96672232",
    // Time of the triggering event
    "eventTime":"2024-04-18T06:14:07.896Z",

    // Contact details
    "contact":{
        "uuid":"2b942528-472b-8a38-86a2-9a204f4aadcf",
        "email":"peter@ranguinc.com",
        "firstName":"Peter",
        "lastName":"Cooper",
        ...
    },
    // Information about the video or webinar
    "video":{
        "identifier":"96672232",
        "objectType":"live",
        "title":"How Rangu can help you build more sustainable cities",
        ...
    },

    // Attendance or viewing details about the video or webinar
    "attendance":{
        ...
    },
    // Engagement with the video or webinar
    "engagement":{
        // Handouts downloaded
        "handouts":[
            ...
        ],
        // Chat messages
        "chatMessages":[
            ...
        ],
        // Questions
        "questions":[
            ...
        ],
        // Poll answers
        "polls":[
            ...
        ]
    }
}

Example payload: Webinar registration

{
    "eventIdentifier":"56718447,peter@ranguinc.com,96672232",
    "eventTime":"2024-04-18T06:14:07.896Z",
    "contact":{
        "uuid":"2b942528-472b-8a38-86a2-9a204f4aadcf",
        "email":"peter@ranguinc.com",
        "firstName":"Peter",
        "lastName":"Cooper",
        "company":"Rangu Inc",
        "phone":"",
        "jobTitle":"",
        "country":"",
        "countryCode":"DK",
        "data_optin":"",
        "marketing_optin":1,
        "totalSessions":1,
        "totalVideosPlayed":0,
        "engagementScore":22,
        "recentActivityDate":"2024-04-18T06:14:07.896Z",
        "industry":"",
        "job_title":"",
        "primary_interest_in_drones":""
    },
    "video":{
        "identifier":"96672232",
        "title":"How Rangu can help you build more sustainable cities",
        "category":"Webinars",
        "tags":"live:96672232",
        "link":"https://video.ranguinc.com/live/96672232",
        "joinLink":"https://video.ranguinc.com/jump/payload?url=https%3A%2F%2Fvideo.ranguinc.com%2Flive%2F96672232%2Froom&payload=ezZ7hIYbqKLltrITo7Rf4g9Vz198qkVgJQlz",
        "roomLink":"https://video.ranguinc.com/live/96672232/room",
        "duration":"",
        "status":"upcoming",
        "objectType":"live"
    },
    "attendance":{
        "registrationTime":"2024-04-18T06:14:07.789",
        "watchedSeconds":null,
        "viewedTime":null,
        "watchedLiveOrOndemand":null,
        "engagementRate":null
    },
    "engagement":{
         "handouts":[],
         "chatMessages":[],
         "questions":[],
         "polls":[]
     }
}

Example: Webinar attendance

{
  "eventIdentifier": "56718447,ana@ranguinc.com,61442398",
  "eventTime": "2021-05-19T08:29:05.080Z",
  "contact": {
    "uuid": "b93a831d-c0a6-8a9f-b8d2-842bf003a7f3",
    "email": "ana@ranguinc.com",
    "firstName": "Ana",
    "lastName": "Navi",
    "company": "TwentyThree",
    "phone": "",
    "jobTitle": "",
    "country": "Denmark",
    "countryCode": "DK",
    "data_optin": 1,
    "marketing_optin": "",
    "totalSessions": 30,
    "totalVideosPlayed": 35,
    "engagementScore": 92,
    "recentActivityDate": "2021-05-19T08:29:05.080Z",
    "industry": "",
    "job_title": "",
    "primary_interest_in_drones": "Surveillance"
  },
  "video": {
    "identifier": "61442398",
    "title": "Measuring Heat Loss in the building phase",
    "category": "Webinars",
    "tags": "live:61442398",
    "link": "https://video.ranguinc.com/live/61442398",
    "joinLink": "https://video.ranguinc.com/jump/payload?url=https%3A%2F%2Fvideo.ranguinc.com%2Flive%2F61442398%2Froom&payload=ICLRY%2B0K9k6FYLOgYmFQNU9OMMLULZiTo",
    "roomLink": "https://video.ranguinc.com/live/61442398/room",
    "duration": 815,
    "status": "previous",
    "objectType": "live"
  },
  "attendance": {
    "registrationTime": "2020-12-01T15:09:51.388761",
    "watchedSeconds": 720,
    "viewedTime": "2020-03-18T12:02:35",
    "watchedLiveOrOndemand": "live",
    "engagementRate": 0.8834355828220859
  },
  "engagement": {
    "handouts": [
      {
        "filename": "2020 Drone Specs.pdf",
        "time": "2020-08-21T07:12:44.999571"
      }
    ],
    "chatMessages": [
      {
        "message": "No lags.",
        "time": "2020-03-18T12:10:53.883628"
      },
      {
        "message": "It's not actually.",
        "time": "2020-03-18T12:10:42.257434"
      },
      {
        "message": "or are we dancer?",
        "time": "2020-03-18T12:10:10.403433"
      },
      {
        "message": "YAY!",
        "time": "2020-03-18T12:06:02.380561"
      },
      {
        "message": "Can I get a mention too?",
        "time": "2020-03-18T12:05:36.335794"
      },
      {
        "message": "This is a very interesting webinar.",
        "time": "2020-03-18T12:04:27.111328"
      }
    ],
    "questions": [
      {
        "question": "Are you aliens?",
        "time": "2020-03-18T12:03:06.842034"
      }
    ],
    "polls": [
      {
        "question": "How would you rate the information in this webinar?",
        "answer": "5 - Excellent",
        "time": "2020-03-18T12:11:43.376333"
      },
      {
        "question": "Does your 2021 monitoring strategy include drones?",
        "answer": "No",
        "time": "2020-03-18T12:02:22.360533"
      }
    ]
  }
}

Example: Video view

{
  "eventIdentifier": "56718447,peter@ranguinc.com,8456758",
  "eventTime": "2024-04-18T14:26:16.000Z",
  "contact": {
    "uuid": "2b942528-472b-8a38-86a2-9a204f4aadcf",
    "email": "peter@ranguinc.com",
    "firstName": "Peter",
    "lastName": "Cooper",
    "company": "Rangu Inc",
    "phone": "",
    "jobTitle": "",
    "country": "",
    "countryCode": "DK",
    "data_optin": "",
    "marketing_optin": 1,
    "totalSessions": 1,
    "totalVideosPlayed": 6,
    "engagementScore": 89,
    "recentActivityDate": "2024-04-18T14:26:16.000Z",
    "industry": "",
    "job_title": "",
    "primary_interest_in_drones": ""
  },
  "video": {
    "identifier": "8456758",
    "title": "This is a demo video",
    "category": "Demo Category",
    "tags": "videotag",
    "link": "https://preview.ranguinc.com/video/8456758",
    "joinLink": null,
    "roomLink": null,
    "duration": 134.933,
    "status": "",
    "objectType": "video"
  },
  "attendance": {
    "registrationTime": "2024-04-18T14:25:48",
    "watchedSeconds": 41,
    "viewedTime": "2024-04-18T14:25:48",
    "watchedLiveOrOndemand": "ondemand",
    "engagementRate": 0.3038545055694308
  },
  "engagement": {
    "handouts": [],
    "chatMessages": [],
    "questions": [],
    "polls": []
  }
}