Data debit proposal

The first step in retrieving private data from a HAT PDA is to submit a Data Debit request — POST /api/v2.6/data-debit/$dataDebitKey. Where dataDebitKey can be any valid URL path, however it needs to be unique on the HAT. The request will fail otherwise.

The general schema of a Data Debit is:

{
	"bundle": "[DataBundle]",
    "conditions": "Optional[DataBundle]",
	"dataDebitKey": "[String]",
	"purpose": "[String]",
	"period": "[Int]",
	"termsUrl": "[String]",
	"cancelAtPeriodEnd": "[Boolean]",
	"requestClientName": "[String]",
	"requestClientUrl": "[String]",
	"requestClientLogoUrl": "[String]",
    "requestClientCallbackUrl": "Optional[String]",
	"requestApplicationId": "Optional[String]",
	"requestDescription": "Optional[String]",
	"start": "[String]"
}
Parameter Type Meaning
dataDebitKey URL Path ID of the data debit — any valid URL path
conditions Data Bundle Object Optional Data Bundle specification — covered in a separate guide
bundle Data Bundle Object Data Bundle specification — covered in a separate guide
start ISO8601 Date When data sharing should start
period Int The period that the data debit will be active. Value in seconds
purpose String The purpose of the data debit. Description of what it does and why it is needed
cancelAtPeriodEnd Boolean A value indicating if the data debit will continue after the specified period elapses
termsUrl URL A URL for the terms and conditions for that URL
requestClientName String The name of the company that created the data debit
requestClientUrl URL Company's website URL
requestClientLogoUrl URL Company's logo URL
requestClientCallbackUrl URL A callback url to be notified for new events
requestApplicationId URL Application id of the app requesting the data debit
requestDescription URL A description that accompanies the data debit request

As a concrete example, the below request asks for user profile together with location data.

{
	"bundle": {
		"name": "testbundlename",
		"bundle": {
			"profile": {
				"endpoints": [
					{
						"endpoint": "rumpel/profile"
					}
				],
				"limit": 1
			}
		}
	},
	"dataDebitKey": "testdatadebitkey",
	"purpose": "This is description of what the data debit is for",
	"period": 3600,
	"termsUrl": "termsurl",
	"cancelAtPeriodEnd": false,
	"requestClientName": "Data Debit Creator Name",
	"requestClientUrl": "https://data-debit-creator-website",
	"requestClientLogoUrl": "https://data-debit-creator-logo-url",
	"requestApplicationId": "applicationId",
	"requestDescription": "A short introduction for what the data debit is",
	"start": "2019-11-06T14:40:44.267Z"
}

If your request is valid and hence accepted by the HAT PDA, the response will be 201 CREATED status, with the full specification of the data debit in the request body. Please note that both the Data Debit ID and the Bundle name must be unique — Data Debit key identifies the relationship between the user and an application, while the Bundle name identifies the specific data being exchanged. The request will fail otherwise.