Method Request Body Response Status Response Content-Type Response Body POST <ManagementURI>/ service-provider/ operator JSON Object 200 (OK) None None 410 (Gone) application/json JSON Object Content of the request body JSON object: Key Type Description Required OperatorID String A Pseudonymous Key generated by an IDA and associated with the Operator being registered. Yes TimeStamp String Time stamp, in DateTime format, of the OperatorID indicating when the IDA created this Pseudonymous Key. Yes Signature String Signature proving that an IDA created this OperatorID. Yes Content of the response body JSON object: Key Type Description Required Reason String An OPTIONAL description of why the registration failed. No Example Example request message: POST service-provider/operator {"OperatorID": "00000000-0000-0000-0000-000000000000", "TimeStamp": "2011-02-14T00:00:00", "Signature": Example response message: HTTP/1.1 410 Gone {"Reason":"Operator was not valid."} Service Provider: Retrieve Operator List A Service Provider uses this operation to retrieve a list of all registered Operators registered to the requesting Service Provider. If successful, an HTTP status code of 200 OK MUST be returned. If unsuccessful, an HTTP error code SHOULD be returned and a JSON object MAY be returned providing some explanation of the failure. Method Request Body Response Status Response Content-Type Response Body
OperatorID String A Pseudonymous Key generated by an IDA and associated with the Operator to be resumed. Yes Content of the response body JSON object in the case of an error: Key Type Description Required Reason String An OPTIONAL description of why the request failed. No Example Example request message: POST service-provider/resumeOperator {"OperatorID": "00000000-0000-0000-0000-000000000000"} Example response message: HTTP/1.1 200 OK Service Provider: Register Devices All Devices associated with a Service Provider are registered in advance of assigned to a Consumer. Register Devices associates one or more Devices with Service Provider, assigns each a device type (Personal or IoT), and validates the Pseudonymous Key of the Device. A Device SHALL be registered only once. Only Operators associated with the registering Service Provider MAY assign the Device to a Consumer. If successful, an HTTP status code of 200 OK MUST be returned. If unsuccessful, an HTTP error code SHOULD be returned and a JSON object MAY be returned providing some explanation of the failure. If validation of the DeviceIDs fails, with a 410 (Gone) error from the IDA, an error 410 (Gone) SHOULD be returned. If any of the DeviceIDs is already in use for another Service Provider, Operator, Consumer or Device, an error 410 (Gone) SHOULD be returned. Method Request Body Response Status Response Content-Type Response Body POST <ManagementURI>/ JSON Object 200 (OK) None None Error code application/json JSON Object Content of the request body JSON object: Key Type Description Required DeviceIDs Array of String An array of Pseudonymous Keys associated with the Devices and generated by an IDA. Yes TimeStamp String Time stamp, in DateTime format, indicating when the IDA created these Pseudonymous Keys. Yes
Key Type Description Required ConsumerID String A Pseudonymous Key representing the requesting Consumer who is the subject of the query. Yes OperatorID String A Pseudonymous Key representing the Consumer’s Operator. Yes TimeWindow Object Indicates start and end time for Atom selection. No StartTime Number Start of time interval to be included in the query. Time in seconds since 1/1/1970 UTC. If absent, 1/1/1970 is assumed. Atoms SHALL be included if their time stamp is between the StartTime and the EndTime. No EndTime Number End of time interval to be included in the query. Time in seconds since 1/1/1970 UTC. If absent, infinity is assumed. Atoms SHALL be included if their time stamp is between the StartTime and the EndTime. No Object The element describing the overall structure of the query. No Filter Object The element describing Atoms to use in the query. No ColName String Column name. No Comparator String One of "=", ">", ">=", "<", "<=", "!=". No Value String Comparison value. No Aggregate Object The element describing how to aggregate values selected in the query. No Columns Array of Object An indicating which columns to aggregate and how to aggregate them. No Aggregator String One of AVG, SUM, COUNT, MIN, MAX, STDDEV. No ColName String Column name. No GroupBy Array of String One or more Column Names to group by. Each unique combination of the values included in the GroupBy element SHALL result in a separate row in the Table element. No Response (200) Content of the response body JSON object when a 200 (OK) status code is returned is either: An array of Atoms; or A table of data (resulting from an aggregate query). Note: Atoms MAY be returned either in the version in which they were originally stored or in the currently supported version. The following JSON Schema defines the structure, spelling and basic type of each element and The response body MUST comply with this schema, and with the additional constraints specified in the remainder of this section. { "$schema": "http://json-schema.org/draft-04/schema#", "type": "object",
Body Content-Type POST <QueryURI>/segment JSON Object 200 (OK) application/json JSON Object (SegmentData) Error code application/json JSON Object (Reason) Content of the request body JSON object: Key Type Description Required ConsumerID String A Pseudonymous Key representing the requesting Consumer who is the subject of the segment data request. Yes OperatorID String A Pseudonymous Key representing the Consumer’s Operator. Yes Content of the response body JSON object when a 200 (OK) status code is returned: Key Type Description Required SegmentData Object An object containing residential time zone and latitude, gender, and year of birth. The field names are ResidentTimeZone, ResidentLatitude, Gender and YearOfBirth. No ResidentTimeZone String The time zone in which the Consumer generally resides, as a string indicating +/-hh:mm from UTC (e.g "-05:00"). No ResidentLatitude Number The latitude (rounded to an integer) at which the Consumer generally resides. No Gender Number Integer representing the gender of the Consumer, 0 = not known; 1 = male; 2 = female; 9 = not applicable. No YearOfBirth Number Year in which the Consumer was born as an integer. No The Gender parameter SHALL have enumerated fields reserved for compliance with [ISO/IEC 5218]. Content of the response body JSON object in the case of an Key Type Description Required Reason String An OPTIONAL description of why the request failed. No Example Example request messages: POST segment {"ConsumerID" : "ed58fc40-a866-11e4-bcd8-0800200c9a66", "OperatorID" : "fd58dc41-a856-31d4-5558-6534237776ac"}