Skip to Content

TwentyThree™ API

API Method: /api/audience/list

List viewer profiles including timeline activities and conversion events.


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.

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:


Example JSON Response

    "status": "ok",
    "permission_level": "read",
    "cached": "0",
    "profiles": [
            "uuid": "471cde15-53b6-05ea-ad32-f33e7d62d63a",
            "identifier": 209355,
            "user": "13697403",
            "email": "",
            "ip": "",
            "profile": {
                "city": "Palo Alto",
                "logo": "",
                "name": "Sarah Bay",
                "site": "",
                "tags": [
                    "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&",
                "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": "",
                "companyType": "private",
                "countryCode": "US",
                "country_iso": "US",
                "companyDomain": "",
                "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": "",
            "source_recent": "site",
            "referer_recent": "",
            "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.