Sentiance Graphql V4

An intro to Sentiance's version 4 Graphql API.

Contact

Support

support@sentiance.com

Terms of Service

https://sentiance.com/terms

API Endpoints
# Endpoint:
https://api.sentiance.com/v4/gql
Headers
Authorization: Bearer <YOUR_API_KEY_HERE>

Intro

Our API primarily speaks GraphQL (GQL, for short). While explaining how GraphQL works is beyond the scope of this guide, there are excellent resources available on the interwebs. Here we will introduce the basic request-response structure of the Sentiance GraphQL API.

Endpoint and Authorization

Our default GraphQL endpoint lives at POST https://api.sentiance.com/v4/gql and accepts the same bearer token based authorization. We adhere to the GraphQL specification but do not support multiple operation types. Since it is possible for a single HTTP request to encompass multiple GraphQL queries with some of them succeeding and some of them failing, the endpoint always returns a 200 OK, unless something severe enough happens on the server-side to guarantee failure of the entire response (such as a 500 status code). After checking for the 200 status code, please also check the body of the response for data and error properties.

Queries

engagement

Description

Engagement data.

Response

Returns an Engagement

Example

Query
query Engagement {
  engagement {
    group {
      created_at
      feed {
        ...UserEngagementGroupFeedFragment
      }
      group_id
      leaderboard {
        ...UserEngagementGroupLeaderboardFragment
      }
      members {
        ...UserEngagementGroupMembersFragment
      }
      name
      points_of_interest {
        ...UserEngagementGroupPoisFragment
      }
      reg_code
    }
  }
}
Response
{"data": {"engagement": {"group": UserEngagementGroup}}}

offloads

Response

Returns [Offload]

Arguments
Name Description
from - String
to - String

Example

Query
query Offloads(
  $from: String,
  $to: String
) {
  offloads(
    from: $from,
    to: $to
  ) {
    day
    files {
      format
      link {
        ...LinkFragment
      }
      name
      size
    }
    type
  }
}
Variables
{
  "from": "abc123",
  "to": "xyz789"
}
Response
{
  "data": {
    "offloads": [
      {
        "day": "2023-03-04",
        "files": [OffloadFile],
        "type": "OFFLOAD_TYPE_PRIMARY_SAFETY_SCORES_USER"
      }
    ]
  }
}

transport

Response

Returns a Transport

Arguments
Name Description
transport_id - String

Example

Query
query Transport($transport_id: String) {
  transport(transport_id: $transport_id) {
    additional_mobility_details {
      raw_data_points {
        ...RawDataPointsFragment
      }
    }
    crash_events {
      crash_event {
        ...CrashEventFragment
      }
    }
    driving_events {
      accelerating {
        ...AcceleratingEventFragment
      }
      braking {
        ...BrakingEventFragment
      }
      calls {
        ...CallEventFragment
      }
      mounted {
        ...MountedEventFragment
      }
      phone_handling {
        ...PhoneHandlingEventFragment
      }
      screens {
        ...ScreenEventFragment
      }
      speeding {
        ...SpeedingEventFragment
      }
      turning {
        ...TurningEventFragment
      }
    }
    duration
    end_at
    metadata
    mode
    occupant_role
    scores {
      safety {
        ...TransportScoresSafetyFragment
      }
    }
    start_at
    top_speed
    trajectory {
      distance
      end_location {
        ...LocationInformationFragment
      }
      map_matched_waypoints {
        ...MapMatchedWaypointFragment
      }
      polyline
      start_location {
        ...LocationInformationFragment
      }
      top_speed
    }
    transport_id
    weather_data {
      weather_at_destination {
        ...WeatherDataFragment
      }
      weather_at_origin {
        ...WeatherDataFragment
      }
    }
  }
}
Variables
{"transport_id": "abc123"}
Response
{
  "data": {
    "transport": {
      "additional_mobility_details": AdditionalMobilityDetails,
      "crash_events": CrashEventsForTransport,
      "driving_events": TransportDrivingEvents,
      "duration": 123,
      "end_at": "xyz789",
      "metadata": "abc123",
      "mode": "abc123",
      "occupant_role": "abc123",
      "scores": TransportScores,
      "start_at": "abc123",
      "top_speed": 987.65,
      "trajectory": TransportTrajectory,
      "transport_id": "abc123",
      "weather_data": TransportWeatherData
    }
  }
}

user

Response

Returns a User

Arguments
Name Description
user_id - String Sentiance ID of the user. This is the ID of the user in the Sentiance platform. If both user_id and external_id are provided, user_id will be used.
external_id - String External ID of the user. This is the ID of the user in your system. External ID based queries are only supported for API Keys. If both user_id and external_id are provided, user_id will be used.

Example

Query
query User(
  $user_id: String,
  $external_id: String
) {
  user(
    user_id: $user_id,
    external_id: $external_id
  ) {
    app_id
    created_at
    diagnostics {
      off_the_grids {
        ...OffTheGridFragment
      }
    }
    engagement {
      aggregations {
        ...UserEngagementAggregationsFragment
      }
      badges {
        ...UserEngagementBadgesFragment
      }
      challenges {
        ...UserEngagementChallengesFragment
      }
      communications {
        ...UserEngagementCommunicationsFragment
      }
      groups {
        ...UserEngagementGroupsFragment
      }
      library {
        ...UserEngagementLibraryFragment
      }
      scores {
        ...UserEngagementScoresFragment
      }
      streaks {
        ...UserEngagementStreaksFragment
      }
      transport {
        ...UserEngagementTransportFragment
      }
      transports {
        ...UserEngagementTransportsFragment
      }
    }
    external_id
    feedback_events {
      created_at
      event_id
      meta_info {
        ...FeedbackEventMetaInfoFragment
      }
      reason
      type
      updated_at
      user_id
    }
    scores {
      driving {
        ...UserScoresDrivingFragment
      }
    }
    transports {
      additional_mobility_details {
        ...AdditionalMobilityDetailsFragment
      }
      crash_events {
        ...CrashEventsForTransportFragment
      }
      driving_events {
        ...TransportDrivingEventsFragment
      }
      duration
      end_at
      metadata
      mode
      occupant_role
      scores {
        ...TransportScoresFragment
      }
      start_at
      top_speed
      trajectory {
        ...TransportTrajectoryFragment
      }
      transport_id
      weather_data {
        ...TransportWeatherDataFragment
      }
    }
    user_id
  }
}
Variables
{
  "user_id": "abc123",
  "external_id": "abc123"
}
Response
{
  "data": {
    "user": {
      "app_id": "xyz789",
      "created_at": "xyz789",
      "diagnostics": Diagnostics,
      "engagement": UserEngagement,
      "external_id": "xyz789",
      "feedback_events": [FeedbackEvent],
      "scores": UserScores,
      "transports": [Transport],
      "user_id": "xyz789"
    }
  }
}

Mutations

abandon_challenge

Description

Mutation for abandoning a challenge.

Response

Returns an AbandonUserEngagementChallenge

Arguments
Name Description
challenge_id - String ID of the challenge to be abandoned.

Example

Query
mutation Abandon_challenge($challenge_id: String) {
  abandon_challenge(challenge_id: $challenge_id) {
    status
  }
}
Variables
{"challenge_id": "abc123"}
Response
{"data": {"abandon_challenge": {"status": false}}}

accept_challenge

Description

Mutation for accepting a challenge.

Response

Returns an AcceptUserEngagementChallenge

Arguments
Name Description
challenge_id - String ID of the challenge to be accepted.

Example

Query
mutation Accept_challenge($challenge_id: String) {
  accept_challenge(challenge_id: $challenge_id) {
    status
  }
}
Variables
{"challenge_id": "abc123"}
Response
{"data": {"accept_challenge": {"status": true}}}

approve_group_join

Description

Mutation for approving a user to join a group.

Response

Returns an ApproveUserEngagementJoin

Arguments
Name Description
group_id - String ID of the group.
pending_user_id - String Sentiance ID of the user to be accepted.

Example

Query
mutation Approve_group_join(
  $group_id: String,
  $pending_user_id: String
) {
  approve_group_join(
    group_id: $group_id,
    pending_user_id: $pending_user_id
  ) {
    status
  }
}
Variables
{
  "group_id": "xyz789",
  "pending_user_id": "xyz789"
}
Response
{"data": {"approve_group_join": {"status": true}}}

create_fake_transport

Description

Mutation for creating a fake transport.

Response

Returns a CreateFakeTransport

Arguments
Name Description
mode - CreateFakeTransportRequest_TransportModeEnum Mode of the transport.
safety_scores - CreateFakeTransportRequest_SafetyScoresInput Safety scores for the transport. Only applies to some transport modes: CAR, BUS, MOTORCYCLE.
with_crash_events - Boolean Flag to include crash events in the transport. Not yet implemented.
with_trajectory - Boolean Flag to include trajectory in the transport payload. Trajectory is the list of waypoints (lat, long) of the transport. We use the trajectory to determine the total distance of the transport.
user_id - String Sentiance ID of the user.

Example

Query
mutation Create_fake_transport(
  $mode: CreateFakeTransportRequest_TransportModeEnum,
  $safety_scores: CreateFakeTransportRequest_SafetyScoresInput,
  $with_crash_events: Boolean,
  $with_trajectory: Boolean,
  $user_id: String
) {
  create_fake_transport(
    mode: $mode,
    safety_scores: $safety_scores,
    with_crash_events: $with_crash_events,
    with_trajectory: $with_trajectory,
    user_id: $user_id
  ) {
    transport_id
  }
}
Variables
{
  "mode": "UNKNOWN",
  "safety_scores": CreateFakeTransportRequest_SafetyScoresInput,
  "with_crash_events": true,
  "with_trajectory": true,
  "user_id": "xyz789"
}
Response
{
  "data": {
    "create_fake_transport": {
      "transport_id": "xyz789"
    }
  }
}

create_feedback_event

Description

Mutation for creating a feedback event.

Response

Returns a CreateFeedbackEvent

Arguments
Name Description
event_id - String ID of the transport/event.
type - FeedbackTypeEnum Type of feedback.
reason - String Reason feedback is provided.
meta_info - FeedbackEventMetaInfoInput Meta information for the feedback event.

Example

Query
mutation Create_feedback_event(
  $event_id: String,
  $type: FeedbackTypeEnum,
  $reason: String,
  $meta_info: FeedbackEventMetaInfoInput
) {
  create_feedback_event(
    event_id: $event_id,
    type: $type,
    reason: $reason,
    meta_info: $meta_info
  ) {
    feedback_event {
      created_at
      event_id
      meta_info {
        ...FeedbackEventMetaInfoFragment
      }
      reason
      type
      updated_at
      user_id
    }
  }
}
Variables
{
  "event_id": "abc123",
  "type": "FEEBACK_TYPE_UNKNOWN",
  "reason": "abc123",
  "meta_info": FeedbackEventMetaInfoInput
}
Response
{
  "data": {
    "create_feedback_event": {
      "feedback_event": FeedbackEvent
    }
  }
}

create_group

Description

Mutation for creating a new group.

Response

Returns a CreateUserEngagementGroup

Arguments
Name Description
name - String Name of the new group.
group_type - UserEngagementGroupTypeEnum Type of the new group. Supported types: SOCIAL.
origin - String A String representing the origin of the group. Ex: 'client_app', 'web_platform', etc
ranking_attributes - [UserEngagementGroupRankingAttributeEnum] Ranking attributes to be used for the group leaderboard. Available options: DRIVER_COACHING_SCORE.
features - CreateUserEngagementGroupRequest_UserEngagementGroupFeaturesInput Features to be enabled for the group.

Example

