Contacts

Contacts represent the resource associated with mobile users or contacts acquired via Experiences.

Contact object: example

The Contact object may differ depending on the specific API. You can explore the Contact object in the definition of each API endpoint.

{
      "cid":"string",
      "title":"string",
      "firstName":"string",
      "lastName":"string",
      "gender":"string",
      "birthDate":"string",
      "birthDay":"string",
      "age":"string",
      "country":"string",
      "zipCode":"string",
      "created":"string",
      "modified":"string",
      "email":"string",
      "emailVerified":true,
      "phone":"string",
      "phoneVerified":true,
      "signupMethod":"string",
      "externalIdentityId":"string",
      "username":"string",
      "locked":true,
      "organizationCid":"string",
      "locationCid":"string",
      "system":"string",
      "enabled":true,
      "type":"string",
      "locationName":"string",
      "personalId":"string",
      "externalSource":"string",
      "lastLogin":"string",
      "segmentCids":"string",
      "logins":0,
      "policies":[
        {
          "name":"string",
          "accepted":true
        }
      ],
      "segments":[
        {
          "cid":"string",
          "name":"string"
        }
      ],
      "extId":{
        "id":"string",
        "prop1":"string",
        "prop2":"string"
      },
      "metrics":{
        "frequencyMonthlyVisit":0,
        "compassTopLocation":"string",
        "compassTopLocationCount":0,
        "topFrequencyBuckets":"string",
        "lastVisitVenue":"string",
        "prefVisitWDay":"string",
        "lastVisitDateUtc":"string",
        "avgVisitLength":0,
        "countVisitedLocations":0,
        "prefVisitTimebucket":"string",
        "prefVisitTimeHour":"string",
        "lastVisitDateBusiness":"string",
        "countTotalVisits":0,
        "conversionRate":0,
        "avgDaysBetweenVisits":0
      }
    }

Endpoints

List all the Contacts of an organization matching the search parameters

get

Role: Organization Manager Scope: organization_read, customer_read

Authorizations

Path parameters

cidstringRequired

organization cid

Query parameters

sidstringOptional

The sid can be used to retrieve a large number of results from a search request. Read the full docs to learn how to use the sid

sizestringOptional

Number of Contacts returned by the request. Allowed values between 1 and 10000. It is not possible to change this values during a scrolling.

hasEmailbooleanOptional

Return Contacts with email

emailVerifiedbooleanOptional

Return Contacts with an email verified

hasPhonebooleanOptional

Return Contacts with phone number

phoneVerifiedbooleanOptional

Return Contacts with an phone number verified

signupMethodsstringOptional

Return Contacts with the requested signup method

locationCidsstringOptional

Return Contacts registered on specific locations

segmentCidsstringOptional

Return Contacts belonging to specific segment or segments (comma separated)

createdStartstringOptional

Return Contacts with creation date >= of request. Format is date iso8601. Eg: 2019-07-31T22:23:24Z

createdEndstringOptional

Return Contacts with creation date <= of request. Format is date iso8601. Eg: 2019-07-31T22:23:24Z

modifiedStartstringOptional

Return Contacts with modified date >= of request. Format is date iso8601. Eg: 2019-07-31T22:23:24Z

modifiedEndstringOptional

Return Contacts with modified date <= of request. Format is date iso8601. Eg: 2019-07-31T22:23:24Z

mktgCommunicationsbooleanOptional

Return Contacts with marketing communication opt-in with value true

ageVerificationbooleanOptional

Return Contacts with age verification set to true

customOptIn.*booleanOptional

Return Contacts with specific custom opt-ins set to true. Eg: customOptin.my_policy=true

sortBystringOptional

firstName, lastName, gender, birthDate, country, created, privacy, termsOfUse, mktgCommunications, ageVerification, phone, phoneVerified, email, emailVerified, provider, username, locked, locations, system, enabled, type, modified_absolute,created_absolute,totalVisits,visitedLocations

sortReversebooleanOptional

Reverse sort order. sortBy argument is required

emailstringOptional

Search by email address

phoneNumberstringOptional

Search by phone number

usernamestringOptional

Search by username

extIdstringOptional

Search by external Id

extProp1stringOptional

Search by external property 1

extProp2stringOptional

Search by external property 2

Responses

200

The array of the customers

application/json

default

errorResponse

get

HTTPcURLJavaScriptPython

