Introduction to Bosch Emergency Assistant

This provided API is to the BEA Gateway, rather than to the BEA Backend. Overall, the Bosch Emergency Assistant system is a combination of different services and libraries, which are depicted in below diagram:

The solution consist of the following components

  • Professional agents in the BEA call center
  • Several server backends for user/device registration, profile storage and secured, privacycompliant health data handling
  • Easy-to-use mobile SDK libraries for usage within Android and iOS applications, which encapsulate
    • Registration of a phone-number-verified user account
    • Phone number verification via SMS code procedure
    • Access to server backends for storage of user and (optionally) health data
    • Retrieving and preparing of all necessary emergency-related information in case of an emergency event
    • Transmission of emergency-related information (includes current positioning data, which is transferred frequently during an ongoing call) to the professional call-center via voice, IP and/or text message (fallback in case no data connection exists)
  • BEA gateway for connecting 3rd party systems to the professional BEA service in case you want to embed the emergency service into your own ecosystem, without using the mobile SDK
  • External or Bosch-provided identity provider systems (for multi-device synchronization and optional user authorization)

Data model and Privacy Notes

By using the provided BEA SDKs, the service allows end-users to register their devices, store general user information like name and birth date as well as store personal health data (PHD) as part of their emergency pass.

Storage of PHD data on our backend systems is optional for the end-user and not enabled by default. Please see following note for further information about how we secure health data within the BEA system.

The following table contains an overview over all data items, their classification and their storage place:

Note: The PHD data is stored encrypted and pseudonymized on a different system component, the SDS, in order to prevent an attacker on any of the systems to access/correlate confidential health data with a specific user. Additionally, the PHD data is always encrypted on the transport channel. If an user has chosen to not store his confidential health information any longer on our BEA backend server on all his connected devices, any previously stored data is removed from backend to respect user’s privacy setting. Please contact your BHCS partner if you need more information on implemented security mechanisms or further questions.

Table 1. BEA data and privacy overview

Data description Data properties Stored in
Health data (PHD) intolerances, indications,pharmaceuticals, blood_group (a) by default only on end-user’s local device; (b) in case of enabled serverside storage: Secure data store (SDS), encrypted, pseudonymized
Device data phone_hash, device_id, manufacturer_name, model_name, serial_number,device_type, device_resolution,OS_type, OS_version,lib_version, locale Device store within User Backend (UB), unencrypted
Emergency data timestamp, latitude, longitude, msisdn, direction, accuracyLevel, accurac On local device (temporarily) and Event Backend
Agent data for emergency type_of_ecall, cause, action, voice_recording Event Backend

Frequently Asked Questions

Below you can find some frequently asked questions about the Bosch Emergency Assistant, please feel free to send further questions to your BHCS partner if anything is missing in the documentation and you need more help.

Who can I (as a developer) contact in case questions?

Please send your questions to your BHCS contact partner.

What is the minimum Android API level that is supported?

API level 18 is the minimum version.

What is the minimum iOS version that is supported?

The iOS platform is supported from version 9.0 on.

How to choose whether mobile SDK or direct backend access is suited best for my business case?

Please address your specific use case and discuss them with your BHCS contact partner.

What happens to an user’s health data on the backend if he disables server-side storage for PHD?

The confidential user data is removed from our backend if server-side storage is disabled on all connected devices.

How can I (as a B2B partner) restrict usage of the service to my customer-base or even a subset of them?

The BEA system allows integration of an additional authorization step, which requires end-users to login to your identity service via OpenID Connect protocol before they can use the emergency service. See section Service authorization models for details.

Service authorization models

The Bosch Emergency Assistant backend provides different models for you as a tenant of the system of how and when end-users will be authorized to use the emergency service. As of today you can embed the service into your application either with implicit permissions granted or via integrating an additional step for verifying that the end-user is registered within your ecosystem. In detail the options look like below:

  1. Each user who uses your app and finishes the BEA device registration flow is allowed to trigger emergency calls
  2. Only end-users who are registered on your identity management system are allowed to trigger an emergency call
  3. Only the subset of your end-users are allowed to trigger an emergency call:
    1. Who are registered on your identity management system, and
    2. Which have a special user role or claim set within

Please clarify with your BHCS contact partner which option should be used for your business and which requirements apply.

In general the current validation of external permissions is based on user-login to your identity management system via the OpenID Connect protocol flow, a layer on top of OAuth2.

