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
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.
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"
}
}
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
- A JSON
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