Contact us
Guides
Go to platform

Build custom response schema

The refine section of the configuration DSL allows you to create a custom response schema independently of the upstream vendor data included in your API

Suggest Edits

📘

About this guide

In this guide you will learn about the refine section from the Demyst proprietary Data API configuration language, which will allow you to create a custom response schema independent of the upstream Data API.

Steps

1 - Create a new Data API

Navigate to https://demyst.com/app/create-api and include the Connector that you want to include in your new Data API.

Creating a Data API

Creating a Data API

2 - Configure data selection through the refine section

The refine option allows the user to define custom attributes, which will be evaluated and returned in the response. These expressions allow a user to create an abstraction layer that allows the underlying data provider and subsequent data attributes to be swapped with minimal impact on integrated systems.

Add your low code JSON snippet to the configuration section of the Data API.

{
  "config": {
    "mode": "cache"
  },
  "providers": {
    "seon_fraud_v2": {
      "version": "$latest"
    }
  },
  "refine": {
    "email_breached": "seon_fraud_v2.data.email_details.breach_details.number_of_breaches",
    "email_disposable": "seon_fraud_v2.data.email_details.domain_details.disposable",
    "email_valid": "seon_fraud_v2.data.email_details.deliverable",
    "ip_behind_vpn": "seon_fraud_v2.data.ip_details.vpn",
    "ip_behind_web_proxy": "seon_fraud_v2.data.ip_details.web_proxy",
    "phone_disposable": "seon_fraud_v2.data.phone_details.disposable",
    "phone_valid": "seon_fraud_v2.data.phone_details.valid"
  }
}
Saving Config in the `Settings` tab

Saving Config in the Settings tab

That configuration can be saved in the Data API directly.

👍

Your API is now configured.

3 - Retrieve refine attributes in the results

Saving that config will now allow you to run transactions and integrate the newly created Data API. When you run a request and start receiving data, you will see the refine section right at the top.

Additional Details

Syntax

  • A JSON object
  • The left-hand side of the JSON object is always an alphanumeric attribute key.
  • The right-hand side can be either of the following.
    • A JSON string — a path to an attribute.
      The custom attribute will contain the value at this path.
    • A JSON object from connector to a function
      Example
      { "domain_from_email": "$isMatch" }
      Returns
      true if the connector function matches
    • A JSON object from connector to a function
      Example
      { "seon_fraud_v2.data.fraud_score": { "$gte": 0.5 }}
      Returns
      true if the connector function matches

Example scenario

  • Pre-fill: Selecting a subset of details as a custom response. For example, getting essential business registration details from a business profile database.
  • Prioritize sources: You may want to prioritize one source over another for specific attributes due to confidence in the quality of the data or other criteria. You can select a set of attributes to be retrieved from one source over another and vice versa, where available. (Checkout Example 2 below on how to do so.)

Payload example

Here are some more examples of the refine section being implemented:

# Simple 1-to-1 mapping from vendor attribute to newly created refined interface
{
  "providers": {
    "hosted_experian_cpdb": {
      "version": "$latest"
    },
    "hosted_infogroup_business_places": {
      "version": "$latest"
    }
  },
  "refine": {
    "sic_code": "hosted_infogroup_business_places.results[0].primary_sic_code_id",
    "naics_code": "hosted_infogroup_business_places.results[0].primary_naics_code_id",
    "year_business_start": "hosted_infogroup_business_places.results[0].estimated_opened_for_business_lower",",
    "sales": "hosted_experian_cpdb.results[0].est_annual_sales_amt",
    "website": "hosted_experian_cpdb.results[0].url"
  },
}

# Including conditional logic into the refine section allows to include sequencing or functions
# into the api interface. In this example, the Experian Connector is only called if the TLOXP 
# connector failed to return
 
{
  "providers": {
    "tloxp_business_judgments_search": {
      "version": "$latest"
    },
    "experian_business_judgments": {
      "version": "$latest",
    }
  },
  "refine": {
    "total_judgments": {
      "$firstOf": [
        "tloxp_business_judgments_search.number_of_records_found",
        "experian_business_judgments.judgment_summary.judgment_count"
      ]
    }
  }
}

# Multiple examples of combining refine with functions.
{
  "refine": {
    # select attribute at path
    "bic":       "experian_business_search_api.results[0].bic", 
    # functions on connector, returns TRUE / FALSE
    "matched":   { "domain_from_email": "$isMatch" },
    # functions on an attribute, returns TRUE / FALSE
    "is_fraud":  { "seon_fraud_v2.data.fraud_score": { "$gte": 0.5 }},
    # functions on list of attributes 
    "sic_code":  { "$firstOf": [ "equifax_austin_tetra_details.primary_sic.sic_code",
                      "hosted_infogroup_business_places.results[0].primary_sic_code_id" ] }
      }
}

Updated over 1 year ago