Skip to Content

TwentyThree™ API

API Method: /api/audience/list

List viewer profiles including timeline activities and conversion events.

Parameters

ParameterDescription
uuidSearch for a specific profile by the automatically assigned uuid.
userSearch for a specific profile by the user id on the TwentyThree platform
objectSearch for profiled that have viewed a specific object.
objectsSearch for profiled that have viewed one or interacted with one of a set of objects, separated by space.
identity_objectsSearch for profiled that converted through one of a set of objects, separated by space.
identifiedLimit to either identified or non-identified profiles.
identity_sourcesFilter by the source for the profile information, for example 'collector:123' or 'hubspot'.
searchFree text search for profiles.
include_timelines_pInclude viewing timelines on the result.
include_events_pInclude conversion events in the result.
orderbyOrdering of the returned items. Valid options are: recent, timeline_count, score, first.
orderOrdering of the returned items. Valid options are: asc, desc.
offsetOffset / page through the returned profiles. Ideally used together with size
sizeSets the number of profiles returned. Max value is 500

In addition the these search option, a number of filters can be applied to the search. Each filter should be prefixed with < for less than; > for greater than or = for exactly the value. For example, to search for profiles most recently seen within the last 60 minutes, search for use recent=<60.

ParameterDescription
firstWhen was the viewer first seen, filterable by minutes.
recentWhen was the viewer most recently seen, filterable by minutes.
timeline_countHow many videos or live events have been watched.
timeline_sessionsHow many visits with videos watched?
timeline_engagementHow many minutes of video engagement?
event_countHow many conversion events?
scoreEngagement score between 0 and 100.

Permission level

The minimum required permission level is:

<pre><code>read</code></pre>

Example JSON Response

{  "status": "ok",  "permission_level": "read",  "cached": "0",  "profiles": [    {      "uuid": "471cde15-53b6-05ea-ad32-f33e7d62d63a",      "identifier": 209355,      "user": "13697403",      "email": "sarah@twentythree.net",      "ip": "24.242.88.191",      "profile": {        "city": "Palo Alto",        "logo": "https://logo.clearbit.com/twentythree.net",        "name": "Sarah Bay",        "site": "http://twentythree.net",        "tags": [          "SAAS",          "B2B",          "Marketing & Advertising",          "Corporate & Business"        ],        "type": "live",        "force": "true",        "company": "TwentyThree",        "country": "United States",        "twitter": "Sassy_Bay",        "callback": "__audcb_1",        "facebook": "twentythree",        "lastname": "Bay",        "latitude": 37.4135,        "username": "sarah",        "firstname": "Sarah",        "longitude": -122.1312,        "formid__sb": "52ebc19c-ccf6-423f-89e2-928154476d44",        "hubspotutk": "54614d089677f1d6e361db0fcdf12f01",        "marketotrk": "id:288-VFC-510&token:_mch-twentythree.net-1481134994764-58835",        "postalCode": "94306",        "regionName": "California",        "submit__sb": "",        "companyInfo": "TwentyThree™ is a video marketing platform that empowers marketing mangers on every step of their marketing funnel.",        "companySite": "http://twentythree.net",        "companyType": "private",        "countryCode": "US",        "country_iso": "US",        "companyDomain": "unity3d.com",        "companySector": "Information Technology",        "continentCode": "NA",        "companyFacebook": "unity3d",        "companyIndustry": "Internet Software & Services",        "companyLinkedin": "company/unity-technologies",        "companyLocation": "795 Folsom St, San Francisco, CA 94103, USA",        "companyTimeZone": "America/Los_Angeles",        "identity_source": "sharpspring",        "companyEmployees": 975,        "companyDescription": "Unity is the ultimate game development platform. Use Unity to build high-quality 3D and 2D games, deploy them across mobile, desktop, VR/AR, consoles or the Web, and connect with loyal and enthusiastic players and customers.",        "companySubIndustry": "Internet Software & Services",        "identity_collector": "14561518",        "companyIndustryGroup": "Software & Services",        "companyprofileid__sb": "MzYwNzQ1sDA1BAA",        "companyEmployeesRange": "251-1000"      },      "identified": true,      "identity_sources": "sharpspring,sharpspring:14561518",      "timeline_count": 210,      "timeline_engagement": 25425,      "timeline_sessions": 72,      "score": 110,      "event_updated": "2016-12-09T16:55:33.200Z",      "event_count": 1,      "source_first": "embed",      "referer_first": "https://www.twentythree.net/",      "source_recent": "site",      "referer_recent": "https://www.twentythree.net/",      "first": "2017-03-14T16:35:47.256Z",      "recent": "2017-03-14T16:45:15.035Z",      "timelines": [        {          "object": "16234013",          "ranges": "1111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111",          "engagement": 573,          "duration": 573,          "type": "ondemand",          "playhead": 573,          "active": true,          "source": "site",          "referer": "",          "first": "2017-03-14T16:35:46",          "updated": "2017-03-14T16:35:47.256225"        },        {          "object": "16195594",          "ranges": "0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",          "engagement": 0,          "duration": 1166,          "type": "ondemand",          "playhead": 0,          "active": true,          "source": "site",          "referer": "",          "first": "2017-03-11T16:32:28",          "updated": "2017-03-11T16:32:29.008182"        },        ....        ]    },    ...  ],  "site": { ...}  "endpoint": "/api/people/list"}

Example XML Response

This endpoint does not support XML responses.