Asked Questions

Asked Questions

These questions are not necessarily asked frequently, and when asked do not necessarily get asked using the form here. However, this is an interpretation of questions and answers that may help explain usage of the Book a Secure Move API.

1. How should a Move's from or to location be changed?

   A Move's from and to location should not normally be PATCHed. To change the from location, cancel the Move and start again. To change just the to location, a redirect event may be more appropriate.

2. Can a Move be uncancelled or uncompleted?

   Normally, no. Please do discuss with us if this is a requirement.

3. Should suppliers be creating allocations?

   We are unaware of a situation where a supplier would need to generate an allocation. Instead, it may be possible that a Move supplier needs to create a Move where the Person details are unavailable. This should be created as a Move without a Person record, rather than an allocation.
   Allocations are specific entities managed by the Authority with associated workflow.

4. Should suppliers keep copies of previous versions of entities and documents?

   The Book a Secure Move API is designed to be a real-time Move management system and cannot be guaranteed to provide an audit of previous versions of data or attachments. Suppliers will need to ensure that any information that they have acted upon is audited appropriately on the supplier side.

5. If a Person's details are changed, will that affect all Moves?

   Yes, if the key facts about a Person are changed (name, gender, date of birth - rather than assessment answers), then all previous, current and future Moves will be affected. If this could cause potential conflics in supplier systems, we suggest an exception process is carried out to decide the appropriate cause of action.

6. How are documents secured?

   When an entity is requested from the API that has a document/image link, a temporary URL will be configured for that document/image that grants access for 5 minutes. After that time, it will be impossible to fetch the document/image using the same URL, and in order to re-fetch the document/image, the parent entity will need to be requested again. As with all API requests, documents and images are served only over HTTPS.

7. Can a Profile be used for multiple Moves?

   Our API is designed in such a way that if a Profile has been created for a Person, then it could be attached to multiple Moves. However, if there is any doubt as to whether the information contained in the Profile (for example, answers to assessment questions) has remained the same, then a new Profile should be generated.

8. Is it possible to send supplier-generated key IDs to the API?

   It is not possible for suppliers or external systems to generate Move IDs, Profile IDs, etc. Instead, on the initial POST of each entity, the newly generated ID will be returned.

9. What happens when a Person cannot be found when suppliers are creating Moves?

   In the case a Person cannot be found, then we suggest creating a new Person record. There will be a reconciliation process to look for and merge unintended duplicate records.

10. Are all Moves without Profile/Person IDs of type allocation?

    It is possible to create a Move without a Person/Profile record to support scenarios like 'Tornado Moves'. These should be fairly unlikely in normal circumstances.

11. In the lockout event (POST moves/{move_id}/lockout), what is the from_location?

    In lockouts, the from_location represents the establishment that the Move was locked out from. This may be the Move's to_location, but not always.

12. In the redirect event (POST moves/{move_id}/redirect), what is the to_location?

    In redirects, the to_location is the replacement for the Move's original to_location. It is a fundamental change to the Move, and any subsequent journeys should normally take place under a new Move.

13. In a journey's lodging record, what does to_location represent?

    The to_location in a lodging record is the place that the lodging takes place.

14. Is there any validation in the API for a Person with both a PNC/PN number? If a Person has both, is there a precedence or should it always be a case that their PNC number and PN numbers are UUID's and as such always lead back to the same Person?

    We cannot guarantee that the records entered into the system will always have the correct PNC and/or PN number, so we would recommend than any discrepancies are verified by the suppliers.

15. To what extent will suppliers be interacting with Allocations? Will suppliers be creating them or modifying them?

    There is currently no expectation for suppliers to modify or create Allocations. Suppliers may find it useful to look at details of Allocations in order to prepare appropriate resources. Please see Allocation Moves