Decision APIs

The decision API is used to ask if a single record is valid for the stated user and purpose. The response explains why, or why not, the purpose is valid. If the full record is not usable for the stated purpose, but a subset of the record is, then the response may include the fields that are permissible so that the caller can redact all other fields.

All calls to this API are audited, so there's automatically a record of each decision. Each query includes a JSON-structured record (independent of the source format) to normalize and simplify several common flows, such as:

• A checkpoint for each record flowing through a transform process
• A gate for data going through aggregation pipelines
• A co-pilot for developers and data scientists asking "what-if" questions
• A point of audit for data used to train models

As an example, suppose you are implementing a transform process that automates pulling data from various sources to provide a single structure to your fulfillment team. You need to make sure that they only get the right data, and that there's an audit trail proving this was done. You would first create a mapping group for the structure that you're providing, and then use that group to transform data. If that structure contained the fields Email and CCNumber, you call the decision interface like this:

curl -X PUT -H "Accept: application/json" -H "Content-Type: application/json" \
    "http://localhost:8890/decision/?purposeId=use.fulfillment&type=platformUse&mappingGroup=Transform" \
-d '{
        "fields" : [ {
            "name" : "Email",
            "value" : "carol@example.com"
        }, {
            "name" : "CCNumber",
            "value" : "1234567812345678"
        } ],
        "returnAllowedFields" : true
    }'

This will return a single structure, accompanied by one of two HTTP codes. A result of 200 means that the purpose is valid for all of the proposed data. A 409 means that the full set of data is not valid for the purpose. By setting returnAllowedFields to true, the latter also includes the set of fields that would satisfy the purpose. For instance, that set might include Email but not CCNumber, so now the transform process can issue the call again or simply drop the dis-allowed fields and proceed.

In the decision trace there's a record of this call and the resulting decision. There's knowledge of this record in context, so the change data capture stream will provide the details behind the decision. Taken together, even though the "record" in this example never existed outside of a transient transformation process, there's all the evidence to prove that the appropriate consents or contracts were in-place for any (e.g.) marketing, training, or operational process at the other end of this transform.