Query
mutation Create_group(
  $name: String,
  $group_type: UserEngagementGroupTypeEnum,
  $origin: String,
  $ranking_attributes: [UserEngagementGroupRankingAttributeEnum],
  $features: CreateUserEngagementGroupRequest_UserEngagementGroupFeaturesInput
) {
  create_group(
    name: $name,
    group_type: $group_type,
    origin: $origin,
    ranking_attributes: $ranking_attributes,
    features: $features
  ) {
    group {
      created_at
      feed {
        ...UserEngagementGroupFeedFragment
      }
      group_id
      leaderboard {
        ...UserEngagementGroupLeaderboardFragment
      }
      members {
        ...UserEngagementGroupMembersFragment
      }
      name
      points_of_interest {
        ...UserEngagementGroupPoisFragment
      }
      reg_code
    }
    status
  }
}
Variables
{
  "name": "xyz789",
  "group_type": "SOCIAL",
  "origin": "xyz789",
  "ranking_attributes": ["DRIVER_COACHING_SCORE"],
  "features": CreateUserEngagementGroupRequest_UserEngagementGroupFeaturesInput
}
Response
{
  "data": {
    "create_group": {
      "group": UserEngagementGroup,
      "status": false
    }
  }
}

create_group_poi

Description

Mutation for creating a new group POI.

Response

Returns a CreateUserEngagementGroupPoi

Arguments
Name Description
group_id - String ID of the group.
poi - EngagementPOIInput Point of Interest to be created.

Example

Query
mutation Create_group_poi(
  $group_id: String,
  $poi: EngagementPOIInput
) {
  create_group_poi(
    group_id: $group_id,
    poi: $poi
  ) {
    status
  }
}
Variables
{
  "group_id": "abc123",
  "poi": EngagementPOIInput
}
Response
{"data": {"create_group_poi": {"status": false}}}

decline_group_join

Description

Mutation for declining a user to join a group.

Response

Returns a DeclineUserEngagementJoin

Arguments
Name Description
group_id - String ID of the group.
pending_user_id - String Sentiance ID of the user to be declined.

Example

Query
mutation Decline_group_join(
  $group_id: String,
  $pending_user_id: String
) {
  decline_group_join(
    group_id: $group_id,
    pending_user_id: $pending_user_id
  ) {
    status
  }
}
Variables
{
  "group_id": "xyz789",
  "pending_user_id": "abc123"
}
Response
{"data": {"decline_group_join": {"status": true}}}

delete_feedback_event

Description

Mutation for deleting a feedback event.

Response

Returns a DeleteFeedbackEvent

Arguments
Name Description
event_id - String ID of the transport/event.
type - FeedbackTypeEnum Type of feedback.

Example

Query
mutation Delete_feedback_event(
  $event_id: String,
  $type: FeedbackTypeEnum
) {
  delete_feedback_event(
    event_id: $event_id,
    type: $type
  ) {
    status
  }
}
Variables
{
  "event_id": "xyz789",
  "type": "FEEBACK_TYPE_UNKNOWN"
}
Response
{"data": {"delete_feedback_event": {"status": true}}}

delete_group

Description

Mutation for deleting a group.

Response

Returns a DeleteUserEngagementGroup

Arguments
Name Description
group_id - String ID of the group to delete.

Example

Query
mutation Delete_group($group_id: String) {
  delete_group(group_id: $group_id) {
    status
  }
}
Variables
{"group_id": "xyz789"}
Response
{"data": {"delete_group": {"status": false}}}

delete_group_poi

Description

Mutation for deleting a group POI.

Response

Returns a DeleteUserEngagementGroupPoi

Arguments
Name Description
group_id - String ID of the group.
poi_id - String ID of the Point of Interest.

Example

Query
mutation Delete_group_poi(
  $group_id: String,
  $poi_id: String
) {
  delete_group_poi(
    group_id: $group_id,
    poi_id: $poi_id
  ) {
    status
  }
}
Variables
{
  "group_id": "abc123",
  "poi_id": "abc123"
}
Response
{"data": {"delete_group_poi": {"status": false}}}

delete_user

Response

Returns a DeleteUserById

Arguments
Name Description
id - String

Example

Query
mutation Delete_user($id: String) {
  delete_user(id: $id) {
    request_id
  }
}
Variables
{"id": "abc123"}
Response
{
  "data": {
    "delete_user": {"request_id": "xyz789"}
  }
}

generate_auth_code

Response

Returns a GenerateAuthCode

Arguments
Name Description
external_id - String

Example

Query
mutation Generate_auth_code($external_id: String) {
  generate_auth_code(external_id: $external_id) {
    authentication_code
    expires_at
  }
}
Variables
{"external_id": "abc123"}
Response
{
  "data": {
    "generate_auth_code": {
      "authentication_code": "abc123",
      "expires_at": "xyz789"
    }
  }
}

generate_offload_url

Response

Returns a GenerateUrl

Arguments
Name Description
day - String
offload_type - OffloadTypeEnum

Example

Query
mutation Generate_offload_url(
  $day: String,
  $offload_type: OffloadTypeEnum
) {
  generate_offload_url(
    day: $day,
    offload_type: $offload_type
  ) {
    offload {
      day
      files {
        ...OffloadFileFragment
      }
      type
    }
  }
}
Variables
{
  "day": "abc123",
  "offload_type": "OFFLOAD_TYPE_PRIMARY_SAFETY_SCORES_USER"
}
Response
{"data": {"generate_offload_url": {"offload": Offload}}}

join_group

Description

Mutation for joining an existing group.

Response

Returns a JoinUserEngagementGroup

Arguments
Name Description
reg_code - String Registration code of the group.

Example

Query
mutation Join_group($reg_code: String) {
  join_group(reg_code: $reg_code) {
    status
  }
}
Variables
{"reg_code": "xyz789"}
Response
{"data": {"join_group": {"status": false}}}

leave_group

Description

Mutation for leaving a group the user is part of.

Response

Returns a LeaveUserEngagementGroup

Arguments
Name Description
group_id - String ID of the group.

Example

Query
mutation Leave_group($group_id: String) {
  leave_group(group_id: $group_id) {
    status
  }
}
Variables
{"group_id": "abc123"}
Response
{"data": {"leave_group": {"status": false}}}

make_group_admin

Description

Mutation for making a user an admin of a group.

Response

Returns a MakeUserEngagementGroupAdmin

Arguments
Name Description
group_id - String ID of the group.
new_admin_user_id - String Sentiance ID of the user to be made admin.

Example

Query
mutation Make_group_admin(
  $group_id: String,
  $new_admin_user_id: String
) {
  make_group_admin(
    group_id: $group_id,
    new_admin_user_id: $new_admin_user_id
  ) {
    status
  }
}
Variables
{
  "group_id": "xyz789",
  "new_admin_user_id": "abc123"
}
Response
{"data": {"make_group_admin": {"status": false}}}

remove_group_membership

Description

Mutation for removing a user from a group.

Arguments
Name Description
group_id - String ID of the group.
removed_user_id - String Sentiance ID of the user to be removed.

Example

Query
mutation Remove_group_membership(
  $group_id: String,
  $removed_user_id: String
) {
  remove_group_membership(
    group_id: $group_id,
    removed_user_id: $removed_user_id
  ) {
    status
  }
}
Variables
{
  "group_id": "xyz789",
  "removed_user_id": "abc123"
}
Response
{"data": {"remove_group_membership": {"status": true}}}

set_in_group_status

Description

Mutation for setting the status of a user in a group.

Response

Returns a SetUserEngagementGroupStatus

Arguments
Name Description
group_id - String ID of the group.
status - String Status of the group. Any String to represent the status of the group. Empty String for no status/removing status
expire_in - Int Time in seconds after which the status will expire. Default: 1 year (31.536.000 seconds)

Example

Query
mutation Set_in_group_status(
  $group_id: String,
  $status: String,
  $expire_in: Int
) {
  set_in_group_status(
    group_id: $group_id,
    status: $status,
    expire_in: $expire_in
  ) {
    status
  }
}
Variables
{
  "group_id": "xyz789",
  "status": "abc123",
  "expire_in": 123
}
Response
{"data": {"set_in_group_status": {"status": false}}}

submit_log_event

Description

Mutation for submitting log events.

Response

Returns a SubmitLogEvent

Arguments
Name Description
event_params - [SubmitLogEventRequest_EventParamsEntryInput] Map of parameters for the event.
event_name - String Name of the event.

Example

Query
mutation Submit_log_event(
  $event_params: [SubmitLogEventRequest_EventParamsEntryInput],
  $event_name: String
) {
  submit_log_event(
    event_params: $event_params,
    event_name: $event_name
  ) {
    message
    status
  }
}
Variables
{
  "event_params": [
    SubmitLogEventRequest_EventParamsEntryInput
  ],
  "event_name": "abc123"
}
Response
{
  "data": {
    "submit_log_event": {
      "message": "xyz789",
      "status": false
    }
  }
}

submit_transport_feedback

Description

Mutation for submitting transport feedback.

Response

Returns a TransportFeedback

Arguments
Name Description
entity_id - String ID of the entity feedback is provided for.
entity_type - String Type of entity. Available options: TRIP, CHALLENGE.
reason - String Reason feedback is provided. Available options: GENERIC, WAS_PASSENGER, WAS_DRIVER, WAS_FOCUSED, NOT_CAR_TRIP, VALID
context - [TransportFeedbackRequest_ContextEntryInput] Map of attributes describing the context feedback was provided.
grace - Boolean Flag for type of feedback. Adjusting a trip (true) or deleting a trip (false)
origin - String Where the feedback originated from. Ex: Trips_page, Challenges_page, etc.

Example

Query
mutation Submit_transport_feedback(
  $entity_id: String,
  $entity_type: String,
  $reason: String,
  $context: [TransportFeedbackRequest_ContextEntryInput],
  $grace: Boolean,
  $origin: String
) {
  submit_transport_feedback(
    entity_id: $entity_id,
    entity_type: $entity_type,
    reason: $reason,
    context: $context,
    grace: $grace,
    origin: $origin
  ) {
    status
  }
}
Variables
{
  "entity_id": "abc123",
  "entity_type": "xyz789",
  "reason": "xyz789",
  "context": [TransportFeedbackRequest_ContextEntryInput],
  "grace": false,
  "origin": "abc123"
}
Response
{"data": {"submit_transport_feedback": {"status": true}}}

submit_user_engagement_preferences

Description

Mutation for submitting user preferences.

Response

Returns a SubmitUserEngagementPreferences

Arguments
Name Description
grace_config - SubmitUserEngagementPreferencesRequest_GraceConfigInput Option for enabling/disabling grace period for a user.
language_config - SubmitUserEngagementPreferencesRequest_LanguageConfigInput Option for choosing preferred language for a user.
location - EngagementCoordinatesInput Set location for the user

Example

Query
mutation Submit_user_engagement_preferences(
  $grace_config: SubmitUserEngagementPreferencesRequest_GraceConfigInput,
  $language_config: SubmitUserEngagementPreferencesRequest_LanguageConfigInput,
  $location: EngagementCoordinatesInput
) {
  submit_user_engagement_preferences(
    grace_config: $grace_config,
    language_config: $language_config,
    location: $location
  ) {
    message
    status
  }
}
Variables
{
  "grace_config": SubmitUserEngagementPreferencesRequest_GraceConfigInput,
  "language_config": SubmitUserEngagementPreferencesRequest_LanguageConfigInput,
  "location": EngagementCoordinatesInput
}
Response
{
  "data": {
    "submit_user_engagement_preferences": {
      "message": "abc123",
      "status": true
    }
  }
}

subscribe_group_poi

Description

Mutation for subscribing to a group POI.

Response

Returns a SubscribeUserEngagementGroupPoi

Arguments
Name Description
group_id - String ID of the group.
poi_id - String ID of the Point of Interest.

Example

Query
mutation Subscribe_group_poi(
  $group_id: String,
  $poi_id: String
) {
  subscribe_group_poi(
    group_id: $group_id,
    poi_id: $poi_id
  ) {
    status
  }
}
Variables
{
  "group_id": "abc123",
  "poi_id": "abc123"
}
Response
{"data": {"subscribe_group_poi": {"status": false}}}

unmake_group_admin

Description

Mutation for unmaking a user an admin of a group.

Response

Returns an UnmakeUserEngagementGroupAdmin

Arguments
Name Description
group_id - String ID of the group.
removed_admin_user_id - String Sentiance ID of the user to be removed as admin.

Example

