API Walkthroughs 10.1 Court to Other move with PNC PN - ministryofjustice/hmpps-book-secure-move-api GitHub Wiki

Moves API Walkthrough

10. Court to Other (excluding Prison/STC/SCH) court_other moves

10.1 Move for a person with a PNC/PN identifier from Court to another Court on a specific move date

  1. Get the existing person record(s) by searching by prison number or police national computer number.

    # search for people by PNC
curl --request GET \
  --url 'http://server/api/people?filter%5Bpolice_national_computer%5D=14%2F120018R&include=profiles' \
  --header 'accept: application/vnd.api+json; version=2' \
  --header 'authorization: Bearer XXX'

# or search by PN
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'

    This method will return a list of matching person records. Where there are multiple records, review them and select the most appropriate one.

    {
  "data": [
    {
      "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": "1ff724b3-6872-485c-8bfb-15abca5e4865",
              "type": "profiles"
            },
            {
              "id": "9ea0a328-2017-44d0-b43e-5bafc98e48cb",
              "type": "profiles"
            }
          ]
        }
      }
    },
    {
      "id": "d913fabc-4810-4de3-9beb-14ae874267c7",
      "type": "people",
      "attributes": {
        "first_names": "DOMSANIGH",
        "last_name": "CASEDY",
        "date_of_birth": "1995-11-17",
        "gender_additional_information": "",
        "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": []
        }
      }
    }
  ],
  "included": [
    {
      "id": "1ff724b3-6872-485c-8bfb-15abca5e4865",
      "type": "profiles",
      "attributes": {
        "assessment_answers": []
      },
      "relationships": {
        "person": {
          "data": {
            "id": "747f3914-620a-441a-847f-472c79def26c",
            "type": "people"
          }
        },
        "documents": {
          "data": []
        },
        "person_escort_record": {
          "data": null
        }
      }
    },
    {
      "id": "9ea0a328-2017-44d0-b43e-5bafc98e48cb",
      "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": [
            {
              "id": "3fcf9777-f40b-4a90-8563-5a9484cff9a2",
              "type": "documents"
            }
          ]
        },
        "person_escort_record": {
          "data": null
        }
      }
    }
  ],
  "links": {
    "self": "http://localhost:5001/api/people?filter%5Bpolice_national_computer%5D=14%2F120018R&include=profiles&page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "first": "http://localhost:5001/api/people?filter%5Bpolice_national_computer%5D=14%2F120018R&include=profiles&page%5Bnumber%5D=1&page%5Bsize%5D=20",
    "prev": null,
    "next": null,
    "last": "http://localhost:5001/api/people?filter%5Bpolice_national_computer%5D=14%2F120018R&include=profiles&page%5Bnumber%5D=1&page%5Bsize%5D=20"
  },
  "meta": {
    "pagination": {
      "per_page": 20,
      "total_pages": 1,
      "total_objects": 2,
      "links": {
        "first": "/api/people?filter%5Bpolice_national_computer%5D=14%2F120018R&include=profiles&page=1",
        "last": "/api/people?filter%5Bpolice_national_computer%5D=14%2F120018R&include=profiles&page=1"
      }
    }
  }
}

  2. Create a new profile record for the person

    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

    To create a profile pre-filled with the Nomis alerts, for people with a prison_number, simply post a blank profile to the POST /people/id/profiles endpoint:

    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: 37f3293d-50b3-4502-ab42-6240d5442458' \
  --data '{ "data": { "type": "profiles" } }'

    This returns a new profile record, pre-populated with Nomis alerts:

    {
  "data": {
    "id": "587253fa-b3b5-4824-953d-a27c18c8138f",
    "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
      }
    }
  }
}

  3. Create a Court to Other court_other 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: 01323579-5dce-4b20-bf61-20b1f5be2e7a' \
  --data '{
  "data": {
    "type": "moves",
    "attributes": {
      "date": "2020-08-04",
      "time_due": "2020-08-04T09:00:00+01:00",
      "status": "requested",
      "additional_information": "example Court to Other move: Huddersfield Youth Court to Bradford County Court",
      "move_type": "court_other"
    },
    "relationships": {
      "profile": {
        "data": {
          "type": "profiles",
          "id": "587253fa-b3b5-4824-953d-a27c18c8138f"
        }
      },
      "from_location": {
        "data": {
          "type": "locations",
          "id": "00034e29-9ef8-4802-a2f5-09342bf9f174"
        }
      },
      "to_location": {
        "data": {
          "type": "locations",
          "id": "ed58f509-5b6b-4ae7-8302-2de70eb59281"
        }
      }
    }
  }
}'

    This returns the new move record:

    {
  "data": {
    "id": "b94447b2-c8db-427b-903b-85822142632f",
    "type": "moves",
    "attributes": {
      "additional_information": "example Court to Other move: Huddersfield Youth Court to Bradford County Court",
      "cancellation_reason": null,
      "cancellation_reason_comment": null,
      "created_at": "2020-08-03T09:45:26+01:00",
      "date": "2020-08-04",
      "date_from": null,
      "date_to": null,
      "move_agreed": null,
      "move_agreed_by": null,
      "move_type": "court_other",
      "reference": "TXK5498M",
      "rejection_reason": null,
      "status": "requested",
      "time_due": "2020-08-04T09:00:00+01:00",
      "updated_at": "2020-08-03T09:45:26+01:00"
    },
    "relationships": {
      "profile": {
        "data": {
          "id": "587253fa-b3b5-4824-953d-a27c18c8138f",
          "type": "profiles"
        }
      },
      "from_location": {
        "data": {
          "id": "00034e29-9ef8-4802-a2f5-09342bf9f174",
          "type": "locations"
        }
      },
      "to_location": {
        "data": {
          "id": "ed58f509-5b6b-4ae7-8302-2de70eb59281",
          "type": "locations"
        }
      },
      "prison_transfer_reason": {
        "data": null
      },
      "court_hearings": {
        "data": []
      },
      "allocation": {
        "data": null
      },
      "original_move": {
        "data": null
      }
    }
  }
}

  4. 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/b94447b2-c8db-427b-903b-85822142632f/accept \
  --header 'accept: application/vnd.api+json; version=2' \
  --header 'authorization: Bearer XXX' \
  --header 'content-type: application/json' \
  --header 'idempotency-key: 6e3ee8c6-3076-45a8-88d9-d8880db0cd89' \
  --data '{
  "data": {
    "type": "accepts",
    "attributes": {
      "timestamp": "2020-08-03T08:48:18.258Z"
    }
  }
}'

    This will return a 204 No Content response.

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

  6. 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/b94447b2-c8db-427b-903b-85822142632f/start \
  --header 'accept: application/vnd.api+json; version=2' \
  --header 'authorization: Bearer XXX' \
  --header 'content-type: application/json' \
  --header 'idempotency-key: 21b5d71d-0929-4c15-88ea-9a30b69b6362' \
  --data '{
  "data": {
    "type": "starts",
    "attributes": {
      "timestamp": "2020-08-03T08:48:37.070Z",
      "notes": "van on the way"
    }
  }
}'

    This will return a 204 No Content response.

  7. 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/b94447b2-c8db-427b-903b-85822142632f/complete \
  --header 'accept: application/vnd.api+json; version=2' \
  --header 'authorization: Bearer XXX' \
  --header 'content-type: application/json' \
  --header 'idempotency-key: 9c6990a3-0756-485b-b8e9-0e4e8b78aa83' \
  --data '{
  "data": {
    "type": "completes",
    "attributes": {
      "timestamp": "2020-08-03T08:49:03.145Z",
      "notes": "all is well"
    }
  }
}'

    This will return a 204 No Content response.

  8. 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/b94447b2-c8db-427b-903b-85822142632f?include=profile.person%2Cfrom_location%2Cto_location' \
  --header 'accept: application/vnd.api+json; version=2' \
  --header 'authorization: Bearer XXX'

    Which returns:

    {
  "data": {
    "id": "b94447b2-c8db-427b-903b-85822142632f",
    "type": "moves",
    "attributes": {
      "additional_information": "example Court to Other move: Huddersfield Youth Court to Bradford County Court",
      "cancellation_reason": null,
      "cancellation_reason_comment": null,
      "created_at": "2020-08-03T09:45:26+01:00",
      "date": "2020-08-04",
      "date_from": null,
      "date_to": null,
      "move_agreed": null,
      "move_agreed_by": null,
      "move_type": "court_other",
      "reference": "TXK5498M",
      "rejection_reason": null,
      "status": "completed",
      "time_due": "2020-08-04T09:00:00+01:00",
      "updated_at": "2020-08-03T09:48:59+01:00"
    },
    "relationships": {
      "profile": {
        "data": {
          "id": "587253fa-b3b5-4824-953d-a27c18c8138f",
          "type": "profiles"
        }
      },
      "from_location": {
        "data": {
          "id": "00034e29-9ef8-4802-a2f5-09342bf9f174",
          "type": "locations"
        }
      },
      "to_location": {
        "data": {
          "id": "ed58f509-5b6b-4ae7-8302-2de70eb59281",
          "type": "locations"
        }
      },
      "prison_transfer_reason": {
        "data": null
      },
      "court_hearings": {
        "data": []
      },
      "allocation": {
        "data": null
      },
      "original_move": {
        "data": null
      }
    }
  },
  "included": [
    {
      "id": "587253fa-b3b5-4824-953d-a27c18c8138f",
      "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": "1ff724b3-6872-485c-8bfb-15abca5e4865",
              "type": "profiles"
            },
            {
              "id": "9ea0a328-2017-44d0-b43e-5bafc98e48cb",
              "type": "profiles"
            },
            {
              "id": "587253fa-b3b5-4824-953d-a27c18c8138f",
              "type": "profiles"
            }
          ]
        }
      }
    },
    {
      "id": "00034e29-9ef8-4802-a2f5-09342bf9f174",
      "type": "locations",
      "attributes": {
        "key": "hudryc",
        "title": "Huddersfield Youth Court",
        "location_type": "court",
        "nomis_agency_id": "HUDRYC",
        "can_upload_documents": false,
        "disabled_at": null
      },
      "relationships": {
        "suppliers": {
          "data": []
        }
      }
    },
    {
      "id": "ed58f509-5b6b-4ae7-8302-2de70eb59281",
      "type": "locations",
      "attributes": {
        "key": "bradct",
        "title": "Bradford County Court",
        "location_type": "court",
        "nomis_agency_id": "BRADCT",
        "can_upload_documents": false,
        "disabled_at": null
      },
      "relationships": {
        "suppliers": {
          "data": []
        }
      }
    }
  ]
}