InfoIdent

The FunnelConnect InfoIdent API is used to handle identity resolution, permission management, and data inlining, including fetching of data from external sources, for example profile API, CDP API, etc. It provides the following operations:

  • creation of a TargetData profile and setting of a 1st party cookie.
  • handling of customer identifiers for example provided through login, telco network identification or other forms of identification like for example Utiq martechpass.
  • retrieval of TargetData profile data, including UMID, marketing permissions, consent or legitimate interest notification acknowledgements, targeting and campaign attributes, identifiers, and identification state. What data gets returned can be configured in the API pipeline.
  • setting and updating of marketing permissions and corresponding consent notification.

GET Request

This operation can create a TargetData profile and retrieve data.

GET /op/[pipeline]/info?umdid=[umdid]&identifiers&permissions&notifications&attributes&out=json

Request Parameters

Name Value Description
umdid (Query Parameter; optional) Random unique value provided by FC. The value of the umdid is stored in a 1st party cookie. It is used to look up the profile. It overrides the umdid cookie for this request in case both are provided. Either the umdid query parameter or the umdid cookie needs to be provided.
umdid (Cookie Parameter; optional) Random unique value provided by FC. The umdid cookie is used for identification. Either the umdid query parameter or the umdid cookie needs to be provided.
[customer identifier] (Query Parameter; optional) Any pipeline enabled customer identifier. The identifier is used to look up the profile or extend a profile with additional customer identifier(s).
out (Query Parameter; optional) out (Query Parameter; optional) Return JavaScript or JSON, default value is js.
identifiers (Query Parameter; optional) no value If parameter is included the identifiers section will be returned in the response body.
nbidentifiers (Query Parameter; optional) no value If parameter is included the nbidentifiers will be returned in the response body.
permissions (Query Parameter; optional) no value If parameter is included the permissions section will be returned in the response body.
notifications (Query Parameter; optional) no value If parameter is included the notifications section will be returned in the response body.
attributes (Query Parameter; optional) no value If parameter is included the attributes section will be returned in the response body.

To restrict access to identifiers and attributes marketing permissions can be defined as conditions. If these conditions are not met, for example the user has not consented to specific marketing permissions, this data would not be returned in the response body.

Custom Request Header and Telco Identity Resolution

Custom request headers can be configured in the pipeline to handle telco network identifier. Alternatively, the system can obtain the IP address and Port of the connection and use that to fetch a telco identifier via server-side API, all part of the same request.

Response HTTP Status Codes

Code Name Description
200 OK Successful request.
400 Bad Request The request does not conform to the specification.
404 Not Found Endpoint has not been configured.
500 Internal Server Error An error occurred on the server side. Please try again later. If persists contact support.

Response Body

All sections except the umid and the identification state are optional in the response body. Permissions and notifications are examples and can be defined as needed.

Field Type Values Optional Description
umid String No Marketing ID
identifiers Array of Objects   Yes  
  name String   No The mapped name of the identifier as configured in the pipeline.
  value String   No The value of the identifier.
nextBestIdentifiers Array of Objects   Yes  
  name String   No The mapped name of the next-best identifier as configured in the pipeline.
  value String   No The value of the next-best identifier.
permissions Object Yes
   LI-OM Boolean true or false Yes The value false equals opt out. Default value is true.
   LI-OPT Boolean true or false Yes The value false equals opt out. Default value is true.
   LI-NBA Boolean true or false Yes The value false equals opt out. Default value is true.
permissionsLastModification Object Yes
   LI-OM String ISO 8601 Date Yes Date and time in UTC this permission has been last modified by an user action. Format YYYY-MM-DD’T’hh:mm:ss’Z'.
   LI-OPT String ISO 8601 Date Yes Date and time in UTC this permission has been last modified by an user action. Format YYYY-MM-DD’T’hh:mm:ss’Z'.
   LI-NBA String ISO 8601 Date Yes Date and time in UTC this permission has been last modified by an user action. Format YYYY-MM-DD’T’hh:mm:ss’Z'.
notificationHistory Array Yes
   name String No Identifier of the notification.
   version Int No Version of the notification.
   permissions Array LI-OPT, LI-NBA, LI-OM No Permission this notification covers.
   date String ISO 8601 Date No Date and time in UTC this notification has been shown to this visitor. Format YYYY-MM-DD’T’hh:mm:ss’Z'.
notificationStatus Object Yes
   LI-OM Boolean true or false Yes This value is computed from the notficationHistory and denotes if a valid notification has been shown for the permission LI-OM. True equals a valid notification for this permission, false equals invalid.
   LI-OPT Boolean true or false Yes This value is computed from the notficationHistory and denotes if a valid notification has been shown for the permission LI-OPT. True equals a valid notification for this permission, false equals invalid.
   LI-NBA Boolean true or false Yes This value is computed from the notficationHistory and denotes if a valid notification has been shown for the permission LI-NBA. True equals a valid notification for this permission, false equals invalid.
state Int 1 or 0 No The state of the current identification. 0 indicates a prospect, 1 an identified customer.
attributes Object Yes Object with the associated attributes.
   [attributeName] String No An attribute key value pair for the identified profile.

