Skip to content

API Walkthroughs 18.2 Prison to AP move with PN

Jump to bottom
danbenton-mojdt edited this page Jun 19, 2023 · 1 revision

Moves API Walkthrough

18.2 Prison to Approved Premises moves

18.2 Move for a person with a PN identifier from Prison to Approved Premises on a specific move date

  1. [FRONTEND] The initial move record is created in a requested state with a specific move date by a PECS Prison user via the frontend. A new profile is assigned to the move.

    It is not expected that suppliers would create the initial record. For the purposes of testing however, frontend requests can be simulated with the following calls:

    #  get the existing person record(s) by searching by *prison number*
curl --request GET \
  --url 'http://server/api/people?filter%5Bprison_number%5D=G8133UA&include=profiles' \
  --header 'accept: application/vnd.api+json; version=2' \
  --header 'authorization: Bearer XXX'

# NB: an existing profile record *may* be re-used across multiple moves. Profiles can be reused over a period of custody. However, we advise that a new profile is created for separate custody periods.
# NB: for people with a prison_number, creating a profile without assessment answers will trigger an initial synchronisation with Nomis. Creating a profile with assessment answers will not trigger a synchronisation with Nomis
# create a new profile synchronised with Nomis alerts
curl --request POST \
  --url http://server/api/people/747f3914-620a-441a-847f-472c79def26c/profiles \
  --header 'accept: application/vnd.api+json; version=2' \
  --header 'authorization: Bearer XXX' \
  --header 'content-type: application/json' \
  --header 'idempotency-key: 66f5db32-cab4-4315-b80a-4dbe4631f8be' \
  --data '{ "data": { "type": "profiles" } }'