Query
mutation Unmake_group_admin(
  $group_id: String,
  $removed_admin_user_id: String
) {
  unmake_group_admin(
    group_id: $group_id,
    removed_admin_user_id: $removed_admin_user_id
  ) {
    status
  }
}
Variables
{
  "group_id": "abc123",
  "removed_admin_user_id": "xyz789"
}
Response
{"data": {"unmake_group_admin": {"status": true}}}

unsubscribe_group_poi

Description

Mutation for unsubscribing from a group POI.

Response

Returns an UnsubscribeUserEngagementGroupPoi

Arguments
Name Description
group_id - String ID of the group.
poi_id - String ID of the Point of Interest.

Example

Query
mutation Unsubscribe_group_poi(
  $group_id: String,
  $poi_id: String
) {
  unsubscribe_group_poi(
    group_id: $group_id,
    poi_id: $poi_id
  ) {
    status
  }
}
Variables
{
  "group_id": "abc123",
  "poi_id": "abc123"
}
Response
{"data": {"unsubscribe_group_poi": {"status": true}}}

update_feedback_event

Description

Mutation for updating a feedback event.

Response

Returns an UpdateFeedbackEvent

Arguments
Name Description
meta_info - FeedbackEventMetaInfoInput Meta information for the feedback event.
event_id - String ID of the transport/event.
type - FeedbackTypeEnum Type of feedback.
reason - String Reason feedback is provided.

Example

Query
mutation Update_feedback_event(
  $meta_info: FeedbackEventMetaInfoInput,
  $event_id: String,
  $type: FeedbackTypeEnum,
  $reason: String
) {
  update_feedback_event(
    meta_info: $meta_info,
    event_id: $event_id,
    type: $type,
    reason: $reason
  ) {
    feedback_event {
      created_at
      event_id
      meta_info {
        ...FeedbackEventMetaInfoFragment
      }
      reason
      type
      updated_at
      user_id
    }
  }
}
Variables
{
  "meta_info": FeedbackEventMetaInfoInput,
  "event_id": "abc123",
  "type": "FEEBACK_TYPE_UNKNOWN",
  "reason": "abc123"
}
Response
{
  "data": {
    "update_feedback_event": {
      "feedback_event": FeedbackEvent
    }
  }
}

update_group

Description

Mutation for updating a group.

Response

Returns an UpdateUserEngagementGroup

Arguments
Name Description
group_id - String ID of the group to update.
name - String New name of the group. Has to non-empty, non-null string.

Example

Query
mutation Update_group(
  $group_id: String,
  $name: String
) {
  update_group(
    group_id: $group_id,
    name: $name
  ) {
    status
  }
}
Variables
{
  "group_id": "abc123",
  "name": "xyz789"
}
Response
{"data": {"update_group": {"status": true}}}

Types

AbandonUserEngagementChallenge

Fields
Field Name Description
status - Boolean Success/Failure status.
Example
{"status": true}

AcceleratingEvent

Fields
Field Name Description
category - String The main category of the acceleration event (e.g. acceleration).
duration - Float Duration of the acceleration event in seconds.
end_at - String The end time of the acceleration event in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
magnitude - Float Max magnitude of the acceleration, measured in m/s².
mean - Float The mean of the acceleration event (e.g. acceleration).
path - [PathElement] Path (waypoints) of the acceleration event while it lasted.
start_at - String The start time of the acceleration event in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
type - String The sub type of the acceleration event (e.g. brake, acceleration).
Example
{
  "category": "xyz789",
  "duration": 987.65,
  "end_at": "xyz789",
  "magnitude": 987.65,
  "mean": 123.45,
  "path": [PathElement],
  "start_at": "xyz789",
  "type": "xyz789"
}

AcceptUserEngagementChallenge

Fields
Field Name Description
status - Boolean Success/Failure status.
Example
{"status": false}

AdditionalMobilityDetails

Fields
Field Name Description
raw_data_points - RawDataPoints
Example
{"raw_data_points": RawDataPoints}

AggregationFunctionEnum

Values
Enum Value Description

AVG

MIN

MAX

SUM

COUNT

Example
"AVG"

ApproveUserEngagementJoin

Fields
Field Name Description
status - Boolean Success/Failure status.
Example
{"status": false}

Boolean

Description

The Boolean scalar type represents true or false.

Example
true

BrakingEvent

Fields
Field Name Description
category - String The main category of the braking event.
duration - Float Duration of the braking event in seconds.
end_at - String The end time of the braking event in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
magnitude - Float Max magnitude of the braking, measured in m/s².
mean - Float The mean of the braking event (e.g. braking).
path - [PathElement] Path (waypoints) of the braking event while it lasted.
start_at - String The start time of the braking event in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
type - String The sub type of the braking event.
Example
{
  "category": "abc123",
  "duration": 123.45,
  "end_at": "xyz789",
  "magnitude": 987.65,
  "mean": 123.45,
  "path": [PathElement],
  "start_at": "xyz789",
  "type": "xyz789"
}

CallEvent

Fields
Field Name Description
category - String The main category of the call event.
duration - Float Duration of the call event in seconds.
end_at - String The end time of the call event in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
speed - PhoneEventSpeed The speed during the call event.
start_at - String The start time of the call event in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
type - String The sub type of the call event.
Example
{
  "category": "xyz789",
  "duration": 987.65,
  "end_at": "abc123",
  "speed": PhoneEventSpeed,
  "start_at": "abc123",
  "type": "xyz789"
}

ComparisonOperatorEnum

Values
Enum Value Description

LT

LTE

GT

GTE

EQ

NEQ

IN

Example
"LT"

CrashEvent

Fields
Field Name Description
confidence - Float confidence
delta_v - Float delta v
event_time - String exact moment of the crash event
max_magnitude - Float max magnitude
origin - String origin of the crash event
speed_at_impact - Float speed at impact
waypoint_direction - Float direction of the last waypoint
waypoint_elevation - Float elevation of the last waypoint
waypoint_horizontal_accuracy - Float horizontal accuracy of the last waypoint
waypoint_latitude - Float latitude of the last waypoint
waypoint_longitude - Float longitude of the last waypoint
waypoint_speed - Float speed of the last waypoint
waypoint_time - String time of the last waypoint
waypoint_vertical_accuracy - Float vertical accuracy of the last waypoint
Example
{
  "confidence": 987.65,
  "delta_v": 987.65,
  "event_time": "abc123",
  "max_magnitude": 987.65,
  "origin": "xyz789",
  "speed_at_impact": 123.45,
  "waypoint_direction": 123.45,
  "waypoint_elevation": 987.65,
  "waypoint_horizontal_accuracy": 123.45,
  "waypoint_latitude": 987.65,
  "waypoint_longitude": 987.65,
  "waypoint_speed": 987.65,
  "waypoint_time": "abc123",
  "waypoint_vertical_accuracy": 123.45
}

CrashEventsForTransport

Fields
Field Name Description
crash_event - CrashEvent List of crash events in this transport.
Example
{"crash_event": CrashEvent}

CreateFakeTransport

Fields
Field Name Description
transport_id - String ID of the created transport. If id is missing or empty string, it means that the transport was not created.
Example
{"transport_id": "xyz789"}

CreateFakeTransportRequest_SafetyScoresInput

Fields
Input Field Description
call_while_moving - Float
overall_safety - Float
legal - Float
focus - Float
smooth - Float
Example
{
  "call_while_moving": 123.45,
  "overall_safety": 987.65,
  "legal": 987.65,
  "focus": 987.65,
  "smooth": 123.45
}

CreateFakeTransportRequest_TransportModeEnum

Values
Enum Value Description

UNKNOWN

BICYCLE

WALKING

RUNNING

TRAM

CAR

MOTORCYCLE

TRAIN

BUS

Example
"UNKNOWN"

CreateFeedbackEvent

Fields
Field Name Description
feedback_event - FeedbackEvent Feedback event created.
Example
{"feedback_event": FeedbackEvent}

CreateUserEngagementGroup

Fields
Field Name Description
group - UserEngagementGroup Details of the newly created group.
status - Boolean Success/Failure status.
Example
{"group": UserEngagementGroup, "status": true}

CreateUserEngagementGroupPoi

Fields
Field Name Description
status - Boolean Success/Failure status.
Example
{"status": true}

CreateUserEngagementGroupRequest_UserEngagementGroupFeaturesInput

Fields
Input Field Description
with_feed - Boolean
with_leaderboard - Boolean
with_poi - Boolean
with_locations - Boolean
Example
{
  "with_feed": true,
  "with_leaderboard": true,
  "with_poi": false,
  "with_locations": true
}

DailyAvgScores

Fields
Field Name Description
slice - [DailyAvgScores_SliceEntry] Map from date to scores. Day is in yyyy-MM-dd format
Example
{"slice": [DailyAvgScores_SliceEntry]}

DailyAvgScores_SliceEntry

Fields
Field Name Description
key - String
value - EngagementScores
Example
{
  "key": "abc123",
  "value": EngagementScores
}

DeclineUserEngagementJoin

Fields
Field Name Description
status - Boolean Success/Failure status.
Example
{"status": true}

DeleteFeedbackEvent

Fields
Field Name Description
status - Boolean Success/Failure status.
Example
{"status": false}

DeleteUserById

Fields
Field Name Description
request_id - String Id of the unique user deletion request generated on our backend. Exists for debugging purposes. If you face any issues with user deletion, you can include this requestID in the support email to support@sentiance.com
Example
{"request_id": "abc123"}

DeleteUserEngagementGroup

Fields
Field Name Description
status - Boolean Success/Failure status.
Example
{"status": false}

DeleteUserEngagementGroupPoi

Fields
Field Name Description
status - Boolean Success/Failure status.
Example
{"status": false}

Diagnostics

Fields
Field Name Description
off_the_grids - [OffTheGrid]
Arguments
to - String

The starting date for the search query in YYYY-MM-DD format (inclusive).

from - String

The starting date for the search query in YYYY-MM-DD format (inclusive).

Example
{"off_the_grids": [OffTheGrid]}

Engagement

Fields
Field Name Description
group - UserEngagementGroup Group details.
Arguments
group_id - String

ID of the group.

reg_code - String

Registration code of the group.

Example
{"group": UserEngagementGroup}

EngagementComparisonAttributeEnum

Values
Enum Value Description

HARSH_MOVEMENT_SCORE

FOCUS_SCORE

CALL_WHILE_MOVING_SCORE

DURATION

CALL_EVENTS_DURATION

PHONE_HANDLING_EVENTS_DURATION

OVERALL_SCORE

DISTANCE

TRANSPORT_MODE

SCREEN_EVENTS_COUNT

SMOOTH_SCORE

PHONE_HANDLING_EVENTS_COUNT

ATTENTION_SCORE

LEGAL_SCORE

OCCUPANT_ROLE

CALL_EVENTS_COUNT

SCREEN_EVENTS_DURATION

MFFS_SCORE

Example
"HARSH_MOVEMENT_SCORE"

EngagementCoordinates

Fields
Field Name Description
latitude - Float The latitude of the location.
longitude - Float The longitude of the location.
timestamp - Float The timestamp of the location if applicable.
Example
{"latitude": 987.65, "longitude": 123.45, "timestamp": 123.45}

EngagementCoordinatesInput

Fields
Input Field Description
longitude - Float
timestamp - Float
latitude - Float
Example
{"longitude": 123.45, "timestamp": 987.65, "latitude": 987.65}

EngagementLocation

Fields
Field Name Description
city - String City of the location.
country - String Country of the location.
district - String District of the location.
region - String Region of the location
street - String Street of the location.
Example
{
  "city": "xyz789",
  "country": "abc123",
  "district": "abc123",
  "region": "abc123",
  "street": "xyz789"
}

EngagementLocationInput

Fields
Input Field Description
country - String
region - String
city - String
district - String
street - String
Example
{
  "country": "abc123",
  "region": "xyz789",
  "city": "abc123",
  "district": "xyz789",
  "street": "xyz789"
}

EngagementPOI

Fields
Field Name Description
address - EngagementLocation Location of the Point of Interest.
coordinates - EngagementCoordinates Coordinates of the Point of Interest.
name - String Name of the Point of Interest.
radius - Int Radius of the Point of Interest. Default 20 meters.
Example
{
  "address": EngagementLocation,
  "coordinates": EngagementCoordinates,
  "name": "xyz789",
  "radius": 123
}