GET //v2/customers/organizations/{cid} HTTP/1.1
Host: explore.cloud4wi.com
Authorization: Bearer JWT
Accept: */*

{
  "generated": "text",
  "totalCount": 1,
  "count": 1,
  "sId": "text",
  "customers": [
    {
      "cid": "text",
      "title": "text",
      "firstName": "text",
      "lastName": "text",
      "gender": "text",
      "birthDate": "text",
      "birthDay": "text",
      "age": "text",
      "country": "text",
      "zipCode": "text",
      "created": "text",
      "modified": "text",
      "email": "text",
      "emailVerified": true,
      "phone": "text",
      "phoneVerified": true,
      "signupMethod": "text",
      "externalIdentityId": "text",
      "username": "text",
      "locked": true,
      "organizationCid": "text",
      "locationCid": "text",
      "system": "text",
      "enabled": true,
      "type": "text",
      "locationName": "text",
      "personalId": "text",
      "externalSource": "text",
      "lastLogin": "text",
      "segmentCids": "text",
      "logins": 1,
      "policies": [
        {
          "name": "text",
          "accepted": true
        }
      ],
      "segments": [
        {
          "cid": "text",
          "name": "text"
        }
      ],
      "extId": {
        "id": "text",
        "prop1": "text",
        "prop2": "text"
      },
      "metrics": {
        "frequencyMonthlyVisit": 1,
        "compassTopLocation": "text",
        "compassTopLocationCount": 1,
        "topFrequencyBuckets": "text",
        "lastVisitVenue": "text",
        "prefVisitWDay": "text",
        "lastVisitDateUtc": "text",
        "avgVisitLength": 1,
        "countVisitedLocations": 1,
        "prefVisitTimebucket": "text",
        "prefVisitTimeHour": "text",
        "lastVisitDateBusiness": "text",
        "countTotalVisits": 1,
        "conversionRate": 1,
        "avgDaysBetweenVisits": 1
      }
    }
  ]
}

Get a Contact

get

Retrieve Contact profile by Id Role: Organization Manager Scope: organization_read, customer_read

Authorizations

Path parameters

cidstringRequired

id of the customer

Responses

200

Data present

get

HTTPcURLJavaScriptPython

GET //v2/customers/{cid} HTTP/1.1
Host: explore.cloud4wi.com
Authorization: Bearer JWT
Accept: */*

200

Data present

No content

List location Events of a Contact

get

Retrieve list of visits and WiFi connections including metadata such as date and duration. Role: Organization Manager Scope: organization_read, customer_read

Authorizations

Path parameters

cidstringRequired

id of the customer

Responses

200

Data present

get

HTTPcURLJavaScriptPython

GET //v2/customers/{cid}/events HTTP/1.1
Host: explore.cloud4wi.com
Authorization: Bearer JWT
Accept: */*

200

Data present

No content

List all devices of a Contact

get

Retrieve device information like WiFi MAC address, number of WiFi connections and last WiFi connection date on the device. Role: Organization Manager Scope: organization_read, customer_read

Authorizations

Path parameters

cidstringRequired

id of the customer

Responses

200

Data present

get

HTTPcURLJavaScriptPython

GET //v2/customers/{cid}/devices HTTP/1.1
Host: explore.cloud4wi.com
Authorization: Bearer JWT
Accept: */*

200

Data present

No content

Update the opt-ins of a Contact

put

For the custom opt-ins add the prefix "customs." to the policyKey. For example, if the custom opt-in has title "emailMarketing" to update it use the policyKey "customs.emailMarketing" Role: Organization Manager Scope: organization_write, customer_write

Authorizations

Path parameters

cidstringRequired

id of the customer

Body

Responses

200

Update done.

application/json

207

Some of the opt-ins have not been updated. More details in the response.

application/json

default

Error

application/json

put

HTTPcURLJavaScriptPython

PUT //v1/customers/{cid}/policies HTTP/1.1
Host: explore.cloud4wi.com
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 51

{
  "policies": [
    {
      "policyKey": "text",
      "accepted": true
    }
  ]
}

{
  "policyKey": true
}

Delete a Contact

delete

Delete a Contact by Id Role: Organization Manager Scope: organization_write, customer_write

Authorizations

Path parameters

cidstringRequired

id of the customer

Responses

200

Deleted done.

application/json

default

unexpected error

application/json

delete

HTTPcURLJavaScriptPython

