Data API

When to use it

You would use the Data API when you have an array of customer domain data and want to do any of the following things:

• allow the webapp user to choose a value for some field from a predefined set, not adding another value to the set;

• validate the user input against a predefined set of values both on frontend and backend;

• populate some more fields based on the user’s choice in another field;

• allow to choose values for different fields, thus filtering and narrowing down the choices for the following fields belonging to the same set of data;

• limit the availability of the whole set to a certain account;

• limit the availability of certain fields to frontend.

How to use it

A typical usage flow:

• The frontend app requests a list of items for a dropdown to display on the field with the dataset rule from the Data API, specifying the dataset fields;

• The Data API responds with a list of item IDs and values for the chosen dataset fields;

• User selects a value;

• The frontend app requests a single dataset item by its ID;

• The API responds with the full set of public fields for the item;

• The frontend app submits a dataset item ID in the payload for the field instead of a set of fields (e.g. company data) to the quote or policy API, e.g. "some_field”: ”dai_some_dataset_item_id________”.

How to retrieve the data

Note

All of the retrieval samples below show unauthenticated requests for publicly available datasets.

When you need to access a dataset locked to an account, add an Authentication: Bearer YOUR_TOKEN header to the request.

Get a dataset information record

Get a dataset information record

GET https://api.kaskocloud.com/datasets/{datasetId}

Path Parameters

Name	Type	Description
datasetId*	String	Dataset ID

200: OK

{
    "id": "dat_abcxyz______________________",
    "name": "Some dataset name",
    "languages": ["en", "de"]
}

List items from a set

List items from a set.

GET https://api.kaskocloud.com/datasets/{datasetId}/dataset_items

Path Parameters

Name	Type	Description
datasetId*	String	Dataset ID

Query Parameters

Name	Type	Description
language*	String	Language
fields*	JSON	Fields to output in the value property
limit*	Integer	Number of items per page, 1 to 100, default = 20
starting_after	String	Item ID to start the page after
ending_before	String	Item ID to end the page before
query	JSON	Search query
sort	JSON	Sorting order

200: OK

{
    [
        {    
            "id": "dai_abcxyz",
            "value": {
                "name": "Kasko",
                "code": "Z1",
            }
        }
    ]
}

The query parameter format is [{"field": "FIELD", "search": "VALUE", "operator": "OPTIONAL_OPERATOR"}].

The search field of the query parameter supports % wildcards; the accepted operators are >, >=, <, <=, and IN. The type of the value is array for the IN operator and string for everything else.

Sample search value:

[
  {"field": "name", "search": "Kas%"},
  {"field": "price", "operator": ">", "search": "10"},
  {"field": "category", "operator": "IN", "search": ["a", "b"]}
]

The sort parameter format is [{"field": "FIELD", "dir": "asc|desc"}].

Example Request

curl 'https://api.kasko.io/datasets/DATASET_ID/dataset_items' \
    -d language=de \
    -d fields=["name","code"]

The Link header holds the links for the next and previous page queries.

List distinct values of a field in a dataset

List items from a set.

GET https://api.kaskocloud.com/datasets/{datasetId}/items_distinct_values

Path Parameters

Name	Type	Description
datasetId*	String	Dataset ID

Query Parameters

Name	Type	Description
language*	String	Language
fields*	JSON	Fields to output in the value property
limit*	Integer	Number of items per page, 1 to 100, default = 20
starting_after	String	Item ID to start the page after
ending_before	String	Item ID to end the page before
query	JSON	Search query
sort	JSON	Sorting order

200: OK

{
    [
        {    
            "id": "dai_abcxyz",
            "value": {
                "name": "Kasko",
                "code": "Z1",
            }
        }
    ]
}

Get one item

Get dataset item

GET https://api.kaskocloud.com/dataset_items/{itemId}

Query Parameters

Name	Type	Description
language*	String	Language

200: OK

{
    "id": "dai_abcxyz",
    "data": {
        "field_name": "field_value"
    }
}

Sending data to backend

Instead of the literal values in the dataset item you send the item ID.

Example Request For a Quote:

GET https://api.kaskocloud.com/quote?data=
{
  ...
  "company": "dai_123_some_item_id_____________",
  ...
}

The backend service transparently converts this input to the full item available to use in pricing, policy, etc.