EngagementPOIInput

Fields
Input Field Description
name - String
coordinates - EngagementCoordinatesInput
radius - Int
address - EngagementLocationInput
Example
{
  "name": "abc123",
  "coordinates": EngagementCoordinatesInput,
  "radius": 123,
  "address": EngagementLocationInput
}

EngagementScore

Fields
Field Name Description
name - EngagementScore_ScoreTypeEnum Score name.
value - Float Score value.
Example
{"name": "CALL_WHILE_MOVING_SCORE", "value": 987.65}

EngagementScore_ScoreTypeEnum

Values
Enum Value Description

CALL_WHILE_MOVING_SCORE

UNKNOWN

HARSH_MOVEMENT_SCORE

FOCUS_SCORE

LEGAL_SCORE

SMOOTH_SCORE

OVERALL_SCORE

MFFS_SCORE

ATTENTION_SCORE

Example
"CALL_WHILE_MOVING_SCORE"

EngagementScores

Fields
Field Name Description
slice - [EngagementScore] List containing scores available for you integration with Sentiance
Example
{"slice": [EngagementScore]}

EngagementStreakThresholds

Fields
Field Name Description
slice - [EngagementScore] List containing streak thresholds for each score. Available scores are: OVERALL_SCORE, MFFS_SCORE, ATTENTION_SCORE, HARSH_MOVEMENT_SCORE, FOCUS_SCORE, CALL_WHILE_MOVING_SCORE, LEGAL_SCORE, depending on your integration with Sentiance.
Example
{"slice": [EngagementScore]}

EngagementTransportEvent

Fields
Field Name Description
name - EngagementTransportEvent_TransportEventTypeEnum Transport event name.
value - Float Transport event value.
Example
{"name": "SCREEN_EVENTS_DURATION", "value": 123.45}

EngagementTransportEvent_TransportEventTypeEnum

Values
Enum Value Description

SCREEN_EVENTS_DURATION

UNKNOWN

CALL_EVENTS_COUNT

CALL_EVENTS_DURATION

PHONE_HANDLING_EVENTS_COUNT

PHONE_HANDLING_EVENTS_DURATION

SCREEN_EVENTS_COUNT

Example
"SCREEN_EVENTS_DURATION"

EngagementTrend

Fields
Field Name Description
end_datetime - String End datetime of the trend in ISO 8601 format.
start_datetime - String Start datetime of the trend in ISO 8601 format.
trend - Float Trend in percentages.
Example
{
  "end_datetime": "xyz789",
  "start_datetime": "xyz789",
  "trend": 987.65
}

FeedbackEvent

Fields
Field Name Description
created_at - String Time when the feedback event was created.
event_id - String ID of the transport/event.
meta_info - FeedbackEventMetaInfo Meta information for the feedback event.
reason - String Reason feedback is provided.
type - FeedbackTypeEnum Type of feedback.
updated_at - String Time when the feedback event was last updated.
user_id - String Sentiance User Id of the Feedback event.
Example
{
  "created_at": "xyz789",
  "event_id": "xyz789",
  "meta_info": FeedbackEventMetaInfo,
  "reason": "abc123",
  "type": "FEEBACK_TYPE_UNKNOWN",
  "updated_at": "xyz789",
  "user_id": "xyz789"
}

FeedbackEventMetaInfo

Fields
Field Name Description
has_sdk_marked_as_crash - Boolean Crash event marked crash by the SDK. Use when FeedbackType is CRASH.
has_user_marked_as_crash - Boolean Crash event marked as crashed by user. Use when FeedbackType is CRASH.
is_false_positive_crash - Boolean Crash event detected is false positive. Use when FeedbackType is CRASH.
original_mode - String Original transport mode. Use when FeedbackType is TRANSPORT_MODE.
recommended_mode - String Recomended transport mode. Use when FeedbackType is TRANSPORT_MODE.
Example
{
  "has_sdk_marked_as_crash": true,
  "has_user_marked_as_crash": false,
  "is_false_positive_crash": true,
  "original_mode": "xyz789",
  "recommended_mode": "abc123"
}

FeedbackEventMetaInfoInput

Fields
Input Field Description
has_sdk_marked_as_crash - Boolean
original_mode - String
recommended_mode - String
is_false_positive_crash - Boolean
has_user_marked_as_crash - Boolean
Example
{
  "has_sdk_marked_as_crash": true,
  "original_mode": "abc123",
  "recommended_mode": "abc123",
  "is_false_positive_crash": false,
  "has_user_marked_as_crash": false
}

FeedbackTypeEnum

Values
Enum Value Description

FEEBACK_TYPE_UNKNOWN

FEEDBACK_TYPE_TRANSPORT_MODE

FEEDBACK_TYPE_CRASH

Example
"FEEBACK_TYPE_UNKNOWN"

FilterInput

Fields
Input Field Description
value - String
attribute - EngagementComparisonAttributeEnum
operator - ComparisonOperatorEnum
Example
{
  "value": "abc123",
  "attribute": "HARSH_MOVEMENT_SCORE",
  "operator": "LT"
}

Float

Description

The Float scalar type represents signed double-precision fractional values as specified by IEEE 754.

Example
123.45

GenerateAuthCode

Fields
Field Name Description
authentication_code - String
expires_at - String Time in ISO-8601 format at which the authentication code expires.
Example
{
  "authentication_code": "abc123",
  "expires_at": "abc123"
}

GenerateUrl

Fields
Field Name Description
offload - Offload
Example
{"offload": Offload}

Int

Description

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Example
123

JoinUserEngagementGroup

Fields
Field Name Description
status - Boolean Success/Failure status.
Example
{"status": true}

LeaveUserEngagementGroup

Fields
Field Name Description
status - Boolean Success/Failure status.
Example
{"status": true}

LocationInformation

Fields
Field Name Description
city - String The city to which the location belongs.
country - String The country to which the location belongs.
district - String The district to which the location belongs.
region - String The region to which the location belongs.
street - String The street to which the location belongs.
Example
{
  "city": "xyz789",
  "country": "xyz789",
  "district": "xyz789",
  "region": "abc123",
  "street": "xyz789"
}

MakeUserEngagementGroupAdmin

Fields
Field Name Description
status - Boolean Success/Failure status.
Example
{"status": true}

MapMatchedWaypoint

Fields
Field Name Description
distance - Float The distance in meters between the current waypoint and the previous waypoint.
latitude - Float Waypoint latitude in degrees with accuracy of 5 decimals.
longitude - Float Waypoint longitude in degrees with accuracy of 5 decimals.
road_type - String The type of road in which the waypoint was mapped (e.g. motorway, pedestrian, highway, etc.).
speed - Float The speed in km/h at the moment the waypoint was mapped.
speed_limit - Float The speed limit in km/h of the road where the waypoint was mapped.
timestamp - String Waypoint timestamp in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
Example
{
  "distance": 987.65,
  "latitude": 987.65,
  "longitude": 123.45,
  "road_type": "abc123",
  "speed": 123.45,
  "speed_limit": 987.65,
  "timestamp": "xyz789"
}

MountedEvent

Fields
Field Name Description
category - String The main category of the mounted phone event.
duration - Float Duration of the mounted phone event in seconds.
end_at - String The end time of the mounted phone event in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
start_at - String The start time of the mounted phone event in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
type - String The sub type of the mounted phone event.
Example
{
  "category": "xyz789",
  "duration": 123.45,
  "end_at": "xyz789",
  "start_at": "abc123",
  "type": "abc123"
}

OffTheGrid

Fields
Field Name Description
end_at - String The end time of the off-the-grid in ISO 8601 format (e.g. 2022-06-27T11:26:48.351+01:00).
off_the_grid_id - String Unique ID of the off-the-grid event.
reason - OffTheGrid_OffTheGridReasonEnum The reason why the off-the-grid started (e.g. OFF_THE_GRID_LOCATION_PERMISSION).
start_at - String The start time of the off-the-grid in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
Example
{
  "end_at": "abc123",
  "off_the_grid_id": "abc123",
  "reason": "OFF_THE_GRID_LOCATION_ACCESS_ALWAYS",
  "start_at": "xyz789"
}

OffTheGrid_OffTheGridReasonEnum

Values
Enum Value Description

OFF_THE_GRID_LOCATION_ACCESS_ALWAYS

OFF_THE_GRID_KILLSWITCH

OFF_THE_GRID_OTHER

OFF_THE_GRID_NO_LOCATION_FIXES

OFF_THE_GRID_OUTAGE

OFF_THE_GRID_LOCATION_ACCURACY_REDUCED

OFF_THE_GRID_DISKUSAGE_PERMISSION

OFF_THE_GRID_LOCATION_MODE_BATTERY_SAVING

OFF_THE_GRID_DISK_QUOTA_EXCEEDED

OFF_THE_GRID_BGACCESS_PERMISSION

OFF_THE_GRID_PLAY_SERVICES

OFF_THE_GRID_NETWORK_PERMISSION

OFF_THE_GRID_AIRPLANE_MODE

OFF_THE_GRID_GEOFENCE_TRANSITION_TIMEOUT

OFF_THE_GRID_BG_EXECUTION_RESTRICTED

OFF_THE_GRID_LOCATION_PERMISSION

OFF_THE_GRID_MOTION_ACTIVITY_PERMISSION

OFF_THE_GRID_LOCATION_MODE_OFF

OFF_THE_GRID_SDK_NOT_RUNNING

OFF_THE_GRID_BG_DETECTIONS_NOT_ALLOWED

OFF_THE_GRID_EXTERNAL_EVENT

OFF_THE_GRID_LOCATION_MODE_DEVICE_ONLY

Example
"OFF_THE_GRID_LOCATION_ACCESS_ALWAYS"

Offload

Fields
Field Name Description
day - String Day must be in YYYY-MM-DD format.
files - [OffloadFile]
type - OffloadTypeEnum
Example
{
  "day": "2023-03-04",
  "files": [OffloadFile],
  "type": "OFFLOAD_TYPE_PRIMARY_SAFETY_SCORES_USER"
}

OffloadFile

Fields
Field Name Description
format - String File format of the offload file.
link - Link
name - String
size - Int Size of the offload file in bytes.
Example
{
  "format": "csv.gz",
  "link": Link,
  "name": "xyz789",
  "size": 987
}

OffloadTypeEnum

Values
Enum Value Description

OFFLOAD_TYPE_PRIMARY_SAFETY_SCORES_USER

OFFLOAD_TYPE_PRIMARY_SAFETY_SCORES_TRANSPORT

OFFLOAD_TYPE_UNKNOWN

OFFLOAD_TYPE_TRANSPORTS

OFFLOAD_TYPE_CUSTOM_SCORES

OFFLOAD_TYPE_DAILY_REWARDS

OFFLOAD_TYPE_DRIVER_PASSENGER

OFFLOAD_TYPE_STREAKS

OFFLOAD_TYPE_SECONDARY_SAFETY_SCORES_TRANSPORT

OFFLOAD_TYPE_DRIVING_EVENTS_ALL

OFFLOAD_TYPE_DRIVING_EVENTS_SIGNIFICANT

OFFLOAD_TYPE_GROUPS

OFFLOAD_TYPE_GROUP_MEMBERS

OFFLOAD_TYPE_FEEDBACK

OFFLOAD_TYPE_TRAJECTORIES

OFFLOAD_TYPE_SECONDARY_SAFETY_SCORES_USER

OFFLOAD_TYPE_COMMUNICATIONS

OFFLOAD_TYPE_APP_EVENTS

OFFLOAD_TYPE_OFF_THE_GRIDS

OFFLOAD_TYPE_BADGES

Example
"OFFLOAD_TYPE_PRIMARY_SAFETY_SCORES_USER"

PathElement

Fields
Field Name Description
latitude - Float Location-fix latitude in degrees with accuracy of 5 decimals.
longitude - Float Location-fix longitude in degrees with accuracy of 5 decimals.
Example
{"latitude": 123.45, "longitude": 987.65}

PhoneEventSpeed

