Visitor List

Visitor list is a set of informations focused on each individual person detected by face recognition. The return ofthis POST method is a visitor list as an array of information. Those infos being:

• Session ID hash - "session_id" is an alphanumerical value associated with this session;
• Visitor ID hash - "visitor_id" is the main individualized alphanumerical identifier value associated to the face detected;
• Visit start Time - "start" is a date and time value YYYY-MM-DDThh:mm:ssZ, to determine visit duration;
• Visit end Time - "end" is a date and time value YYYY-MM-DDThh:mm:ssZ, to determine visit duration;
• Amount of contacts - "tracks_acount" is a numerical value refering to amount of times specific visitor was detected among devices in this session;
• Total contact duration - "tracks_duration" is a numerical value in seconds, referring to total amount of time customer was actively being detected by camera;
• Estimated age of visitor - "age" is a numerical value in years associated to visitor estimated age;
• Deviation margin of visitor estimated age - "age_deviation" is numerical value in years, referring to +/- years margin of error, associates with calculated image quality in %;
• Visitor gender - "sex" is a numerical value associate to gender: 1 for men, 2 for women;
• Devices IDs which detected and recognized this customer - numerical value associated with device ID a the platform, p.eg. "https://mycompany.displayforce.ai/n/#/devs?devId=13106";
• Campaign played during visitor contact - numerical value associated with campaigns played at device during visitor's contacts, p.eg; "https://mycompany.displayforce.ai/n/#/campaigns/47781" 

Extracted information of one individual customer looks like this:

        {
	    "session_id": "d180shetvh5dffdd3r5g",
			"visitor_id": "d17bpgog6m8s6r87fe0g",
			"start": "2025-06-15T09:13:09Z",
			"end": "2025-06-15T09:13:14Z",
			"tracks_count": 1,
			"tracks_duration": 5,
			"age": 68,
			"age_deviation": 4,
			"sex": 1,
			"devices": [
				12897
			],
			"campaigns": []
		},

How to set up API for collecting Visitor List

1. POST command for link https://api.displayforce.ai/public/v1/stats/visitor/list
   
2. Header X-API-Token (alphanumerical value in XXXX-XXXX-XXXX-XXXX format, below partially hidden for privacy reasons), value being the API token acquired from your CMS platform. 
   WARNING: do not disclose your API token with untrusted third-parties.
   

3. Body in JSON format, containing the period of time of desired information. in the following format:

   {
     "start": "YYYY-MM-DDThh:mm:ssZ",   //start date and time, later date
     "end": "YYYY-MM-DDThh:mm:ssZ"
         //end date and time, more recent date
   }

   
   Parameters "start" and "end" are mandatory body parameters.There are others that are optional, such as "glasses", "device", "campaign", etc. Filtering by campaigns and devices is possible.
   Paginated data output mechanism: A maximum of 1.000 visitors can be returned in a single response.
   For detailed information on request parameters, see Schema, at the API help file.