Backend Gateway Public API

The public backend gateway is intended for use by systems and applications that are not based on an mobile application, but rather want the BEA integrated directly into a client or backend system.

For access to the backend API you’ll also need to have a valid contract with BHCS, and you’ll get a tenant identifier to be used in all requests.

Note: Depending on the type of integration (access by end-user clients or access by trusted 3rd party backend) different authentication options are planned. Currently only pre-shared access secrets are defined and need to be provided in each request, in a future version also other authentication options like client certificates are planned.

Integration options into client systems

The BEA allows for different levels of integration into your own client backend system by optionally providing hooks:

  • No additional authorisation of end-users, all requests will be accepted by BEA
  • A hook for verification of end-user’s service authorisation is provided by your backend, which gets a user identifier (e.g. id, phone hash) and returns with a true/false response
  • Both a hook for verification of end-user’s service authorisation as well as a hook for retrieval of additional user date is used
Note: Above hooks are not yet part of the documentation, please get in contact with your Bosch contact in order to get details for this.

Limitations

The backend gateway can only be used for directly triggering an emergency event to the BEA service, but does not include any user management or server-side storage of personal or health related user information.

You can, though, provide user-related information within the data that you send to the BEA service, which can (and should) contain at least a user’s first and last name as well as a valid phone number that can be used for callback by the service agents.

Example request for raising an event

Visit the Get Started page for more information.

API Reference

POST /event

Description

This is the single endpoint which is directly to be triggered by all 3rd party backends in order to create an event.

Parameters

Type Name Required Description Schema
Header bes-tenant-id Yes The UUID-formatted tenant id which is provided to the tenant upon tenant set-up, in order to identify incoming requests string (uuid)
Body event Yes The defined set of data for an event Event

Responses

HTTP Code Description Schema
200 OK Event.Response
412 PreconditionFailedError Error

Security

Type Name
apiKey auth_bes_tenant

Example HTTP request

                          
curl -i -X POST \
   -H "bes-tenant-id:093f4bec-d307-4c55-9538-2708c5eb7040" \
   -H "KeyId: ADD_YOUR_API_KEY_HERE" \
   -H "Content-Type:application/json" \
   -d \
'{
  "version": "3.0",
  "msisdn": "+491234567890",
  "identifier": "e8bd567e917e41a827e93d920c096d24306dd9378394540df7fd94a611e96439",
  "reporting_id": "cd0a781beaa5cb2d3a320c25f10260e26e166313591f8e1792c28805bc3ba804",
  "tenant_key": "BSO20",
  "event_id": "220529a2-cbde-4d69-940b-7931c03069c9",
  "monitoringRequestFlag": false,
  "msd": {
    "geoPosition": {
      "accuracyLevel": "fused",
      "timeStamp": "2017-07-11T13:54:34.181Z",
      "latitude": 52.5019859,
      "longitude": 13.4484715,
      "accuracy": 15,
      "direction": -1
    },
    "language": "en",
    "timeStamp": "2017-07-11T13:54:34.181Z",
    "event_type": 1,
    "event_cause": 2,
    "event_context_info": [
      "+491234567890",
      "+491357924680"
    ],
    "call_handling": "voice",
    "trigger_type": "manual",
    "test": true
  },
  "esd": {
    "user_confidential": "$AES/GCM/PKCS5Padding$XQl5It8g+JgpWl83/WXOyg==$TysCsHQN5XVcY5u03k9xa3e5FSvowgDCibeg1JI68JRs63KGJk6niSpL73JK7qn8hw/fDuGwaD7hCNEL40DBSBD8ibtxJOKrq5VgB2HXC8hP9+z5HN7cCBg0fNIshMZRoYSLv3bLiue05SD36fX1Mw==",
    "user_meta": {
      "salutation": "string",
      "first_name": "Anna",
      "last_name": "Bell",
      "date_of_birth": "2017-07-06T00:00:00.000Z",
      "emergency_contacts": [
        {
          "salutation": "string",
          "first_name": "Lara",
          "last_name": "Lee",
          "phone_hash": "9a37cb57951ef945a6d9a9c32299ba62b3b7c4acddf26c1b5adebccc6a8ba87a",
          "phone_number": "+492222222222"
        }
      ],
      "mail": "anna.bell@domain.com"
    }
  }
}' \
 'https://ews-emea.api.bosch.com/healthcare/sandbox/emergency-assistant/gate/v1/event'