Fields
Field Name Description
max - Float
min - Float
Example
{"max": 987.65, "min": 987.65}

PhoneHandlingEvent

Fields
Field Name Description
category - String The main category of the phone handling event.
duration - Float Duration of the phone handling event in seconds.
end_at - String The end time of the phone handling event in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
path - [PathElement] Path (waypoints) of the phone handling event while it lasted.
speed - PhoneEventSpeed The speed during the phone handling event.
start_at - String The start time of the phone handling event in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
type - String The sub type of the phone handling event.
Example
{
  "category": "xyz789",
  "duration": 123.45,
  "end_at": "abc123",
  "path": [PathElement],
  "speed": PhoneEventSpeed,
  "start_at": "abc123",
  "type": "abc123"
}

PrimarySafetyScores

Fields
Field Name Description
attention - Float A combined score of handheld calling, hands-free calling and handling without calling. Range: 0..1. If we did not obtain sufficient data, the value will be -1.
legal - Float The legal driving score measures how well you adhere to speed limits. The higher your score, the more you respect the speed limits. Range: 0..1. If we did not obtain sufficient data, the value will be -1.
overall - Float A combined score of the legal, smooth, and attention scores. Range: 0..1. If we did not obtain sufficient data, the value will be -1.
smooth - Float The smooth driving score measures how smooth you drive. High accelerations, heavy braking and heavy turning result in a lower score. The use of coasting results in a higher score. Scores are normalized with respect to a wide population. The higher your score, the smoother you drive. Range: 0..1. If we did not obtain sufficient data, the value will be -1.
Example
{"attention": 987.65, "legal": 987.65, "overall": 123.45, "smooth": 987.65}

RawDataPoints

Fields
Field Name Description
distance - Float The total distance travelled in meters. Based on the Haversine distance
raw_waypoints - [RawWaypoint] List of raw waypoints.
top_speed - Float Top speed reached in the transport in km/h.
Example
{
  "distance": 987.65,
  "raw_waypoints": [RawWaypoint],
  "top_speed": 987.65
}

RawWaypoint

Fields
Field Name Description
accuracy - Int Waypoint accuracy in meters.
latitude - Float Waypoint latitude in degrees with accuracy of 5 decimals.
longitude - Float Waypoint longitude in degrees with accuracy of 5 decimals.
speed - Float The speed in m/s
timestamp - String Waypoint timestamp in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
Example
{
  "accuracy": 123,
  "latitude": 987.65,
  "longitude": 123.45,
  "speed": 987.65,
  "timestamp": "xyz789"
}

RemoveUserEngagementGroupMembership

Fields
Field Name Description
status - Boolean Success/Failure status.
Example
{"status": false}

ScoresTrend

Fields
Field Name Description
slice - [ScoresTrend_SliceEntry] Scores name to trend mapping.
Example
{"slice": [ScoresTrend_SliceEntry]}

ScoresTrend_SliceEntry

Fields
Field Name Description
key - String
value - EngagementTrend
Example
{
  "key": "abc123",
  "value": EngagementTrend
}

ScreenEvent

Fields
Field Name Description
category - String The main category of the phone screen event.
duration - Float Duration of the phone screen event in seconds.
end_at - String The end time of the phone screen event in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
speed - PhoneEventSpeed The speed during the phone screen event.
start_at - String The start time of the phone screen event in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
type - String The sub type of the phone screen event.
Example
{
  "category": "xyz789",
  "duration": 987.65,
  "end_at": "abc123",
  "speed": PhoneEventSpeed,
  "start_at": "xyz789",
  "type": "abc123"
}

SecondarySafetyScores

Fields
Field Name Description
anticipation - Float The anticipative driving score measures how well you anticipate turns. Hard accelerations before or hard braking during a turn result in a lower score. The use of coasting results in a higher score. The higher your score, the more anticipative you drive. Range: 0..1. If we did not obtain sufficient data, the value will be -1.
focus - Float The proportion of time (percentage) the user is focused while driving, being focused means: not using the phone, which is detected through phone handling. Range: 0..1. If we did not obtain sufficient data, the value will be -1.
harsh_acceleration - Float Measures how often you accelerate hard. Every hard acceleration will be penalised by subtracting a percentage of your score. Range: 0..1. If we did not obtain sufficient data, the value will be -1.
harsh_braking - Float Measures how often you need to brake hard. Every hard brake will be penalised by subtracting a percentage of your score. Range: 0..1. If we did not obtain sufficient data, the value will be -1.
harsh_events - Float This is a combination of hard_accel and hard_brake score. The hard brakes and accelerations are also normalized by the total number of events. When we do not have sufficient data this value will be -1.
harsh_turning - Float Measures how often you turn hard. Every hard turn will be penalised by subtracting a percentage of your score. Range: 0..1. If we did not obtain sufficient data, the value will be -1.
mounted - Float The proportion of time (percentage) the phone is mounted while driving. Range: 0..1. If we did not obtain sufficient data, the value will be -1.
Example
{
  "anticipation": 987.65,
  "focus": 123.45,
  "harsh_acceleration": 987.65,
  "harsh_braking": 987.65,
  "harsh_events": 987.65,
  "harsh_turning": 987.65,
  "mounted": 123.45
}

SetUserEngagementGroupStatus

Fields
Field Name Description
status - Boolean Success/Failure status.
Example
{"status": true}

SliceByEnum

Values
Enum Value Description

YEAR

WEEK_SUNDAY

DAY

WEEK

MONTH

Example
"YEAR"

SpeedingEvent

Fields
Field Name Description
category - String The main category of the speeding event.
duration - Float Duration of the speeding event in seconds.
end_at - String The end time of the speeding event in ISO 8601 format (e.g. 2022-06-26T11:26:48.350+01:00).
path - [PathElement] Path (waypoints) of the speeding event while it lasted.
speed_limits - [Int] List of speed limits in km/h corresponding to the waypoints in the path.
speeds - [Float] List of speeds in km/h corresponding to the waypoints in the path.
start_at - String The start time of the speeding event in ISO 8601 format (e.g. 2022-06-26T11:26:48.350+01:00).
type - String The sub type of the speeding event.
Example
{
  "category": "xyz789",
  "duration": 987.65,
  "end_at": "xyz789",
  "path": [PathElement],
  "speed_limits": [987],
  "speeds": [987.65],
  "start_at": "abc123",
  "type": "abc123"
}

StreakTypeEnum

Values
Enum Value Description

STREAK_TYPE_UNKNOWN

STREAK_TYPE_STRICT

STREAK_TYPE_SELF_COMPETING

Example
"STREAK_TYPE_UNKNOWN"

StreakVariantEnum

Values
Enum Value Description

STREAK_VARIANT_DAY

STREAK_VARIANT_UNKNOWN

STREAK_VARIANT_TRIP

Example
"STREAK_VARIANT_DAY"

String

Description

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Example
"abc123"

SubmitLogEvent

Fields
Field Name Description
message - String Success/Failure message.
status - Boolean Success/Failure status.
Example
{"message": "abc123", "status": false}

SubmitLogEventRequest_EventParamsEntryInput

Fields
Input Field Description
key - String!
value - String!
Example
{
  "key": "xyz789",
  "value": "abc123"
}

SubmitUserEngagementPreferences

Fields
Field Name Description
message - String Success/Failure message.
status - Boolean Success/Failure status.
Example
{"message": "abc123", "status": false}

SubmitUserEngagementPreferencesRequest_GraceConfigInput

Fields
Input Field Description
enabled - Boolean
Example
{"enabled": true}

SubmitUserEngagementPreferencesRequest_LanguageConfigInput

Fields
Input Field Description
code - String
name - String
Example
{
  "code": "xyz789",
  "name": "abc123"
}

SubscribeUserEngagementGroupPoi

Fields
Field Name Description
status - Boolean Success/Failure status.
Example
{"status": true}

TimeFrame

Fields
Field Name Description
from - String Start of the time frame in yyyy-MM-dd'T'HH:mm:ss format (e.g. 2024-03-31T23:59:59).
timezone - String Timezone of the time frame in IANA timezone format (e.g. Europe/Brussels). Default is Etc/UTC
to - String End of the time frame in yyyy-MM-dd'T'HH:mm:ss format (e.g. 2024-03-31T23:59:59).
Example
{
  "from": "abc123",
  "timezone": "xyz789",
  "to": "abc123"
}

TimeFrameInput

Fields
Input Field Description
from - String
to - String
timezone - String
Example
{
  "from": "abc123",
  "to": "abc123",
  "timezone": "abc123"
}

Transport

Fields
Field Name Description
additional_mobility_details - AdditionalMobilityDetails Additional mobility insights of the transport.
crash_events - CrashEventsForTransport Crash events for the transport
driving_events - TransportDrivingEvents The driving events detected in the transport (CAR only).
Arguments
show - TransportDrivingEventsRequest_DrivingEventsFilterEnum

Accepted values are ALL (obtain significant and non-significant driving events) or SIGNIFICANT (obtain only significant driving events).

duration - Int Total duration of the transport in seconds.
end_at - String End time of the transport in ISO 8601 format (e.g. 2022-06-26T15:21:21.351+01:00).
metadata - String JSON array of of key-value pairs with metadata sent by the client.
mode - String The transport mode. Possible values are: [biking, bus, car, ferry, idle, insufficient_data, running, train, tram, unsupported_mode, walking].
occupant_role - String The occupant role information of the transport.
scores - TransportScores The driving scores assigned to the transport.
start_at - String Start time of the transport in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
top_speed - Float Top speed reached in the transport in km/h.
trajectory - TransportTrajectory The trajectory details of the transport.
transport_id - String The unique ID of the transport.
weather_data - TransportWeatherData The weather data at the origin and destination of the transport
Example
{
  "additional_mobility_details": AdditionalMobilityDetails,
  "crash_events": CrashEventsForTransport,
  "driving_events": TransportDrivingEvents,
  "duration": 123,
  "end_at": "xyz789",
  "metadata": "abc123",
  "mode": "xyz789",
  "occupant_role": "abc123",
  "scores": TransportScores,
  "start_at": "xyz789",
  "top_speed": 987.65,
  "trajectory": TransportTrajectory,
  "transport_id": "xyz789",
  "weather_data": TransportWeatherData
}

TransportDrivingEvents

Fields
Field Name Description
accelerating - [AcceleratingEvent] List of accelerating events.
braking - [BrakingEvent] List of braking events.
calls - [CallEvent] List of call events.
mounted - [MountedEvent] List of mounted events.
phone_handling - [PhoneHandlingEvent] List of phone-handling events.
screens - [ScreenEvent] List of screen events.
speeding - [SpeedingEvent] List of speeding events.
turning - [TurningEvent] List of turning events.
Example
{
  "accelerating": [AcceleratingEvent],
  "braking": [BrakingEvent],
  "calls": [CallEvent],
  "mounted": [MountedEvent],
  "phone_handling": [PhoneHandlingEvent],
  "screens": [ScreenEvent],
  "speeding": [SpeedingEvent],
  "turning": [TurningEvent]
}

TransportDrivingEventsRequest_DrivingEventsFilterEnum

Values
Enum Value Description

ALL

SIGNIFICANT

Example
"ALL"

TransportFeedback

Fields
Field Name Description
status - Boolean Success/Failure status.
Example
{"status": false}

TransportFeedbackRequest_ContextEntryInput

Fields
Input Field Description
key - String!
value - String!
Example
{
  "key": "abc123",
  "value": "abc123"
}

TransportScores

Fields
Field Name Description
safety - TransportScoresSafety
Example
{"safety": TransportScoresSafety}

TransportScoresSafety

Fields
Field Name Description
primary - PrimarySafetyScores Primary driving safety scores assigned to the transport.
secondary - SecondarySafetyScores Secondary driving safety scores assigned to the transport.
unified - UnifiedSafetyScores Unified safety scores assigned to the transport.
Example
{
  "primary": PrimarySafetyScores,
  "secondary": SecondarySafetyScores,
  "unified": UnifiedSafetyScores
}

TransportTrajectory