Notification Types

Notification types can be defined. The following provides an example.

Type Key / Name Context
Notification for consent or legitimate interest disclosure in WEB channel. WEB LI-OM, LI-OPT, LI-NBA
Notification for consent or legitimate interest disclosure in APP channel. APP LI-OM, LI-OPT, LI-NBA
Notification for consent or legitimate interest disclosure in TV channel. TV LI-OM, LI-OPT, LI-NBA

Permission Types

Permission types can be defined. The following provides an example.

Name Description
LI-OM Legitimate Interest based Online Marketing permission with default set to true.
LI-OPT Legitimate Interest based Optimisation permission with default set to true.
LI-NBA Legitimate Interest based personalisation permission with default set to true.
C-PII Consent (optin) based personal identifiable data use. Default set to false.
C-WT Consent (optin) based personal identifiable data and web tracking use. Default set to false.

Example JSON Response Body

Content-Type: application/json

{
  "umid": "161023af-f228-407c-8fb1-af3a5a4d791b",
  "identifiers": [
    {
      "name": "e8",
      "value": "oVPqLNc4pQ+TXPM1IeyGqg=="
    },
    {
      "name": "e7",
      "value": "aaaaaa826809a841550c21951d31e2ecce3809513ada39121197ad15678da1b6"
    }
  ],
  "permissions": {
    "LI-OM": true,
    "LI-OPT": true,
    "LI-NBA": true,
  },
  "permissionsLastModification": {
      "LI-OPT": "2018-01-15T15:53:00Z",
      "LI-NBA": "2018-01-15T15:53:00Z"
  },
  "notificationHistory": [
    {
      "name": "WEB",
      "version": 1,
      "permissions": ["LI-OM", "LI-OPT"],
      "date": "2018-01-15T15:53:00Z"
    },
    {
      "name": "APP",
      "version": 1,
      "permissions": ["LI-OM", "LI-OPT"],
      "date": "2018-02-15T15:53:00Z"
    },
    {
      "name": "TV",
      "version": 1,
      "permissions": ["LI-OM", "LI-OPT"],
      "date": "2018-02-15T15:53:00Z"
    }
  ],
  "notificationStatus": {
    "LI-OM": true,
    "LI-OPT": false,
    "LI-NBA": true
  },
  "state": 1,
  "attributes": {
    "key": "value",
    "abs": "111,222,3335"
  }
}

Example JavaScript Response Body

Content-Type: application/javascript

var fcData = {
  "umid": "161023af-f228-407c-8fb1-af3a5a4d791b",
  "identifiers": [
    {
      "name": "e8",
      "value": "oVPqLNc4pQ+TXPM1IeyGqg=="
    },
    {
      "name": "e7",
      "value": "aaaaaa826809a841550c21951d31e2ecce3809513ada39121197ad15678da1b6"
    }
  ],
  "permissions": {
    "LI-OM": true,
    "LI-OPT": true,
    "LI-NBA": true,
  },
  "permissionsLastModification": {
      "LI-OPT": "2018-01-15T15:53:00Z",
      "LI-NBA": "2018-01-15T15:53:00Z"
  },
  "notificationHistory": [
    {
      "name": "WEB",
      "version": 1,
      "permissions": ["LI-OM", "LI-OPT"],
      "date": "2018-01-15T15:53:00Z"
    },
    {
      "name": "APP",
      "version": 1,
      "permissions": ["LI-OM", "LI-OPT"],
      "date": "2018-02-15T15:53:00Z"
    },
    {
      "name": "TV",
      "version": 1,
      "permissions": ["LI-OM", "LI-OPT"],
      "date": "2018-02-15T15:53:00Z"
    }
  ],
  "notificationStatus": {
    "LI-OM": true,
    "LI-OPT": false,
    "LI-NBA": true
  },
  "state": 1,
  "attributes": {
    "key": "value",
    "abs": "111,222,333"
  }
};

POST Request

This operation can create a TargetData profile, retrieve data, as well as set and update marketing permissions, and consent notification acknowledgments.

POST /op/[pipeline]/info?identifiers&permissions&notifications&attributes&out=json&umdid=[umdid]

Request Body

Permission Update

Legitimate Interest based Online Marketing permission change.

{ 
	"permission": { 
		"LI-OM": false
	}
}

Notification Update

Legitimate Interest based Online Marketing, Optimisation, and Next Best Action (personalisation) notification disclosure update on web channel.

{ 
	"notification": [
        { 
    		"name": "WEB", 
	    	"version": 1, 
    		"permissions": ["LI-OM", "LI-OPT", "LI-NBA"] 
    	}
    ]
}

Notification & Permission Update

Combined update of web and app channel notification disclosure and permissions.

{ 
	"permission": { 
		"LI-OM": true, 
		"LI-OPT": true, 
		"LI-NBA": true
	}, 
	"notification": [
        { 
    		"name": "WEB", 
	    	"version": 1, 
    		"permissions": ["LI-OM", "LI-OPT"] 
    	},
    	{ 
    		"name": "APP", 
    		"version": 1, 
    		"permissions": ["LI-OM", "LI-OPT"] 
    	}
    ]
}