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
get
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
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
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
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
put
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
delete
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
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":"imuccini3@cloud4wi.com",
         "emailVerified":false,
         "phone":"+14156264284",
         "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":{
            
         }
      }
   ]
}

Last updated

Was this helpful?