Retrieving archived lookups

๐Ÿ“˜

About this guide

Demyst offers you access to archived data that can greatly expand the value and efficiency of your deployed systems. In this guide you will learn to retrieve archived stored data that captures information on attributes that may have changed over time. This empowers you to retrospectively review data to support decision-making.

To access archived data, you must first create a Data API from an applicable hosted Connector to execute requests. Only a hosted Connector may have archived data. Many of the hosted Connector (Connector ID beginning with 'hosted') contain archived data. To execute an Archived Lookup, you would fill in your inputs like a regular request, however, you must also input dates (YYYY-MM-DD format) for the earliest_snapshot and latest_snapshot input attributes for the desired lookup range.

Steps

1 - Open an existing Data API

Open one of your existing Data API that has been in use for a while. The Archived Lookups work only if records exist for the period of time the lookup is referencing.

2 - Edit the Config of the Data API

We will perform an Archived Lookup to observe a recorded change of address for a business between June 1 and July 31 of 2021. Below is a configuration that will provide us with the address of the archived data in June 2021 and July 2021. The Connector will output an as_of_date attribute for each archived record when we execute a request. This attribute provides the archive date of the returned data.

		
{
  "providers": {
    "hosted_experian_cpdb": {
      "version": "$latest"
    }
  },
    "inputs": {
      "business_name": "Demyst Data, Limited",
      "city": "New York",
      "state": "NY",
      "post_code": "10001",
      "country": "us",
      # Specifying the snapshots will allow to return specific date for a connector that supports it.
      "earliest_snapshot": "2021-06-01",
      "latest_snapshot": "2021-07-31"
    },
      "refine": {
        "archive_date_07_2021": "hosted_experian_cpdb.results[0].as_of_date",
        "street_07_2021": "hosted_experian_cpdb.results[0].address",
        "city_07_2021": "hosted_experian_cpdb.results[0].city",
        "state_07_2021": "hosted_experian_cpdb.results[0].state",
        "post_code_07_2021": "hosted_experian_cpdb.results[0].post_code",

        "archive_date_06_2021": "hosted_experian_cpdb.results[1].as_of_date",
        "street_06_2021": "hosted_experian_cpdb.results[1].address",
        "city_06_2021": "hosted_experian_cpdb.results[1].city",
        "state_06_2021": "hosted_experian_cpdb.results[1].state",
        "post_code_06_2021": "hosted_experian_cpdb.results[1].post_code"
}	

3 - Execute the request

Executing a request with the above configuration will yield the following response:

{
  "transaction_id" : "9412ae14-1d4b-4eeb-88da-57fc05c3327c",
  "refine" : {
    "archive_date_06_2021" : "2021-06",
    "archive_date_07_2021" : "2021-07",
    "city_06_2021" : "New York",
    "city_07_2021" : "New York",
    "post_code_06_2021" : "10010",
    "post_code_07_2021" : "10001",
    "state_06_2021" : "NY",
    "state_07_2021" : "NY",
    "street_06_2021" : "28 W 25th St Fl 9",
    "street_07_2021" : "1261 Broadway # Level4"
  },
  "output" : {
    "hosted_experian_cpdb" : {
      "data" : {
        "is_hit" : true,
        "results" : [
				# July 2021 Archived Data
        {
            "address" : "1261 Broadway # Level4",
            "address_confidence_score" : null,
            "address_type_code" : "P",
            "aged_trd_lines" : null,
            "annual_sales_size_code" : null,
            "as_of_date" : "2021-07",

            ...

            "ultim_parent_city" : "NEW YORK",
            "ultim_parent_cntry_code" : "USA",
            "ultim_parent_company_ind" : "Y",
            "ultim_parent_name" : "DEMYST DATA, LIMITED",
            "ultim_parent_state" : "NY",
            "url" : "demyst.com",
            "year_business_started" : 2010,
            "years_in_business_code" : "E",
            "years_in_file" : 6
          },
				# June 2021 Archived Data
        {
            "address" : "28 W 25th St Fl 9",
            "address_confidence_score" : null,
            "address_type_code" : "P",
            "aged_trd_lines" : null,
            "annual_sales_size_code" : null,
            "as_of_date" : "2021-06",

            ...

            "ultim_parent_city" : "NEW YORK",
            "ultim_parent_cntry_code" : "USA",
            "ultim_parent_company_ind" : "Y",
            "ultim_parent_name" : "DEMYST DATA, LIMITED",
            "ultim_parent_state" : "NY",
            "url" : "demyst.com",
            "year_business_started" : 2010,
            "years_in_business_code" : "E",
            "years_in_file" : 6
          }
        ]
    }
}

From the refine section of the output, we see that the archived data for street and post_code have changed between June and July.

Additional Details

Syntax

To determine if a Connector has Archived Lookup capabilities, determine if the earliest_snapshot and latest_snapshot attributes are available. The archive frequency (daily, monthly, etc.) may vary depending on the Connector. To clarify the archive frequency or a first-time setup, reach out to your Demyst representative.

Use the refine section to extract the archived lookup results with the earliest snapshot corresponding to the last available index of the results, and the latest snapshot corresponding to the [0]th index of results.

The Connector will output an as_of_date attribute for each archived record when we execute a request.

Example Scenario

Updating Business Details: You can use archived lookups for collecting changes and updates in attributes like company executives, phone numbers, addresses, and more.

Evolving Risk or Credit Models: Archived lookups are especially important for evolving risk scores or credit scores. Once collected you can use this data to sense check past results from your downstream models or even re-calculate the scores.