# create a Prison to Approved Premises move using the new profile
curl --request POST \
  --url http://server/api/moves \
  --header 'accept: application/vnd.api+json; version=2' \
  --header 'authorization: Bearer XXX' \
  --header 'content-type: application/json' \
  --header 'idempotency-key: 5fea0ab5-3307-4b77-99b0-4dfaa22c3897' \
  --data '{
  "data": {
    "type": "moves",
    "attributes": {
      "date": "2020-08-07",
      "status": "requested",
      "additional_information": "example Prison to AP move: HMP Isle of Wight to Brigstocke Road Approved Premises",
      "move_type": "approved_premises"
    },
    "relationships": {
      "profile": {
        "data": {
          "type": "profiles",
          "id": "325a81c9-e8d5-4439-99c0-5978e22b147f"
        }
      },
      "from_location": {
        "data": {
          "type": "locations",
          "id": "57872fcf-d26e-404e-ab8c-0e91b27657c4"
        }
      },
      "to_location": {
        "data": {
          "type": "locations",
          "id": "0a4f6c97-1757-452a-8c0b-9db422f6e7d7"
        }
      }
    }
  }
}'

    This returns the new move record:

    {
  "data": {
    "id": "d75d8d7e-b4c8-4a8c-bbcf-f71a82001899",
    "type": "moves",
    "attributes": {
      "additional_information": "example Prison to Hospital move: HMP Isle of Wight to Brigstocke Road Approved Premises",
      "cancellation_reason": null,
      "cancellation_reason_comment": null,
      "created_at": "2020-08-06T16:41:13+01:00",
      "date": "2020-08-07",
      "date_from": null,
      "date_to": null,
      "move_agreed": null,
      "move_agreed_by": null,
      "move_type": "approved_premises",
      "reference": "JHY4716X",
      "rejection_reason": null,
      "status": "requested",
      "time_due": null,
      "updated_at": "2020-08-06T16:41:13+01:00"
    },
    "relationships": {
      "profile": {
        "data": {
          "id": "325a81c9-e8d5-4439-99c0-5978e22b147f",
          "type": "profiles"
        }
      },
      "from_location": {
        "data": {
          "id": "056eed18-772b-45b3-b64a-4d7d563641f7",
          "type": "locations"
        }
      },
      "to_location": {
        "data": {
          "id": "57872fcf-d26e-404e-ab8c-0e91b27657c4",
          "type": "locations"
        }
      },
      "prison_transfer_reason": {
        "data": null
      },
      "court_hearings": {
        "data": []
      },
      "allocation": {
        "data": null
      },
      "original_move": {
        "data": null
      }
    }
  }
}

  2. Suppliers can retrieve a list of requested moves for specific dates by calling the get moves endpoint with appropriate filters:

    curl --request GET \
  --url 'http://server/api/moves?filter%5Bdate_from%5D=2020-08-07&filter%5Bdate_to%5D=2020-08-07&filter%5Bstatus%5D=requested&include=profile.person%2Cfrom_location%2Cto_location' \
  --header 'accept: application/vnd.api+json; version=2' \
  --header 'authorization: Bearer XXX'

    This returns the following JSON:

    {
  "data": [
    {
      "id": "d75d8d7e-b4c8-4a8c-bbcf-f71a82001899",
      "type": "moves",
      "attributes": {
        "additional_information": "example Prison to Hospital move: HMP Isle of Wight to Brigstocke Road Approved Premises",
        "cancellation_reason": null,
        "cancellation_reason_comment": null,
        "created_at": "2020-08-06T16:41:13+01:00",
        "date": "2020-08-07",
        "date_from": null,
        "date_to": null,
        "move_agreed": null,
        "move_agreed_by": null,
        "move_type": "approved_premises",
        "reference": "JHY4716X",
        "rejection_reason": null,
        "status": "requested",
        "time_due": null,
        "updated_at": "2020-08-06T16:41:13+01:00"
      },
      "relationships": {
        "profile": {
          "data": {
            "id": "325a81c9-e8d5-4439-99c0-5978e22b147f",
            "type": "profiles"
          }
        },
        "from_location": {
          "data": {
            "id": "056eed18-772b-45b3-b64a-4d7d563641f7",
            "type": "locations"
          }
        },
        "to_location": {
          "data": {
            "id": "57872fcf-d26e-404e-ab8c-0e91b27657c4",
            "type": "locations"
          }
        },
        "prison_transfer_reason": {
          "data": null
        },
        "court_hearings": {
          "data": []
        },
        "allocation": {
          "data": null
        },
        "original_move": {
          "data": null
        }
      }
    }
  ],
  "included": [
    {
      "id": "325a81c9-e8d5-4439-99c0-5978e22b147f",
      "type": "profiles",
      "attributes": {
        "assessment_answers": [
          {
            "title": "Any other risks",
            "comments": "lAzCdJPxAuYiYJlAzCdJPxAuYiYJ",
            "created_at": "2014-10-17",
            "expires_at": "2015-11-04",
            "assessment_question_id": "4e37ac1a-a461-45a8-bca9-f0e994d3105e",
            "category": "risk",
            "key": "other_risks",
            "nomis_alert_type": "P",
            "nomis_alert_code": "P0",
            "nomis_alert_type_description": "MAPPP Case",
            "nomis_alert_description": "MAPPA Nominal",
            "imported_from_nomis": true
          },
          {
            "title": "Violent",
            "comments": null,
            "created_at": "2015-02-22",
            "expires_at": null,
            "assessment_question_id": "af8cfc67-757c-4019-9d5e-618017de1617",
            "category": "risk",
            "key": "violent",
            "nomis_alert_type": "R",
            "nomis_alert_code": "ROM",
            "nomis_alert_type_description": "Risk",
            "nomis_alert_description": "OASys Serious Harm-Medium",
            "imported_from_nomis": true
          },
          {
            "title": "Violent",
            "comments": "HRErJMfhUuLHisGPkEhGRpvHSvjfHHRErJMfhUuLHisGPkEhGRpvHSvjfH",
            "created_at": "2017-02-03",
            "expires_at": null,
            "assessment_question_id": "af8cfc67-757c-4019-9d5e-618017de1617",
            "category": "risk",
            "key": "violent",
            "nomis_alert_type": "P",
            "nomis_alert_code": "PC2",
            "nomis_alert_type_description": "MAPPP Case",
            "nomis_alert_description": "MAPPA Cat 2",
            "imported_from_nomis": true
          },
          {
            "title": "Health issue",
            "comments": null,
            "created_at": "2014-07-28",
            "expires_at": null,
            "assessment_question_id": "8872ad2e-b1b6-44c1-a937-b7540e633355",
            "category": "health",
            "key": "health_issue",
            "nomis_alert_type": "DISAB",
            "nomis_alert_code": "ND",
            "nomis_alert_type_description": "Unknown",
            "nomis_alert_description": "No Disability",
            "imported_from_nomis": true
          },
          {
            "title": "Health issue",
            "comments": null,
            "created_at": "2014-07-31",
            "expires_at": null,
            "assessment_question_id": "8872ad2e-b1b6-44c1-a937-b7540e633355",
            "category": "health",
            "key": "health_issue",
            "nomis_alert_type": "DISAB",
            "nomis_alert_code": "ND",
            "nomis_alert_type_description": "Unknown",
            "nomis_alert_description": "No Disability",
            "imported_from_nomis": true
          },
          {
            "title": "Health issue",
            "comments": null,
            "created_at": "2014-10-16",
            "expires_at": null,
            "assessment_question_id": "8872ad2e-b1b6-44c1-a937-b7540e633355",
            "category": "health",
            "key": "health_issue",
            "nomis_alert_type": "DISAB",
            "nomis_alert_code": "ND",
            "nomis_alert_type_description": "Unknown",
            "nomis_alert_description": "No Disability",
            "imported_from_nomis": true
          }
        ]
      },
      "relationships": {
        "person": {
          "data": {
            "id": "747f3914-620a-441a-847f-472c79def26c",
            "type": "people"
          }
        },
        "documents": {
          "data": []
        },
        "person_escort_record": {
          "data": null
        }
      }
    },
    {
      "id": "747f3914-620a-441a-847f-472c79def26c",
      "type": "people",
      "attributes": {
        "first_names": "DOMSANIGH",
        "last_name": "CASEDY",
        "date_of_birth": "1995-11-17",
        "gender_additional_information": null,
        "prison_number": "G8133UA",
        "criminal_records_office": "351774/14D",
        "police_national_computer": "14/120018R"
      },
      "relationships": {
        "ethnicity": {
          "data": {
            "id": "a4f988ba-5ebc-4b24-9dfe-b7fa0c23c30e",
            "type": "ethnicities"
          }
        },
        "gender": {
          "data": {
            "id": "ffac6763-26d6-4425-8005-6e5d052aed88",
            "type": "genders"
          }
        },
        "profiles": {
          "data": [
            {
              "id": "325a81c9-e8d5-4439-99c0-5978e22b147f",
              "type": "profiles"
            }
          ]
        }
      }
    },
    {
      "id": "056eed18-772b-45b3-b64a-4d7d563641f7",
      "type": "locations",
      "attributes": {
        "key": "iwi",
        "title": "ISLE OF WIGHT (HMP)",
        "location_type": "prison",
        "nomis_agency_id": "IWI",
        "can_upload_documents": false,
        "disabled_at": null
      },
      "relationships": {
        "suppliers": {
          "data": []
        }
      }
    },
    {
      "id": "57872fcf-d26e-404e-ab8c-0e91b27657c4",
      "type": "locations",
      "attributes": {
        "key": "aspap3",
        "title": "Brigstocke Road Approved Premises",
        "location_type": "approved_premises",
        "nomis_agency_id": "ASPAP3",
        "can_upload_documents": false,
        "disabled_at": null
      },
      "relationships": {
        "suppliers": {
          "data": []
        }
      }
    }
  ],
  "links": {
    "self": "http://localhost:5001/api/moves?filter%5Bdate_from%5D=2020-08-07&filter%5Bdate_to%5D=2020-08-07&filter%5Bstatus%5D=requested&include=profile.person%2Cfrom_location%2Cto_location&page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "http://localhost:5001/api/moves?filter%5Bdate_from%5D=2020-08-07&filter%5Bdate_to%5D=2020-08-07&filter%5Bstatus%5D=requested&include=profile.person%2Cfrom_location%2Cto_location&page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "http://localhost:5001/api/moves?filter%5Bdate_from%5D=2020-08-07&filter%5Bdate_to%5D=2020-08-07&filter%5Bstatus%5D=requested&include=profile.person%2Cfrom_location%2Cto_location&page%5Bnumber%5D=1&page%5Bsize%5D=20"
  },
  "meta": {
    "pagination": {
      "per_page": 20,
      "total_pages": 1,
      "total_objects": 1,
      "links": {
        "first": "/api/moves?filter%5Bdate_from%5D=2020-08-07&filter%5Bdate_to%5D=2020-08-07&filter%5Bstatus%5D=requested&include=profile.person%2Cfrom_location%2Cto_location&page=1",
        "last": "/api/moves?filter%5Bdate_from%5D=2020-08-07&filter%5Bdate_to%5D=2020-08-07&filter%5Bstatus%5D=requested&include=profile.person%2Cfrom_location%2Cto_location&page=1"
      }
    }
  }
}

  3. The new move can then be accepted changing its status from "requested" to "booked" by calling the accept endpoint:

    curl --request POST \
  --url http://server/api/moves/d75d8d7e-b4c8-4a8c-bbcf-f71a82001899/accept \
  --header 'accept: application/vnd.api+json; version=2' \
  --header 'authorization: Bearer XXX' \
  --header 'content-type: application/json' \
  --header 'idempotency-key: 858fad68-7688-410c-b5dc-29e5cb577ae3' \
  --data '{
  "data": {
    "type": "accepts",
    "attributes": {
      "timestamp": "2020-08-06T15:45:07.027Z"
    }
  }
}'

    This will return a 204 No Content response.

  4. Journeys should be added to move: please see the separate Journey API walkthrough document.

  5. The move can be started, changing its status from "booked" to "in_transit" by calling the start endpoint:

    curl --request POST \
  --url http://server/api/moves/d75d8d7e-b4c8-4a8c-bbcf-f71a82001899/start \
  --header 'accept: application/vnd.api+json; version=2' \
  --header 'authorization: Bearer XXX' \
  --header 'content-type: application/json' \
  --header 'idempotency-key: 995124c6-31c0-44a0-8634-e243e36b33b1' \
  --data '{
  "data": {
    "type": "starts",
    "attributes": {
      "timestamp": "2020-08-06T15:45:24.059Z",
      "notes": "van on the way"
    }
  }
}'

    This will return a 204 No Content response.

  6. Finally, the move can be completed, changing its status from "in_transit" to "completed" by posting to the complete endpoint:

    curl --request POST \
  --url http://server/api/moves/d75d8d7e-b4c8-4a8c-bbcf-f71a82001899/complete \
  --header 'accept: application/vnd.api+json; version=2' \
  --header 'authorization: Bearer XXX' \
  --header 'content-type: application/json' \
  --header 'idempotency-key: 193b07eb-46f6-4711-9183-a190ce168597' \
  --data '{
  "data": {
    "type": "completes",
    "attributes": {
      "timestamp": "2020-08-06T15:45:43.780Z",
      "notes": "all is well"
    }
  }
}'

    This will return a 204 No Content response.

  7. Optionally, the current move record can be inspected at any time by calling the GET move endpoint, using an ?include parameter as required to return the full person, profile or location records:

    curl --request GET \
  --url 'http://server/api/moves/d75d8d7e-b4c8-4a8c-bbcf-f71a82001899?include=profile.person%2Cfrom_location%2Cto_location' \
  --header 'accept: application/vnd.api+json; version=2' \
  --header 'authorization: Bearer XXX'

    Which returns:

    {
  "data": {
    "id": "d75d8d7e-b4c8-4a8c-bbcf-f71a82001899",
    "type": "moves",
    "attributes": {
      "additional_information": "example Prison to Hospital move: HMP Isle of Wight to Brigstocke Road Approved Premises",
      "cancellation_reason": null,
      "cancellation_reason_comment": null,
      "created_at": "2020-08-06T16:41:13+01:00",
      "date": "2020-08-07",
      "date_from": null,
      "date_to": null,
      "move_agreed": null,
      "move_agreed_by": null,
      "move_type": "approved_premises",
      "reference": "JHY4716X",
      "rejection_reason": null,
      "status": "completed",
      "time_due": null,
      "updated_at": "2020-08-06T16:41:32+01:00"
    },
    "relationships": {
      "profile": {
        "data": {
          "id": "325a81c9-e8d5-4439-99c0-5978e22b147f",
          "type": "profiles"
        }
      },
      "from_location": {
        "data": {
          "id": "056eed18-772b-45b3-b64a-4d7d563641f7",
          "type": "locations"
        }
      },
      "to_location": {
        "data": {
          "id": "57872fcf-d26e-404e-ab8c-0e91b27657c4",
          "type": "locations"
        }
      },
      "prison_transfer_reason": {
        "data": null
      },
      "court_hearings": {
        "data": []
      },
      "allocation": {
        "data": null
      },
      "original_move": {
        "data": null
      }
    }
  },
  "included": [
    {
      "id": "325a81c9-e8d5-4439-99c0-5978e22b147f",
      "type": "profiles",
      "attributes": {
        "assessment_answers": [
          {
            "title": "Any other risks",
            "comments": "lAzCdJPxAuYiYJlAzCdJPxAuYiYJ",
            "created_at": "2014-10-17",
            "expires_at": "2015-11-04",
            "assessment_question_id": "4e37ac1a-a461-45a8-bca9-f0e994d3105e",
            "category": "risk",
            "key": "other_risks",
            "nomis_alert_type": "P",
            "nomis_alert_code": "P0",
            "nomis_alert_type_description": "MAPPP Case",
            "nomis_alert_description": "MAPPA Nominal",
            "imported_from_nomis": true
          },
          {
            "title": "Violent",
            "comments": null,
            "created_at": "2015-02-22",
            "expires_at": null,
            "assessment_question_id": "af8cfc67-757c-4019-9d5e-618017de1617",
            "category": "risk",
            "key": "violent",
            "nomis_alert_type": "R",
            "nomis_alert_code": "ROM",
            "nomis_alert_type_description": "Risk",
            "nomis_alert_description": "OASys Serious Harm-Medium",
            "imported_from_nomis": true
          },
          {
            "title": "Violent",
            "comments": "HRErJMfhUuLHisGPkEhGRpvHSvjfHHRErJMfhUuLHisGPkEhGRpvHSvjfH",
            "created_at": "2017-02-03",
            "expires_at": null,
            "assessment_question_id": "af8cfc67-757c-4019-9d5e-618017de1617",
            "category": "risk",
            "key": "violent",
            "nomis_alert_type": "P",
            "nomis_alert_code": "PC2",
            "nomis_alert_type_description": "MAPPP Case",
            "nomis_alert_description": "MAPPA Cat 2",
            "imported_from_nomis": true
          },
          {
            "title": "Health issue",
            "comments": null,
            "created_at": "2014-07-28",
            "expires_at": null,
            "assessment_question_id": "8872ad2e-b1b6-44c1-a937-b7540e633355",
            "category": "health",
            "key": "health_issue",
            "nomis_alert_type": "DISAB",
            "nomis_alert_code": "ND",
            "nomis_alert_type_description": "Unknown",
            "nomis_alert_description": "No Disability",
            "imported_from_nomis": true
          },
          {
            "title": "Health issue",
            "comments": null,
            "created_at": "2014-07-31",
            "expires_at": null,
            "assessment_question_id": "8872ad2e-b1b6-44c1-a937-b7540e633355",
            "category": "health",
            "key": "health_issue",
            "nomis_alert_type": "DISAB",
            "nomis_alert_code": "ND",
            "nomis_alert_type_description": "Unknown",
            "nomis_alert_description": "No Disability",
            "imported_from_nomis": true
          },
          {
            "title": "Health issue",
            "comments": null,
            "created_at": "2014-10-16",
            "expires_at": null,
            "assessment_question_id": "8872ad2e-b1b6-44c1-a937-b7540e633355",
            "category": "health",
            "key": "health_issue",
            "nomis_alert_type": "DISAB",
            "nomis_alert_code": "ND",
            "nomis_alert_type_description": "Unknown",
            "nomis_alert_description": "No Disability",
            "imported_from_nomis": true
          }
        ]
      },
      "relationships": {
        "person": {
          "data": {
            "id": "747f3914-620a-441a-847f-472c79def26c",
            "type": "people"
          }
        },
        "documents": {
          "data": []
        },
        "person_escort_record": {
          "data": null
        }
      }
    },
    {
      "id": "747f3914-620a-441a-847f-472c79def26c",
      "type": "people",
      "attributes": {
        "first_names": "DOMSANIGH",
        "last_name": "CASEDY",
        "date_of_birth": "1995-11-17",
        "gender_additional_information": null,
        "prison_number": "G8133UA",
        "criminal_records_office": "351774/14D",
        "police_national_computer": "14/120018R"
      },
      "relationships": {
        "ethnicity": {
          "data": {
            "id": "a4f988ba-5ebc-4b24-9dfe-b7fa0c23c30e",
            "type": "ethnicities"
          }
        },
        "gender": {
          "data": {
            "id": "ffac6763-26d6-4425-8005-6e5d052aed88",
            "type": "genders"
          }
        },
        "profiles": {
          "data": [
            {
              "id": "325a81c9-e8d5-4439-99c0-5978e22b147f",
              "type": "profiles"
            }
          ]
        }
      }
    },
    {
      "id": "056eed18-772b-45b3-b64a-4d7d563641f7",
      "type": "locations",
      "attributes": {
        "key": "iwi",
        "title": "ISLE OF WIGHT (HMP)",
        "location_type": "prison",
        "nomis_agency_id": "IWI",
        "can_upload_documents": false,
        "disabled_at": null
      },
      "relationships": {
        "suppliers": {
          "data": []
        }
      }
    },
    {
      "id": "57872fcf-d26e-404e-ab8c-0e91b27657c4",
      "type": "locations",
      "attributes": {
        "key": "aspap3",
        "title": "Brigstocke Road Approved Premises",
        "location_type": "approved_premises",
        "nomis_agency_id": "ASPAP3",
        "can_upload_documents": false,
        "disabled_at": null
      },
      "relationships": {
        "suppliers": {
          "data": []
        }
      }
    }
  ]
}
Clone this wiki locally