-
Notifications
You must be signed in to change notification settings - Fork 1
Journey Events
This document describes journey events in the Book A Secure Move Api.
The typical order of journey events during the pick-up process from a designated location is expected to be:
- JourneyArriveAtOuterGate (of pick-up location)
- JourneyAdmitThroughOuterGate (of pick-up location)
- JourneyAdmitToReception (of pick-up location)
- JourneyHandoverToSupplier
- JourneyPersonBoardsVehicle
- JourneyStart
- JourneyReadyToExit (pick-up location)
- JourneyExitThroughOuterGate (of pick-up location)
The typical order of journey events during the drop-off process at a designated location is expected to be:
- JourneyArriveAtOuterGate (of drop-off location)
- JourneyAdmitThroughOuterGate (of drop-off location)
- JourneyAdmitToReception (of drop-off location)
- JourneyPersonLeaveVehicle
- JourneyHandoverToDestination
- JourneyComplete
Starting a journey will change the proposed
journey state to in_progress
. Indicates that the vehicle has begun to move. NB: This event occurs after the vehicle has been loaded and is ready to exit but before the vehicle has exited through the outer gate. A Move / Journey should not be started in the case where a vehicle moves to reposition itself at the pick up location.
Journey events do not alter the parent move associated with the journey: additional API calls may be necessary to complete or cancel the move.
Common attributes, only
POST /api/events
{
"data": {
"type": "events",
"attributes": {
"occurred_at": "2020-12-03T10:50:33+00:00",
"recorded_at": "2020-12-03T10:50:33+00:00",
"notes": "Additional information about this event",
"details": {
"vehicle_reg": "AB12 CDE"
},
"event_type": "JourneyStart"
},
"relationships": {
"eventable": {
"data": {
"type": "journeys",
"id": "1ac0e4b3-786b-4dee-a0ce-9ae4035963ac"
}
}
}
}
}
Common validations, only
Updates the journey state to in_progress
and updates the vehicle registration on the Journey if vehicle_reg
is supplied
Cancelling a journey will change the journey state from in_progress
to cancelled
.
Journey events do not alter the parent move associated with the journey: additional API calls may be necessary to complete or cancel the move.
Common attributes, only
POST /api/events
{
"data": {
"type": "events",
"attributes": {
"occurred_at": "2020-12-03 10:50:31 +0000",
"recorded_at": "2020-12-03 10:50:31 +0000",
"notes": "Additional information about this event",
"details": {
},
"event_type": "JourneyCancel"
},
"relationships": {
"eventable": {
"data": {
"type": "journeys",
"id": "ed0ec488-2875-45bb-9594-4b4bb7fa8cb3"
}
}
}
}
}
Common validations, only
Updates the journey status to cancelled
Completing a journey will change the journey state from in_progress
to completed
. NB: suppliers must complete Journeys when the person has been handed over to staff at a designated location.
Journey events do not alter the parent move associated with the journey: additional API calls may be necessary to complete or cancel the move. for billing.
Common attributes, only
POST /api/events
{
"data": {
"type": "events",
"attributes": {
"occurred_at": "2020-12-03T10:50:32+00:00",
"recorded_at": "2020-12-03T10:50:32+00:00",
"notes": "Additional information about this event",
"details": {
"vehicle_reg": "AB12 CDE"
},
"event_type": "JourneyComplete"
},
"relationships": {
"eventable": {
"data": {
"type": "journeys",
"id": "efd413e2-00c5-4f0c-bc4b-ab38c728ba51"
}
}
}
}
}
Common validations, only
Updates the journey status to completed
and updates the vehicle registration of the Journey if vehicle_reg
is supplied
DEPRECATED Recording a lockout event does not change the journey's state. After recording the lockout, the journey should be completed or cancelled and additional journey records created to a new location.
-
from_location
- The location the person was locked out from.
POST /api/events
{
"data": {
"type": "events",
"attributes": {
"occurred_at": "2020-12-03T10:50:33+00:00",
"recorded_at": "2020-12-03T10:50:33+00:00",
"notes": "Additional information about this event",
"details": {
},
"event_type": "JourneyLockout"
},
"relationships": {
"eventable": {
"data": {
"type": "journeys",
"id": "868a6c7e-f3b7-4ed8-aae3-ea737f599956"
}
},
"from_location": {
"data": {
"id": "e2374a91-af87-44a2-8c68-171ca0aafffa",
"type": "locations"
}
}
}
}
}
-
from_location
must be present in relationships.
None
DEPRECATED Recording a lodging event does not change the journey's state and is purely an auditing event.
-
to_location
- The location the person was lodging in.
POST /api/events
{
"data": {
"type": "events",
"attributes": {
"occurred_at": "2020-12-03T10:50:33+00:00",
"recorded_at": "2020-12-03T10:50:33+00:00",
"notes": "Additional information about this event",
"details": {
},
"event_type": "JourneyLodging"
},
"relationships": {
"eventable": {
"data": {
"type": "journeys",
"id": "419b99fd-691f-4a00-9487-1021de358a0d"
}
},
"to_location": {
"data": {
"id": "99c66b71-f89e-4e04-be4d-7b9d094db018",
"type": "locations"
}
}
}
}
}
-
from_location
must be present in relationships.
None
Indicates the moment when the person was expected to board the vehicle.
-
vehicle_reg
- the registration of the vehicle that was boarded. Required for reporting -
vehicle_type
- indicates the type of the vehicle being boarded.
POST /api/events
{
"data": {
"type": "events",
"attributes": {
"occurred_at": "2020-12-03T10:50:34+00:00",
"recorded_at": "2020-12-03T10:50:34+00:00",
"notes": "Additional information about this event",
"details": {
"vehicle_type": "pro_cab",
"vehicle_reg": "CQE-2755"
},
"event_type": "JourneyPersonBoardsVehicle"
},
"relationships": {
"eventable": {
"data": {
"type": "journeys",
"id": "0cdbbeb7-a813-4ae6-bab6-ebaa30ee070c"
}
}
}
}
}
-
vehicle_type
- presence, one of c4, pro_cab, mpv, 2_cell, 3_cell, 6_cell or 12_cell -
vehicle_reg
- presence
Person leaves escort vehicle.
Common attributes, only
POST /api/events
{
"data": {
"type": "events",
"attributes": {
"occurred_at": "2020-12-03T10:50:33+00:00",
"recorded_at": "2020-12-03T10:50:33+00:00",
"notes": "Additional information about this event",
"details": {
"vehicle_reg": "AB12 CDE"
},
"event_type": "JourneyPersonLeaveVehicle"
},
"relationships": {
"eventable": {
"data": {
"type": "journeys",
"id": "c46efa19-17c7-4bdc-a228-3ca00875bfe0"
}
}
}
}
}
Common validations, only
None
Escort vehicle loaded and ready to exit from the pick-up designated location. The location must be specified in the relationship data of the request.
Common attributes, only
POST /api/events
{
"data": {
"type": "events",
"attributes": {
"occurred_at": "2020-12-03T10:50:32+00:00",
"recorded_at": "2020-12-03T10:50:32+00:00",
"notes": "Additional information about this event",
"details": {
"vehicle_reg": "AB12 CDE"
},
"event_type": "JourneyReadyToExit"
},
"relationships": {
"eventable": {
"data": {
"type": "journeys",
"id": "3dc7a534-da02-4784-976e-4c29ed1ec11b"
}
},
"location": {
"data": {
"id": "0ee995d1-9390-4e85-9f5a-c6a436716234",
"type": "locations"
}
}
}
}
}
Common validations, only
None
Rejecting a journey will change the proposed
journey state to rejected
.
Journey events do not alter the parent move associated with the journey: additional API calls may be necessary to complete or cancel the move.
Common attributes, only
POST /api/events
{
"data": {
"type": "events",
"attributes": {
"occurred_at": "2020-12-03T10:50:32+00:00",
"recorded_at": "2020-12-03T10:50:32+00:00",
"notes": "Additional information about this event",
"details": {
},
"event_type": "JourneyReject"
},
"relationships": {
"eventable": {
"data": {
"type": "journeys",
"id": "e79aa38e-d432-474e-9b54-cd5c0aa5ed3e"
}
}
}
}
}
Common validations, only
Changes the state of a journey from proposed
to rejected
The vehicle exited through the outer gate of the pick-up designated location. The location must be specified in the relationship data of the request.
Common attributes, only
POST /api/events
{
"data": {
"type": "events",
"attributes": {
"occurred_at": "2020-12-03T10:50:32+00:00",
"recorded_at": "2020-12-03T10:50:32+00:00",
"notes": "Additional information about this event",
"details": {
"vehicle_reg": "AB12 CDE"
},
"event_type": "JourneyExitThroughOuterGate"
},
"relationships": {
"eventable": {
"data": {
"type": "journeys",
"id": "91297dea-9648-4efe-9f6a-e2162c02ea27"
}
},
"location": {
"data": {
"id": "0ee995d1-9390-4e85-9f5a-c6a436716234",
"type": "locations"
}
}
}
}
}
Common validations, only
None
The vehicle for the current journey has arrived at the outer gate of the pick-up or drop-off designated location. The location must be specified in the relationship data of the request.
Common attributes, only
POST /api/events
{
"data": {
"type": "events",
"attributes": {
"occurred_at": "2020-12-03T10:50:33+00:00",
"recorded_at": "2020-12-03T10:50:33+00:00",
"notes": "Additional information about this event",
"details": {
"vehicle_reg": "AB12 CDE"
},
"event_type": "JourneyArriveAtOuterGate"
},
"relationships": {
"eventable": {
"data": {
"type": "journeys",
"id": "9274313a-8e87-4ff0-82e6-248d72464a4f"
}
},
"location": {
"data": {
"id": "0ee995d1-9390-4e85-9f5a-c6a436716234",
"type": "locations"
}
}
}
}
}
Common validations, only
None
The vehicle was admitted through the outer gate of the pick-up or drop-off designated location. The location must be specified in the relationship data of the request.
-
vehicle_reg
- the registration of the vehicle that was admitted through the outer gate. Required for reporting -
supplier_personnel_number
- the supplier's unique identifier of the personnel driving the vehicle
POST /api/events
{
"data": {
"type": "events",
"attributes": {
"occurred_at": "2020-12-03T10:50:33+00:00",
"recorded_at": "2020-12-03T10:50:33+00:00",
"notes": "Additional information about this event",
"details": {
"vehicle_reg": "DYV-5576",
"supplier_personnel_number": "cd0c8221-6d7a-453d-b7f6-8816bf40a17d"
},
"event_type": "JourneyAdmitThroughOuterGate"
},
"relationships": {
"eventable": {
"data": {
"type": "journeys",
"id": "05307eb0-141d-4ffb-80e5-6010eafaab28"
}
},
"location": {
"data": {
"id": "0ee995d1-9390-4e85-9f5a-c6a436716234",
"type": "locations"
}
}
}
}
}
-
vehicle_reg
must be present in attributes.
None
The supplier has been admitted to the reception of the pick-up or drop-off designated location in order to perform a handover. The location must be specified in the relationship data of the request.
Common attributes, only
POST /api/events
{
"data": {
"type": "events",
"attributes": {
"occurred_at": "2020-12-03T10:50:33+00:00",
"recorded_at": "2020-12-03T10:50:33+00:00",
"notes": "Additional information about this event",
"details": {
"vehicle_reg": "AB12 CDE"
},
"event_type": "JourneyAdmitToReception"
},
"relationships": {
"eventable": {
"data": {
"type": "journeys",
"id": "05307eb0-141d-4ffb-80e5-6010eafaab28"
}
},
"location": {
"data": {
"id": "0ee995d1-9390-4e85-9f5a-c6a436716234",
"type": "locations"
}
}
}
}
}
Common validations, only
None
Person admitted to the Reception/Custody area of a designated location and handed over
-
supplier_personnel_number
- the supplier's unique identifier of the personnel handing over the person
POST /api/events
{
"data": {
"type": "events",
"attributes": {
"occurred_at": "2020-12-03T10:50:34+00:00",
"recorded_at": "2020-12-03T10:50:34+00:00",
"notes": "Additional information about this event",
"details": {
"supplier_personnel_number": "cb90b124-b1b6-4ebb-b5a2-e50bc09db5e6"
},
"event_type": "JourneyHandoverToDestination"
},
"relationships": {
"eventable": {
"data": {
"type": "journeys",
"id": "8daaef1c-a3f2-481e-be95-cd3aa3d96cb9"
}
}
}
}
}
Common validations, only
None
Person handed over from a pick-up designated location to the custody of the supplier
-
supplier_personnel_number
- the supplier's unique identifier of the personnel handing over the person
POST /api/events
{
"data": {
"type": "events",
"attributes": {
"occurred_at": "2020-12-03T10:50:34+00:00",
"recorded_at": "2020-12-03T10:50:34+00:00",
"notes": "Additional information about this event",
"details": {
"supplier_personnel_number": "cb90b124-b1b6-4ebb-b5a2-e50bc09db5e6"
},
"event_type": "JourneyHandoverToSupplier"
},
"relationships": {
"eventable": {
"data": {
"type": "journeys",
"id": "8daaef1c-a3f2-481e-be95-cd3aa3d96cb9"
}
}
}
}
}
Common validations, only
None
Uncancelling a journey will revert the cancelled
journey state to in_progress
.
Journey events do not alter the parent move associated with the journey: additional API calls may be necessary to complete or cancel the move.
Common attributes, only
POST /api/events
{
"data": {
"type": "events",
"attributes": {
"occurred_at": "2020-12-03T10:50:33+00:00",
"recorded_at": "2020-12-03T10:50:33+00:00",
"notes": "Additional information about this event",
"details": {
},
"event_type": "JourneyUncancel"
},
"relationships": {
"eventable": {
"data": {
"type": "journeys",
"id": "0f8bdc1c-0494-4a24-83ee-223dbf153a2c"
}
}
}
}
}
Common validations, only
Changes a journey's state from cancelled
to in_progress
Uncompleting a journey will revert the completed
journey state back to in_progress
.
Journey events do not alter the parent move associated with the journey: additional API calls may be necessary to complete or cancel the move.
Common attributes, only
POST /api/events
{
"data": {
"type": "events",
"attributes": {
"occurred_at": "2020-12-03T10:50:33+00:00",
"recorded_at": "2020-12-03T10:50:33+00:00",
"notes": "Additional information about this event",
"details": {
},
"event_type": "JourneyUncomplete"
},
"relationships": {
"eventable": {
"data": {
"type": "journeys",
"id": "742146df-2293-49da-9420-517011c3f748"
}
}
}
}
}
Common validations, only
Changes a journey's state from completed
to in_progress
Reflects a change in vehicle for pricing purposes. Usually after a PersonMoveVehicleBrokeDown or PersonMoveVehicleSystemsFailed event a change of vehicle happens. Use this event to capture when this event occurs and needs to be stored.
-
vehicle_reg
- The registration of the vehicle -
previous_vehicle_reg
- The registration of the vehicle that needed replacing
POST /api/events
{
"data": {
"type": "events",
"attributes": {
"occurred_at": "2020-12-03T10:50:33+00:00",
"recorded_at": "2020-12-03T10:50:33+00:00",
"notes": "Additional information about this event",
"details": {
"vehicle_reg": "YYR-3044",
"previous_vehicle_reg": "CID-1535"
},
"event_type": "JourneyChangeVehicle"
},
"relationships": {
"eventable": {
"data": {
"type": "journeys",
"id": "d7bb8e16-6f35-4997-abe1-46eb53fa8dc0"
}
}
}
}
}
-
vehicle_reg
- presence -
previous_vehicle_reg
- presence
Updates the Journey vehicle_registration
attribute which gets reflected in the JPC price calculations.
- API Guide
- Version 2
- Asked Questions
- Webhook & Email notifications
- Walkthroughs
- Deployment
- Useful Queries
- Data quality improvements
-
Journeys and Payment Related Calls
- Single journey move
- Redirection before move commences
- Redirection after move commences
- Lockouts and Lodgings
- Assessments
- Event Documentation
- GPS Track a move