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
Ours Privacy API key
In: header
Query Parameters
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
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
Ours Privacy API key
In: header
Query Parameters
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?

