Getting Started
End to end workflows
Create a campaign
Here are the steps to create a campaign of any type (Collect, Extend, Confirm):
- Data custodian authenticates.
- Data custodian creates/uploads a dataset. This can serve as the storage location for existing data that requires consent or as the data repository for newly collected data.
- Data custodian publishes a consent campaign to data owners.
- Data owners receive emails and accept/decline the consent requests.
- Data recipient downloads data and receives consented data based on the corresponding data sharing policy in the consent campaign.
Collect campaign payload includes a surveyContent field, which is the JSON object representing the preference request.
Create a data sharing policy
Here are the steps for setting up attribute-based conditional data sharing policies:
- Data custodian authenticates.
- Data custodian creates/uploads a dataset. This refers to the dataset or the location of the data that will be shared.
- Data custodian creates a data sharing policy and specifies the conditions under which each data recipient can receive specific attributes.
- Authorized data recipient subscribes to a policy.
- Data recipient downloads data from the data sharing policy.
Create a data retention policy
Here are the steps for setting up a data retention policy:
- Data custodian authenticates.
- Data custodian creates/uploads a dataset. This refers to the dataset or the location of the data that will be protected.
- Data custodian creates a data retention policy with protectionLevel set to 'AES,' validPeriod set to true, and specifies the values for 'validPeriodTime' and 'validPeriodUnit'.
- Authorized data recipient subscribes to a policy.
- Data recipient downloads data from the data sharing policy.
Details
We provide 3 test environments: Dev, Staging, Sandbox. The server URL for each environment can be found on the Swagger page. You can also download postman examples here.
Authenticate
In order to get your bearer authorization token, send a POST request to:
[server URL]/v1/users/login
The parameters required are
- username
- password
A successful response will provide you with your authorization token.
Connect to/upload a dataset
After you have successfuly retrieved your authorization token, you can use the token to create a dataset by sending a POST request to:
[server URL]/v2/datasources
The required parameter is "request", with a payload that looks like the example below:
{
"name": "",
"source": "POSTGRESQL",
"fields":[
{"level":0,"type":"folder","format":"","path":[""]},
{"level":1,"type":"folder","format":"string","path":["",""]},
{"level":1,"type":"folder","format":"string","path":["",""]}],
"datasourceConnection": {
"dbType": "postgresql",
"dbName": "",
"dbHost": "",
"dbPort": "",
"dbUsername": "",
"dbPassword": "",
"dbTable": ""
}
}
You will need to include different variables depends on the type of the dataset.
A successful response will include the Id of the dataset you just created.
Publish a consent campaign
You can create a consent campaign on an existing dataset. This can be:
- a dataset you have already collected but will require consents for downstream consumption
- an empty data location where data will be stored once it is collected
- an aggregated dataset
All datasets must include a column that contains the data owner's email address for publishing the campaign.
To create a campaign, send a POST request to:
[server URL]/v1/campaigns
The required parameter is "request", with a payload that looks like the example below:
{
"title": "",
"protectionLevel": "AES",
"reviewer":"",
"dataUsageDescription": "",
"dataUsageDuration": "",
"dataUsageDurationUnit": "",
"datasets": [
{
"datasetId": "",
"columnNameEmailOwner": "EMAIL",
"payloads": [
{
"attributes": [
{"path": ""},
{"path": ""}],
"conditions": [
{"columnName": "",
"operator": "EQUAL",
"value": ""}],
"recipients": [
{"recipient": ""}]
}
],
"rewards": [
{
"description": "",
"quantity": ""
}
],
"showMetaData": false
}
]
}
A successful response will include the ID of the campaign you just created.
When a campaign is created successfully, the campaign will be in draft mode. When you are ready to publish the campaign to data owners, you can send a POST request to:
[server URL]/v1/campaigns//publish
Create a policy
You can create a data sharing policy on an existing dataset by sending a POST request to:
[server URL]/v2/policies
The required parameter is "PolicyRequest", with a payload that looks like the example below:
{
"datasourceId": "",
"name": "",
"reviewer": "",
"protectionLevel": "NONE",
"approveSubscriber": false,
"subscriptionFee": 0,
"currencyType":"dollar",
"subscriptionType":"",
"updateFrequency": "",
"isRealTime":true,
"validPeriod":true,
"validPeriodTime":"Hours",
"validPeriodUnit":1,
"timezone":"America/New_York",
"description": "",
"dataAvailableTime": {
"publishTime": {
"time": "+00:00",
"day": 0
}
},
"rules":[
{"shareWith":[""],
"attributes":[
{"path":["",""],"fee":0},
{"path":["",""],"fee":0}],
"conditions":[{"column":"","operator":"EQUAL","value":""}]}]
}
A successful response will include the Id of the policy you just created.
Subscribe to a policy
All authorized data recipients can subscribe to a policy before consuming data. To subscribe to a policy, send a POST request to:
[server URL]/v2/policies/{policyId}/subscribe
Download data
The data custodian and all authorized data recipients can download data. To download data from a policy, send a GET request to:
[server URL]/v2/policies//data
If the data is encrypted, the above request will return the encrypted .enoc version of the data. You can download unencrypted data by sending a GET request to:
[server URL]/v2/policies//data/unencrypted
Conclusion
Congratulations on successfully completing an end-to-end workflow!
- To read about these endpoints more in-depth, please look at the pages within "Endpoints In-Depth".
- To view all of our existing endpoints and test out their functionality, please check out our Swagger page.
If you need assistance, don't hesitate to reach out to the One Creation Support Team.