Skip to content

Gateway API

The DemystLive API is accessed at https://gw.CC.demystdata.com/v2/execute, where CC is the region your execution servers will be running in (us, au, eu, sg). 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": 0,
    }
  }
}

Request

Field Description
api_key Your API Key.
config See configuration
inputs See inputs.
providers An array of provider names.

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
    }
  }