-
Notifications
You must be signed in to change notification settings - Fork 1
Journeys and Payment Related Calls
Here are a set of scenarios related to how to update the API when things happen that may affect how a move will be paid.
In particular, please note the "billable"
attribute on each request.
- Single journey move
- Redirection before move commences
- Redirection after move commences
NB: the documentation below is currently being reviewed; please refer to the documentation above for the latest updates
GIVEN a move requested with the Book a secure move service to transfer a person from Location A to Location B requires multiple journeys to undertake,
WHEN redirections occur due to the suppliers fault,
THEN the supplier will be given the opportunity to indicate the journeys they should not be paid for.
Journeys should be created via the create journeys endpoint. Journey events can be logged against the new journey, and the billable flag can be set via a PATCH on the journey.
-
Create a billable journey for the move (in a proposed state)
POST /moves/{move_id}/journeys { "type": "journeys", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "billable": true, "date": "2020-04-21", "vehicle": { "id": "12345678ABC", "registration": "AB12 CDE" } }, "relationships": { "from_location": { "data": { "type": "locations", "id": "AAAAAAAA-0154-49ec-b01e-d60ded8e0ab1" } }, "to_location": { "data": { "type": "locations", "id": " BBBBBBBB-0154-49ec-b01e-d60ded8e0ab1" } }, } }
-
Start the journey, changing its state from proposed to in_progress
POST /moves/{move_id}/journeys/{journey_id}/start { "type": "starts", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "notes": "Going via M25 to avoid traffic" } }
-
Cancel the original journey because of a problem
POST /moves/{move_id}/journeys/{journey_id}/cancel { "type": "cancels", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "notes": "breakdown - flat tyre" } }
-
Update the original journey to mark it as not billable
PATCH /moves/{move_id}/journeys/{journey_id} { "type": "journeys", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "billable": false } }
-
Create a new non-billable journey2 to go to an alternative location
POST /moves/{move_id}/journeys { "type": "journeys", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "billable": false, "date": "2020-04-21", "vehicle": { "id": "987654321DEF", "registration": "FG34 HIJ" } }, "relationships": { "from_location": { "data": { "type": "locations", "id": "AAAAAAAA-0154-49ec-b01e-d60ded8e0ab1" } }, "to_location": { "data": { "type": "locations", "id": " CCCCCCCC-0154-49ec-b01e-d60ded8e0ab1" } }, } }
-
Start the new journey2, changing its state from proposed to in_progress
POST /moves/{move_id}/journeys/{journey_id2}/start { "type": "starts", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "notes": "going to alternative location" } }
-
Complete the new journey
POST /moves/{move_id}/journeys/{journey_id2}/complete { "type": "completes", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "notes": "arrived at alternative location" } }
GIVEN a move has been requested with the Book a secure move service to transfer a person from Location A to Location B,
AND there have been no redirection events during the move,
WHEN the supplier marks the move as completed,
THEN the authority will need to pay the supplier the corresponding price found in the journey price catalogue for the ultimate start and end points of the move.
AND all intermediate journeys undertaken by the supplier to complete the move will not be used to calculate the payment.
-
Create a billable journey for the move (in a proposed state)
POST /moves/{move_id}/journeys { "type": "journeys", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "billable": true, "date": "2020-04-21", "vehicle": { "id": "12345678ABC", "registration": "AB12 CDE" } }, "relationships": { "from_location": { "data": { "type": "locations", "id": "AAAAAAAA-0154-49ec-b01e-d60ded8e0ab1" } }, "to_location": { "data": { "type": "locations", "id": "BBBBBBBB-0154-49ec-b01e-d60ded8e0ab1" } }, } }
-
Start the first journey, changing its state from proposed to in_progress
POST /moves/{move_id}/journeys/{journey_id}/start { "type": "starts", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "notes": "heavy traffic reported" } }
-
Complete the first journey
POST /moves/{move_id}/journeys/{journey_id}/complete { "type": "completes", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "notes": "arrived at intermediate destination" } }
-
Create a billable second journey for the move (in a proposed state)
POST /moves/{move_id}/journeys { "type": "journeys", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "billable": true, "date": "2020-04-21", "vehicle": { "id": "12345678ABC", "registration": "AB12 CDE" } }, "relationships": { "from_location": { "data": { "type": "locations", "id": "BBBBBBBB-0154-49ec-b01e-d60ded8e0ab1" } }, "to_location": { "data": { "type": "locations", "id": "CCCCCCCC-0154-49ec-b01e-d60ded8e0ab1" } }, } }
-
Start the second journey, changing its state from proposed to in_progress
POST /moves/{move_id}/journeys/{journey_id2}/start { "type": "starts", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z" } }
-
Complete the second journey
POST /moves/{move_id}/journeys/{journey_id2}/complete { "type": "completes", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "notes": "arrived at final destination" } }
-
Complete the move
POST /moves/{move_id}/complete { "type": "completes", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "notes": "move completed without problems" } }
A move redirected at the request of PMU when the supplier is not at fault, composed of cancelled and completed journeys (both billable)
GIVEN a move has been requested with the Book a secure move service to transfer a person from Location A to Location B,
AND the supplier commences the move,
AND the supplier has yet to complete the move,
AND the supplier is notified by the Population Management Unit to transfer the person to an alternative Location C,
WHEN the supplier marks the move as completed,
THEN the authority will need to pay the supplier the corresponding price found in the journey price catalogue for the intended journey,
AND the authority will need to pay the supplier for subsequent journeys made by to deliver the person to the ultimate end point for the move.
-
Create a billable journey for the move (in a proposed state)
POST /moves/{move_id}/journeys { "type": "journeys", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "billable": true, "date": "2020-04-21", "vehicle": { "id": "12345678ABC", "registration": "AB12 CDE" } }, "relationships": { "from_location": { "data": { "type": "locations", "id": "AAAAAAAA-0154-49ec-b01e-d60ded8e0ab1" } }, "to_location": { "data": { "type": "locations", "id": "BBBBBBBB-0154-49ec-b01e-d60ded8e0ab1" } }, } }
-
Start the first journey, changing its state from proposed to in_progress
POST /moves/{move_id}/journeys/{journey_id}/start { "type": "starts", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "notes": "nothing of note" } }
-
Cancel the first journey as PMU request a redirect to new location NB: although the journey is marked as cancelled, it is also still marked as billable and so should factor into the billable calculation
POST /moves/{move_id}/journeys/{journey_id}/cancel { "type": "cancels", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "notes": "cancelling journey for redirection to new location" } }
-
Redirect move to new location
POST /moves/{move_id}/redirects { "type": "redirects", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "notes": "redirect requested by PMU" }, "relationships": { "to_location": { "data": { "type": "locations", "id": "CCCCCCCC-0154-49ec-b01e-d60ded8e0ab1" } } } }
-
Create a second billable journey for the move (in a proposed state)
POST /moves/{move_id}/journeys { "type": "journeys", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "billable": true, "date": "2020-04-21", "vehicle": { "id": "12345678ABC", "registration": "AB12 CDE" } }, "relationships": { "from_location": { "data": { "type": "locations", "id": "AAAAAAAA-0154-49ec-b01e-d60ded8e0ab1" } }, "to_location": { "data": { "type": "locations", "id": "CCCCCCCC-0154-49ec-b01e-d60ded8e0ab1" } }, } }
-
Start the second journey, changing its state from proposed to in_progress
POST /moves/{move_id}/journeys/{journey_id2}/start { "type": "starts", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "notes": "new redirected journey to CCCCCCCC" } }
-
Complete the second journey
POST /moves/{move_id}/journeys/{journey_id2}/complete { "type": "completes", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "notes": "completed journey to redirected location" } }
-
Complete the move
POST /moves/{move_id}/complete { "type": "completes", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "notes": "move completed with a redirect" } }
A redirected move caused by a lockout when the supplier is not at fault, composed of cancelled and completed journeys (billable)
GIVEN a move has been requested with the Book a secure move service to transfer a person from Location A to Location B,
AND the supplier is delayed leaving the prison because the prisoner absconds,
AND the supplier commences the move,
AND the supplier has yet to complete the move,
AND the supplier notifies the PMU that because of the delay they will be locked out of the Location B and the PMU agrees to transfer the person to an alternative Location C,
WHEN the supplier marks the move as completed,
THEN the authority will need to pay the supplier the corresponding price found in the journey price catalogue for the intended journey,
AND the authority will need to pay the supplier for subsequent journeys made by to deliver the person to the ultimate end point for the move.
-
Create a billable journey for the move (in a proposed state)
POST /moves/{move_id}/journeys { "type": "journeys", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "billable": true, "date": "2020-04-21", "vehicle": { "id": "12345678ABC", "registration": "AB12 CDE" } }, "relationships": { "from_location": { "data": { "type": "locations", "id": "AAAAAAAA-0154-49ec-b01e-d60ded8e0ab1" } }, "to_location": { "data": { "type": "locations", "id": "BBBBBBBB-0154-49ec-b01e-d60ded8e0ab1" } }, } }
-
Start the first journey, changing its state from proposed to in_progress
POST /moves/{move_id}/journeys/{journey_id}/start { "type": "starts", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "notes": "delayed start because prisoner absconded" } }
-
We need to record a lockout at the move destination because the van will not arrive in time (owing to the delayed start)
POST /moves/{move_id}/lockouts { "type": "lockouts", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "notes": "locked out owing to delayed start" }, "relationships": { "from_location": { "data": { "type": "locations", "id": "BBBBBBBB-0154-49ec-b01e-d60ded8e0ab1" } } } }
-
Redirect move to new location following agreement with PMU
POST /moves/{move_id}/redirects { "type": "redirects", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "notes": "redirect requested by PMU" }, "relationships": { "to_location": { "data": { "type": "locations", "id": "CCCCCCCC-0154-49ec-b01e-d60ded8e0ab1" } } } }
-
Now cancel the first journey as it we are redirecting to a new location (NB: although cancelled, it is still billable)
POST /moves/{move_id}/journeys/{journey_id}/cancel { "type": "cancels", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "notes": "cancelling journey for redirection to new location" } }
-
Create a second billable journey for the move (in a proposed state)
POST /moves/{move_id}/journeys { "type": "journeys", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "billable": true, "date": "2020-04-21", "vehicle": { "id": "12345678ABC", "registration": "AB12 CDE" } }, "relationships": { "from_location": { "data": { "type": "locations", "id": "AAAAAAAA-0154-49ec-b01e-d60ded8e0ab1" } }, "to_location": { "data": { "type": "locations", "id": "CCCCCCCC-0154-49ec-b01e-d60ded8e0ab1" } }, } }
-
Start the second journey
POST /moves/{move_id}/journeys/{journey_id2}/start { "type": "starts", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "notes": "redirected journey to CCCCCCCC" } }
-
Complete the second journey
POST /moves/{move_id}/journeys/{journey_id2}/complete { "type": "completes", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "notes": "redirected journey to CCCCCCCC" } }
-
Complete the move
POST /moves/{move_id}/complete { "type": "completes", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "notes": "move completed with a lockout and redirect" } }
A redirected move caused by a lockout when the supplier is at fault, composed of cancelled and completed journeys (partially billable)
GIVEN a move has been requested with the Book a secure move service to transfer a person from Location A to Location B,
AND the supplier commences the move,
AND the supplier has yet to complete the move,
AND the supplier is required to transfer the person to an alternative Location C due to no fault of the authority,
WHEN the supplier marks the move as completed,
THEN the authority will need to pay the supplier the corresponding price found in the journey price catalogue for the journeys marked as billable by the supplier.
-
Create a billable journey for the move (in a proposed state)
POST /moves/{move_id}/journeys { "type": "journeys", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "billable": true, "date": "2020-04-21", "vehicle": { "id": "12345678ABC", "registration": "AB12 CDE" } }, "relationships": { "from_location": { "data": { "type": "locations", "id": "AAAAAAAA-0154-49ec-b01e-d60ded8e0ab1" } }, "to_location": { "data": { "type": "locations", "id": "BBBBBBBB-0154-49ec-b01e-d60ded8e0ab1" } }, } }
-
Start the first journey, changing its state from proposed to in_progress
POST /moves/{move_id}/journeys/{journey_id}/start { "type": "starts", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "notes": "nothing to report" } }
-
There is van breakdown (flat tyre) causing a delay and lockout. In this case it is agreed that the original journey will not be billable and a new billable journey is created to an alternative location
Cancel the journey
POST /moves/{move_id}/journeys/{journey_id}/cancel { "type": "cancels", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "notes": "cancelling journey owing to breakdown (flat tyre)" } }
-
Update the original journey and mark it as not billable
PATCH /moves/{move_id}/journeys/{journey_id} { "type": "journeys", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "billable": false } }
-
We need to record a lockout at the move destination because the van will not arrive in time (owing to break down)
POST /moves/{move_id}/lockouts { "type": "lockouts", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "notes": "locked out owing to breakdown" }, "relationships": { "from_location": { "data": { "type": "locations", "id": "BBBBBBBB-0154-49ec-b01e-d60ded8e0ab1" } } } }
-
Redirect move to new location following agreement with PMU
POST /moves/{move_id}/redirects { "type": "redirects", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "notes": "redirect due to breakdown, agreed with PMU" }, "relationships": { "to_location": { "data": { "type": "locations", "id": "CCCCCCCC-0154-49ec-b01e-d60ded8e0ab1" } } } }
-
Create a second billable journey for the move (in a proposed state)
POST /moves/{move_id}/journeys { "type": "journeys", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "billable": true, "date": "2020-04-21", "vehicle": { "id": "12345678ABC", "registration": "AB12 CDE" } }, "relationships": { "from_location": { "data": { "type": "locations", "id": "AAAAAAAA-0154-49ec-b01e-d60ded8e0ab1" } }, "to_location": { "data": { "type": "locations", "id": "CCCCCCCC-0154-49ec-b01e-d60ded8e0ab1" } }, } }
-
Start the second journey
POST /moves/{move_id}/journeys/{journey_id2}/start { "type": "starts", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "notes": "redirected journey to CCCCCCCC" } }
-
Complete the second journey
POST /moves/{move_id}/journeys/{journey_id2}/complete { "type": "completes", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "notes": "redirected journey to CCCCCCCC" } }
-
Complete the move
POST /moves/{move_id}/complete { "type": "completes", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "notes": "move completed with a lockout and redirect" } }
A redirected move caused by a lockout when the supplier is at fault, with lodging at an intermediate location, composed of cancelled and completed journeys (partially billable)
GIVEN a move has been requested with the Book a secure move service to transfer a person from Location A to Location B,
AND the supplier commences the move,
AND the supplier has yet to complete the move,
AND the supplier is required to lodge the person to an alternative Location C due to no fault of the authority,
WHEN the supplier marks the move as completed,
THEN the authority will need to pay the supplier the corresponding price found in the journey price catalogue for the journeys marked as billable by the supplier.
-
Create a billable journey for the move (in a proposed state)
POST /moves/{move_id}/journeys { "type": "journeys", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "billable": true, "date": "2020-04-21", "vehicle": { "id": "12345678ABC", "registration": "AB12 CDE" } }, "relationships": { "from_location": { "data": { "type": "locations", "id": "AAAAAAAA-0154-49ec-b01e-d60ded8e0ab1" } }, "to_location": { "data": { "type": "locations", "id": "BBBBBBBB-0154-49ec-b01e-d60ded8e0ab1" } }, } }
-
Start the first journey, changing its state from proposed to in_progress
POST /moves/{move_id}/journeys/{journey_id}/start { "type": "starts", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "notes": "nothing to report" } }
-
There is a delay caused by lack of fuel which in turn causes a lockout from the original destination. In this case it is agreed to lodge overnight at an alternative location at the suppliers expense
POST /moves/{move_id}/journeys/{journey_id}/cancel { "type": "cancels", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "notes": "cancelling journey because of delay caused by lack of fuel" } }
-
We need to record a lockout at the move destination because the van will not arrive in time (owing to delay)
POST /moves/{move_id}/lockouts { "type": "lockouts", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "notes": "locked out owing to delay (lack of fuel)" }, "relationships": { "from_location": { "data": { "type": "locations", "id": "BBBBBBBB-0154-49ec-b01e-d60ded8e0ab1" } } } }
-
Create a second non-billable journey for the move to a lodging location LLLL (in a proposed state), at supplier’s expense
POST /moves/{move_id}/journeys { "type": "journeys", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "billable": false, "date": "2020-04-21", "vehicle": { "id": "12345678ABC", "registration": "AB12 CDE" } }, "relationships": { "from_location": { "data": { "type": "locations", "id": "AAAAAAAA-0154-49ec-b01e-d60ded8e0ab1" } }, "to_location": { "data": { "type": "locations", "id": "LLLLLLLL-0154-49ec-b01e-d60ded8e0ab1" } }, } }
-
Start the second journey, changing its state from proposed to in_progress
POST /moves/{move_id}/journeys/{journey_id2}/start { "type": "starts", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "notes": "going to lodging location" } }
-
Complete the second journey
POST /moves/{move_id}/journeys/{journey_id2}/complete { "type": "completes", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "notes": "arrived at lodging location" } }
-
Record the lodging against the second journey
POST /moves/{move_id}/journeys/{journey_id2}/lodgings { "type": "lodgings", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "notes": "cancelling journey owing to breakdown" }, "relationships": { "from_location": { "data": { "type": "locations", "id": "LLLLLLLL-0154-49ec-b01e-d60ded8e0ab1" } } } }
-
Create a third non-billable journey for the move from the lodging location LLLL to the final destination BBBB (in a proposed state), at supplier’s expense
POST /moves/{move_id}/journeys { "type": "journeys", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "billable": false, "date": "2020-04-21", "vehicle": { "id": "12345678ABC", "registration": "AB12 CDE" } }, "relationships": { "from_location": { "data": { "type": "locations", "id": "LLLLLLLL-0154-49ec-b01e-d60ded8e0ab1" } }, "to_location": { "data": { "type": "locations", "id": "BBBBBBBB-0154-49ec-b01e-d60ded8e0ab1" } }, } }
-
Start the third journey
POST /moves/{move_id}/journeys/{journey_id3}/start { "type": "starts", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "notes": "en route to final destination BBBB after lodging at LLLLL" } }
-
Complete the third journey
POST /moves/{move_id}/journeys/{journey_id3}/complete { "type": "completes", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "notes": "arrived at BBBB" } }
-
Complete the move
POST /moves/{move_id}/complete { "type": "completes", "attributes": { "timestamp": "2020-04-21T13:20:50.52Z", "notes": "move completed with a lockout and lodging" } }
- 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