Language

The first step in retrieving private data from a HAT is to submit a Data Debit request - POST /api/v2/data-debit/DATA_DEBIT_ID. The DATA_DEBIT_ID can be any valid URL path, however it needs to be unique on the HAT.

The general schema of a Data Debit is:

{
    "bundle": {
        "name": [String],
        "bundle": [Data Bundle Object]
    },
    "startDate": [ISO8601 Date],
    "endDate": [ISO8601 Date],
    "rolling": [Boolean]
}
ParameterTypeMeaning
DATADEBITIDURL PathID of the data debit - any valid URL path
nameStringUnique name of the data bundle
bundleData Bundle ObjectData Bundle specification - covered in a separate guide
startDateISO8601 DateWhen data sharing should start
endDateISO8601 DateWhen data sharing should finish
rollingBooleanWhether to automatically extend data sharing after the current period ends

As a concrete example, the below request asks for user profile together with location data - an example we used in the past.

curl --request POST \
  --url https://test.hubat.net/api/v2/data-debit/userprofile \
  --header 'content-type: application/json' \
  --header 'x-auth-token: ACCESS_TOKEN' \
  --data '{"bundle":{"name":"userprofile","bundle":{"profile":{"endpoints":[{"endpoint":"rumpel/profile"}],"limit":1},"location":{"endpoints":[{"endpoint":"rumpel/locations","mapping":{"longitude":"data.locations.longitude","latitude":"data.locations.latitude"}}],"limit":5}}},"startDate":"2017-05-13T09:32:47+00:00","endDate":"2017-06-13T09:32:47+00:00","rolling":false}'
var data = JSON.stringify({
  "bundle": {
    "name": "userprofile",
    "bundle": {
      "profile": {
        "endpoints": [
          {
            "endpoint": "rumpel/profile"
          }
        ],
        "limit": 1
      },
      "location": {
        "endpoints": [
          {
            "endpoint": "rumpel/locations",
            "mapping": {
              "longitude": "data.locations.longitude",
              "latitude": "data.locations.latitude"
            }
          }
        ],
        "limit": 5
      }
    }
  },
  "startDate": "2017-05-13T09:32:47+00:00",
  "endDate": "2017-06-13T09:32:47+00:00",
  "rolling": false
});

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://test.hubat.net/api/v2/data-debit/userprofile");
xhr.setRequestHeader("content-type", "application/json");
xhr.setRequestHeader("x-auth-token", "ACCESS_TOKEN");

xhr.send(data);
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://test.hubat.net/api/v2/data-debit/userprofile",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"bundle\":{\"name\":\"userprofile\",\"bundle\":{\"profile\":{\"endpoints\":[{\"endpoint\":\"rumpel/profile\"}],\"limit\":1},\"location\":{\"endpoints\":[{\"endpoint\":\"rumpel/locations\",\"mapping\":{\"longitude\":\"data.locations.longitude\",\"latitude\":\"data.locations.latitude\"}}],\"limit\":5}}},\"startDate\":\"2017-05-13T09:32:47+00:00\",\"endDate\":\"2017-06-13T09:32:47+00:00\",\"rolling\":false}",
  CURLOPT_HTTPHEADER => array(
    "content-type: application/json",
    "x-auth-token: ACCESS_TOKEN"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
import requests

url = "https://test.hubat.net/api/v2/data-debit/userprofile"

payload = "{\"bundle\":{\"name\":\"userprofile\",\"bundle\":{\"profile\":{\"endpoints\":[{\"endpoint\":\"rumpel/profile\"}],\"limit\":1},\"location\":{\"endpoints\":[{\"endpoint\":\"rumpel/locations\",\"mapping\":{\"longitude\":\"data.locations.longitude\",\"latitude\":\"data.locations.latitude\"}}],\"limit\":5}}},\"startDate\":\"2017-05-13T09:32:47+00:00\",\"endDate\":\"2017-06-13T09:32:47+00:00\",\"rolling\":false}"
headers = {
    'content-type': "application/json",
    'x-auth-token': "ACCESS_TOKEN"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)
require 'uri'
require 'net/http'

url = URI("https://test.hubat.net/api/v2/data-debit/userprofile")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["x-auth-token"] = 'ACCESS_TOKEN'
request.body = "{\"bundle\":{\"name\":\"userprofile\",\"bundle\":{\"profile\":{\"endpoints\":[{\"endpoint\":\"rumpel/profile\"}],\"limit\":1},\"location\":{\"endpoints\":[{\"endpoint\":\"rumpel/locations\",\"mapping\":{\"longitude\":\"data.locations.longitude\",\"latitude\":\"data.locations.latitude\"}}],\"limit\":5}}},\"startDate\":\"2017-05-13T09:32:47+00:00\",\"endDate\":\"2017-06-13T09:32:47+00:00\",\"rolling\":false}"

response = http.request(request)
puts response.read_body

If your request is valid and hence accepted by the HAT, the response will contain the HTTP 201 CREATED status, with the full specification of the data debit in the request body. It is important to reiterate, that both the Data Debit ID and the Bundle name must be unique - the former identifies the relationship between the user and an application, while the latter identifies the specific data being exchanged.