Osano PII API Documentation
Osano provides one endpoint with two methods for storing and retrieving data from the secure PII data store.
Storing personal data to the API requires an understanding of how the Osano API encrypts data. Keys are stored in plain text while values are one-way encrypted using SHA512 and a salt that is unique to each Osano customer.
The Osano API leverages a high throughput, private blockchain document storage engine. Due to the immutable nature of blockchain storage, entries are cryptographically verifiable and well suited for use in litigation or wherever proving that records have not been modified may be important.
Authorization
Each account is issued a single API key with full read/write access to the data under your account.
Authorization is performed by including the x-api-key key/value pair in the header of your request, such as in the below example.
curl -X GET -H "x-api-key: your-osano-api-key" -H "Content-Type: application/json" -d '{"key":"val"}' https://pii.api.osano.com
Storing Data
Method: POST
Note: All values inside of the data object are one-way encrypted and can not be unencrypted but can be searched against.
| Key | Data Type | Required? | Description |
| destination | String | Y |
The freeform name of a vendor with whom this data has been shared (e.g. Salesforce).
|
| source | String | Y |
The freeform name of a datasource where this information has been stored (e.g. SQL Server - US East).
|
| cid | String | N |
The customer-defined unique identifier. The cid should never contain personal data.
|
| data | Object | Y |
JSON Object containing key/value pairs of personal data. Keys are stored in plain text, while values are one-way encrypted. Keys should never contain personal data.
|
Example of recording the storing new personal data with a 3rd party vendor:
curl -X POST -H "x-api-key: your-osano-api-key" -H "Content-Type: application/json" -d '{"destination":"Salesforce Sales Cloud", "source": "MySQL user table emails", "cid": "myuniqueid", "data": {"ssn": "123-45-6789", "dob": "01/11/1971" }}' "https://pii.api.osano.com/update"
On successful storage you will receive a status 200 message with the Osano id in the following format:
{"oid": "11111111-2222-3333-4444-555555555555"}
Supplying the Osano id as part of the POST payload will update an existing record, for example, the payload to add an email address to an existing record:
{"oid": "11111111-2222-3333-4444-555555555555": "destination":"Salesforce Sales Cloud", "source": "MySQL user table emails", "cid": "myuniqueid", "data": {"email": "me@my.com", "ssn": "123-45-6789", "dob": "01/11/1971"}}
Retrieving Data
Note: One-way encrypted personal data can be checked for existence and to identify the vendor, data source, Osano and customer identifiers but the data itself cannot be decrypted and therefore cannot be retrieved.
Example of retrieving the data source data for a particular user:
curl -X GET -H "x-api-key: your-osano-api-key" "https://pii.api.osano.com/search?key=ssn&val=123-45-6789"
If a matching record(s) is found Osano will respond with a HTTP Status 200 and the data in the following format:
[ {
"created": 1585917999999,
"updated": 1585917999999,
"source": "MySQL user table emails",
"destination": "Salesforce Sales Cloud",
"oid": "11111111-2222-3333-4444-555555555555",
"cid": "123456789abcdefg",
"fields": [
"dob",
"ssn"
]
},
{
"created": 1585918000000,
"updated": 1585918000000,
"source": "Wordpress",
"destination": "Stripe",
"oid": "66666666-7777-8888-9999-aaaaaaaaaaaa",
"cid": "123456789abcdefg",
"fields": [
"dob",
"ssn"
]
}
]
If no record is found an HTTP status 404 is returned.