Data Retrieval

This API provides access to various data sources (incl. TargetData, CDS, and external data systems, CDPs, etc.) using a pipeline to retrieve data for specified fields, for example identifiers, permissions and attributes, as well as the internal and external data sources. Data retrieval from multiple data sources can be combined in a single request.

The pipeline defines what data is returned for each top-level field provided in the request including sub-level fields, for example identifiers of specific name, type and other sub-level fields.

Basic authentication is normally required.

If a client initiated call is required, the pipeline can also use an enrcypted string, for example email, passed in query string parameter for validation of the request.

Request

Request TargetData profile information requires a profile identifier like for example the UMID, which can be retrieved with the FunnelConnect Info call. Any other identifier linked to that profile can be used, for example an encrypted email address.

Server call with basic authentication:

JS

curl -X GET \
  -H 'Authorization: Basic XYZ' \
  https://[domain]/api/v1/[pipeline]/data?attributes&identifiers&permissions&rtNba&cds&out=json&umid=[umid]

Client call with hashed email:

JS

curl -X GET \
  --cookie 'umdid=[umdid]' \
  https://[domain]/api/v1/[pipeline]/data?attributes&identifiers&permissions&rtNba&cds&out=json&encem=[encryptedEmail]

Parameters

Specify the top-level fields you require. Only fields enabled in that pipeline will be returned. Some fields hold more data in sub-level fields. The pipeline configuration will define which of these sub-level fields will be returned.

Name	Type	Description
attributes	Array	Returns an array of attribute objects.
identifiers	Array	Returns an array of identifier objects.
permissions	Array	Returns an array of permission objects.
rtNba	Array	Returns an array of real-time NBA objects.
cds	Array	Returns an array of CDS (Customer Data Store) objects. The “source” field is always provided in the output and has the value “beh_inlining“. In future extensions more elements with different sources might be added to the array. The caller should pick the respective data based on the source. If a field is missing in CDS, it is missing in the output as well. If no profile for the ID was found or all fields are missing, no element is added to the cds array.
out	String	Is used to specify the return message, for example out=json returns a JSON, out=js returns the fcData variable with JSON object.
umid	String	Identifier for the TargetData lookup.
encem	String	Encrypted email used for request authentication.

Response

HTTP Status Codes

Code	Name	Description
200	OK	Successful TargetData lookup. Profile was found and data is returned.
400	Bad Request	The request was malformed. For example an invalid identifier was provided.
401	Unauthorised	Authentication failed.
404	Not Found	Incorrect request method or path or pipeline does not exist.
413	Payload Too Large	The request headers are larger than the configured maximum on the server.
500	Internal Server Error	An error occurred when processing the request. For example the DB access timed out.

Examples

Responses contain either a JSON or JavaSript body, depending on the out-parameter provided in the request.

out=json

JSON

{
  "identifiers": [
    {
      "name": "msisdn-sha2",
      "value": "ea5eb5ce8941948be64a0ef2236a0560f0bbe2a8509d30d7251d96f14ec048a2"
    },
    {
      "name": "umid",
      "value": "87f9e7fe-bcae-48e2-adb8-3dbec4705cf6"
    }
  ],
  "attributes": [
    {
      "name": "dwhPostcode",
      "value": "24787",
      "metadata": {
        "extractDate": "20190928",
        "contractDateEnd": "20210507"
      }
    },
    {
      "name": "device",
      "value": "Apple iPhone 8 (A1905) HSDPA EDGE 3G (GSM/DCS/PCS/LTE)",
      "metadata": {
        "extractDate": "20190928",
        "contractDateEnd": "20210507"
      }
    }
  ],
  "permissions": [
    {
      "name": "LI-OM",
      "value": true,
      "sources": [
        "DWH_IMPORT"
      ],
      "lastUpdated": "2019-05-26T04:09:37Z"
    },
    {
      "name": "LI-NBA",
      "value": true,
      "sources": [
        "WEB"
      ],
      "lastUpdated": "2019-09-28T10:08:25Z"
    }
  ],
  "rtNba": [
    {
      "priority": "1.0",
      "issue": "ACC_Re",
      "cellcode": "4G_SWAP4",
      "campcode": "MCC_3102",
      "group": "ACC_Re_group"
    }
  ],
  "cds": [
    {
      "source": "beh_inlining",
      "product": "red business prime mit premium-smartphone",
      "product_category": "tariff",
      "fixnet_isp": "Deutsche Telekom AG",
      "mobile_isp": "O2 Germany GmbH & Co. OHG"
    }
  ]
}

out=js

JS

var fcData = {
  "identifiers": [
    {
      "name": "msisdn-sha2",
      "value": "ea5eb5ce8941948be64a0ef2236a0560f0bbe2a8509d30d7251d96f14ec048a2"
    },
    {
      "name": "umid",
      "value": "87f9e7fe-bcae-48e2-adb8-3dbec4705cf6"
    }
  ],
  "attributes": [
    {
      "name": "dwhPostcode",
      "value": "24787",
      "metadata": {
        "extractDate": "20190928",
        "contractDateEnd": "20210507"
      }
    },
    {
      "name": "device",
      "value": "Apple iPhone 8 (A1905) HSDPA EDGE 3G (GSM/DCS/PCS/LTE)",
      "metadata": {
        "extractDate": "20190928",
        "contractDateEnd": "20210507"
      }
    }
  ],
  "permissions": [
    {
      "name": "LI-OM",
      "value": true,
      "sources": [
        "DWH_IMPORT"
      ],
      "lastUpdated": "2019-05-26T04:09:37Z"
    },
    {
      "name": "LI-NBA",
      "value": true,
      "sources": [
        "WEB"
      ],
      "lastUpdated": "2019-09-28T10:08:25Z"
    }
  ],
  "rtNba": [
    {
      "priority": "1.0",
      "issue": "ACC_Re",
      "cellcode": "4G_SWAP4",
      "campcode": "MCC_3102",
      "group": "ACC_Re_group"
    }
  ],
  "cds": [
    {
      "source": "beh_inlining",
      "product": "business prime mit premium-smartphone",
      "product_category": "tariff",
      "fixnet_isp": "Deutsche Telekom AG",
      "mobile_isp": "O2 Germany GmbH & Co. OHG"
    }
  ]
};