Data Dictionary

This is a reference to help you interpret the data contained in the results returned from your api requests.

Visits - standard

• Endpoint: https://results-api.hgem.com/visits/standard

  • Response data:

    Field Name	Data type	Nullable	Definition
    visitId	Integer	-	HGEM's unique identifier for the visit
    clientId	Integer	-	HGEM's Client Identifier (the same as the hgemClientId query parameter)
    clientName	String	-	HGEM's name for the HGEM Client
    brandName	String	Y	HGEM's name for the Client's brand (may be the same as the clientName)
    branchId	Integer	-	HGEM's Branch Identifier
    branchCode	String	Y	HGEM's Client's identifier for the branch (usually supplied by the HGEM Client)
    branchName	String	-	HGEM's name for the branch
    visitType	String	-	The type of visit (see VisitTypes for further definition)
    visitScore	Integer	-	The overall score, as a percentage, for this one visit
    recommendScore	Integer	Y	The score against the single question that contributes towards Net Promoter Score (NPS)
    recommendComment	String	Y	The comment made when answering the question that contributes towards Net Promoter Score (NPS)
    visitDateTime	ISO date/time	-	The date and time the visit took place
    modificationDate	ISO date/time	-	The date and time the visit was last modified
    visitSource	String	Y	The source of the visit. Value is dependent on the visit type
    sections	Array[Section]	_	The sections from the visit questionnaire. (see Sections for further definition)

Visits - plus

• Endpoint: https://results-api.hgem.com/visits/plus

  • Returns all of the fields from the standard endpoint, plus the following fields...

    Field Name	Data type	Nullable	Notes
    guestId	String	Y	Only for OF visit type, where guestId was supplied on survey URL
    optIns	Class	-	See optIns.[PropertyName] below
    optIns.contactByEmail	Boolean	Y	Respondant/assessor has opted in to being contacted by email for communication exclusively relating to this single visit/feedback
    optIns.joinMarketing	Boolean	Y	Respondant/assessor has opted in to being included in marketing email lists managed by, or on behalf of, the HGEM client

  • Plus, the following fields will be returned and may be populated if consent has been granted (see notes below)...

    Field Name	Data type	Nullable	Notes
    email	String	Y
    firstName	String	Y
    surname	String	Y
    age	String	Y	(1)(3)
    birthday	String	Y	(2)
    gender	String	Y	(1)

    • Notes:
      1. Format depends on how the survey question was set up - contact HGEM to clarify for a particular HGEM client.
      2. Format is MMMM DD, e.g: 'October 31'. This is NOT DoB (Date of Birth).
      3. Where the value returned has a value other than null, this is usually an age range, e.g '20 > 30', not the respondant's actual age.

      NB: For these fields, where the value returned is null, either:

      • the data was not captured, or
      • the data has been witheld due to the state of the two opt-in flags, at least one of which must be true for the data to be returned.
      
      

    • Examples of extra fields returned in the JSON for a visit:

      • When consenting:

            "guestId": "ABC1234567",
            "firstName": "Fred",
            "surname": "Bloggs",
            "email": "fred.bloggs@example.com",
            "age": "20 > 30",
            "birthday": "October 31",
            "gender": null,
            "optIns": {
                "contactByEmail": true,
                "joinMarketing": false
            }
        

      • When NOT consenting:

            "guestId": null,
            "firstName": null,
            "surname": null,
            "email": null,
            "age": null,
            "birthday": null,
            "gender": null,
            "optIns": {
                "contactByEmail": false,
                "joinMarketing": false
            }
        

      • When consent data has not been captured:

            "guestId": null,
            "firstName": null,
            "surname": null,
            "email": null,
            "age": null,
            "birthday": null,
            "gender": null,
            "optIns": {
                "contactByEmail": null,
                "joinMarketing": null
            }