Fields
Field Name Description
distance - Float The total distance travelled in meters.
end_location - LocationInformation Information about the ending location of the trajectory.
map_matched_waypoints - [MapMatchedWaypoint] The map-matched waypoints of the trajectory.
polyline - String The encoded path using Google's Encoded Polyline Algorithm format.
start_location - LocationInformation Information about the starting location of the trajectory.
top_speed - Float Top speed reached in the transport in km/h.
Example
{
  "distance": 987.65,
  "end_location": LocationInformation,
  "map_matched_waypoints": [MapMatchedWaypoint],
  "polyline": "abc123",
  "start_location": LocationInformation,
  "top_speed": 123.45
}

TransportWeatherData

Fields
Field Name Description
weather_at_destination - WeatherData The weather data at the destination of the transport
weather_at_origin - WeatherData The weather data at the origin of the transport
Example
{
  "weather_at_destination": WeatherData,
  "weather_at_origin": WeatherData
}

TurningEvent

Fields
Field Name Description
category - String The main category of the turning event (e.g. turning).
duration - Float Duration of the turning event in seconds.
end_at - String The end time of the turning event in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
magnitude - Float Max magnitude of the turning, measured in m/s².
path - [PathElement] Path (waypoints) of the turning event while it lasted.
start_at - String The start time of the turning event in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
type - String The sub type of the turning event (e.g. left turn, right turn).
Example
{
  "category": "xyz789",
  "duration": 123.45,
  "end_at": "abc123",
  "magnitude": 123.45,
  "path": [PathElement],
  "start_at": "abc123",
  "type": "xyz789"
}

UnifiedSafetyScores

Fields
Field Name Description
attentive - Float The attentive driving score measures how attentive you are to your surroundings (for example: are you distracted by a call or phone handling). The exact definition could depend on your use-case. Range: 0..1. If we did not obtain sufficient data, the value will be -1.
legal - Float The legal driving score measures how well you adhere to legal conditions (for example: adhering to speed limits). The exact definition could depend on your use-case. Range: 0..1. If we did not obtain sufficient data, the value will be -1.
overall - Float A combined score of the legal, smooth, and attentive scores. The exact definition could depend on your use-case. Range: 0..1. If we did not obtain sufficient data, the value will be -1.
smooth - Float The smooth driving score measures how smoothly you drive (for example: high accelerations, heavy braking and heavy turning could result in a lower score). The exact definition could depend on your use-case. Range: 0..1. If we did not obtain sufficient data, the value will be -1.
Example
{"attentive": 123.45, "legal": 123.45, "overall": 123.45, "smooth": 987.65}

UnmakeUserEngagementGroupAdmin

Fields
Field Name Description
status - Boolean Success/Failure status.
Example
{"status": true}

UnsubscribeUserEngagementGroupPoi

Fields
Field Name Description
status - Boolean Success/Failure status.
Example
{"status": false}

UpdateFeedbackEvent

Fields
Field Name Description
feedback_event - FeedbackEvent Feedback event updated.
Example
{"feedback_event": FeedbackEvent}

UpdateUserEngagementGroup

Fields
Field Name Description
status - Boolean Success/Failure status.
Example
{"status": true}

User

Fields
Field Name Description
app_id - String App ID to which the user belongs.
created_at - String Date and time of user creation in the Sentiance platform in ISO 8601 format (e.g. 2022-06-26T11:26:48.000+00:00).
diagnostics - Diagnostics Diagnostics API for user-related events and information.
engagement - UserEngagement Engagement information e.g driver coaching score, streaks, challenges, etc.
external_id - String ID of the user given by the client application (if present).
feedback_events - [FeedbackEvent] Get feedback event(s) for a user.
Arguments
type - FeedbackTypeEnum

Type of feedback.

event_id - String

Filter for the ID of the transport/event. Only single event can be filtered.

scores - UserScores Time-aggregated driving scores of the user.
Arguments
by - String

Aggregate user scores by either DAY, WEEK, MONTH or QUARTER.

date - String

The date for which to aggregate scores in YYYY-MM-DD format. If DAY is used, the exact given date is used. If WEEK is used, the given date is backtracked to Monday. If MONTH is used, the given date is backtracked to the first day of the month. If QUARTER is used, the given date is backtracked to the first day of the quarter.

transports - [Transport] List of transports belonging to the user.
Arguments
from - String

The starting date for the search query in YYYY-MM-DD format (inclusive).

to - String

The starting date for the search query in YYYY-MM-DD format (inclusive).

user_id - String Sentiance ID of the user.
Example
{
  "app_id": "xyz789",
  "created_at": "xyz789",
  "diagnostics": Diagnostics,
  "engagement": UserEngagement,
  "external_id": "xyz789",
  "feedback_events": [FeedbackEvent],
  "scores": UserScores,
  "transports": [Transport],
  "user_id": "abc123"
}

UserEngagement

Fields
Field Name Description
aggregations - UserEngagementAggregations Aggregations of a user.
Arguments
time_frame - TimeFrameInput

Time frame for the aggregation.

function - AggregationFunctionEnum

Type of aggregation to perform. Default is AVG

slice_by - SliceByEnum

Slice the aggregation by DAY, WEEK, MONTH or YEAR. If no option is provided, the aggregation will not be sliced and the aggregation for the entire period will pe returned.

badges - UserEngagementBadges Engagement user badges.
challenges - UserEngagementChallenges Engagement user challenges.
communications - UserEngagementCommunications Communications of a user.
groups - UserEngagementGroups Engagement user groups.
Arguments
roles - [UserEngagementGroupRoleEnum]

Filter for groups where user has selected roles. Available options: ADMIN, MEMBER, PENDING. Not choosing any role will return all groups.

group_id - String

Filter for a specific group_id. Only one filter por request is allowed.

library - UserEngagementLibrary Engagement Content Library.
scores - UserEngagementScores Engagement user scores.
Arguments
transport_mode - UserEngagementScoresRequest_TransportModeEnum

Filter for transport mode. Available options: BIKING, BUS, CAR, FERRY, IDLE, RUNNING, TRAIN, TRAM, WALKING. Default: CAR.

streaks - UserEngagementStreaks Engagement user streaks.
Arguments
transport_mode - UserEngagementScoresRequest_TransportModeEnum

Filter for transport mode. Available options: BIKING, BUS, CAR, FERRY, IDLE, RUNNING, TRAIN, TRAM, WALKING. Default: CAR.

type - StreakTypeEnum

Filter for type of the streak. Available options: TRIP, DAY. Default: TRIP.

variant - StreakVariantEnum

Filter for variant of the streak. Available options: STRICT, SELF_COMPETING. Default: STRICT.

transport - UserEngagementTransport Transport of a user by ID.
Arguments
transport_id - String

ID of the transport.

transports - UserEngagementTransports Transports of the user.
Arguments
in_grace_period - UserEngagementTransportsRequest_InGracePeriodEnum

Filter for transports in grace period. Available options: ALL, TRUE, FALSE. Default: ALL.

mode - UserEngagementTransportsRequest_TransportModeEnum

Filter for transport mode. Available options: ANY_MODE, BIKING, BUS, CAR, FERRY, IDLE, RUNNING, TRAIN, TRAM, WALKING, INSUFFICIENT_DATA, UNSUPPORTED_MODE, MOTORCYCLE. Default: CAR.

limit - Int

Number of transports to return.

pagination_token - String

Pagination token.

occupant_role - UserEngagementTransportsRequest_OccupantRoleEnum

Filter for occupant role of transports. Available options: ANY, DRIVER, PASSENGER, DRIVER_AND_PASSENGER and UNKNOWN. Default: ANY

Example
{
  "aggregations": UserEngagementAggregations,
  "badges": UserEngagementBadges,
  "challenges": UserEngagementChallenges,
  "communications": UserEngagementCommunications,
  "groups": UserEngagementGroups,
  "library": UserEngagementLibrary,
  "scores": UserEngagementScores,
  "streaks": UserEngagementStreaks,
  "transport": UserEngagementTransport,
  "transports": UserEngagementTransports
}

UserEngagementAggregations

Fields
Field Name Description
daily_rewards - UserEngagementDailyRewardsAggregationsSlice Engagement user aggregated data for daily rewards.
transports - UserEngagementTransportAggregationsSlice Engagement user aggregated data for transports.
Arguments
filters - [FilterInput]

Filters to apply before the aggregation is computed

user_id - String Sentiance ID of the user.
Example
{
  "daily_rewards": UserEngagementDailyRewardsAggregationsSlice,
  "transports": UserEngagementTransportAggregationsSlice,
  "user_id": "xyz789"
}

UserEngagementBadge

Fields
Field Name Description
category - String Category of the badge.
completed_at - String Completed time in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
description - String Description of the badge.
id - String ID of the badge.
image_url - String Image URL of the badge.
level - Int Level of the badge.
name - String Name of the badge.
progress - Int Progress of the badge.
reward_text - String Reward text of the badge.
started_at - String Start time in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
status - String Status of the badge.
updated_at - String Updated time in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
Example
{
  "category": "abc123",
  "completed_at": "abc123",
  "description": "abc123",
  "id": "xyz789",
  "image_url": "xyz789",
  "level": 987,
  "name": "abc123",
  "progress": 123,
  "reward_text": "xyz789",
  "started_at": "abc123",
  "status": "abc123",
  "updated_at": "xyz789"
}

UserEngagementBadges

Fields
Field Name Description
slice - [UserEngagementBadge] List of badges.
Example
{"slice": [UserEngagementBadge]}

UserEngagementChallenge

Fields
Field Name Description
accepted_at - String Accepted time in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
can_receive_feedback - Boolean Flag that marks the challenge as eligible for feedback.
category - String Category of the challenge.
challenge_id - String ID of the challenge.
count - Int Order of the challenge by difficulty.
description - String Description of the challenge.
difficulty - String Difficulty of the challenge.
ended_at - String Ended time in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
id - String Use challenge_id instead.
image_url - String Image URL of the challenge.
new - String String that has value 'new' if this challenge has never been accepted by the user. Null otherwise.
ordering - Int Order of the challenge by subcategory.
progress - Int Progress of the challenge.
status - String Status of the challenge.
subcategory - String Subcategory of the challenge.
updated_at - String Updated time in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
Example
{
  "accepted_at": "abc123",
  "can_receive_feedback": false,
  "category": "abc123",
  "challenge_id": "abc123",
  "count": 987,
  "description": "abc123",
  "difficulty": "abc123",
  "ended_at": "abc123",
  "id": "xyz789",
  "image_url": "abc123",
  "new": "xyz789",
  "ordering": 987,
  "progress": 987,
  "status": "abc123",
  "subcategory": "abc123",
  "updated_at": "xyz789"
}

UserEngagementChallenges

Fields
Field Name Description
active - UserEngagementChallengesSlice Active Challenges of the user
available - UserEngagementChallengesSlice Available Challenges of the user
completed - UserEngagementChallengesSlice Completed Challenges of the user.
Example
{
  "active": UserEngagementChallengesSlice,
  "available": UserEngagementChallengesSlice,
  "completed": UserEngagementChallengesSlice
}

UserEngagementChallengesSlice

Fields
Field Name Description
slice - [UserEngagementChallenge] List of challenges.
Example
{"slice": [UserEngagementChallenge]}

UserEngagementCommunication

Fields
Field Name Description
button_label - String Button label text for communications that have a button.
button_url - String Redirect url for communications that have a button.
category - String Category of the communication.
communication_id - String ID of the communication.
context - [UserEngagementCommunicationResponse_ContextEntry] Map containing the context in which the communication was generated.
evaluation_id - String Evaluation ID of the communication.
expires_at - String Expire time in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
generated_at - String Generated time in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
message - String Message of the communication.
priority - Int Priority of the communication.
status - String Status of the communication.
title - String Title of the communication.
transport_mode - String Transport mode for communications that are related to a transport.
type - String Type of the communication.
updated_at - String Updated time in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
Example
{
  "button_label": "xyz789",
  "button_url": "xyz789",
  "category": "xyz789",
  "communication_id": "xyz789",
  "context": [
    UserEngagementCommunicationResponse_ContextEntry
  ],
  "evaluation_id": "xyz789",
  "expires_at": "abc123",
  "generated_at": "xyz789",
  "message": "xyz789",
  "priority": 123,
  "status": "abc123",
  "title": "xyz789",
  "transport_mode": "xyz789",
  "type": "xyz789",
  "updated_at": "abc123"
}