DELETE //v1/customers/{cid} HTTP/1.1
Host: explore.cloud4wi.com
Authorization: Bearer JWT
Accept: */*

{
  "status": "text",
  "generated": "text"
}

List all WiFi Connections of a Contact

get

Retrieve WiFi connections of a specific Contact Id, including metadata such as duration, traffic, access point used Role: Organization Manager Scope: organization_read, customer_read

Authorizations

Path parameters

cidstringRequired

id of the customer

Responses

200

Array with the accountings

application/json

get

HTTPcURLJavaScriptPython

GET //v2/customers/{cid}/accountings HTTP/1.1
Host: explore.cloud4wi.com
Authorization: Bearer JWT
Accept: */*

200

Array with the accountings

{
  "generated": "text",
  "sId": "text",
  "count": 1,
  "connections": [
    {
      "start": "text",
      "startBusiness": "text",
      "stop": "text",
      "stopBusiness": "text",
      "duration": 1,
      "traffic": 1,
      "locationName": "text",
      "locationId": "text",
      "apName": "text",
      "apId": "text",
      "latitude": 1,
      "longitude": 1,
      "macAddressClient": "text",
      "ipAddressClient": "text",
      "terminateCause": "text"
    }
  ]
}

Data example

Example of Contact object returned by the endpoint https://explore.cloud4wi.com//v2/customers/organizations/{cid}

{
   "generated":"2022-11-15T15:45:04Z",
   "totalCount":1,
   "count":1,
   "customers":[
      {
         "segments":[
            {
               "cid":"12d1f8713a1fecb953bcc64220813bc6",
               "name":"Loyal Customer"
            }
         ],
         "cid":"f4c6be2cebc56bf4b8a16a2d463d5b60",
         "title":null,
         "firstName":"Ivan",
         "lastName":"Muccini",
         "gender":"male",
         "birthDate":"1982",
         "birthDay":"01-29",
         "age":38,
         "country":"us",
         "zipCode":null,
         "created":"2022-07-21T17:58:35Z",
         "createdBusiness":"2022-07-21T17:58:35Z",
         "modified":"2022-11-15T05:19:43Z",
         "email":"[e-mail]",
         "emailVerified":false,
         "phone":"[phone]",
         "phoneNumber":"4156264284",
         "phonePrefix":"+1",
         "phoneVerified":false,
         "signupMethod":"passthrough",
         "externalIdentityId":null,
         "username":"RG1DXHXHMRTW",
         "locked":false,
         "organizationCid":"155d60f21dc1938562900a0e201d54f6",
         "locationCid":"ff808081803ff92a01820195deb26263",
         "system":"mobileapp",
         "enabled":true,
         "type":"guest",
         "locationName":"hiddden_SECUREWIFI.IO",
         "personalId":null,
         "externalSource":"Cloud4wi",
         "policies":[
            {
               "name":"termsOfUse",
               "accepted":true,
               "date":"2022-07-21T17:58:35.000Z",
               "version":"default"
            },
            {
               "name":"privacy",
               "accepted":true,
               "date":"2022-07-21T17:58:35.000Z",
               "version":"default"
            },
            {
               "name":"mktgCommunications",
               "accepted":true,
               "date":"2022-07-21T17:58:35.000Z",
               "version":"default"
            },
            {
               "name":"profiling",
               "accepted":false,
               "date":"2020-10-26T14:18:21.000Z",
               "version":"1.00"
            }
         ],
         "lastLogin":"2022-08-02T14:48:57.000Z",
         "logins":182,
         "metrics":{
            "frequencyMonthlyVisit":3.0897396143865636,
            "compassTopLocation":"ff808081803ff92a01821d4cfd856805",
            "compassTopLocationCount":12,
            "topFrequencyBuckets":"daily",
            "lastVisitVenue":"ff808081803ff92a01821d4cfd856805",
            "prefVisitWDay":2,
            "lastVisitDateUtc":"2022-08-02T14:54:36Z",
            "avgVisitLength":461.3333333333333,
            "countVisitedLocations":1,
            "prefVisitTimebucket":"afternoon",
            "prefVisitTimeHour":"15",
            "lastVisitDateBusiness":"2022-08-02T07:54:36Z",
            "countTotalVisits":12,
            "conversionRate":1,
            "avgDaysBetweenVisits":1.0909090909090908
         },
         "emailValid":null,
         "language":"it",
         "splashLanguage":"it",
         "genericCustomField":[
            {
               "key":"loyalty_card",
               "value":"9500000012143687"
            }
         ],
         "extId":{
            
         }
      }
   ]
}