CDPGuidesSupport

Query Visitors

Find visitors with matching events and search current profiles through the Ours Privacy Platform API.

Use Query Visitors to find visitor IDs with matching events in an inclusive date range. Add event filters, first- or last-touch UTM filters, and profile search results to narrow the list. JSON-encode the input object in the query string, then continue with pagination.nextCursor while hasMore is true.

The list includes matching-event counts and current profile fields the caller may view. Profile search returns visitor IDs to pass into the list input and requires visitor-profile access.

GET/rest/v1/query-visitors

GET
/rest/v1/query-visitors
AuthorizationBearer <token>

Ours Privacy API key

In: header

Query Parameters

input*string

Query Visitors filters and page. JSON-encode input in the REST query string.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/rest/v1/query-visitors?input=%7B%22version%22%3A1%2C%22from%22%3A%222026-11-01%22%2C%22to%22%3A%222026-11-17%22%2C%22include%22%3A%5B%7B%22eventNames%22%3A%5B%22Purchase%22%5D%7D%5D%2C%22match%22%3A%22ANY%22%7D"
{  "rows": [    {      "visitorId": "string",      "match": {        "eventCount": 0,        "firstEventAt": "2019-08-24T14:15:22Z",        "lastEventAt": "2019-08-24T14:15:22Z"      },      "profile": {        "status": "FOUND",        "email": "string",        "firstName": "string",        "lastName": "string",        "externalId": "string",        "firstSeenAt": "2019-08-24T14:15:22Z",        "lastSeenAt": "2019-08-24T14:15:22Z"      }    }  ],  "matchedCount": 0,  "pagination": {    "hasMore": true,    "nextCursor": "string"  },  "freshness": {    "coverageWatermark": "2019-08-24T14:15:22Z",    "coverageStatus": "UNKNOWN",    "syncCursor": "2019-08-24T14:15:22Z",    "syncCompletedAt": "2019-08-24T14:15:22Z"  }}

GET/rest/v1/query-visitors/capabilities

GET
/rest/v1/query-visitors/capabilities
AuthorizationBearer <token>

Ours Privacy API key

In: header

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/rest/v1/query-visitors/capabilities"
{  "version": 1,  "defaultPageSize": 25,  "maxPageSize": 100,  "maxDateRangeDays": 31,  "maxSelections": 10,  "touchEnabled": true,  "touchLookbackDays": [    0  ],  "defaultTouchLookbackDays": 0,  "supportsVerifiedCoverageWatermark": true}
GET
/rest/v1/query-visitors/profile-search
AuthorizationBearer <token>

Ours Privacy API key

In: header

Query Parameters

input*string

Current profile search filters. JSON-encode input in the REST query string.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/rest/v1/query-visitors/profile-search?input=%7B%22search%22%3A%22example-visitor%22%2C%22from%22%3A%222026-11-01%22%2C%22to%22%3A%222026-11-17%22%2C%22limit%22%3A8%7D"
{  "matches": [    {      "visitorId": "string",      "email": "string",      "firstName": "string",      "lastName": "string",      "externalId": "string",      "lastSeenAt": "2019-08-24T14:15:22Z"    }  ],  "visitorIds": [    "string"  ],  "truncated": true}

Next Steps

How is this guide?