UserEngagementCommunicationResponse_ContextEntry

Fields
Field Name Description
key - String
value - String
Example
{
  "key": "abc123",
  "value": "abc123"
}

UserEngagementCommunications

Fields
Field Name Description
all - UserEngagementCommunicationsSlice All Communications of the user
Arguments
limit - Int

Number of communications to return.

category - UserEngagementCommunicationsRequest_CategoryEnum

Category of the communication. Available options: ALL, CHALLENGES, BADGES, STREAKS, SCORES, LEADERBOARD, TRIPS, PROFILE, SCHEDULED.

type - UserEngagementCommunicationsRequest_TypeEnum

Type of the communication. Available options: IN_APP_MESSAGE, REACTIVE_MESSAGE.

transport_mode - UserEngagementTransportsRequest_TransportModeEnum

Filter for transport mode. Available options: ANY_MODE, BIKING, BUS, CAR, FERRY, IDLE, RUNNING, TRAIN, TRAM, WALKING, INSUFFICIENT_DATA, UNSUPPORTED_MODE, MOTORCYCLE. Default: CAR.

closed - UserEngagementCommunicationsSlice Closed Communications of the user
Arguments
category - UserEngagementCommunicationsRequest_CategoryEnum

Category of the communication. Available options: ALL, CHALLENGES, BADGES, STREAKS, SCORES, LEADERBOARD, TRIPS, PROFILE, SCHEDULED.

type - UserEngagementCommunicationsRequest_TypeEnum

Type of the communication. Available options: IN_APP_MESSAGE, REACTIVE_MESSAGE.

transport_mode - UserEngagementTransportsRequest_TransportModeEnum

Filter for transport mode. Available options: ANY_MODE, BIKING, BUS, CAR, FERRY, IDLE, RUNNING, TRAIN, TRAM, WALKING, INSUFFICIENT_DATA, UNSUPPORTED_MODE, MOTORCYCLE. Default: CAR.

limit - Int

Number of communications to return.

expired - UserEngagementCommunicationsSlice Expired Communications of the user
Arguments
limit - Int

Number of communications to return.

category - UserEngagementCommunicationsRequest_CategoryEnum

Category of the communication. Available options: ALL, CHALLENGES, BADGES, STREAKS, SCORES, LEADERBOARD, TRIPS, PROFILE, SCHEDULED.

type - UserEngagementCommunicationsRequest_TypeEnum

Type of the communication. Available options: IN_APP_MESSAGE, REACTIVE_MESSAGE.

transport_mode - UserEngagementTransportsRequest_TransportModeEnum

Filter for transport mode. Available options: ANY_MODE, BIKING, BUS, CAR, FERRY, IDLE, RUNNING, TRAIN, TRAM, WALKING, INSUFFICIENT_DATA, UNSUPPORTED_MODE, MOTORCYCLE. Default: CAR.

new - UserEngagementCommunicationsSlice New Communications of the user
Arguments
type - UserEngagementCommunicationsRequest_TypeEnum

Type of the communication. Available options: IN_APP_MESSAGE, REACTIVE_MESSAGE.

transport_mode - UserEngagementTransportsRequest_TransportModeEnum

Filter for transport mode. Available options: ANY_MODE, BIKING, BUS, CAR, FERRY, IDLE, RUNNING, TRAIN, TRAM, WALKING, INSUFFICIENT_DATA, UNSUPPORTED_MODE, MOTORCYCLE. Default: CAR.

limit - Int

Number of communications to return.

category - UserEngagementCommunicationsRequest_CategoryEnum

Category of the communication. Available options: ALL, CHALLENGES, BADGES, STREAKS, SCORES, LEADERBOARD, TRIPS, PROFILE, SCHEDULED.

Example
{
  "all": UserEngagementCommunicationsSlice,
  "closed": UserEngagementCommunicationsSlice,
  "expired": UserEngagementCommunicationsSlice,
  "new": UserEngagementCommunicationsSlice
}

UserEngagementCommunicationsRequest_CategoryEnum

Values
Enum Value Description

STREAKS

SCORES

TRIPS

GROUPS

CHALLENGES

BADGES

LEADERBOARD

PROFILE

SCHEDULED

ALL

Example
"STREAKS"

UserEngagementCommunicationsRequest_TypeEnum

Values
Enum Value Description

IN_APP_MESSAGE

REACTIVE_MESSAGE

Example
"IN_APP_MESSAGE"

UserEngagementCommunicationsSlice

Fields
Field Name Description
slice - [UserEngagementCommunication] List of communications.
Example
{"slice": [UserEngagementCommunication]}

UserEngagementCurrentPOI

Fields
Field Name Description
entered_poi_at - Float Timestamp when the user entered the POI in epoch milliseconds.
poi_details - EngagementPOI POI details.
poi_id - String ID of the POI.
Example
{
  "entered_poi_at": 987.65,
  "poi_details": EngagementPOI,
  "poi_id": "xyz789"
}

UserEngagementDailyRewardsAggregations

Fields
Field Name Description
data - UserEngagementDailyRewardsAggregationsData Data that was aggregated.
dimensions - UserEngagementDailyRewardsAggregationsDimensions Dimensions for the aggregation. All data is grouped by these dimensions except when it's not sliced
metadata - UserEngagementDailyRewardsAggregationsMetadata Metadata for the aggregation.
Example
{
  "data": UserEngagementDailyRewardsAggregationsData,
  "dimensions": UserEngagementDailyRewardsAggregationsDimensions,
  "metadata": UserEngagementDailyRewardsAggregationsMetadata
}

UserEngagementDailyRewardsAggregationsData

Fields
Field Name Description
points - Float Value of chosen aggregation type for points.
Example
{"points": 123.45}

UserEngagementDailyRewardsAggregationsDimensions

Fields
Field Name Description
time_frame - TimeFrame Time frame for the aggregation.
Example
{"time_frame": TimeFrame}

UserEngagementDailyRewardsAggregationsMetadata

Fields
Field Name Description
function - AggregationFunctionEnum Type of aggregation performed.
slice_by - SliceByEnum How data was sliced. Can be missing if the request didn't contain a slice_by field.
Example
{"function": "AVG", "slice_by": "YEAR"}

UserEngagementDailyRewardsAggregationsSlice

Fields
Field Name Description
slice - [UserEngagementDailyRewardsAggregations] Slice of aggregated data for the user.
Example
{"slice": [UserEngagementDailyRewardsAggregations]}

UserEngagementGroup

Fields
Field Name Description
created_at - Float Create time in epoch milliseconds.
feed - UserEngagementGroupFeed Events feed of the group.
Arguments
ranking_attribute - UserEngagementGroupRankingAttributeEnum

Ranking attribute to populate the group feed by. Available options: DRIVER_COACHING_SCORE. Options applicable depending on how the group was created.

group_id - String ID of the group.
leaderboard - UserEngagementGroupLeaderboard Leaderboard of the group.
Arguments
ranking_attribute - UserEngagementGroupRankingAttributeEnum

Ranking attribute to populate the group leaderboard by. Available options: DRIVER_COACHING_SCORE.

members - UserEngagementGroupMembers Members of the group.
name - String Name of the group.
points_of_interest - UserEngagementGroupPois Points of interest of the group.
reg_code - String Registration code of the group.
Example
{
  "created_at": 123.45,
  "feed": UserEngagementGroupFeed,
  "group_id": "xyz789",
  "leaderboard": UserEngagementGroupLeaderboard,
  "members": UserEngagementGroupMembers,
  "name": "abc123",
  "points_of_interest": UserEngagementGroupPois,
  "reg_code": "abc123"
}

UserEngagementGroupFeed

Fields
Field Name Description
group_id - String ID of the group.
slice - [UserEngagementGroupFeedMessage] List of feed messages.
Example
{
  "group_id": "abc123",
  "slice": [UserEngagementGroupFeedMessage]
}

UserEngagementGroupFeedMessage

Fields
Field Name Description
generated_at - String Time feed message was generated in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
message - String Parameterised feed message.
params - [String] List of parameters to be replaced in the feed message.
Example
{
  "generated_at": "abc123",
  "message": "xyz789",
  "params": ["abc123"]
}

UserEngagementGroupLeaderboard

Fields
Field Name Description
group_id - String ID of the group.
slice - [UserEngagementGroupLeaderboardMember] List of leaderboard members.
Example
{
  "group_id": "abc123",
  "slice": [UserEngagementGroupLeaderboardMember]
}

UserEngagementGroupLeaderboardMember

Fields
Field Name Description
rank - Int User's rank in the group's leaderboard.
ranking_attr - String Attribute by which the leaderboard was ranked.
ranking_score - Float User's score in the group's leaderboard.
user_id - String Sentiance ID of the user.
Example
{
  "rank": 987,
  "ranking_attr": "abc123",
  "ranking_score": 987.65,
  "user_id": "xyz789"
}

UserEngagementGroupMember

Fields
Field Name Description
current_poi - UserEngagementCurrentPOI Current POI the user is inside.
joined_at - Float Join timestamp in epoch milliseconds.
last_known_location - EngagementCoordinates Last known location coordinates of the user.
poi_subscriptions - [String] List of POIs the user is subscribed to.
role - UserEngagementGroupRoleEnum Role of the user in the group.
status - String Status of the user.
status_expires_at - Float Timestamp when the status expires in epoch milliseconds.
user_id - String Sentiance ID of the user.
Example
{
  "current_poi": UserEngagementCurrentPOI,
  "joined_at": 123.45,
  "last_known_location": EngagementCoordinates,
  "poi_subscriptions": ["xyz789"],
  "role": "UNKNOWN",
  "status": "abc123",
  "status_expires_at": 987.65,
  "user_id": "xyz789"
}

UserEngagementGroupMembers

Fields
Field Name Description
slice - [UserEngagementGroupMember] List of group members.
Example
{"slice": [UserEngagementGroupMember]}

UserEngagementGroupPois

Fields
Field Name Description
group_id - String ID of the group.
slice - [UserEngagementGroupPoisSlice] List of POIs.
Example
{
  "group_id": "xyz789",
  "slice": [UserEngagementGroupPoisSlice]
}

UserEngagementGroupPoisSlice

Fields
Field Name Description
poi_details - EngagementPOI POI details.
poi_id - String ID of the POI.
Example
{
  "poi_details": EngagementPOI,
  "poi_id": "abc123"
}

UserEngagementGroupRankingAttributeEnum

Values
Enum Value Description

DRIVER_COACHING_SCORE

Example
"DRIVER_COACHING_SCORE"

UserEngagementGroupRoleEnum

Values
Enum Value Description

UNKNOWN

ADMIN

MEMBER

PENDING

Example
"UNKNOWN"

UserEngagementGroupTypeEnum

Values
Enum Value Description

SOCIAL

Example
"SOCIAL"

UserEngagementGroups

Fields
Field Name Description
slice - [UserEngagementGroup] Groups of a user,
user_id - String Sentiance ID of the user.
Example
{
  "slice": [UserEngagementGroup],
  "user_id": "abc123"
}

UserEngagementLibrary

Fields
Field Name Description
knowledge_bites - UserEngagementLibraryKnowledgeBites Engagement knowledge bytes.
smart_tips - UserEngagementLibrarySmartTips Engagement smart tips.
Example
{
  "knowledge_bites": UserEngagementLibraryKnowledgeBites,
  "smart_tips": UserEngagementLibrarySmartTips
}

UserEngagementLibraryItem

Fields
Field Name Description
category - String Category of library item.
content - String Content of library item.
content_extra - String Extra content of library item.
created_at - String Created time in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
item_id - String ID of library item.
subcategory - String Subcategory of library item.
title - String Title of library item.
Example
{
  "category": "xyz789",
  "content": "abc123",
  "content_extra": "abc123",
  "created_at": "xyz789",
  "item_id": "xyz789",
  "subcategory": "xyz789",
  "title": "xyz789"
}

