DemystLive API

This guide will help you to understand how you can integrate your enterprise application with the DemystLive. The details of your integration may differ depending on how the integration is configured. All requests to the DemystLive are made over secure TLS channels using HTTP.

Execute

The execute endpoint will help you in evaluating the live connections and the data products you prefer to use. It is accessed at https://gw.us.demystdata.com/v2/execute, replacing us with au, eu or sg for accessing in regions outside US. Requests to the live endpoint are sent as HTTP POST requests and include the body defined below.

Sample request

Minimal sample request

{
  "api_key": "4a4d40f9e7f803b18ed2a073a0f39626",
  "providers": [ "domain_from_email" ],
  "inputs": {
    "email_address": "test@demsytdata.com"
  }
}

Sample response

{
  "transaction_id": "18de2573-f1ba-4d52-87f0-23c869dec036",
  "output": {
    "domain_from_email": {
      "data": {
        "user": "test",
        "host": "demsytdata.com"
      },
      "response_time": 3,
    }
  }
}

Request

Field Description
api_key Your API Key.
config See configuration
inputs See inputs.
providers An array of provider names (Available as Product ID).

Inputs

Inputs are specified as a JSON object, for example like this:

{
  "email_address": "test@demsytdata.com"
}

Demyst validates all received inputs before sending to provider. Required formats are specified here

Configuration

Field Description
mode Described below.
return_raw_data Includes the upstream provider’s response.
return_flattened_data Returns data in an alternative format.
Mode

sample — this mode by default will run each provider using our internally saved static sample response for that provider. You can optionally provide your own stub response for each provider, see the “Custom Sample Data” section for more details on that. This will be the only allowed mode and the default mode (will not need to be explicitly request) when using a test api key.

cache — when executing in cache mode we will look in our provider cache to see if the provider response is there before calling out to the data provider. If you have called the provider with the exact same inputs in cache mode in the last 7 days, it will be in the cache. If you call a provider in cache mode, and it’s response is not in the cache already, it will be added to the cache.

cache_read_only — when executing in cache_read_only mode, no live call will ever be attempted. The response will be looked for in the cache and if it’s not there the provider will return an error.

cache_write_only — when executing in cache_write_only mode, a live call will always be attempted and if successful, that result will be written to the cache. If a cache entry already exists for the input digest, it will be overwritten.

live: this is the default mode for production keys and does not need to be declared explicitly. In live mode we will always pull fresh data from the data source.

Responses

Successful responses

The successful response contains the following top-level fields

  • transaction_id Unique identifier for the transaction
  • output – Structured data returned from providers. Output contains an object where the keys are the provider names and the values are an object containing additional information:
    • data – Object where the keys are the top-level fields returned by the given provider and the values are values for those fields or nested objects containing similar key/value pairs.
    • response_time – The time (in milliseconds) the provider took to execute

Unsuccessful responses

The server will respond with an error to a badly formed request, if the api_key and id parameters are not included, or if the parameters are not valid.

If a provider errors due to upstream error, missing keys, or timeout the full response will return but there will be an error object in the errored provider containing the fields:

  • type — type of error (timeout, upstream error, provider unresponsive, insufficient_input)
  • message — detailed error message

Example:

{
  "transaction_id" : "0e766760-4b5b-4bf3-b8f1-b1e113cb07f8",
  "output" : {
    "mh_customers" : {
      "error" : {
        "type" : "insufficient_input",
        "message" : "Inputs are missing a field that is necessary to run this data provider"
      },
      "response_time" : 0
    },
    "mh_blacklist" : {
      "error" : {
        "type" : "insufficient_input",
        "message" : "Inputs are missing a field that is necessary to run this data provider"
      },
      "response_time" : 0
    }
  }
}

Channel

The channel endpoint is when you want to productionalize the calls, with or without the need of customizing the output. It is accessed at https://gw.us.demystdata.com/v2/channel, with region(us) dependent on the region you are working with.

Sample request

Minimal sample request

{
  "api_key": "4a4d40f9e7f803b18ed2a073a0f39626",
  "id": [ "838" ],
  "inputs": {
    "business_name": "Example Inc",
    "email_address":"johndoe@example.com",
    "ip4": "45.62.176.5"
  }
}

Sample response

{
  "transaction_id" : "ab67fff7-4be4-40dd-9de0-496633b46f83",
  "output" : {
    "mh_customers" : {
      "data" : {
        "customer_id" : 14
      },
      "response_time" : 179
    },
    "mh_blacklist" : {
      "data" : {
        "country" : "US",
        "email_address" : "stan.duckett@example.com",
        "first_name" : "Stan",
        "last_name" : "Duckett"
      },
      "response_time" : 15
    }
  },
  "pipes" : {
    "active_2017" : {
      "result" : {
        "sum_credit" : 0,
        "sum_debit" : 0,
        "avg_credit" : null,
        "avg_debit" : null,
        "credit_count" : 0,
        "debit_count" : 0,
        "max_credit" : null,
        "credit_range" : null,
        "max_debit" : null,
        "debit_range" : null,
        "total" : 0,
        "approved" : true
      }
    }
  }
}

Request

Field Description
api_key Your API Key.
config See configuration
inputs See inputs
id A channel id configured by Demyst exclusively for your use-case

Responses

In this example two providers are queried: mh_customers and mh_blacklist. Mh_customers returns a single field (customer_id) in 179ms while mh_blacklist returns a set of four in 15ms.

These results are then passed to a pipe called “active_2017” where a further set of 12 fields is calculated inside a data function.

The original provider info and data function(customization logic) response is then returned as the result of the API, as seen above

Successful responses

The successful response contains the following top-level fields

  • transaction_id Unique identifier for the transaction
  • output – Structured data returned from providers. Output contains an object where the keys are the provider names and the values are an object containing additional information:
    • data – Object where the keys are the top-level fields returned by the given provider and the values are values for those fields or nested objects containing similar key/value pairs.
    • response_time – The time (in milliseconds) the provider took to execute
  • pipes – Customized response from the data function(customization logic) created by Demyst
    • pipe_name – “active_2017” in the example that contains the structured data attributes created in data function from the providers output.
Close Menu