UserEngagementLibraryKnowledgeBites

Fields
Field Name Description
slice - [UserEngagementLibraryItem] List of knowledge bytes.
Example
{"slice": [UserEngagementLibraryItem]}

UserEngagementLibrarySmartTips

Fields
Field Name Description
slice - [UserEngagementLibraryItem] List of smart tips.
Example
{"slice": [UserEngagementLibraryItem]}

UserEngagementScores

Fields
Field Name Description
slice - [EngagementScore] List containing scores. Available scores are: OVERALL_SCORE, MFFS_SCORE, ATTENTION_SCORE, HARSH_MOVEMENT_SCORE, FOCUS_SCORE, CALL_WHILE_MOVING_SCORE, LEGAL_SCORE, SMOOTH_SCORE depending on your integration with Sentiance.
Example
{"slice": [EngagementScore]}

UserEngagementScoresRequest_TransportModeEnum

Values
Enum Value Description

BIKING

BUS

CAR

IDLE

TRAIN

FERRY

RUNNING

TRAM

WALKING

MOTORCYCLE

Example
"BIKING"

UserEngagementStreaks

Fields
Field Name Description
best - UserEngagementStreaksCount Best streaks of the user
current - UserEngagementStreaksCount Current streaks of the user.
user_id - String Sentiance ID of the user.
Example
{
  "best": UserEngagementStreaksCount,
  "current": UserEngagementStreaksCount,
  "user_id": "abc123"
}

UserEngagementStreaksContext

Fields
Field Name Description
daily_avg_scores - DailyAvgScores Daily average scores, excluding today.
scores_trend - ScoresTrend Trend of the scores.
streak_thresholds - EngagementStreakThresholds Streaks thresholds configuration.
today_avg_scores - EngagementScores Today's average scores.
Example
{
  "daily_avg_scores": DailyAvgScores,
  "scores_trend": ScoresTrend,
  "streak_thresholds": EngagementStreakThresholds,
  "today_avg_scores": EngagementScores
}

UserEngagementStreaksCount

Fields
Field Name Description
context - UserEngagementStreaksContext Context around streaks. Values returned here depend on your integration with Sentiance.
slice - [EngagementScore] List containing streaks for each score. Available scores are: OVERALL_SCORE, MFFS_SCORE, ATTENTION_SCORE, HARSH_MOVEMENT_SCORE, FOCUS_SCORE, CALL_WHILE_MOVING_SCORE, LEGAL_SCORE, SMOOTH_SCORE depending on your integration with Sentiance.
Example
{
  "context": UserEngagementStreaksContext,
  "slice": [EngagementScore]
}

UserEngagementTransport

Fields
Field Name Description
can_receive_feedback - Boolean Flag that marks the transport eligible to receive feedback.
created_at - String Create time in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
duration - Float Total duration in minutes.
end_at - String End time in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
in_grace_period - Boolean Flag that marks the transport as inside of the grace period or outside of grace period. Always false if grace period not enabled for user.
mode - String Mode of transport.
occupant_role - String Occupant role of the transport if mode is CAR.
scores - UserEngagementTransportScores Scores for the transport.
start_at - String Start time in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
trajectory - UserEngagementTransportTrajectory Trajectory of the transport.
transport_id - String ID of the transport.
Example
{
  "can_receive_feedback": false,
  "created_at": "xyz789",
  "duration": 123.45,
  "end_at": "abc123",
  "in_grace_period": false,
  "mode": "xyz789",
  "occupant_role": "xyz789",
  "scores": UserEngagementTransportScores,
  "start_at": "abc123",
  "trajectory": UserEngagementTransportTrajectory,
  "transport_id": "abc123"
}

UserEngagementTransportAggregationsData

Fields
Field Name Description
distance - Float Value of chosen aggregation type for distance. Unit is meters.
duration - Float Value of chosen aggregation type for duration. Unit is minutes.
events - UserEngagementTransportAggregationsData_UserEngagementTransportEventsAggregations Events for the aggregation. Only applicable for CAR,MOTORCYCLE, BUS transport mode with occupant role DRIVER. For rest of transport modes/occupant roles this filed is ignored and null is returned.
scores - UserEngagementTransportAggregationsData_UserEngagementTransportScoresAggregations Scores for the aggregation. Only applicable for CAR, MOTORCYCLE, BUS transport mode with occupant role DRIVER. For rest of transport modes/occupant roles this filed is ignored and null is returned.
Example
{
  "distance": 987.65,
  "duration": 123.45,
  "events": UserEngagementTransportAggregationsData_UserEngagementTransportEventsAggregations,
  "scores": UserEngagementTransportAggregationsData_UserEngagementTransportScoresAggregations
}

UserEngagementTransportAggregationsData_UserEngagementTransportEventsAggregations

Fields
Field Name Description
slice - [EngagementTransportEvent] List containing aggregated transport events. Available events are: CALL_EVENTS_COUNT, CALL_EVENTS_DURATION, PHONE_HANDLING_EVENTS_COUNT, PHONE_HANDLING_EVENTS_DURATION, SCREEN_EVENTS_COUNT, SCREEN_EVENTS_DURATION depending on your integration with Sentiance.
Example
{"slice": [EngagementTransportEvent]}

UserEngagementTransportAggregationsData_UserEngagementTransportScoresAggregations

Fields
Field Name Description
slice - [EngagementScore] List containing aggregated scores. Available scores are: OVERALL_SCORE, MFFS_SCORE, ATTENTION_SCORE, HARSH_MOVEMENT_SCORE, FOCUS_SCORE, CALL_WHILE_MOVING_SCORE, LEGAL_SCORE, SMOOTH_SCORE depending on your integration with Sentiance.
Example
{"slice": [EngagementScore]}

UserEngagementTransportAggregationsDimensions

Fields
Field Name Description
occupant_role - String Occupant role for the aggregation. Note: only applicable for CAR or BUS transport mode. For rest of transport modes this filed is ignored and null is returned.
time_frame - TimeFrame Time frame for the aggregation.
transport_mode - String Transport mode for the aggregation.
Example
{
  "occupant_role": "xyz789",
  "time_frame": TimeFrame,
  "transport_mode": "abc123"
}

UserEngagementTransportAggregationsMetadata

Fields
Field Name Description
function - AggregationFunctionEnum Type of aggregation performed.
slice_by - SliceByEnum How data was sliced. Can be missing if the request didn't contain a slice_by field.
Example
{"function": "AVG", "slice_by": "YEAR"}

UserEngagementTransportAggregationsSlice

Fields
Field Name Description
slice - [UserEngagementTransportsAggregations] Slice of aggregated data for the user.
Example
{"slice": [UserEngagementTransportsAggregations]}

UserEngagementTransportScores

Fields
Field Name Description
slice - [EngagementScore] List containing scores. Available scores are: OVERALL_SCORE, MFFS_SCORE, ATTENTION_SCORE, HARSH_MOVEMENT_SCORE, FOCUS_SCORE, CALL_WHILE_MOVING_SCORE, LEGAL_SCORE, SMOOTH_SCORE depending on your integration with Sentiance.
Example
{"slice": [EngagementScore]}

UserEngagementTransportTrajectory

Fields
Field Name Description
distance - Float Total distance travelled in meters.
end_location - UserEngagementTransportTrajectoryLocation End location of the transport.
polyline - String The encoded path using Google's Encoded Polyline Algorithm format.
start_location - UserEngagementTransportTrajectoryLocation Start location of the transport.
Example
{
  "distance": 123.45,
  "end_location": UserEngagementTransportTrajectoryLocation,
  "polyline": "abc123",
  "start_location": UserEngagementTransportTrajectoryLocation
}

UserEngagementTransportTrajectoryLocation

Fields
Field Name Description
city - String City name.
country - String Country name.
district - String District name.
latitude - Float Latitude of the location.
longitude - Float Longitude of the location.
region - String Region name.
street - String Street name.
Example
{
  "city": "abc123",
  "country": "abc123",
  "district": "xyz789",
  "latitude": 123.45,
  "longitude": 987.65,
  "region": "abc123",
  "street": "abc123"
}

UserEngagementTransports

Fields
Field Name Description
meta - UserEngagementTransportsMeta Metadata of the transport response.
slice - [UserEngagementTransport] List of transports.
Example
{
  "meta": UserEngagementTransportsMeta,
  "slice": [UserEngagementTransport]
}

UserEngagementTransportsAggregations

Fields
Field Name Description
data - UserEngagementTransportAggregationsData Data that was aggregated.
dimensions - UserEngagementTransportAggregationsDimensions Dimensions for the aggregation. All data is grouped by these dimensions except when it's not sliced, than is grouped only by transport mode and occupant role. The reason for this grouping is that this is how the Sentiance data makes sense and should be interpreted.
metadata - UserEngagementTransportAggregationsMetadata Metadata for the aggregation.
Example
{
  "data": UserEngagementTransportAggregationsData,
  "dimensions": UserEngagementTransportAggregationsDimensions,
  "metadata": UserEngagementTransportAggregationsMetadata
}

UserEngagementTransportsMeta

Fields
Field Name Description
next_token - String Pagination token to be used in the next transports request.
Example
{"next_token": "xyz789"}

UserEngagementTransportsRequest_InGracePeriodEnum

Values
Enum Value Description

FALSE

ALL

TRUE

Example
"FALSE"

UserEngagementTransportsRequest_OccupantRoleEnum

Values
Enum Value Description

ANY

DRIVER

PASSENGER

DRIVER_AND_PASSENGER

UNKNOWN

Example
"ANY"

UserEngagementTransportsRequest_TransportModeEnum

Values
Enum Value Description

WALKING

BIKING

BUS

FERRY

IDLE

TRAM

UNSUPPORTED_MODE

MOTORCYCLE

ANY_MODE

CAR

RUNNING

TRAIN

INSUFFICIENT_DATA

Example
"WALKING"

UserScores

Fields
Field Name Description
driving - UserScoresDriving
Example
{"driving": UserScoresDriving}

UserScoresDriving

Fields
Field Name Description
safety - UserScoresDrivingSafety
Example
{"safety": UserScoresDrivingSafety}

UserScoresDrivingSafety

Fields
Field Name Description
primary - PrimarySafetyScores Primary safety scores belonging to the user.
secondary - SecondarySafetyScores Secondary safety scores belonging to the user.
unified - UnifiedSafetyScores Unified safety scores belonging to the user.
Example
{
  "primary": PrimarySafetyScores,
  "secondary": SecondarySafetyScores,
  "unified": UnifiedSafetyScores
}

WeatherData

Fields
Field Name Description
apparent_temperature - Float The apparent temperature is a measure for the human thermal comfort. On the basis of the air temperature, the apparent temperature is computed considering effects of relative humidity, wind speed and solar radiation.
cloud_cover - Float Cloud cover as a fraction between 0-1.
dew_point - Float Dew point in degrees celcius
humidity - Float Relative humidity as a fraction between 0-1.
icon - String URL of the icon representing the weather
ozone - Float deprecated; no longer available
precipitation_intensity - Float Precipitation accumulated over the past hour in millimeter
precipitation_probability - Float Probability of precipitation
pressure - Float Pressure in millibars
summary - String Textual description of the weather
sunrise - String time of sunrise
sunset - String time of sunset
temperature - Float Instantaneous temperature at 2m above ground in degrees Celsius
uv_index - Float UV Index
visibility - Float Visibility in km
wind_bearing - Float Wind direction in degrees due north
wind_gust - Float Wind gust in m/s
wind_speed - Float Wind speed in m/s
Example
{
  "apparent_temperature": 123.45,
  "cloud_cover": 123.45,
  "dew_point": 123.45,
  "humidity": 123.45,
  "icon": "abc123",
  "ozone": 987.65,
  "precipitation_intensity": 987.65,
  "precipitation_probability": 987.65,
  "pressure": 123.45,
  "summary": "abc123",
  "sunrise": "xyz789",
  "sunset": "xyz789",
  "temperature": 123.45,
  "uv_index": 123.45,
  "visibility": 987.65,
  "wind_bearing": 987.65,
  "wind_gust": 123.45,
  "wind_speed": 123.45
}