HMPPS Integration API v1.0

A long-lived API that exposes data from HMPPS systems such as the National Offender Management Information System (NOMIS), nDelius (probation system) and Offender Assessment System (OASys), providing a single point of entry for consumers.

Servers

Development server

https://dev.integration-api.hmpps.service.justice.gov.uk

Pre-production server, containing live data

https://preprod.integration-api.hmpps.service.justice.gov.uk

Production

https://integration-api.hmpps.service.justice.gov.uk

/v1/persons/{hmppsId}/expression-of-interest/jobs/{jobid}

put

Returns completed response

Parameters

Parameter	In	Type	Required	Description
hmppsId	path	string	true	A HMPPS identifier
jobid	path	string	true	A job identifier

Responses

Status	Description	Schema
200	Successfully submitted an expression of interest `{ "data": { }, "errors": [ { "causedBy": "string", "type": "string", "description": "string" } ] }`	ResponseUnit
400	Bad Request `{ "status": 400, "userMessage": "Validation failure: No query parameters specified.", "developerMessage": "No query parameters specified." }`	BadRequest
403	Access is forbidden `{ "status": 403, "userMessage": "Forbidden to complete action by upstream service", "developerMessage": "Forbidden to complete action by upstream service" }`	ForbiddenResponse
404	Not Found `{ "status": 404, "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.", "developerMessage": "Could not find person with HMPPS id: 2003/0011991D." }`	PersonNotFound

/queue-admin/retry-dlq/{dlqName}

put

Parameters

Parameter	In	Type	Required	Description
dlqName	path	string	true

Responses

Status Description Schema

200

Status	Description	Schema
200	OK `{ "messagesFoundCount": "integer" }`	RetryDlqResult

{
  "messagesFoundCount": "integer"
}

RetryDlqResult

/queue-admin/retry-all-dlqs

put

Responses

Status Description Schema

200

Status	Description	Schema
200	OK `{ }`

{
}

/queue-admin/purge-queue/{queueName}

put

Parameters

Parameter	In	Type	Required	Description
queueName	path	string	true

Responses

Status Description Schema

200

Status	Description	Schema
200	OK `{ "messagesFoundCount": "integer" }`	PurgeQueueResult

{
  "messagesFoundCount": "integer"
}

PurgeQueueResult

/v1/prison/{prisonId}/prisoners/{hmppsId}/transactions

post

Make a financial transaction.

Request body

Applicable filters:

prisons

Parameters

Parameter	In	Type	Required	Description
prisonId	path	string	true	The ID of the prison that holds the account
hmppsId	path	string	true	The HMPPS ID of the person

Responses

Status	Description	Schema
200	Successfully created a transaction. `{ "data": { "transactionId": "string" } }`	DataResponseTransactionCreateResponse
400	Bad Request `{ "status": 400, "userMessage": "Validation failure: No query parameters specified.", "developerMessage": "No query parameters specified." }`	BadRequest
404	Not Found `{ "status": 404, "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.", "developerMessage": "Could not find person with HMPPS id: 2003/0011991D." }`	PersonNotFound
409	Conflict `{ "status": 409, "userMessage": "Conflict", "developerMessage": "Duplicate post - The client_unique_ref has been used before" }`	TransactionConflict
500	Internal Server Error `{ "status": 500, "userMessage": "Internal Server Error", "developerMessage": "Unable to complete request as an upstream service is not responding." }`	InternalServerError

/v1/prison/{prisonId}/prisoners/{hmppsId}/transactions/transfer

post

Transfer funds between the accounts of a prisoner.

Currently only able to move from spends to savings.

Request body

Applicable filters:

prisons

Parameters

Parameter	In	Type	Required	Description
prisonId	path	string	true	The ID of the prison that holds the account
hmppsId	path	string	true	The HMPPS ID of the person

Responses

Status	Description	Schema
200	Successfully created a transaction transfer. `{ "data": { "debitTransactionId": "string", "creditTransactionId": "string", "transactionId": "string" } }`	DataResponseTransactionTransferCreateResponse
400	Bad Request `{ "status": 400, "userMessage": "Validation failure: No query parameters specified.", "developerMessage": "No query parameters specified." }`	BadRequest
404	Not Found `{ "status": 404, "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.", "developerMessage": "Could not find person with HMPPS id: 2003/0011991D." }`	PersonNotFound
409	Conflict `{ "status": 409, "userMessage": "Conflict", "developerMessage": "Duplicate post - The client_unique_ref has been used before" }`	TransactionConflict
500	Internal Server Error `{ "status": 500, "userMessage": "Internal Server Error", "developerMessage": "Unable to complete request as an upstream service is not responding." }`	InternalServerError

/v1/visit/{visitReference}

get

Get visit information for a visit by visit reference.

Parameters

Parameter	In	Type	Required	Description
visitReference	path	string	true	The visit reference number relating to the visit.

Responses

Status Description Schema

200

Status	Description	Schema
200	Successfully found visit information for a given visit reference. { "data": { "applicationReference": "dfs-wjs-eqr", "reference": "v9-d7-ed-7u", "prisonerId": "AF34567G", "prisonId": "MDI", "prisonName": "Moorland (HMP & YOI)", "sessionTemplateReference": "v9d.7ed.7u", "visitRoom": "Visits Main Hall", "visitType": "SOCIAL", "visitStatus": "BOOKED", "outcomeStatus": "ADMINISTRATIVE_CANCELLATION", "visitRestriction": "OPEN", "startTimestamp": "string", "endTimestamp": "string", "visitNotes": [ { "type": "VISITOR_CONCERN", "text": "Visitor is concerned that his mother in-law is coming!" } ], "visitContact": { "name": "John Smith", "telephone": "01234 567890", "email": "email@example.com" }, "visitors": [ { "contactId": 1234, "visitContact": true } ], "visitorSupport": { "description": "Visually impaired assistance" }, "createdTimestamp": "string", "modifiedTimestamp": "string", "firstBookedDateTime": "string" } }	DataResponseVisit
404	Not Found `{ "status": 404, "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.", "developerMessage": "Could not find person with HMPPS id: 2003/0011991D." }`	PersonNotFound
500	Internal Server Error `{ "status": 500, "userMessage": "Internal Server Error", "developerMessage": "Unable to complete request as an upstream service is not responding." }`	InternalServerError

Successfully found visit information for a given visit reference.

{
  "data": {
    "applicationReference": "dfs-wjs-eqr",
    "reference": "v9-d7-ed-7u",
    "prisonerId": "AF34567G",
    "prisonId": "MDI",
    "prisonName": "Moorland (HMP & YOI)",
    "sessionTemplateReference": "v9d.7ed.7u",
    "visitRoom": "Visits Main Hall",
    "visitType": "SOCIAL",
    "visitStatus": "BOOKED",
    "outcomeStatus": "ADMINISTRATIVE_CANCELLATION",
    "visitRestriction": "OPEN",
    "startTimestamp": "string",
    "endTimestamp": "string",
    "visitNotes": [
      {
        "type": "VISITOR_CONCERN",
        "text": "Visitor is concerned that his mother in-law is coming!"
      }
    ],
    "visitContact": {
      "name": "John Smith",
      "telephone": "01234 567890",
      "email": "email@example.com"
    },
    "visitors": [
      {
        "contactId": 1234,
        "visitContact": true
      }
    ],
    "visitorSupport": {
      "description": "Visually impaired assistance"
    },
    "createdTimestamp": "string",
    "modifiedTimestamp": "string",
    "firstBookedDateTime": "string"
  }
}

DataResponseVisit

404

Not Found

{
  "status": 404,
  "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.",
  "developerMessage": "Could not find person with HMPPS id: 2003/0011991D."
}

PersonNotFound

500

Internal Server Error

{
  "status": 500,
  "userMessage": "Internal Server Error",
  "developerMessage": "Unable to complete request as an upstream service is not responding."
}

InternalServerError

/v1/prison/{prisonId}/visit/search

get

Searches for visits by prisonId and criteria.

Applicable filters:

prisons

Parameters

Parameter	In	Type	Required	Description
prisonId	path	string	true	The ID of the prison to be queried against
hmppsId	query	string	false	The HMPPS ID of the person
fromDate	query	string	false	The start date of the visit
toDate	query	string	false	The end date of the visit
visitStatus	query	string	true	The status of the visit. (BOOKING or CANCELLED)
page	query	string	false	The page number
size	query	string	false	The maximum number of results for a page

Responses

Status	Description	Schema
200	Successfully performed the query on upstream APIs. An empty list is returned when no results are found. { "data": [ { "applicationReference": "dfs-wjs-eqr", "reference": "v9-d7-ed-7u", "prisonerId": "AF34567G", "prisonId": "MDI", "prisonName": "Moorland (HMP & YOI)", "sessionTemplateReference": "v9d.7ed.7u", "visitRoom": "Visits Main Hall", "visitType": "SOCIAL", "visitStatus": "BOOKED", "outcomeStatus": "ADMINISTRATIVE_CANCELLATION", "visitRestriction": "OPEN", "startTimestamp": "string", "endTimestamp": "string", "visitNotes": [ { "type": "VISITOR_CONCERN", "text": "Visitor is concerned that his mother in-law is coming!" } ], "visitContact": { "name": "John Smith", "telephone": "01234 567890", "email": "email@example.com" }, "visitors": [ { "contactId": 1234, "visitContact": true } ], "visitorSupport": { "description": "Visually impaired assistance" }, "createdTimestamp": "string", "modifiedTimestamp": "string", "firstBookedDateTime": "string" } ], "pagination": { "isLastPage": true, "count": 1, "page": 1, "perPage": 10, "totalCount": 1, "totalPages": 1 } }	PaginatedResponseVisit
400	Bad Request `{ "status": 400, "userMessage": "Validation failure: No query parameters specified.", "developerMessage": "No query parameters specified." }`	BadRequest
403	Forbidden `{ "status": 403, "userMessage": "Forbidden to complete action by upstream service", "developerMessage": "Forbidden to complete action by upstream service" }`	ForbiddenResponse
404	Not Found `{ "status": 404, "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.", "developerMessage": "Could not find person with HMPPS id: 2003/0011991D." }`	PersonNotFound
500	Internal Server Error `{ "status": 500, "userMessage": "Internal Server Error", "developerMessage": "Unable to complete request as an upstream service is not responding." }`	InternalServerError

/v1/prison/{prisonId}/prisoners/{hmppsId}/transactions/{clientUniqueRef}

get

Returns details for a transaction by clientUniqueRef.

Applicable filters:

prisons

Parameters

Parameter	In	Type	Required	Description
prisonId	path	string	true	The HMPPS ID of the person
hmppsId	path	string	true	The ID of the prison that holds the account
clientUniqueRef	path	string	true	The clientUniqueRef used when the transaction was created

Responses

Status	Description	Schema
200	Successfully found a transaction. `{ "data": { "id": "string", "type": { "code": "string", "desc": "string" }, "description": "string", "amount": "integer", "date": "string" } }`	DataResponseTransaction
400	The request data has an invalid format or the prisoner does not have transaction associated with the clientUniqueRef. `{ "status": 400, "userMessage": "Validation failure: No query parameters specified.", "developerMessage": "No query parameters specified." }`	BadRequest
404	Not Found `{ "status": 404, "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.", "developerMessage": "Could not find person with HMPPS id: 2003/0011991D." }`	PersonNotFound
500	Internal Server Error `{ "status": 500, "userMessage": "Internal Server Error", "developerMessage": "Unable to complete request as an upstream service is not responding." }`	InternalServerError

/v1/prison/{prisonId}/prisoners/{hmppsId}/non-associations

get

Returns a single prisoners list of non associates.

Applicable filters:

prisons

includeOpen is true by default, includeClosed is false by default. At least one must be true. The role READNONASSOCIATIONS is required for this endpoint.

Parameters

Parameter	In	Type	Required	Description
hmppsId	path	string	true	The HMPPS ID of the prisoner
prisonId	path	string	true	The prison ID of the prisoner
includeOpen	query	boolean	false
includeClosed	query	boolean	false

Responses

Status	Description	Schema
200	Successfully found prisoners non associates. { "data": { "nonAssociations": [ { "id": "integer", "role": "VICTIM", "roleDescription": "Victim", "reason": "BULLYING", "reasonDescription": "Bullying", "restrictionType": "CELL", "restrictionTypeDescription": "Cell only", "comment": "John and Luke always end up fighting", "authorisedBy": "OFF3_GEN", "whenCreated": "2021-12-31T12:34:56.789012", "whenUpdated": "2021-12-31T12:34:56.789012", "updatedBy": "string", "isClosed": "boolean", "closedBy": "string", "closedReason": "string", "closedAt": "string", "otherPrisonerDetails": { "prisonerNumber": "D5678EF", "role": "VICTIM", "roleDescription": "string", "firstName": "John", "lastName": "Smith", "prisonId": "MDI", "prisonName": "Moorland", "cellLocation": "B-2-007" }, "isOpen": "boolean" } ] } }	DataResponseNonAssociations
400	The HMPPS ID provided has an invalid format. `{ "status": 400, "userMessage": "Validation failure: No query parameters specified.", "developerMessage": "No query parameters specified." }`	BadRequest
404	Not Found `{ "status": 404, "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.", "developerMessage": "Could not find person with HMPPS id: 2003/0011991D." }`	PersonNotFound
500	Internal Server Error `{ "status": 500, "userMessage": "Internal Server Error", "developerMessage": "Unable to complete request as an upstream service is not responding." }`	InternalServerError

/v1/prison/{prisonId}/prisoners/{hmppsId}/balances

get

Returns all accounts for a prisoner that they have at a prison.

Applicable filters:

prisons

Parameters

Parameter	In	Type	Required	Description
hmppsId	path	string	true
prisonId	path	string	true

Responses

Status	Description	Schema
200	Successfully found a prisoner’s accounts. `{ "data": { "balances": [ { "accountCode": "string", "amount": "integer" } ] } }`	DataResponseBalances
400	The HMPPS ID provided has an invalid format or the prisoner does hot have accounts at the specified prison. `{ "status": 400, "userMessage": "Validation failure: No query parameters specified.", "developerMessage": "No query parameters specified." }`	BadRequest
404	Not Found `{ "status": 404, "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.", "developerMessage": "Could not find person with HMPPS id: 2003/0011991D." }`	PersonNotFound
500	Internal Server Error `{ "status": 500, "userMessage": "Internal Server Error", "developerMessage": "Unable to complete request as an upstream service is not responding." }`	InternalServerError

/v1/prison/{prisonId}/prisoners/{hmppsId}/accounts/{accountCode}/transactions

get

Returns all transactions for a prisoner associated with an account code that they have at a prison.

Applicable filters:

prisons

Parameters

Parameter	In	Type	Required	Description
hmppsId	path	string	true	The HMPPS ID of the person
prisonId	path	string	true	The ID of the prison that holds the account
accountCode	path	string	true	The code of the account to be accessed, one of ‘spends’, ‘savings’ or ‘cash’
from_date	query	string	false	Start date for transactions (defaults to today if not supplied)
to_date	query	string	false	To date for transactions (defaults to today if not supplied)

Responses

Status	Description	Schema
200	Successfully found a prisoner’s transactions. `{ "data": { "transactions": [ { "id": "string", "type": { "code": "string", "desc": "string" }, "description": "string", "amount": "integer", "date": "string" } ] } }`	DataResponseTransactions
400	The request data has an invalid format or the prisoner does hot have transactions at the specified prison. `{ "status": 400, "userMessage": "Validation failure: No query parameters specified.", "developerMessage": "No query parameters specified." }`	BadRequest
404	Not Found `{ "status": 404, "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.", "developerMessage": "Could not find person with HMPPS id: 2003/0011991D." }`	PersonNotFound
500	Internal Server Error `{ "status": 500, "userMessage": "Internal Server Error", "developerMessage": "Unable to complete request as an upstream service is not responding." }`	InternalServerError

/v1/prison/{prisonId}/prisoners/{hmppsId}/accounts/{accountCode}/balances

get

Returns a specific account for a prisoner that they have at a prison, based on the account code provided.

Applicable filters:

prisons

Parameters

Parameter	In	Type	Required
hmppsId	path	string	true
prisonId	path	string	true
accountCode	path	string	true

Responses

Status	Description	Schema
200	Successfully found a prisoner’s account. `{ "data": { "balance": { "accountCode": "string", "amount": "integer" } } }`	DataResponseBalance
400	The HMPPS ID provided has an invalid format, the account code is not one of the allowable accounts or the prisoner does hot have accounts at the specified prison. `{ "status": 400, "userMessage": "Validation failure: No query parameters specified.", "developerMessage": "No query parameters specified." }`	BadRequest
404	Not Found `{ "status": 404, "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.", "developerMessage": "Could not find person with HMPPS id: 2003/0011991D." }`	PersonNotFound
500	Internal Server Error `{ "status": 500, "userMessage": "Internal Server Error", "developerMessage": "Unable to complete request as an upstream service is not responding." }`	InternalServerError

/v1/prison/prisoners

get

Returns person(s) by search criteria, sorted by date of birth (newest first). Only queries prisoner search.

Applicable filters:

prisons

Parameters

Parameter	In	Type	Required	Description
first_name	query	string	false	The first name of the person
last_name	query	string	false	The last name of the person
date_of_birth	query	string	false	The date of birth of the person
search_within_aliases	query	boolean	false	Whether to return results that match the search criteria within the aliases of a person.
page	query	string	false	The page number (starting from 1)
perPage	query	string	false	The maximum number of results for a page

Responses

Status	Description	Schema
200	Successfully performed the query on upstream APIs. An empty list is returned when no results are found. { "data": [ { "firstName": "John", "lastName": "Morgan", "middleName": "John", "dateOfBirth": "1965-12-01", "gender": "Male", "ethnicity": "White: Eng./Welsh/Scot./N.Irish/British", "aliases": [ { "firstName": "John", "lastName": "Marston", "middleName": "Marston", "dateOfBirth": "1965-12-01", "gender": "Male", "ethnicity": "Prefer not to say" } ], "identifiers": { "nomisNumber": "A1234AA", "croNumber": "SF80/655108T", "deliusCrn": "X00001" }, "pncId": "string", "category": "C", "csra": "HIGH", "receptionDate": "2021-12-01", "status": "ACTIVE IN", "prisonId": "MDI", "prisonName": "HMP Leeds", "cellLocation": "A-1-002" } ], "pagination": { "isLastPage": true, "count": 1, "page": 1, "perPage": 10, "totalCount": 1, "totalPages": 1 } }	PaginatedResponsePersonInPrison
400	There were no query parameters passed in. At least one must be specified. `{ "status": 400, "userMessage": "Validation failure: No query parameters specified.", "developerMessage": "No query parameters specified." }`	BadRequest
403	Forbidden `{ "status": 403, "userMessage": "Forbidden to complete action by upstream service", "developerMessage": "Forbidden to complete action by upstream service" }`	ForbiddenResponse
500	Internal Server Error `{ "status": 500, "userMessage": "Internal Server Error", "developerMessage": "Unable to complete request as an upstream service is not responding." }`	InternalServerError

/v1/prison/prisoners/{hmppsId}

get

Returns a single prisoners details given an hmppsId, does not query for a probation person.

Applicable filters:

prisons

Parameters

Parameter	In	Type	Required	Description
hmppsId	path	string	true	The HMPPS ID of the person

Responses

Status	Description	Schema
200	Successfully found a prisoner with the provided HMPPS ID. { "data": { "firstName": "John", "lastName": "Morgan", "middleName": "John", "dateOfBirth": "1965-12-01", "gender": "Male", "ethnicity": "White: Eng./Welsh/Scot./N.Irish/British", "aliases": [ { "firstName": "John", "lastName": "Marston", "middleName": "Marston", "dateOfBirth": "1965-12-01", "gender": "Male", "ethnicity": "Prefer not to say" } ], "identifiers": { "nomisNumber": "A1234AA", "croNumber": "SF80/655108T", "deliusCrn": "X00001" }, "pncId": "string", "category": "C", "csra": "HIGH", "receptionDate": "2021-12-01", "status": "ACTIVE IN", "prisonId": "MDI", "prisonName": "HMP Leeds", "cellLocation": "A-1-002" } }	DataResponsePersonInPrison
400	The HMPPS ID provided has an invalid format. `{ "status": 400, "userMessage": "Validation failure: No query parameters specified.", "developerMessage": "No query parameters specified." }`	BadRequest
404	Not Found `{ "status": 404, "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.", "developerMessage": "Could not find person with HMPPS id: 2003/0011991D." }`	PersonNotFound
500	Internal Server Error `{ "status": 500, "userMessage": "Internal Server Error", "developerMessage": "Unable to complete request as an upstream service is not responding." }`	InternalServerError

/v1/pnd/persons/{encodedHmppsId}/alerts

get

Returns alerts associated with a person, sorted by dateCreated (newest first).

Parameters

Parameter	In	Type	Required	Description
encodedHmppsId	path	string	true	A URL-encoded HMPPS identifier
page	query	string	false	The page number (starting from 1)
perPage	query	string	false	The maximum number of results for a page

Responses

Status Description Schema

200

Successfully found alerts for a person with the provided HMPPS ID.

{
  "data": [
    {
      "offenderNo": "Z1234ZZ",
      "type": "X",
      "typeDescription": "Security",
      "code": "PO",
      "codeDescription": "MAPPA Nominal",
      "comment": "Professional lock pick",
      "dateCreated": "2014-09-23",
      "dateExpired": "2015-09-23",
      "expired": true,
      "active": true
    }
  ],
  "pagination": {
    "isLastPage": true,
    "count": 1,
    "page": 1,
    "perPage": 10,
    "totalCount": 1,
    "totalPages": 1
  }
}

PaginatedResponseAlert

404

Not Found

{
  "status": 404,
  "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.",
  "developerMessage": "Could not find person with HMPPS id: 2003/0011991D."
}

PersonNotFound

500

Internal Server Error

{
  "status": 500,
  "userMessage": "Internal Server Error",
  "developerMessage": "Unable to complete request as an upstream service is not responding."
}

InternalServerError

/v1/persons

get

Returns person(s) by search criteria, sorted by date of birth (newest first). At least one query parameter must be specified.

Parameters

Parameter	In	Type	Required	Description
first_name	query	string	false	The first name of the person
last_name	query	string	false	The last name of the person
pnc_number	query	string	false	A URL-encoded pnc identifier
date_of_birth	query	string	false	The date of birth of the person
search_within_aliases	query	boolean	false	Whether to return results that match the search criteria within the aliases of a person.
page	query	string	false	The page number (starting from 1)
perPage	query	string	false	The maximum number of results for a page

Responses

Status Description Schema

200

Status	Description	Schema
200	Successfully performed the query on upstream APIs. An empty list is returned when no results are found. { "data": [ { "firstName": "John", "lastName": "Morgan", "middleName": "John", "dateOfBirth": "1965-12-01", "gender": "Male", "ethnicity": "White: Eng./Welsh/Scot./N.Irish/British", "aliases": [ { "firstName": "John", "lastName": "Marston", "middleName": "Marston", "dateOfBirth": "1965-12-01", "gender": "Male", "ethnicity": "Prefer not to say" } ], "identifiers": { "nomisNumber": "A1234AA", "croNumber": "SF80/655108T", "deliusCrn": "X00001" }, "pncId": "string", "hmppsId": "2008/0545166T", "contactDetails": { "phoneNumbers": [ { "number": "079123456789", "type": "TELEPHONE" } ], "emails": [ { } ] }, "currentRestriction": "boolean", "restrictionMessage": "string", "currentExclusion": "boolean", "exclusionMessage": "string" } ], "pagination": { "isLastPage": true, "count": 1, "page": 1, "perPage": 10, "totalCount": 1, "totalPages": 1 } }	PaginatedResponsePerson
400	There were no query parameters passed in. At least one must be specified. `{ "status": 400, "userMessage": "Validation failure: No query parameters specified.", "developerMessage": "No query parameters specified." }`	BadRequest
500	Internal Server Error `{ "status": 500, "userMessage": "Internal Server Error", "developerMessage": "Unable to complete request as an upstream service is not responding." }`	InternalServerError

Successfully performed the query on upstream APIs. An empty list is returned when no results are found.

{
  "data": [
    {
      "firstName": "John",
      "lastName": "Morgan",
      "middleName": "John",
      "dateOfBirth": "1965-12-01",
      "gender": "Male",
      "ethnicity": "White: Eng./Welsh/Scot./N.Irish/British",
      "aliases": [
        {
          "firstName": "John",
          "lastName": "Marston",
          "middleName": "Marston",
          "dateOfBirth": "1965-12-01",
          "gender": "Male",
          "ethnicity": "Prefer not to say"
        }
      ],
      "identifiers": {
        "nomisNumber": "A1234AA",
        "croNumber": "SF80/655108T",
        "deliusCrn": "X00001"
      },
      "pncId": "string",
      "hmppsId": "2008/0545166T",
      "contactDetails": {
        "phoneNumbers": [
          {
            "number": "079123456789",
            "type": "TELEPHONE"
          }
        ],
        "emails": [
          {
          }
        ]
      },
      "currentRestriction": "boolean",
      "restrictionMessage": "string",
      "currentExclusion": "boolean",
      "exclusionMessage": "string"
    }
  ],
  "pagination": {
    "isLastPage": true,
    "count": 1,
    "page": 1,
    "perPage": 10,
    "totalCount": 1,
    "totalPages": 1
  }
}

PaginatedResponsePerson

400

There were no query parameters passed in. At least one must be specified.

{
  "status": 400,
  "userMessage": "Validation failure: No query parameters specified.",
  "developerMessage": "No query parameters specified."
}

BadRequest

500

Internal Server Error

{
  "status": 500,
  "userMessage": "Internal Server Error",
  "developerMessage": "Unable to complete request as an upstream service is not responding."
}

InternalServerError

/v1/persons/{hmppsId}/visitor/{contactId}/restrictions

get

Gets visitor restrictions.

Returns visitor restrictions for a prisoner

Parameters

Parameter	In	Type	Required	Description
hmppsId	path	string	true	A HMPPS identifier
contactId	path	string	true	A contact ID

Responses

Status	Description	Schema
200	Successfully found a prisoners vistor restrictions with the provided HMPPS ID and contact ID. { "data": { "prisonerContactRestrictions": [ { "restrictionType": "string", "restrictionTypeDescription": "Banned", "startDate": "2024-01-01", "expiryDate": "2024-01-01", "comments": "N/A", "enteredByUsername": "admin", "enteredByDisplayName": "John Smith", "createdBy": "admin", "createdTime": "2023-09-23T10:15:30", "updatedBy": "admin", "updatedTime": "2023-09-23T10:15:30" } ], "contactGlobalRestrictions": [ { "restrictionType": "string", "restrictionTypeDescription": "Banned", "startDate": "2024-01-01", "expiryDate": "2024-01-01", "comments": "N/A", "enteredByUsername": "admin", "enteredByDisplayName": "John Smith", "createdBy": "admin", "createdTime": "2023-09-23T10:15:30", "updatedBy": "admin", "updatedTime": "2023-09-23T10:15:30" } ] } }	DataResponsePrisonerContactRestrictions
400	Bad Request `{ "status": 400, "userMessage": "Validation failure: No query parameters specified.", "developerMessage": "No query parameters specified." }`	BadRequest
404	Not Found `{ "status": 404, "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.", "developerMessage": "Could not find person with HMPPS id: 2003/0011991D." }`	PersonNotFound
500	Internal Server Error `{ "status": 500, "userMessage": "Internal Server Error", "developerMessage": "Unable to complete request as an upstream service is not responding." }`	InternalServerError

/v1/persons/{hmppsId}/visit/future

get

Get Future Visit Information.

Applicable filters:

prisons

Parameters

Parameter	In	Type	Required	Description
hmppsId	path	string	true	A HMPPS identifier

Responses

Status	Description	Schema
200	Successfully found a person’s future visits with the provided HMPPS ID. { "data": [ { "applicationReference": "dfs-wjs-eqr", "reference": "v9-d7-ed-7u", "prisonerId": "AF34567G", "prisonId": "MDI", "prisonName": "Moorland (HMP & YOI)", "sessionTemplateReference": "v9d.7ed.7u", "visitRoom": "Visits Main Hall", "visitType": "SOCIAL", "visitStatus": "BOOKED", "outcomeStatus": "ADMINISTRATIVE_CANCELLATION", "visitRestriction": "OPEN", "startTimestamp": "string", "endTimestamp": "string", "visitNotes": [ { "type": "VISITOR_CONCERN", "text": "Visitor is concerned that his mother in-law is coming!" } ], "visitContact": { "name": "John Smith", "telephone": "01234 567890", "email": "email@example.com" }, "visitors": [ { "contactId": 1234, "visitContact": true } ], "visitorSupport": { "description": "Visually impaired assistance" }, "createdTimestamp": "string", "modifiedTimestamp": "string", "firstBookedDateTime": "string" } ] }	DataResponseListVisit
400	Bad Request `{ "status": 400, "userMessage": "Validation failure: No query parameters specified.", "developerMessage": "No query parameters specified." }`	BadRequest
404	Not Found `{ "status": 404, "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.", "developerMessage": "Could not find person with HMPPS id: 2003/0011991D." }`	PersonNotFound
500	Internal Server Error `{ "status": 500, "userMessage": "Internal Server Error", "developerMessage": "Unable to complete request as an upstream service is not responding." }`	InternalServerError

/v1/persons/{hmppsId}/visit-restrictions

get

Gets restrictions for latest booking.

Returns a list of restrictions for the latest booking

Parameters

Parameter	In	Type	Required	Description
hmppsId	path	string	true	A HMPPS identifier

Responses

Status	Description	Schema
200	Successfully found a person’s visit restrictions with the provided HMPPS ID. `{ "data": [ { "restrictionId": "integer", "comment": "string", "restrictionType": "string", "restrictionTypeDescription": "string", "startDate": "1980-01-01", "expiryDate": "1980-01-01", "active": "boolean" } ] }`	DataResponseListPersonVisitRestriction
400	Bad Request `{ "status": 400, "userMessage": "Validation failure: No query parameters specified.", "developerMessage": "No query parameters specified." }`	BadRequest
404	Not Found `{ "status": 404, "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.", "developerMessage": "Could not find person with HMPPS id: 2003/0011991D." }`	PersonNotFound
500	Internal Server Error `{ "status": 500, "userMessage": "Internal Server Error", "developerMessage": "Unable to complete request as an upstream service is not responding." }`	InternalServerError

/v1/persons/{hmppsId}/visit-orders

get

Returns visit orders.

Parameters

Parameter	In	Type	Required	Description
hmppsId	path	string	true	The HMPPS ID of the prisoner

Responses

Status Description Schema

200

Status	Description	Schema
200	Successfully found a prisoners visit orders. `{ "data": { "remainingVisitOrders": 123456, "remainingPrivilegeVisitOrders": 123456 } }`	DataResponseVisitOrders
404	Not Found `{ "status": 404, "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.", "developerMessage": "Could not find person with HMPPS id: 2003/0011991D." }`	PersonNotFound
500	Internal Server Error `{ "status": 500, "userMessage": "Internal Server Error", "developerMessage": "Unable to complete request as an upstream service is not responding." }`	InternalServerError

Successfully found a prisoners visit orders.

{
  "data": {
    "remainingVisitOrders": 123456,
    "remainingPrivilegeVisitOrders": 123456
  }
}

DataResponseVisitOrders

404

Not Found

{
  "status": 404,
  "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.",
  "developerMessage": "Could not find person with HMPPS id: 2003/0011991D."
}

PersonNotFound

500

Internal Server Error

{
  "status": 500,
  "userMessage": "Internal Server Error",
  "developerMessage": "Unable to complete request as an upstream service is not responding."
}

InternalServerError

/v1/persons/{hmppsId}/sentences

get

Returns sentences associated with a person, sorted by dateOfSentencing (newest first).

Applicable filters:

prisons

Parameters

Parameter	In	Type	Required	Description
hmppsId	path	string	true	The HMPPS ID of the person
page	query	string	false	The page number (starting from 1)
perPage	query	string	false	The maximum number of results for a page

Responses

Status	Description	Schema
200	Successfully found sentences for a person with the provided HMPPS ID. `{ "data": [ { "serviceSource": "NOMIS", "systemSource": "PROBATION_SYSTEMS", "dateOfSentencing": "2009-09-09", "description": "Young Offender Inst - >=12 mths", "isActive": true, "isCustodial": true, "fineAmount": 480.59, "length": { "duration": 10, "units": "Hours", "terms": [ { "years": 5, "months": 4, "weeks": 3, "days": 2, "hours": 1, "prisonTermCode": "IMP" } ] } } ], "pagination": { "isLastPage": true, "count": 1, "page": 1, "perPage": 10, "totalCount": 1, "totalPages": 1 } }`	PaginatedResponseSentence
400	Bad Request `{ "status": 400, "userMessage": "Validation failure: No query parameters specified.", "developerMessage": "No query parameters specified." }`	BadRequest
404	Not Found `{ "status": 404, "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.", "developerMessage": "Could not find person with HMPPS id: 2003/0011991D." }`	PersonNotFound
500	Internal Server Error `{ "status": 500, "userMessage": "Internal Server Error", "developerMessage": "Unable to complete request as an upstream service is not responding." }`	InternalServerError

/v1/persons/{hmppsId}/risks/categories

get

Returns the categories related to an offender.

Applicable filters:

prisons

Parameters

Parameter	In	Type	Required	Description
hmppsId	path	string	true	The HMPPS ID of the person

Responses

Status	Description	Schema
200	Successfully found risk categories for a person with the provided HMPPS ID. `{ "data": { "offenderNo": "string", "assessments": [ { "classificationCode": "C", "classification": "Cat C", "assessmentCode": "CATEGORY", "assessmentDescription": "Categorisation", "assessmentDate": "2018-02-11", "nextReviewDate": "2018-02-11", "assessmentAgencyId": "MDI", "assessmentStatus": "P", "assessmentComment": "Comment details" } ], "category": "string", "categoryCode": "string" } }`	DataResponseRiskCategory
404	Not Found `{ "status": 404, "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.", "developerMessage": "Could not find person with HMPPS id: 2003/0011991D." }`	PersonNotFound
400	Bad Request `{ "status": 400, "userMessage": "Validation failure: No query parameters specified.", "developerMessage": "No query parameters specified." }`	BadRequest
500	Internal Server Error `{ "status": 500, "userMessage": "Internal Server Error", "developerMessage": "Unable to complete request as an upstream service is not responding." }`	InternalServerError

/v1/persons/{hmppsId}/reported-adjudications

get

Returns adjudications associated with a person, sorted by dateTimeOfIncident (newest first).

Applicable filters:

prisons

Parameters

Parameter	In	Type	Required	Description
hmppsId	path	string	true	The HMPPS ID of the person
page	query	string	false	The page number (starting from 1)
perPage	query	string	false	The maximum number of results for a page

Responses

Status	Description	Schema
200	OK { "data": [ { "incidentDetails": { "dateTimeOfIncident": "string" }, "isYouthOffender": "boolean", "incidentRole": { "roleCode": "string", "offenceRule": { "paragraphNumber": "string", "paragraphDescription": "string" } }, "offenceDetails": { "offenceCode": "number", "offenceRule": { "paragraphNumber": "string", "paragraphDescription": "string" } }, "status": "string", "statusReason": "string", "statusDetails": "string", "hearings": [ { "dateTimeOfHearing": "string", "oicHearingType": "string", "outcome": { "code": "string", "reason": "string", "details": "string", "plea": "string" } } ], "outcomes": [ { "hearing": { "dateTimeOfHearing": "string", "oicHearingType": "string", "outcome": { "code": "string", "reason": "string", "details": "string", "plea": "string" } }, "outcome": { "outcome": { "code": "string", "details": "string", "reason": "string", "quashedReason": "string", "canRemove": "boolean" }, "referralOutcome": { "code": "string", "details": "string", "reason": "string", "quashedReason": "string", "canRemove": "boolean" } } } ], "punishments": [ { "type": "string", "privilegeType": "string", "otherPrivilege": "string", "schedule": { "days": "number", "startDate": "string", "endDate": "string", "suspendedUntil": "string" } } ], "punishmentComments": [ { "comment": "string", "reasonForChange": "string", "dateTime": "string" } ] } ], "pagination": { "isLastPage": true, "count": 1, "page": 1, "perPage": 10, "totalCount": 1, "totalPages": 1 } }	PaginatedResponseAdjudication
404	Failed to find adjudications for the person with the provided hmppsId. `{ "status": 404, "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.", "developerMessage": "Could not find person with HMPPS id: 2003/0011991D." }`	PersonNotFound
400	Malformed hmppsId. `{ "status": 400, "userMessage": "Validation failure: No query parameters specified.", "developerMessage": "No query parameters specified." }`	BadRequest
500	Internal Server Error `{ "status": 500, "userMessage": "Internal Server Error", "developerMessage": "Unable to complete request as an upstream service is not responding." }`	InternalServerError

/v1/persons/{hmppsId}/protected-characteristics

get

Returns protected characteristics of a person.

Applicable filters:

prisons

Parameters

Parameter	In	Type	Required	Description
hmppsId	path	string	true	The HMPPS ID of the person

Responses

Status	Description	Schema
200	OK { "data": { "age": 35, "gender": "Female", "sexualOrientation": "Unknown", "ethnicity": "White: Eng./Welsh/Scot./N.Irish/British", "nationality": "Egyptian", "religion": "Church of England (Anglican)", "disabilities": [ { "disabilityType": { "code": "string", "description": "string" }, "condition": { "code": "string", "description": "string" }, "startDate": "string", "endDate": "string", "notes": "Walking issue" } ], "maritalStatus": "Widowed", "reasonableAdjustments": [ { "treatmentCode": "WHEELCHR_ACC", "commentText": "abcd", "startDate": "2013-04-11", "endDate": "2023-04-11", "treatmentDescription": "Wheelchair accessibility" } ] } }	DataResponsePersonProtectedCharacteristics
400	Bad Request `{ "status": 400, "userMessage": "Validation failure: No query parameters specified.", "developerMessage": "No query parameters specified." }`	BadRequest
404	Not Found `{ "status": 404, "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.", "developerMessage": "Could not find person with HMPPS id: 2003/0011991D." }`	PersonNotFound
500	Internal Server Error `{ "status": 500, "userMessage": "Internal Server Error", "developerMessage": "Unable to complete request as an upstream service is not responding." }`	InternalServerError

/v1/persons/{hmppsId}/plp-review-schedule

get

Returns the plp review schedule associated with a person.

Parameters

Parameter	In	Type	Required	Description
hmppsId	path	string	true	A HmppsId
statuses	query	array	false	Filter by review schedule statuses

Responses

Status Description Schema

200

Successfully found induction schedule for a person with the provided HMPPS ID.

{
  "data": {
    "reviewSchedules": [
      {
        "nomisNumber": "A1234BC",
        "reference": "string",
        "reviewDateFrom": "string",
        "reviewDateTo": "string",
        "status": "string",
        "calculationRule": "string",
        "createdBy": "string",
        "createdByDisplayName": "string",
        "createdAt": "string",
        "createdAtPrison": "string",
        "updatedBy": "string",
        "updatedByDisplayName": "string",
        "updatedAt": "string",
        "updatedAtPrison": "string",
        "version": "integer",
        "reviewCompletedBy": "string",
        "reviewCompletedByRole": "string",
        "reviewCompletedAt": "string",
        "reviewType": "string",
        "reviewReason": "string"
      }
    ]
  }
}

DataResponseReviewSchedules

404

Not Found

{
  "status": 404,
  "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.",
  "developerMessage": "Could not find person with HMPPS id: 2003/0011991D."
}

PersonNotFound

500

Internal Server Error

{
  "status": 500,
  "userMessage": "Internal Server Error",
  "developerMessage": "Unable to complete request as an upstream service is not responding."
}

InternalServerError

/v1/persons/{hmppsId}/plp-induction-schedule

get

Returns plp the current induction schedule associated with a person.

Parameters

Parameter	In	Type	Required	Description
hmppsId	path	string	true	A HMPPS id

Responses

Status Description Schema

200

Successfully found induction schedule for a person with the provided HMPPS ID.

{
  "data": {
    "deadlineDate": "2023-09-01",
    "status": "SCHEDULED",
    "calculationRule": "NEW_PRISON_ADMISSION",
    "nomisNumber": "A1234BC",
    "systemCreatedBy": "John Smith",
    "systemCreatedAt": "2023-06-19T09:39:44Z",
    "systemCreatedAtPrison": "BXI",
    "systemUpdatedBy": "Fred Jones",
    "systemUpdatedAt": "2023-06-19T09:39:44Z",
    "systemUpdatedAtPrison": "BXI",
    "inductionPerformedBy": "Fred Jones",
    "inductionPerformedAt": "2023-06-30",
    "inductionPerformedByRole": "Peer Mentor",
    "inductionPerformedAtPrison": "BXI",
    "exemptionReason": "EXEMPT_SYSTEM_TECHNICAL_ISSUE",
    "version": "integer"
  }
}

DataResponseInductionSchedule

404

Not Found

{
  "status": 404,
  "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.",
  "developerMessage": "Could not find person with HMPPS id: 2003/0011991D."
}

PersonNotFound

500

Internal Server Error

{
  "status": 500,
  "userMessage": "Internal Server Error",
  "developerMessage": "Unable to complete request as an upstream service is not responding."
}

InternalServerError

/v1/persons/{hmppsId}/plp-induction-schedule/history

get

Returns the plp induction schedule history associated with a person.

Parameters

Parameter	In	Type	Required	Description
hmppsId	path	string	true	A HMPPS id

Responses

Status Description Schema

200

Successfully found induction schedule history for a person with the provided HMPPS ID.

{
  "data": {
    "inductionSchedules": [
      {
        "deadlineDate": "2023-09-01",
        "status": "SCHEDULED",
        "calculationRule": "NEW_PRISON_ADMISSION",
        "nomisNumber": "A1234BC",
        "systemCreatedBy": "John Smith",
        "systemCreatedAt": "2023-06-19T09:39:44Z",
        "systemCreatedAtPrison": "BXI",
        "systemUpdatedBy": "Fred Jones",
        "systemUpdatedAt": "2023-06-19T09:39:44Z",
        "systemUpdatedAtPrison": "BXI",
        "inductionPerformedBy": "Fred Jones",
        "inductionPerformedAt": "2023-06-30",
        "inductionPerformedByRole": "Peer Mentor",
        "inductionPerformedAtPrison": "BXI",
        "exemptionReason": "EXEMPT_SYSTEM_TECHNICAL_ISSUE",
        "version": "integer"
      }
    ]
  }
}

DataResponseInductionSchedules

404

Not Found

{
  "status": 404,
  "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.",
  "developerMessage": "Could not find person with HMPPS id: 2003/0011991D."
}

PersonNotFound

500

Internal Server Error

{
  "status": 500,
  "userMessage": "Internal Server Error",
  "developerMessage": "Unable to complete request as an upstream service is not responding."
}

InternalServerError

/v1/persons/{hmppsId}/name

get

Returns a person’s name

Applicable filters:

prisons

Parameters

Parameter	In	Type	Required	Description
hmppsId	path	string	true	The HMPPS ID of the person

Responses

Status	Description	Schema
200	Successfully found a person with the provided HMPPS ID. `{ "data": { "firstName": "string", "lastName": "string" } }`	DataResponsePersonName
400	Bad Request `{ "status": 400, "userMessage": "Validation failure: No query parameters specified.", "developerMessage": "No query parameters specified." }`	BadRequest
404	Not Found `{ "status": 404, "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.", "developerMessage": "Could not find person with HMPPS id: 2003/0011991D." }`	PersonNotFound
500	Internal Server Error `{ "status": 500, "userMessage": "Internal Server Error", "developerMessage": "Unable to complete request as an upstream service is not responding." }`	InternalServerError

/v1/persons/{hmppsId}/iep-level

get

Returns a prisoners IEP level.

Applicable filters:

prisons

Parameters

Parameter	In	Type	Required	Description
hmppsId	path	string	true	The HMPPS ID of the prisoner

Responses

Status	Description	Schema
200	Successfully found a prisoners contacts. `{ "data": { "iepCode": "STD", "iepLevel": "Standard" } }`	DataResponseIEPLevel
400	Bad Request `{ "status": 400, "userMessage": "Validation failure: No query parameters specified.", "developerMessage": "No query parameters specified." }`	BadRequest
404	Not Found `{ "status": 404, "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.", "developerMessage": "Could not find person with HMPPS id: 2003/0011991D." }`	PersonNotFound
500	Internal Server Error `{ "status": 500, "userMessage": "Internal Server Error", "developerMessage": "Unable to complete request as an upstream service is not responding." }`	InternalServerError

/v1/persons/{hmppsId}/contacts

get

Returns a prisoners contacts.

Applicable filters:

prisons

Parameters

Parameter	In	Type	Required	Description
hmppsId	path	string	true	The HMPPS ID of the prisoner
page	query	string	false	The page number (starting from 1)
perPage	query	string	false	The maximum number of results for a page

Responses

Status Description Schema

200

Successfully found a prisoners contacts.

{
  "data": [
    {
      "contact": {
        "contactId": 123456,
        "lastName": "Doe",
        "firstName": "John",
        "middleNames": "William",
        "dateOfBirth": "1980-01-01",
        "flat": "Flat 2B",
        "property": "Mansion House",
        "street": "Acacia Avenue",
        "area": "Morton Heights",
        "cityCode": "25343",
        "cityDescription": "Sheffield",
        "countyCode": "S.YORKSHIRE",
        "countyDescription": "South Yorkshire",
        "postCode": "S13 4FH",
        "countryCode": "ENG",
        "countryDescription": "England",
        "primaryAddress": true,
        "mailAddress": true,
        "phoneType": "MOB",
        "phoneTypeDescription": "Mobile",
        "phoneNumber": "+1234567890",
        "extNumber": "123"
      },
      "relationship": {
        "relationshipTypeCode": "Social",
        "relationshipTypeDescription": "Friend",
        "relationshipToPrisonerCode": "FRI",
        "relationshipToPrisonerDescription": "Friend",
        "approvedVisitor": true,
        "nextOfKin": "boolean",
        "emergencyContact": true,
        "isRelationshipActive": true,
        "currentTerm": true,
        "comments": "Close family friend"
      }
    }
  ],
  "pagination": {
    "isLastPage": true,
    "count": 1,
    "page": 1,
    "perPage": 10,
    "totalCount": 1,
    "totalPages": 1
  }
}

PaginatedResponsePrisonerContact

404

Not Found

{
  "status": 404,
  "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.",
  "developerMessage": "Could not find person with HMPPS id: 2003/0011991D."
}

PersonNotFound

500

Internal Server Error

{
  "status": 500,
  "userMessage": "Internal Server Error",
  "developerMessage": "Unable to complete request as an upstream service is not responding."
}

InternalServerError

/v1/persons/{hmppsId}/cell-location

get

Returns the cell location of a person.

Applicable filters:

prisons

Parameters

Parameter	In	Type	Required	Description
hmppsId	path	string	true	The HMPPS ID of the person

Responses

Status	Description	Schema
200	Successfully found a persons cell location. `{ "data": { "prisonCode": "string", "prisonName": "string", "cell": "string" } }`	DataResponseCellLocation
400	The HMPPS ID provided has an invalid format. `{ "status": 400, "userMessage": "Validation failure: No query parameters specified.", "developerMessage": "No query parameters specified." }`	BadRequest
404	Not Found `{ "status": 404, "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.", "developerMessage": "Could not find person with HMPPS id: 2003/0011991D." }`	PersonNotFound
500	Internal Server Error `{ "status": 500, "userMessage": "Internal Server Error", "developerMessage": "Unable to complete request as an upstream service is not responding." }`	InternalServerError

/v1/persons/{hmppsId}/alerts

get

Returns alerts associated with a person, sorted by dateCreated (newest first).

Applicable filters:

prisons

Parameters

Parameter	In	Type	Required	Description
hmppsId	path	string	true	The HMPPS ID of the person
page	query	string	false	The page number (starting from 1)
perPage	query	string	false	The maximum number of results for a page

Responses

Status	Description	Schema
200	Successfully found alerts for a person with the provided HMPPS ID. `{ "data": [ { "offenderNo": "Z1234ZZ", "type": "X", "typeDescription": "Security", "code": "PO", "codeDescription": "MAPPA Nominal", "comment": "Professional lock pick", "dateCreated": "2014-09-23", "dateExpired": "2015-09-23", "expired": true, "active": true } ], "pagination": { "isLastPage": true, "count": 1, "page": 1, "perPage": 10, "totalCount": 1, "totalPages": 1 } }`	PaginatedResponseAlert
400	Bad Request `{ "status": 400, "userMessage": "Validation failure: No query parameters specified.", "developerMessage": "No query parameters specified." }`	BadRequest
404	Not Found `{ "status": 404, "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.", "developerMessage": "Could not find person with HMPPS id: 2003/0011991D." }`	PersonNotFound
500	Internal Server Error `{ "status": 500, "userMessage": "Internal Server Error", "developerMessage": "Unable to complete request as an upstream service is not responding." }`	InternalServerError

/v1/persons/{hmppsId}/addresses

get

Returns addresses associated with a person, ordered by startDate.

Applicable filters:

prisons

Parameters

Parameter	In	Type	Required	Description
hmppsId	path	string	true	The HMPPS ID of the person

Responses

Status	Description	Schema
200	Successfully found a person with the provided HMPPS ID. `{ "data": [ { "country": "England", "county": "Greater London", "endDate": "string", "locality": "London Bridge", "name": "Name of the building of residence", "noFixedAddress": true, "number": "1", "postcode": "SE1 1TE", "startDate": "string", "street": "O'Meara Street", "town": "London", "types": [ { "code": "string", "desc": "string" } ], "notes": "This is their partner's address." } ] }`	DataResponseListAddress
400	Bad Request `{ "status": 400, "userMessage": "Validation failure: No query parameters specified.", "developerMessage": "No query parameters specified." }`	BadRequest
404	Not Found `{ "status": 404, "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.", "developerMessage": "Could not find person with HMPPS id: 2003/0011991D." }`	PersonNotFound
500	Internal Server Error `{ "status": 500, "userMessage": "Internal Server Error", "developerMessage": "Unable to complete request as an upstream service is not responding." }`	InternalServerError

/v1/persons/{encodedHmppsId}

get

Returns a person.

Parameters

Parameter	In	Type	Required	Description
encodedHmppsId	path	string	true	A URL-encoded HMPPS identifier

Responses

Status Description Schema

200

Successfully found a person with the provided HMPPS ID.

{
  "data": {
    "prisonerOffenderSearch": {
      "firstName": "John",
      "lastName": "Morgan",
      "middleName": "John",
      "dateOfBirth": "1965-12-01",
      "gender": "Male",
      "ethnicity": "White: Eng./Welsh/Scot./N.Irish/British",
      "aliases": [
        {
          "firstName": "John",
          "lastName": "Marston",
          "middleName": "Marston",
          "dateOfBirth": "1965-12-01",
          "gender": "Male",
          "ethnicity": "Prefer not to say"
        }
      ],
      "identifiers": {
        "nomisNumber": "A1234AA",
        "croNumber": "SF80/655108T",
        "deliusCrn": "X00001"
      },
      "pncId": "string",
      "hmppsId": "2008/0545166T",
      "contactDetails": {
        "phoneNumbers": [
          {
            "number": "079123456789",
            "type": "TELEPHONE"
          }
        ],
        "emails": [
          {
          }
        ]
      },
      "currentRestriction": "boolean",
      "restrictionMessage": "string",
      "currentExclusion": "boolean",
      "exclusionMessage": "string"
    },
    "probationOffenderSearch": {
      "person": {
        "firstName": "John",
        "lastName": "Morgan",
        "middleName": "John",
        "dateOfBirth": "1965-12-01",
        "gender": "Male",
        "ethnicity": "White: Eng./Welsh/Scot./N.Irish/British",
        "aliases": [
          {
            "firstName": "John",
            "lastName": "Marston",
            "middleName": "Marston",
            "dateOfBirth": "1965-12-01",
            "gender": "Male",
            "ethnicity": "Prefer not to say"
          }
        ],
        "identifiers": {
          "nomisNumber": "A1234AA",
          "croNumber": "SF80/655108T",
          "deliusCrn": "X00001"
        },
        "pncId": "string",
        "hmppsId": "2008/0545166T",
        "contactDetails": {
          "phoneNumbers": [
            {
              "number": "079123456789",
              "type": "TELEPHONE"
            }
          ],
          "emails": [
            {
            }
          ]
        },
        "currentRestriction": "boolean",
        "restrictionMessage": "string",
        "currentExclusion": "boolean",
        "exclusionMessage": "string"
      },
      "underActiveSupervision": "boolean",
      "firstName": "string",
      "lastName": "string",
      "middleName": "string",
      "dateOfBirth": "string",
      "gender": "string",
      "ethnicity": "string",
      "aliases": [
        {
          "firstName": "John",
          "lastName": "Marston",
          "middleName": "Marston",
          "dateOfBirth": "1965-12-01",
          "gender": "Male",
          "ethnicity": "Prefer not to say"
        }
      ],
      "identifiers": {
        "nomisNumber": "A1234AA",
        "croNumber": "SF80/655108T",
        "deliusCrn": "X00001"
      },
      "pncId": "string",
      "hmppsId": "string",
      "contactDetails": {
        "phoneNumbers": [
          {
            "number": "079123456789",
            "type": "TELEPHONE"
          }
        ],
        "emails": [
          {
          }
        ]
      },
      "currentRestriction": "boolean",
      "restrictionMessage": "string",
      "currentExclusion": "boolean",
      "exclusionMessage": "string"
    }
  }
}

DataResponseOffenderSearchResponse

404

Not Found

{
  "status": 404,
  "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.",
  "developerMessage": "Could not find person with HMPPS id: 2003/0011991D."
}

PersonNotFound

500

Internal Server Error

{
  "status": 500,
  "userMessage": "Internal Server Error",
  "developerMessage": "Unable to complete request as an upstream service is not responding."
}

InternalServerError

/v1/persons/{encodedHmppsId}/status-information

get

Returns the status information associated with a person.

Parameters

Parameter	In	Type	Required	Description
encodedHmppsId	path	string	true	A URL-encoded HMPPS identifier
page	query	string	false	The page number (starting from 1)
perPage	query	string	false	The maximum number of results for a page

Responses

Status Description Schema

200

Successfully found status information for a person with the provided HMPPS ID.

{
  "data": [
    {
      "code": "ASFO",
      "description": "Serious Further Offence - Subject to SFO review/investigation",
      "startDate": "2022-01-01",
      "reviewDate": "2025-01-01",
      "notes": "This is a note"
    }
  ],
  "pagination": {
    "isLastPage": true,
    "count": 1,
    "page": 1,
    "perPage": 10,
    "totalCount": 1,
    "totalPages": 1
  }
}

PaginatedResponseStatusInformation

404

Not Found

{
  "status": 404,
  "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.",
  "developerMessage": "Could not find person with HMPPS id: 2003/0011991D."
}

PersonNotFound

500

Internal Server Error

{
  "status": 500,
  "userMessage": "Internal Server Error",
  "developerMessage": "Unable to complete request as an upstream service is not responding."
}

InternalServerError

/v1/persons/{encodedHmppsId}/sentences/latest-key-dates-and-adjustments

get

Returns the key dates and adjustments about a person’s release from prison for their latest sentence.

Applicable filters:

prisons

Parameters

Parameter	In	Type	Required	Description
encodedHmppsId	path	string	true	A URL-encoded HMPPS identifier

Responses

Status	Description	Schema
200	Successfully found latest sentence key dates and adjustments for a person with the provided HMPPS ID. { "data": { "adjustments": { "additionalDaysAwarded": 10, "unlawfullyAtLarge": 16, "lawfullyAtLarge": 11, "restoredAdditionalDaysAwarded": 20, "specialRemission": 14, "recallSentenceRemand": 7, "recallSentenceTaggedBail": 19, "remand": 3, "taggedBail": 13, "unusedRemand": 13 }, "automaticRelease": { "date": "2023-03-01", "overrideDate": "2023-03-01" }, "conditionalRelease": { "date": "2023-03-01", "overrideDate": "2023-03-01" }, "dtoPostRecallRelease": { "date": "2023-03-01", "overrideDate": "2023-03-01" }, "earlyTerm": { "date": "2023-03-01", "overrideDate": "2023-03-01", "calculatedDate": "2023-03-01" }, "homeDetentionCurfew": { "actualDate": "string", "eligibilityCalculatedDate": "string", "eligibilityDate": "string", "eligibilityOverrideDate": "string", "endDate": "string" }, "lateTerm": { "date": "2023-03-01", "overrideDate": "2023-03-01", "calculatedDate": "2023-03-01" }, "licenceExpiry": { "date": "2023-03-01", "overrideDate": "2023-03-01", "calculatedDate": "2023-03-01" }, "midTerm": { "date": "2023-03-01", "overrideDate": "2023-03-01", "calculatedDate": "2023-03-01" }, "nonDto": { "date": "2023-03-01", "releaseDateType": "ARD" }, "nonParole": { "date": "2023-03-01", "overrideDate": "2023-03-01" }, "paroleEligibility": { "date": "2023-03-01", "overrideDate": "2023-03-01", "calculatedDate": "2023-03-01" }, "postRecallRelease": { "date": "2023-03-01", "overrideDate": "2023-03-01" }, "release": { "date": "2023-03-01", "confirmedDate": "2023-03-01" }, "sentence": { "effectiveEndDate": "2023-03-01", "expiryCalculatedDate": "2023-03-01", "expiryDate": "2023-03-01", "expiryOverrideDate": "2023-03-01", "startDate": "2023-03-01" }, "topupSupervision": { "expiryCalculatedDate": "2023-03-01", "expiryDate": "2023-03-01", "expiryOverrideDate": "2023-03-01", "startDate": "2023-03-01" }, "actualParoleDate": "2023-03-01", "earlyRemovalSchemeEligibilityDate": "2023-03-01", "releaseOnTemporaryLicenceDate": "2023-03-01", "tariffDate": "2023-03-01", "tariffEarlyRemovalSchemeEligibilityDate": "2023-03-01" } }	DataResponseLatestSentenceKeyDatesAndAdjustments
400	Bad Request `{ "status": 400, "userMessage": "Validation failure: No query parameters specified.", "developerMessage": "No query parameters specified." }`	BadRequest
404	Not Found `{ "status": 404, "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.", "developerMessage": "Could not find person with HMPPS id: 2003/0011991D." }`	PersonNotFound
500	Internal Server Error `{ "status": 500, "userMessage": "Internal Server Error", "developerMessage": "Unable to complete request as an upstream service is not responding." }`	InternalServerError

/v1/persons/{encodedHmppsId}/risks/serious-harm

get

Returns Risk of Serious Harm (ROSH) risks associated with a person. Returns only assessments completed in the last year. This endpoint does not serve LAO (Limited Access Offender) data.

Parameters

Parameter	In	Type	Required	Description
encodedHmppsId	path	string	true	A URL-encoded HMPPS identifier

Responses

Status Description Schema

200

Successfully found risks for a person with the provided HMPPS ID.

{
  "data": {
    "assessedOn": "string",
    "riskToSelf": {
      "suicide": {
        "risk": "YES",
        "previous": "NO",
        "previousConcernsText": "Risk of self harm concerns due to ...",
        "current": "YES",
        "currentConcernsText": "Risk of self harm concerns due to ..."
      },
      "selfHarm": {
        "risk": "YES",
        "previous": "NO",
        "previousConcernsText": "Risk of self harm concerns due to ...",
        "current": "YES",
        "currentConcernsText": "Risk of self harm concerns due to ..."
      },
      "custody": {
        "risk": "YES",
        "previous": "NO",
        "previousConcernsText": "Risk of self harm concerns due to ...",
        "current": "YES",
        "currentConcernsText": "Risk of self harm concerns due to ..."
      },
      "hostelSetting": {
        "risk": "YES",
        "previous": "NO",
        "previousConcernsText": "Risk of self harm concerns due to ...",
        "current": "YES",
        "currentConcernsText": "Risk of self harm concerns due to ..."
      },
      "vulnerability": {
        "risk": "YES",
        "previous": "NO",
        "previousConcernsText": "Risk of self harm concerns due to ...",
        "current": "YES",
        "currentConcernsText": "Risk of self harm concerns due to ..."
      }
    },
    "otherRisks": {
      "escapeOrAbscond": "YES",
      "controlIssuesDisruptiveBehaviour": "DK",
      "breachOfTrust": "NO",
      "riskToOtherPrisoners": "YES"
    },
    "summary": {
      "whoIsAtRisk": "X, Y and Z are at risk",
      "natureOfRisk": "The nature of the risk is X",
      "riskImminence": "The risk is imminent and more probable in X situation",
      "riskIncreaseFactors": "If offender in situation X the risk can be higher",
      "riskMitigationFactors": "Giving offender therapy in X will reduce the risk",
      "overallRiskLevel": "HIGH",
      "riskInCommunity": {
      },
      "riskInCustody": {
      }
    }
  }
}

DataResponseRisks

404

Not Found

{
  "status": 404,
  "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.",
  "developerMessage": "Could not find person with HMPPS id: 2003/0011991D."
}

PersonNotFound

500

Internal Server Error

{
  "status": 500,
  "userMessage": "Internal Server Error",
  "developerMessage": "Unable to complete request as an upstream service is not responding."
}

InternalServerError

/v1/persons/{encodedHmppsId}/risks/scores

get

Returns risk scores from the last year associated with a person, sorted by completedDate (newest first). This endpoint does not serve LAO (Limited Access Offender) data.

Parameters

Parameter	In	Type	Required	Description
encodedHmppsId	path	string	true	A URL-encoded HMPPS identifier
page	query	string	false	The page number (starting from 1)
perPage	query	string	false	The maximum number of results for a page

Responses

Status Description Schema

200

Successfully found risk scores for a person with the provided HMPPS ID.

{
  "data": [
    {
      "completedDate": "string",
      "assessmentStatus": "COMPLETED",
      "generalPredictor": {
        "scoreLevel": "VERY_HIGH"
      },
      "violencePredictor": {
        "scoreLevel": "MEDIUM"
      },
      "groupReconviction": {
        "scoreLevel": "LOW"
      },
      "riskOfSeriousRecidivism": {
        "scoreLevel": "MEDIUM"
      },
      "sexualPredictor": {
        "indecentScoreLevel": "MEDIUM",
        "contactScoreLevel": "MEDIUM"
      }
    }
  ],
  "pagination": {
    "isLastPage": true,
    "count": 1,
    "page": 1,
    "perPage": 10,
    "totalCount": 1,
    "totalPages": 1
  }
}

PaginatedResponseRiskPredictorScore

404

Not Found

{
  "status": 404,
  "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.",
  "developerMessage": "Could not find person with HMPPS id: 2003/0011991D."
}

PersonNotFound

500

Internal Server Error

{
  "status": 500,
  "userMessage": "Internal Server Error",
  "developerMessage": "Unable to complete request as an upstream service is not responding."
}

InternalServerError

/v1/persons/{encodedHmppsId}/risks/mappadetail

get

Returns the mappa detail related to a person.

Parameters

Parameter	In	Type	Required	Description
encodedHmppsId	path	string	true	A URL-encoded HMPPS identifier

Responses

Status Description Schema

200

Successfully found mappa detail for a person with the provided HMPPS ID.

{
  "data": {
    "level": 1,
    "levelDescription": "Description of M1",
    "category": 2,
    "categoryDescription": "Description of M2",
    "startDate": "2024-02-07",
    "reviewDate": "2024-02-07",
    "notes": "Mappa Detail for X00001"
  }
}

DataResponseMappaDetail

404

Not Found

{
  "status": 404,
  "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.",
  "developerMessage": "Could not find person with HMPPS id: 2003/0011991D."
}

PersonNotFound

500

Internal Server Error

{
  "status": 500,
  "userMessage": "Internal Server Error",
  "developerMessage": "Unable to complete request as an upstream service is not responding."
}

InternalServerError

/v1/persons/{encodedHmppsId}/risks/dynamic

get

Returns dynamic risks associated with a person.

Parameters

Parameter	In	Type	Required	Description
encodedHmppsId	path	string	true	A URL-encoded HMPPS identifier
page	query	string	false	The page number (starting from 1)
perPage	query	string	false	The maximum number of results for a page

Responses

Status Description Schema

200

Successfully found dynamic risks for a person with the provided HMPPS ID.

{
  "data": [
    {
      "code": "RCCO",
      "description": "Child Concerns - Safeguarding concerns where a child is at risk from the offender",
      "startDate": "2022-01-01",
      "reviewDate": "2025-01-01",
      "notes": "This is a note"
    }
  ],
  "pagination": {
    "isLastPage": true,
    "count": 1,
    "page": 1,
    "perPage": 10,
    "totalCount": 1,
    "totalPages": 1
  }
}

PaginatedResponseDynamicRisk

404

Not Found

{
  "status": 404,
  "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.",
  "developerMessage": "Could not find person with HMPPS id: 2003/0011991D."
}

PersonNotFound

500

Internal Server Error

{
  "status": 500,
  "userMessage": "Internal Server Error",
  "developerMessage": "Unable to complete request as an upstream service is not responding."
}

InternalServerError

/v1/persons/{encodedHmppsId}/risk-management-plan

get

Returns a list of Risk Management Plans created for the person with the provided HMPPS ID.

Parameters

Parameter	In	Type	Required	Description
encodedHmppsId	path	string	true	A URL-encoded HMPPS identifier
page	query	string	false	The page number (starting from 1)
perPage	query	string	false	The maximum number of results for a page

Responses

Status	Description	Schema
200	Successfully found risk management plans for a person with the provided HMPPS ID. { "data": [ { "assessmentId": "123456", "dateCompleted": "2024-05-04T01:04:20", "initiationDate": "2024-05-04T01:04:20", "assessmentStatus": "COMPLETE", "assessmentType": "string", "keyInformationCurrentSituation": "string", "furtherConsiderationsCurrentSituation": "string", "supervision": "string", "monitoringAndControl": "string", "interventionsAndTreatment": "string", "victimSafetyPlanning": "string", "contingencyPlans": "string", "latestSignLockDate": "2024-05-04T01:04:20", "latestCompleteDate": "2024-05-04T01:04:20" } ], "pagination": { "isLastPage": true, "count": 1, "page": 1, "perPage": 10, "totalCount": 1, "totalPages": 1 } }	PaginatedResponseRiskManagementPlan
403	Forbidden `{ "status": 403, "userMessage": "Forbidden to complete action by upstream service", "developerMessage": "Forbidden to complete action by upstream service" }`	ForbiddenResponse
404	Not Found `{ "status": 404, "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.", "developerMessage": "Could not find person with HMPPS id: 2003/0011991D." }`	PersonNotFound
500	Internal Server Error `{ "status": 500, "userMessage": "Internal Server Error", "developerMessage": "Unable to complete request as an upstream service is not responding." }`	InternalServerError

/v1/persons/{encodedHmppsId}/person-responsible-officer

get

Returns the person responsible officer associated with a person.

Parameters

Parameter	In	Type	Required	Description
encodedHmppsId	path	string	true	A URL-encoded HMPPS identifier

Responses

Status Description Schema

200

Successfully found the person responsible officer for a person with the provided HMPPS ID.

{
  "data": {
    "prisonOffenderManager": {
      "forename": "string",
      "surname": "string",
      "prison": {
        "code": "string"
      }
    },
    "communityOffenderManager": {
      "name": {
        "forename": "string",
        "surname": "string"
      },
      "email": "string",
      "telephoneNumber": "string",
      "team": {
        "code": "string",
        "description": "string",
        "email": "string",
        "telephoneNumber": "string"
      }
    }
  }
}

DataResponsePersonResponsibleOfficer

404

Not Found

{
  "status": 404,
  "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.",
  "developerMessage": "Could not find person with HMPPS id: 2003/0011991D."
}

PersonNotFound

500

Internal Server Error

{
  "status": 500,
  "userMessage": "Internal Server Error",
  "developerMessage": "Unable to complete request as an upstream service is not responding."
}

InternalServerError

/v1/persons/{encodedHmppsId}/offences

get

Returns offences associated with a person, ordered by startDate (newest first). > Note: This API does not contain the complete list of offences for a person. > Offences are retrieved from Prison and Probation systems exclusively. > Prison systems record only custodial sentences, while Probation systems record only the main offence and some additional offences for case management purposes. Other offences recorded by HMCTS and police may not be included.

Parameters

Parameter	In	Type	Required	Description
encodedHmppsId	path	string	true	A URL-encoded HMPPS identifier
page	query	string	false	The page number (starting from 1)
perPage	query	string	false	The maximum number of results for a page

Responses

Status Description Schema

200

Successfully found offences for a person with the provided HMPPS ID.

{
  "data": [
    {
      "serviceSource": "NOMIS",
      "systemSource": "PRISON_SYSTEMS",
      "cjsCode": "RR84170",
      "courtDates": [
        "2018-02-10",
        "2019-02-10"
      ],
      "courtName": "London Magistrates Court",
      "description": "Commit an act / series of acts with intent to pervert the course of public justice",
      "endDate": "2018-03-10",
      "hoCode": 3457,
      "startDate": "1965-12-01",
      "statuteCode": "RR84"
    },
    {
      "serviceSource": "NDELIUS",
      "systemSource": "PROBATION_SYSTEMS",
      "cjsCode": "RR12345",
      "courtDates": [
        "2020-05-15",
        "2021-05-15"
      ],
      "courtName": "Manchester Crown Court",
      "description": "Assault causing grievous bodily harm",
      "endDate": "2020-06-20",
      "hoCode": 3458,
      "startDate": "2020-05-10",
      "statuteCode": "RR85"
    }
  ]
}

PaginatedResponse

404

Not Found

{
  "status": 404,
  "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.",
  "developerMessage": "Could not find person with HMPPS id: 2003/0011991D."
}

PersonNotFound

500

Internal Server Error

{
  "status": 500,
  "userMessage": "Internal Server Error",
  "developerMessage": "Unable to complete request as an upstream service is not responding."
}

InternalServerError

/v1/persons/{encodedHmppsId}/needs

get

Returns criminogenic needs associated with a person. This endpoint does not serve LAO (Limited Access Offender) data. Note: Criminogenic needs are dynamic factors that are directly linked to criminal behaviour. Eight criminogenic needs are measured in OASys: Accommodation, Employability, Relationships, Lifestyle and Associates, Drug Misuse, Alcohol Misuse, Thinking & Behaviour and Attitudes. These are scored according to whether there is “no need”, “some need” or “severe need”, and a need is identified in a specific section based on calculations around these scores. However, the process by which needs are assessed is changing as early as next year (2024), specifically moving to a strength-based model that seeks to identify and develop the strengths of people with convictions. As a consequence of this, the information provided by this endpoint will also change.

Parameters

Parameter	In	Type	Required	Description
encodedHmppsId	path	string	true	A URL-encoded HMPPS identifier

Responses

Status Description Schema

200

Successfully found criminogenic needs for a person with the provided HMPPS ID.

{
  "data": {
    "assessedOn": "string",
    "identifiedNeeds": [
      {
        "type": "DRUG_MISUSE",
        "riskOfHarm": "boolean",
        "riskOfReoffending": "boolean",
        "severity": "NO_NEED"
      }
    ],
    "notIdentifiedNeeds": [
      {
        "type": "DRUG_MISUSE",
        "riskOfHarm": "boolean",
        "riskOfReoffending": "boolean",
        "severity": "NO_NEED"
      }
    ],
    "unansweredNeeds": [
      {
        "type": "DRUG_MISUSE",
        "riskOfHarm": "boolean",
        "riskOfReoffending": "boolean",
        "severity": "NO_NEED"
      }
    ]
  }
}

DataResponseNeeds

404

Not Found

{
  "status": 404,
  "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.",
  "developerMessage": "Could not find person with HMPPS id: 2003/0011991D."
}

PersonNotFound

500

Internal Server Error

{
  "status": 500,
  "userMessage": "Internal Server Error",
  "developerMessage": "Unable to complete request as an upstream service is not responding."
}

InternalServerError

/v1/persons/{encodedHmppsId}/licences/conditions

get

Returns license conditions associated with a person, sorted by createdDateTime (newest first).

Parameters

Parameter	In	Type	Required	Description
encodedHmppsId	path	string	true	A URL-encoded HMPPS identifier

Responses

Status Description Schema

200

Successfully found licenses for a person with the provided HMPPS ID.

{
  "data": {
    "hmppsId": "2008/0545166T",
    "offenderNumber": "Z1234ZZ",
    "licences": [
      {
        "status": "string",
        "typeCode": "string",
        "createdDate": "string",
        "approvedDate": "string",
        "updatedDate": "string",
        "conditions": [
          {
            "type": "string",
            "code": "string",
            "category": "string",
            "condition": "string"
          }
        ]
      }
    ]
  }
}

DataResponsePersonLicences

404

Not Found

{
  "status": 404,
  "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.",
  "developerMessage": "Could not find person with HMPPS id: 2003/0011991D."
}

PersonNotFound

500

Internal Server Error

{
  "status": 500,
  "userMessage": "Internal Server Error",
  "developerMessage": "Unable to complete request as an upstream service is not responding."
}

InternalServerError

/v1/persons/{encodedHmppsId}/images

get

Returns metadata of images associated with a person sorted by captureDateTime (newest first).

Parameters

Parameter	In	Type	Required	Description
encodedHmppsId	path	string	true	A URL-encoded HMPPS identifier
page	query	string	false	The page number (starting from 1)
perPage	query	string	false	The maximum number of results for a page

Responses

Status Description Schema

200

Successfully found a person with the provided HMPPS ID. If a person doesn’t have any images, then an empty list ([]) is returned in the data property.

{
  "data": [
    {
      "id": 2461788,
      "active": true,
      "captureDateTime": "string",
      "view": "FACE",
      "orientation": "FRONT",
      "type": "OFF_BKG"
    }
  ],
  "pagination": {
    "isLastPage": true,
    "count": 1,
    "page": 1,
    "perPage": 10,
    "totalCount": 1,
    "totalPages": 1
  }
}

PaginatedResponseImageMetadata

404

Not Found

{
  "status": 404,
  "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.",
  "developerMessage": "Could not find person with HMPPS id: 2003/0011991D."
}

PersonNotFound

500

Internal Server Error

{
  "status": 500,
  "userMessage": "Internal Server Error",
  "developerMessage": "Unable to complete request as an upstream service is not responding."
}

InternalServerError

/v1/persons/{encodedHmppsId}/case-notes

get

Returns case notes associated with a person.

Parameters

Parameter	In	Type	Required	Description
encodedHmppsId	path	string	true	A URL-encoded HMPPS identifier
startDate	query	string	false	Filter case notes from this date
endDate	query	string	false	Filter case notes up to this date
locationId	query	string	false	Filter by the location. example MDI
page	query	integer	false
perPage	query	integer	false

Responses

Status	Description	Schema
200	Successfully found case notes for a person with the provided HMPPS ID. { "data": [ { "caseNoteId": "1234", "offenderIdentifier": "A1234AA", "type": "KA", "typeDescription": "Key Worker", "subType": "KS", "subTypeDescription": "Key Worker Session", "creationDateTime": "string", "occurrenceDateTime": "string", "text": "This is some text", "locationId": "MDI", "sensitive": "boolean", "amendments": [ { "caseNoteAmendmentId": 123232, "creationDateTime": "string", "additionalNoteText": "Some Additional Text" } ] } ], "pagination": { "isLastPage": true, "count": 1, "page": 1, "perPage": 10, "totalCount": 1, "totalPages": 1 } }	PaginatedResponseCaseNote
404	Not Found `{ "status": 404, "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.", "developerMessage": "Could not find person with HMPPS id: 2003/0011991D." }`	PersonNotFound
403	Forbidden `{ "status": 403, "userMessage": "Forbidden to complete action by upstream service", "developerMessage": "Forbidden to complete action by upstream service" }`	ForbiddenResponse
500	Internal Server Error `{ "status": 500, "userMessage": "Internal Server Error", "developerMessage": "Unable to complete request as an upstream service is not responding." }`	InternalServerError

/v1/persons/{encodedHmppsId}/alerts/pnd

get

Returns alerts associated with a person, sorted by dateCreated (newest first).

Parameters

Parameter	In	Type	Required	Description
encodedHmppsId	path	string	true	A URL-encoded HMPPS identifier
page	query	string	false	The page number (starting from 1)
perPage	query	string	false	The maximum number of results for a page

Responses

Status Description Schema

200

Successfully found alerts for a person with the provided HMPPS ID.

{
  "data": [
    {
      "offenderNo": "Z1234ZZ",
      "type": "X",
      "typeDescription": "Security",
      "code": "PO",
      "codeDescription": "MAPPA Nominal",
      "comment": "Professional lock pick",
      "dateCreated": "2014-09-23",
      "dateExpired": "2015-09-23",
      "expired": true,
      "active": true
    }
  ],
  "pagination": {
    "isLastPage": true,
    "count": 1,
    "page": 1,
    "perPage": 10,
    "totalCount": 1,
    "totalPages": 1
  }
}

PaginatedResponseAlert

404

Not Found

{
  "status": 404,
  "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.",
  "developerMessage": "Could not find person with HMPPS id: 2003/0011991D."
}

PersonNotFound

500

Internal Server Error

{
  "status": 500,
  "userMessage": "Internal Server Error",
  "developerMessage": "Unable to complete request as an upstream service is not responding."
}

InternalServerError

/v1/images/{id}

get

Returns an image in bytes as a JPEG.

Parameters

Parameter	In	Type	Required	Description
id	path	integer	true

Responses

Status Description Schema

200

Successfully found an image with the provided ID.

404

Failed to find an image with the provided ID.

{
  "status": 404,
  "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.",
  "developerMessage": "Could not find person with HMPPS id: 2003/0011991D."
}

PersonNotFound

500

Internal Server Error

{
  "status": 500,
  "userMessage": "Internal Server Error",
  "developerMessage": "Unable to complete request as an upstream service is not responding."
}

InternalServerError

/v1/hmpps/reference-data

get

Returns probation and prison reference data codes descriptions for values returned by the API

Responses

Status Description Schema

200

Successfully returned prison and probation reference data.

{
  "data": {
    "prisonReferenceData": {
      "PHONE_TYPE": [
        {
          "code": "a",
          "description": "desc_a"
        }
      ],
      "ALERT_TYPE": [
        {
          "code": "a",
          "description": "desc_a"
        }
      ]
    },
    "probationReferenceData": {
      "PHONE_TYPE": [
        {
          "code": "a",
          "description": "desc_a"
        }
      ],
      "REGISTER_TYPE": [
        {
          "code": "a",
          "description": "desc_a"
        }
      ]
    }
  },
  "errors": [

  ]
}

Response

500

Internal Server Error

{
  "status": 500,
  "userMessage": "Internal Server Error",
  "developerMessage": "Unable to complete request as an upstream service is not responding."
}

InternalServerError

/v1/hmpps/id/nomis-number/by-hmpps-id/{hmppsId}

get

Return nomis number for a given HMPPS Id

  Accepts a HMPPS Id (hmppsId) and looks up the corresponding nomis number.<br>
  <b>Applicable filters</b>: <ul><li>prisons</li></ul>

Parameters

Parameter	In	Type	Required	Description
hmppsId	path	string	true

Responses

Status Description Schema

200

{
  "data": {
    "nomisNumber": "string"
  }
}

DataResponseNomisNumber

404

Nomis number could not be found.

{
  "data": {
    "nomisNumber": "string"
  }
}

DataResponseNomisNumber

400

Invalid hmppsId.

{
  "data": {
    "nomisNumber": "string"
  }
}

DataResponseNomisNumber

/v1/hmpps/id/nomis-number/{nomisNumber}

get

Return a HMPPS id for a given nomis number

Accepts a nomis number and looks up the corresponding HMPPS Id (hmppsId).

Applicable filters:

prisons

Parameters

Parameter	In	Type	Required	Description
nomisNumber	path	string	true

Responses

Status Description Schema

200

{
  "data": {
    "hmppsId": "string"
  }
}

DataResponseHmppsId

404

Nomis number could not be found.

{
  "data": {
    "hmppsId": "string"
  }
}

DataResponseHmppsId

400

Invalid hmppsId.

{
  "data": {
    "hmppsId": "string"
  }
}

DataResponseHmppsId

/v1/hmpps/id/by-nomis-number/{nomisNumber}

get

Return a HMPPS id for a given nomis number

Accepts a nomis number and looks up the corresponding HMPPS Id (hmppsId).

Applicable filters:

prisons

Parameters

Parameter	In	Type	Required	Description
nomisNumber	path	string	true

Responses

Status Description Schema

200

{
  "data": {
    "hmppsId": "string"
  }
}

DataResponseHmppsId

404

Nomis number could not be found.

{
  "data": {
    "hmppsId": "string"
  }
}

DataResponseHmppsId

400

Invalid hmppsId.

{
  "data": {
    "hmppsId": "string"
  }
}

DataResponseHmppsId

/v1/epf/person-details/{hmppsId}/{eventNumber}

get

Probation case information for the Effective Proposals Framework service

Accepts an HMPPS Id (hmppsId) and Delius Event number and returns a data structure giving background information on the probation case for use in the Effective Proposals Framework system. The information is used to reduce the need for the EPF user to re-key information already held in Delius.

Parameters

Parameter	In	Type	Required	Description
hmppsId	path	string	true
eventNumber	path	integer	true

Responses

Status Description Schema

200

{
  "data": {
    "nomsId": "string",
    "name": {
      "forename": "string",
      "middleName": "string",
      "surname": "string"
    },
    "dateOfBirth": "string",
    "gender": "string",
    "courtAppearance": {
      "date": "string",
      "court": {
        "name": "Manchester Crown Court"
      }
    },
    "sentence": {
      "date": "string",
      "sentencingCourt": {
        "name": "string"
      },
      "releaseDate": "string",
      "expectedReleaseDate": "string"
    },
    "responsibleProvider": {
      "code": "string",
      "name": "string"
    },
    "ogrsScore": "integer",
    "rsrScore": "number",
    "age": "integer",
    "ageAtRelease": "integer"
  },
  "errors": [
    {
      "causedBy": "string",
      "type": "string",
      "description": "string"
    }
  ]
}

ResponseCaseDetail

404

Not Found

{
  "status": 404,
  "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.",
  "developerMessage": "Could not find person with HMPPS id: 2003/0011991D."
}

PersonNotFound

500

Internal Server Error

{
  "status": 500,
  "userMessage": "Internal Server Error",
  "developerMessage": "Unable to complete request as an upstream service is not responding."
}

InternalServerError

/v1/contacts/{contactId}

get

Returns a contact by ID.

Parameters

Parameter	In	Type	Required	Description
contactId	path	string	true

Responses

Status	Description	Schema
200	Successfully found contact by contact ID. { "data": { "contactId": 123456, "titleCode": "MR", "titleDescription": "Mr", "lastName": "Doe", "firstName": "John", "middleNames": "William", "dateOfBirth": "1980-01-01", "isStaff": "boolean", "deceasedDate": "1980-01-01", "languageCode": "ENG", "languageDescription": "English", "interpreterRequired": true, "addresses": [ { "addressType": "HOME", "addressTypeDescription": "string", "primaryAddress": true, "flat": "Flat 2B", "property": "Mansion House", "street": "Acacia Avenue", "area": "Morton Heights", "cityCode": "25343", "cityDescription": "Sheffield", "countyCode": "S.YORKSHIRE", "countyDescription": "South Yorkshire", "postcode": "S13 4FH", "countryCode": "ENG", "countryDescription": "England", "verified": "boolean", "verifiedBy": "NJKG44D", "verifiedTime": "2024-01-01T00:00:00Z", "mailFlag": "boolean", "startDate": "2024-01-01", "endDate": "2024-01-01", "noFixedAddress": "boolean", "comments": "Some additional information", "phoneNumbers": [ { "phoneType": "MOB", "phoneTypeDescription": "Mobile", "phoneNumber": "+1234567890", "extNumber": "123" } ], "createdBy": "JD000001", "createdTime": "2024-01-01T00:00:00Z", "updatedBy": "JD000001", "updatedTime": "2024-01-01T00:00:00Z" } ], "phoneNumbers": [ { "phoneType": "MOB", "phoneTypeDescription": "Mobile", "phoneNumber": "+1234567890", "extNumber": "123" } ], "emailAddresses": [ { "emailAddress": "test@example.com" } ], "genderCode": "string", "genderDescription": "string" }, "errors": [ { "causedBy": "string", "type": "string", "description": "string" } ] }	ResponseDetailedContact
400	The contact is in invalid format. `{ "status": 400, "userMessage": "Validation failure: No query parameters specified.", "developerMessage": "No query parameters specified." }`	BadRequest
404	Not Found `{ "status": 404, "userMessage": "404 Not found error: Could not find person with HMPPS id: 2003/0011991D.", "developerMessage": "Could not find person with HMPPS id: 2003/0011991D." }`	PersonNotFound
500	Internal Server Error `{ "status": 500, "userMessage": "Internal Server Error", "developerMessage": "Unable to complete request as an upstream service is not responding." }`	InternalServerError

/queue-admin/get-dlq-messages/{dlqName}

get

Parameters

Parameter	In	Type	Required	Description
dlqName	path	string	true
maxMessages	query	integer	false

Responses

Status Description Schema

200

{
  "messagesFoundCount": "integer",
  "messagesReturnedCount": "integer",
  "messages": [
    {
      "body": {
      },
      "messageId": "string"
    }
  ]
}

GetDlqResult

Schemas

ResponseUnit

Name	Type	Required	Description	Schema
data	object	true		Unit
errors	array	true		UpstreamApiError

Unit

UpstreamApiError

Name	Type	Required
causedBy	string	true
type	string	true
description	string	false

RetryDlqResult

Name	Type	Required	Description	Schema
messagesFoundCount	integer	true

PurgeQueueResult

Name	Type	Required	Description	Schema
messagesFoundCount	integer	true

TransactionRequest

Name	Type	Required	Description
type	string	true	Transaction type. Determines which accounts will be debited and credited.
description	string	false	Description of the transaction.
amount	integer	true	Amount of money in pence, must be positive. Whether the transaction is a credit or debit is determined by the type.
clientTransactionId	string	true	Client Transaction ID.
clientUniqueRef	string	true	A reference unique to the client making the post. Maximum size 64 characters, only alphabetic, numeric, ‘-’ and ‘_’ are allowed.

DataResponseTransactionCreateResponse

Name	Type	Required	Description	Schema
data	object	true		TransactionCreateResponse

TransactionCreateResponse

Name	Type	Required	Description	Schema
transactionId	string	true

TransactionTransferRequest

Name	Type	Required	Description
description	string	true	Description of the transaction.
amount	integer	true	Amount of money in pence, must be positive.
clientTransactionId	string	true	Client Transaction Id.
clientUniqueRef	string	true	A reference unique to the client making the post. Maximum size 64 characters, only alphabetic, numeric, ‘-’ and ‘_’ are allowed.
fromAccount	string	true	The account to move money from. Must be ‘spends’.
toAccount	string	true	The account to move money to. Must be ‘savings’.

DataResponseTransactionTransferCreateResponse

Name	Type	Required	Description	Schema
data	object	true		TransactionTransferCreateResponse

TransactionTransferCreateResponse

Name	Type	Required	Description
debitTransactionId	string	true	Transaction id for the debit portion of the transaction.
creditTransactionId	string	true	Transaction id for the credit portion of the transaction.
transactionId	string	true	Transaction id for the whole transaction.

DataResponseVisit

Name	Type	Required	Description	Schema
data	object	true		Visit

Visit

Name	Type	Required	Description	Schema
applicationReference	string	false	Application Reference
reference	string	false	Visit Reference
prisonerId	string	true	Prisoner Id
prisonId	string	true	Prison Id
prisonName	string	true	Prison Name
sessionTemplateReference	string	false	Session Template Reference
visitRoom	string	true	Location of Visit
visitType	string	true	Type of Visit
visitStatus	string	true	Visit Status
outcomeStatus	string	false	Outcome Status of Visit
visitRestriction	string	true	Visit Restriction
startTimestamp	string	true	The date and time of the visit
endTimestamp	string	true	The finishing date and time of the visit
visitNotes	array	true	Visit Notes	VisitNotes
visitContact	object	true	Contact associated with the visit	VisitContact
visitors	array	true	List of visitors associated with the visit	Visitors
visitorSupport	object	true	Additional support associated with the visit	VisitorSupport
createdTimestamp	string	true	The visit created date and time
modifiedTimestamp	string	true	The visit modified date and time
firstBookedDateTime	string	true	Date the visit was first booked or migrated

VisitContact

Contact associated with the visit

Name	Type	Required	Description
name	string	true	Contact name
telephone	string	true	Contact Phone Number
email	string	true	Contact Email Address

VisitNotes

Visit Notes

Name	Type	Required	Description	Schema
type	string	true	Note type
text	string	true	Note Text

VisitorSupport

Additional support associated with the visit

Name	Type	Required	Description	Schema
description	string	true	Support text description

Visitors

List of visitors associated with the visit

Name	Type	Required	Description	Schema
contactId	integer	true	Person ID (nomis) of the visitor
visitContact	boolean	false	true if visitor is the contact for the visit otherwise false

PaginatedResponseVisit

Name	Type	Required	Description	Schema
data	array	true		Visit
pagination	object	true		Pagination

Pagination

Name	Type	Required	Description
isLastPage	boolean	true	Is the current page the last one?
count	integer	true	The number of results in `data` for the current page
page	integer	true	The current page number
perPage	integer	true	The maximum number of results in `data` for a page
totalCount	integer	true	The total number of results in `data` across all pages
totalPages	integer	true	The total number of pages

DataResponseTransaction

Name	Type	Required	Description	Schema
data	object	true		Transaction

Transaction

Name	Type	Required	Schema
id	string	true
type	object	true	Type
description	string	true
amount	integer	true
date	string	true

Type

Name	Type	Required	Description	Schema
code	string	true
desc	string	true

DataResponseNonAssociations

Name	Type	Required	Description	Schema
data	object	true		NonAssociations

NonAssociation

List of non-associations

Name	Type	Required	Description	Schema
id	integer	true	The ID of the non association
role	string	true	The prisoner’s role code in the non-association
roleDescription	string	true	The description of the prisoner’s role in the non-association
reason	string	true	The reason code why these prisoners should be kept apart
reasonDescription	string	true	The reason description why these prisoners should be kept apart
restrictionType	string	true	Location-based restriction code
restrictionTypeDescription	string	true	Location-based restriction description
comment	string	true	Explanation of why prisoners are non-associated
authorisedBy	string	true	User ID of the person who created the non-association.
whenCreated	string	true	When the non-association was created
whenUpdated	string	true	When the non-association was last updated
updatedBy	string	true	User ID of the person who last updated the non-association
isClosed	boolean	true	Whether the non-association is closed or is in effect
closedBy	string	false	User ID of the person who closed the non-association. Only present when the non-association is closed, null for open non-associations
closedReason	string	false	Reason why the non-association was closed. Only present when the non-association is closed, null for open non-associations
closedAt	string	false	Date and time of when the non-association was closed. Only present when the non-association is closed, null for open non-associations
otherPrisonerDetails	object	true	Details about the other person in the non-association.	NonAssociationPrisonerDetails
isOpen	boolean	true	Whether the non-association is open or closed

NonAssociationPrisonerDetails

Details about the other person in the non-association.

Name	Type	Required	Description
prisonerNumber	string	true	Prisoner number
role	string	true	Other prisoner’s role code in the non-association
roleDescription	string	true	Other prisoner’s role description in the non-association
firstName	string	true	First name
lastName	string	true	Last name
prisonId	string	true	ID of the prison
prisonName	string	true	Name of the prison
cellLocation	string	true	Cell the prisoner is assigned to

NonAssociations

Name	Type	Required	Description	Schema
nonAssociations	array	true	List of non-associations	NonAssociation

AccountBalance

Name	Type	Required	Description	Schema
accountCode	string	true
amount	integer	true

Balances

Name	Type	Required	Description	Schema
balances	array	true		AccountBalance

DataResponseBalances

Name	Type	Required	Description	Schema
data	object	true		Balances

DataResponseTransactions

Name	Type	Required	Description	Schema
data	object	true		Transactions

Transactions

Name	Type	Required	Description	Schema
transactions	array	true		Transaction

Balance

Name	Type	Required	Description	Schema
balance	object	true		AccountBalance

DataResponseBalance

Name	Type	Required	Description	Schema
data	object	true		Balance

Alias

Name	Type	Required	Description
firstName	string	true	first name
lastName	string	true	last name
middleName	string	false	last name
dateOfBirth	string	false	date of birth
gender	string	false	gender
ethnicity	string	false	ethnicity

Identifiers

Other unique identifiers for a person.

Name	Type	Required	Description
nomisNumber	string	false	A prisoner identifier from NOMIS.
croNumber	string	false	A Criminal Records Office identifier from National Identification Service (NIS) or National Automated Fingerprint Identification System (NAFIS).
deliusCrn	string	false	A Case Reference Number from Delius.

PaginatedResponsePersonInPrison

Name	Type	Required	Description	Schema
data	array	true		PersonInPrison
pagination	object	true		Pagination

PersonInPrison

Name	Type	Required	Description	Schema
firstName	string	true	First name
lastName	string	true	Last name
middleName	string	false	Middle name
dateOfBirth	string	false	Date of birth
gender	string	false	Gender
ethnicity	string	false	Ethnicity
aliases	array	true		Alias
identifiers	object	true	Other unique identifiers for a person.	Identifiers
pncId	string	false	An identifier from the Police National Computer (PNC)
category	string	false	Category
csra	string	false	Cell sharing risk assessment
receptionDate	string	false	Date prisoner was received into the prison
status	string	false	Status of the prisoner
prisonId	string	false	Prison ID
prisonName	string	false	Name of the prison
cellLocation	string	false	In prison cell location

DataResponsePersonInPrison

Name	Type	Required	Description	Schema
data	object	true		PersonInPrison

Alert

Name	Type	Required	Description
offenderNo	string	false	Offender unique reference
type	string	false	Alert type
typeDescription	string	false	Alert type description
code	string	false	Alert code
codeDescription	string	false	Alert code description
comment	string	false	Alert comment
dateCreated	string	false	Date of the alert, which might differ from the date it was created
dateExpired	string	false	Date that the alert expires
expired	boolean	false	Whether the alert has expired
active	boolean	false	Whether the alert is active

PaginatedResponseAlert

Name	Type	Required	Description	Schema
data	array	true		Alert
pagination	object	true		Pagination

ContactDetailsWithEmailAndPhone

Name	Type	Required	Description	Schema
phoneNumbers	array	false		PhoneNumber
emails	array	false	A list of email addresses

PaginatedResponsePerson

Name	Type	Required	Description	Schema
data	array	true		Person
pagination	object	true		Pagination

Person

Name	Type	Required	Description	Schema
firstName	string	true	First name
lastName	string	true	Last name
middleName	string	false	Middle name
dateOfBirth	string	false	Date of birth
gender	string	false	Gender
ethnicity	string	false	Ethnicity
aliases	array	true		Alias
identifiers	object	true	Other unique identifiers for a person.	Identifiers
pncId	string	false	An identifier from the Police National Computer (PNC)
hmppsId	string	false	HMPPS identifier
contactDetails	object	false		ContactDetailsWithEmailAndPhone
currentRestriction	boolean	false
restrictionMessage	string	false
currentExclusion	boolean	false
exclusionMessage	string	false

PhoneNumber

Name	Type	Required	Description	Schema
number	string	false	A phone number
type	string	false	The type of number

ContactRestriction

Global (estate-wide) restrictions for the contact

Name	Type	Required	Description
restrictionType	string	true	The restriction code
restrictionTypeDescription	string	true	The description of the restriction type
startDate	string	true	Restriction created date
expiryDate	string	true	Restriction expiry date
comments	string	true	Comments for the restriction
enteredByUsername	string	true	The username of either the person who created the restriction or the last person to update it if it has been modified
enteredByDisplayName	string	true	The display name of either the person who created the restriction or the last person to update it if it has been modified
createdBy	string	true	User who created the entry
createdTime	string	true	Timestamp when the entry was created
updatedBy	string	true	User who updated the entry
updatedTime	string	true	Timestamp when the entry was updated

DataResponsePrisonerContactRestrictions

Name	Type	Required	Description	Schema
data	object	true		PrisonerContactRestrictions

PrisonerContactRestrictions

Name	Type	Required	Description	Schema
prisonerContactRestrictions	array	true	Relationship specific restrictions	ContactRestriction
contactGlobalRestrictions	array	true	Global (estate-wide) restrictions for the contact	ContactRestriction

DataResponseListVisit

Name	Type	Required	Description	Schema
data	array	true		Visit

DataResponseListPersonVisitRestriction

Name	Type	Required	Description	Schema
data	array	true		PersonVisitRestriction

PersonVisitRestriction

Name	Type	Required	Description
restrictionId	integer	true	Restriction ID
comment	string	true	Restriction comment text
restrictionType	string	true	Code of restriction type
restrictionTypeDescription	string	true	Description of restriction type
startDate	string	true	Date from which the restrictions applies
expiryDate	string	false	Date restriction applies to, or indefinitely if null
active	boolean	true	True if restriction is within the start date and optional expiry date range

DataResponseVisitOrders

Name	Type	Required	Description	Schema
data	object	true		VisitOrders

VisitOrders

Name	Type	Required	Description	Schema
remainingVisitOrders	integer	true	The prisoners remaining visit orders
remainingPrivilegeVisitOrders	integer	true	The prisoners remaining privilege visit orders

PaginatedResponseSentence

Name	Type	Required	Description	Schema
data	array	true		Sentence
pagination	object	true		Pagination

Sentence

Name	Type	Required	Description	Schema
serviceSource	string	true	Which upstream API service the sentence originates from. Possible values are: `NOMIS`, `NDELIUS`
systemSource	string	true	Which upstream API system the sentence originates from. Possible values are: `PRISON_SYSTEMS`, `PROBATION_SYSTEMS`
dateOfSentencing	string	false	Date of sentencing
description	string	false	Description of the sentence
isActive	boolean	false	Whether the sentence is active
isCustodial	boolean	true	Whether the sentence is custodial
fineAmount	number	false	The amount of fine related to the sentence and offence
length	object	true		SentenceLength

SentenceLength

Name	Type	Required	Description	Schema
duration	integer	false	Duration of the sentence
units	string	false	Time unit that is used in combination with the duration field. Possible values are: `Hours`, `Days`, `Weeks`, `Months`, `Years`
terms	array	true		SentenceTerm

SentenceTerm

Name	Type	Required	Description
years	integer	false	Number of years in the term
months	integer	false	Number of months in the term
weeks	integer	false	Number of weeks in the term
days	integer	false	Number of days in the term
hours	integer	false	Number of hours in the term
prisonTermCode	string	false	The sentence term code Possible values are: `CUR` - Curfew Period, `DEF` - Deferment Period, `DET` - Detention, `HOURS` - Hours Ordered, `IMP` - Imprisonment, `LIC` - Licence, `PSYCH` - Psychiatric Hospital, `SCUS` - Custodial Period, `SEC104` - Breach of supervision requirements, `SEC105` - Breach due to imprisonable offence, `SEC86` - Section 86 of 2000 Act, `SUP` - Sentence Length, `SUSP` - Suspension Period

DataResponseRiskCategory

Name	Type	Required	Description	Schema
data	object	true		RiskCategory

RiskAssessment

Name	Type	Required	Description
classificationCode	string	false	The classification code of the risk
classification	string	false	The classification of the code
assessmentCode	string	false	The assessment code
assessmentDescription	string	false	The description of the assessment
assessmentDate	string	false	The date of the assessment
nextReviewDate	string	false	Next review date
assessmentAgencyId	string	false	Agency ID of the assessment
assessmentStatus	string	false	The status of the assessment
assessmentComment	string	false	Comments regarding the assessment

RiskCategory

Name	Type	Required	Schema
offenderNo	string	false
assessments	array	true	RiskAssessment
category	string	false
categoryCode	string	false

Adjudication

Name	Type	Required	Schema
incidentDetails	object	false	IncidentDetailsDto
isYouthOffender	boolean	false
incidentRole	object	false	IncidentRoleDto
offenceDetails	object	false	OffenceDto
status	string	false
statusReason	string	false
statusDetails	string	false
hearings	array	false	HearingDto
outcomes	array	false	OutcomeHistoryDto
punishments	array	false	PunishmentDto
punishmentComments	array	false	PunishmentCommentDto

CombinedOutcomeDto

Name	Type	Required	Description	Schema
outcome	object	false		OutcomeDto
referralOutcome	object	false		OutcomeDto

HearingDto

Name	Type	Required	Schema
dateTimeOfHearing	string	false
oicHearingType	string	false
outcome	object	false	HearingOutcomeDto

HearingOutcomeDto

Name	Type	Required
code	string	false
reason	string	false
details	string	false
plea	string	false

IncidentDetailsDto

Name	Type	Required	Description	Schema
dateTimeOfIncident	string	false

IncidentRoleDto

Name	Type	Required	Description	Schema
roleCode	string	false
offenceRule	object	false		OffenceRuleDetailsDto

OffenceDto

Name	Type	Required	Description	Schema
offenceCode	number	false
offenceRule	object	false		OffenceRuleDto

OffenceRuleDetailsDto

Name	Type	Required	Description	Schema
paragraphNumber	string	false
paragraphDescription	string	false

OffenceRuleDto

Name	Type	Required	Description	Schema
paragraphNumber	string	false
paragraphDescription	string	false

OutcomeDto

Name	Type	Required
code	string	false
details	string	false
reason	string	false
quashedReason	string	false
canRemove	boolean	false

OutcomeHistoryDto

Name	Type	Required	Description	Schema
hearing	object	false		HearingDto
outcome	object	false		CombinedOutcomeDto

PaginatedResponseAdjudication

Name	Type	Required	Description	Schema
data	array	true		Adjudication
pagination	object	true		Pagination

PunishmentCommentDto

Name	Type	Required
comment	string	false
reasonForChange	string	false
dateTime	string	false

PunishmentDto

Name	Type	Required	Schema
type	string	false
privilegeType	string	false
otherPrivilege	string	false
schedule	object	false	PunishmentScheduleDto

PunishmentScheduleDto

Name	Type	Required
days	number	false
startDate	string	false
endDate	string	false
suspendedUntil	string	false

DataResponsePersonProtectedCharacteristics

Name	Type	Required	Description	Schema
data	object	true		PersonProtectedCharacteristics

Disability

Name	Type	Required	Schema
disabilityType	object	false	KeyValue
condition	object	false	KeyValue
startDate	string	false
endDate	string	false
notes	string	false

KeyValue

Name	Type	Required	Description	Schema
code	string	false
description	string	false

PersonProtectedCharacteristics

Name	Type	Required	Description	Schema
age	number	true	Age of the person
gender	string	false	Gender of the person
sexualOrientation	string	false	Sexual orientation of the person
ethnicity	string	false	Ethnicity of the person
nationality	string	false	Nationality of the person
religion	string	false	Religion of the person
disabilities	array	true		Disability
maritalStatus	string	false	Marital status of the person
reasonableAdjustments	array	true		ReasonableAdjustment

ReasonableAdjustment

Name	Type	Required	Description
treatmentCode	string	false	Treatment code
commentText	string	false	Comment text
startDate	string	false	Start date
endDate	string	false	End date
treatmentDescription	string	false	Treatment description

DataResponseReviewSchedules

Name	Type	Required	Description	Schema
data	object	true		ReviewSchedules

ReviewSchedule

   A list of review schedules for this prisoner.
   Note that this will return multiple versions of the the same schedule.
   This is because down stream clients need to know the previous states of the review schedules.
   grouping by reference and then ordering by highest version number will present the review schedules with the most up to date data.

Name	Type	Required	Description
nomisNumber	string	false	The Nomis number of the person.
reference	string	true	The UUID reference for the review schedule record.
reviewDateFrom	string	true	The earliest date that the review should be carried out.
reviewDateTo	string	true	The latest date that the review should be carried out.
status	string	true	The status of this review schedule possible values are: SCHEDULED EXEMPT_PRISONER_DRUG_OR_ALCOHOL_DEPENDENCY EXEMPT_PRISONER_OTHER_HEALTH_ISSUES EXEMPT_PRISONER_FAILED_TO_ENGAGE EXEMPT_PRISONER_ESCAPED_OR_ABSCONDED EXEMPT_PRISONER_SAFETY_ISSUES EXEMPT_PRISON_REGIME_CIRCUMSTANCES EXEMPT_PRISON_STAFF_REDEPLOYMENT EXEMPT_PRISON_OPERATION_OR_SECURITY_ISSUE EXEMPT_SECURITY_ISSUE_RISK_TO_STAFF EXEMPT_SYSTEM_TECHNICAL_ISSUE EXEMPT_PRISONER_TRANSFER EXEMPT_PRISONER_RELEASE EXEMPT_PRISONER_DEATH EXEMPT_PRISONER_MERGE EXEMPT_UNKNOWN COMPLETED
calculationRule	string	true	`The calculation rule that was used to workout the review schedule window. Possible values are: PRISONER_READMISSION PRISONER_TRANSFER BETWEEN_RELEASE_AND_3_MONTHS_TO_SERVE BETWEEN_3_MONTHS_AND_3_MONTHS_7_DAYS_TO_SERVE BETWEEN_3_MONTHS_8_DAYS_AND_6_MONTHS_TO_SERVE BETWEEN_6_AND_12_MONTHS_TO_SERVE BETWEEN_12_AND_60_MONTHS_TO_SERVE MORE_THAN_60_MONTHS_TO_SERVE INDETERMINATE_SENTENCE PRISONER_ON_REMAND PRISONER_UN_SENTENCED`
createdBy	string	true
createdByDisplayName	string	true
createdAt	string	true
createdAtPrison	string	true
updatedBy	string	true
updatedByDisplayName	string	true
updatedAt	string	true
updatedAtPrison	string	true
version	integer	true	`The review schedule can change status numerous times. The version number indicates which version of the review schedule this one is, the higher the number the newer the update. use the version number in conjunction with the reference UUID. ie if you group the schedules by reference then the version numbers represent different versions of the same schedule. The final status of each grouping is COMPLETED.`
reviewCompletedBy	string	false	When the review schedule has a completed review this will be populated by the name of the person who did the review.
reviewCompletedByRole	string	false	When the review schedule has a completed review this will be populated by the role of the person who did the review.
reviewCompletedAt	string	false	When the review schedule has a completed review this will be populated with the date that the CIAG entered into the system when completing the Review. It is the date that the user did the Review in person, rather than the date that it was entered into the system..
reviewType	string	false	`When the review schedule has a completed review this will be populated with the type of the review. values are: REGULAR, PRE_RELEASE`
reviewReason	string	false	`When the review schedule has a completed review this will be populated with the reason for the review. values are: REOFFENCE, TRANSFER, REGULAR`

ReviewSchedules

Name Type Required Description Schema

reviewSchedules

array

true

   A list of review schedules for this prisoner.
   Note that this will return multiple versions of the the same schedule.
   This is because down stream clients need to know the previous states of the review schedules.
   grouping by reference and then ordering by highest version number will present the review schedules with the most up to date data.

ReviewSchedule

DataResponseInductionSchedule

Name	Type	Required	Description	Schema
data	object	true		InductionSchedule

InductionSchedule

Name	Type	Required	Description
deadlineDate	string	false	An ISO-8601 date representing when the Induction should be completed by.
status	string	false	The current status of the Induction Schedule. list of values: SCHEDULED COMPLETED EXEMPT_PRISONER_DRUG_OR_ALCOHOL_DEPENDENCY EXEMPT_PRISONER_OTHER_HEALTH_ISSUES EXEMPT_PRISONER_FAILED_TO_ENGAGE EXEMPT_PRISONER_ESCAPED_OR_ABSCONDED EXEMPT_PRISONER_SAFETY_ISSUES EXEMPT_PRISON_REGIME_CIRCUMSTANCES EXEMPT_PRISON_STAFF_REDEPLOYMENT EXEMPT_PRISON_OPERATION_OR_SECURITY_ISSUE EXEMPT_SECURITY_ISSUE_RISK_TO_STAFF EXEMPT_SYSTEM_TECHNICAL_ISSUE EXEMPT_PRISONER_TRANSFER EXEMPT_PRISONER_RELEASE EXEMPT_PRISONER_DEATH EXEMPT_SCREENING_AND_ASSESSMENT_IN_PROGRESS EXEMPT_SCREENING_AND_ASSESSMENT_INCOMPLETE EXEMPT_PRISONER_MERGE
calculationRule	string	false	`The Induction Schedule rule used to determine deadline date. list of values are: NEW_PRISON_ADMISSION EXISTING_PRISONER_LESS_THAN_6_MONTHS_TO_SERVE EXISTING_PRISONER_BETWEEN_6_AND_12_MONTHS_TO_SERVE EXISTING_PRISONER_BETWEEN_12_AND_60_MONTHS_TO_SERVE EXISTING_PRISONER_INDETERMINATE_SENTENCE EXISTING_PRISONER_ON_REMAND EXISTING_PRISONER_UN_SENTENCED`
nomisNumber	string	false	The Nomis number of the person.
systemCreatedBy	string	false	The name of the person who used the PLP system to create the Induction Schedule, or ‘system’ for system generated updates.
systemCreatedAt	string	false	An ISO-8601 timestamp representing the time the PLP system was used to create the Induction Schedule.
systemCreatedAtPrison	string	false	The code of the prison where the induction was Created
systemUpdatedBy	string	false	`The name of the person who performed the Induction with the prisoner. In the case of system generated updates or setting an exemption this field will not be present.`
systemUpdatedAt	string	false	An ISO-8601 timestamp representing the time the PLP system was used to update the Induction Schedule.
systemUpdatedAtPrison	string	false	The code of the prison where the induction was updated
inductionPerformedBy	string	false	`The name of the person who performed the Induction with the prisoner. In the case of system generated updates or setting an exemption this field will not be present.`
inductionPerformedAt	string	false	`When the induction schedule has a completed induction this will be populated with the date that the CIAG entered into the system when completing the Induction. It is the date that the user did the Induction in person, rather than the date that it was entered into the system.`
inductionPerformedByRole	string	false	`The role of the person who performed the Induction with the prisoner. In the case of system generated updates or setting an exemption this field will not be present.`
inductionPerformedAtPrison	string	false	The prison code that the induction was performed at.
exemptionReason	string	false	If reason the induction schedule was exempted.
version	integer	false	`The induction schedule can change status numerous times. When looking at the plp-induction-schedule/history of the inductions. The version number indicates which version of the induction schedule this one is, the higher the number the newer the update.`

DataResponseInductionSchedules

Name	Type	Required	Description	Schema
data	object	true		InductionSchedules

InductionSchedules

Name Type Required Description Schema

inductionSchedules

array

true

   A list of induction schedule versions for this prisoner.
   The prisoner will only have one induction schedule but for various reasons the schedule can be updated.
   This list will show each change the schedule has been through. This allows for reports to be generated.

InductionSchedule

DataResponsePersonName

Name	Type	Required	Description	Schema
data	object	true		PersonName

PersonName

Name	Type	Required	Description	Schema
firstName	string	false
lastName	string	false

DataResponseIEPLevel

Name	Type	Required	Description	Schema
data	object	true		IEPLevel

IEPLevel

Name	Type	Required	Description	Schema
iepCode	string	true	Incentive Level Code
iepLevel	string	true	Incentive Level

Contact

The details of a contact as an individual

Name	Type	Required	Description
contactId	integer	true	The ID of the contact
lastName	string	true	The last name of the contact
firstName	string	true	The first name of the contact
middleNames	string	false	The middle names of the contact, if any
dateOfBirth	string	true	The date of birth of the contact, if known
flat	string	false	Flat number or name
property	string	false	Building or house number or name
street	string	false	Street or road name
area	string	false	Area
cityCode	string	false	City code
cityDescription	string	false	The description of the city code
countyCode	string	false	County code
countyDescription	string	false	The description of county code
postCode	string	false	Postcode
countryCode	string	false	Country code
countryDescription	string	false	The description of country code
primaryAddress	boolean	false	True if this is the primary address otherwise false
mailAddress	boolean	false	If true this address should be considered for sending mail to
phoneType	string	true	Type of phone
phoneTypeDescription	string	true	Description of the type of phone
phoneNumber	string	true	Phone number
extNumber	string	false	Extension number

PaginatedResponsePrisonerContact

Name	Type	Required	Description	Schema
data	array	true		PrisonerContact
pagination	object	true		Pagination

PrisonerContact

Name	Type	Required	Description	Schema
contact	object	true	The details of a contact as an individual	Contact
relationship	object	true	The details of the relationship between the prisoner and this contact	PrisonerContactRelationship

PrisonerContactRelationship

The details of the relationship between the prisoner and this contact

Name	Type	Required	Description
relationshipTypeCode	string	false	Coded value indicating either a social or official contact. This is a coded value from the group code CONTACT_TYPE in reference data
relationshipTypeDescription	string	false	The description of the relationship type
relationshipToPrisonerCode	string	false	The relationship to the prisoner. A code from SOCIALRELATIONSHIP or OFFICIALRELATIONSHIP reference data groups depending on the relationship type
relationshipToPrisonerDescription	string	false	The description of the relationship to the prisoner
approvedVisitor	boolean	false	Indicates whether the contact is an approved visitor
nextOfKin	boolean	false	Is this contact the prisoner’s next of kin?
emergencyContact	boolean	false	Is this contact the prisoner’s emergency contact?
isRelationshipActive	boolean	false	Is this contact the prisoner’s next of kin?
currentTerm	boolean	false	Is this relationship active for the current booking?
comments	string	false	Any additional comments

CellLocation

Name	Type	Required
prisonCode	string	false
prisonName	string	false
cell	string	false

DataResponseCellLocation

Name	Type	Required	Description	Schema
data	object	true		CellLocation

Address

Name	Type	Required	Description	Schema
country	string	false
county	string	false
endDate	string	false
locality	string	false
name	string	false
noFixedAddress	boolean	true	Indicates whether the person has a permanent place of residence
number	string	false
postcode	string	false
startDate	string	false
street	string	false
town	string	false
types	array	true		Type
notes	string	false

DataResponseListAddress

Name	Type	Required	Description	Schema
data	array	true		Address

DataResponseOffenderSearchResponse

Name	Type	Required	Description	Schema
data	object	true		OffenderSearchResponse

OffenderSearchResponse

Name	Type	Required	Description	Schema
prisonerOffenderSearch	object	false		Person
probationOffenderSearch	object	false		PersonOnProbation

PersonOnProbation

Name	Type	Required	Description	Schema
person	object	false		Person
underActiveSupervision	boolean	true
firstName	string	true
lastName	string	true
middleName	string	false
dateOfBirth	string	false
gender	string	false
ethnicity	string	false
aliases	array	true		Alias
identifiers	object	true	Other unique identifiers for a person.	Identifiers
pncId	string	false
hmppsId	string	false
contactDetails	object	false		ContactDetailsWithEmailAndPhone
currentRestriction	boolean	false
restrictionMessage	string	false
currentExclusion	boolean	false
exclusionMessage	string	false

PaginatedResponseStatusInformation

Name	Type	Required	Description	Schema
data	array	true		StatusInformation
pagination	object	true		Pagination

StatusInformation

Name	Type	Required
code	string	false
description	string	false
startDate	string	false
reviewDate	string	false
notes	string	false

DataResponseLatestSentenceKeyDatesAndAdjustments

Name	Type	Required	Description	Schema
data	object	true		LatestSentenceKeyDatesAndAdjustments

HomeDetentionCurfewDate

Name	Type	Required
actualDate	string	false
eligibilityCalculatedDate	string	false
eligibilityDate	string	false
eligibilityOverrideDate	string	false
endDate	string	false

LatestSentenceKeyDatesAndAdjustments

Name	Type	Required	Description	Schema
adjustments	object	false		SentenceAdjustment
automaticRelease	object	false		SentenceKeyDate
conditionalRelease	object	false		SentenceKeyDate
dtoPostRecallRelease	object	false		SentenceKeyDate
earlyTerm	object	false		SentenceKeyDateWithCalculatedDate
homeDetentionCurfew	object	false		HomeDetentionCurfewDate
lateTerm	object	false		SentenceKeyDateWithCalculatedDate
licenceExpiry	object	false		SentenceKeyDateWithCalculatedDate
midTerm	object	false		SentenceKeyDateWithCalculatedDate
nonDto	object	false		NonDtoDate
nonParole	object	false		SentenceKeyDate
paroleEligibility	object	false		SentenceKeyDateWithCalculatedDate
postRecallRelease	object	false		SentenceKeyDate
release	object	false		ReleaseDate
sentence	object	false		SentenceDate
topupSupervision	object	false		TopupSupervision
actualParoleDate	string	false	the offender’s actual parole date
earlyRemovalSchemeEligibilityDate	string	false	the date on which offender will be eligible for early removal (under the Early Removal Scheme for foreign nationals).
releaseOnTemporaryLicenceDate	string	false	the date on which offender will be released on temporary licence.
tariffDate	string	false	date on which minimum term is reached for parole (indeterminate/life sentences).
tariffEarlyRemovalSchemeEligibilityDate	string	false	tariffEarlyRemovalSchemeEligibilityDate.

NonDtoDate

Name	Type	Required	Description	Schema
date	string	false	Release date for non-DTO sentence (if applicable). This will be based on one of ARD, CRD, NPD or PRRD. NonDto stands for Non-Detention training order.
releaseDateType	string	false	Indicates which type of non-DTO release date is the effective release date. One of 'ARD', 'CRD', 'NPD' or 'PRRD'. Possible values are: `ARD`, `CRD`, `NPD`, `PRRD`.

ReleaseDate

Name Type Required Description Schema

date

string

false

  Confirmed, actual, approved, provisional or calculated release date for offender, according to offender release date algorithm.

  Algorithm
  If there is a confirmed release date, the offender release date is the confirmed release date.
  If there is no confirmed release date for the offender, the offender release date is either the actual parole date or the home detention curfew actual date.
  If there is no confirmed release date, actual parole date or home detention curfew actual date for the offender, the release date is the later of the nonDtoReleaseDate or midTermDate value (if either or both are present)

confirmedDate

string

false

Confirmed release date for offender.

SentenceAdjustment

Name	Type	Required	Description
additionalDaysAwarded	number	false	Number of additional days awarded
unlawfullyAtLarge	number	false	Number unlawfully at large days
lawfullyAtLarge	number	false	Number of lawfully at large days
restoredAdditionalDaysAwarded	number	false	Number of restored additional days awarded
specialRemission	number	false	Number of special remission days
recallSentenceRemand	number	false	Number of recall sentence remand days
recallSentenceTaggedBail	number	false	Number of recall sentence tagged bail days
remand	number	false	Number of remand days
taggedBail	number	false	Number of tagged bail days
unusedRemand	number	false	Number of unused remand days

SentenceDate

Name	Type	Required	Description
effectiveEndDate	string	false	Effective sentence end date.
expiryCalculatedDate	string	false	date on which sentence expired (as calculated by NOMIS).
expiryDate	string	false	date on which sentence expires.
expiryOverrideDate	string	false	date on which sentence expires (override).
startDate	string	false	Sentence start date.

SentenceKeyDate

Name	Type	Required	Description	Schema
date	string	false	release date for offender
overrideDate	string	false	release override date for offender

SentenceKeyDateWithCalculatedDate

Name	Type	Required	Description
date	string	false	release date for offender
overrideDate	string	false	release override date for offender
calculatedDate	string	false	release calculated date for offender

TopupSupervision

Name	Type	Required	Description
expiryCalculatedDate	string	false	(calculated) - top-up supervision expiry date for offender.
expiryDate	string	false	top-up supervision expiry date for offender.
expiryOverrideDate	string	false	(override) - top-up supervision expiry date for offender.
startDate	string	false	Top-up supervision start date for offender - calculated as licence end date + 1 day or releaseDate if licence end date not set.

DataResponseRisks

Name	Type	Required	Description	Schema
data	object	true		Risks

OtherRisks

Name	Type	Required	Description
escapeOrAbscond	string	false	Risk of escape/abscond. Possible values are: `YES`, `NO`, `DK`, `NA`
controlIssuesDisruptiveBehaviour	string	false	Risk control issues/disruptive behaviour. Possible values are: `YES`, `NO`, `DK`, `NA`
breachOfTrust	string	false	Risk of breach of trust. Possible values are: `YES`, `NO`, `DK`, `NA`
riskToOtherPrisoners	string	false	Risk to other prisoners. Possible values are: `YES`, `NO`, `DK`, `NA`

Risk

Name	Type	Required	Description
risk	string	false	Presence of risk. Possible values are: `YES`, `NO`, `DK`, `NA`
previous	string	false	Previous concerns. Possible values are: `YES`, `NO`, `DK`, `NA`
previousConcernsText	string	false	Supporting comments for any previous concerns.
current	string	false	Current concerns. Possible values are: `YES`, `NO`, `DK`, `NA`
currentConcernsText	string	false	Supporting comments for any current concerns.

RiskSummary

Name	Type	Required	Description
whoIsAtRisk	string	false	Who is at risk
natureOfRisk	string	false	What is the nature of the risk
riskImminence	string	false	When is the risk likely to be greatest. Consider the timescale and indicate whether risk is immediate or not. Consider the risks in custody as well as on release.
riskIncreaseFactors	string	false	What circumstances are likely to increase risk. Describe factors, actions, events which might increase level of risk, now and in the future.
riskMitigationFactors	string	false	What factors are likely to reduce the risk. Describe factors, actions, and events which may reduce or contain the level of risk. What has previously stopped them?
overallRiskLevel	string	false	The overall risk level
riskInCommunity	object	false	Assess the risk of serious harm the offender poses on the basis that they could be released imminently back into the community. This field is a map which can return all or some of the properties given.
riskInCustody	object	false	Assess both the risk of serious harm the offender presents now, in custody, and the risk they could present to others whilst in a custodial setting. This field is a map which can return all or some of the properties given.

RiskToSelf

Name	Type	Required	Schema
suicide	object	true	Risk
selfHarm	object	true	Risk
custody	object	true	Risk
hostelSetting	object	true	Risk
vulnerability	object	true	Risk

Risks

Name	Type	Required	Description	Schema
assessedOn	string	false	Date of risk assessment
riskToSelf	object	true		RiskToSelf
otherRisks	object	true		OtherRisks
summary	object	true		RiskSummary

GeneralPredictor

Name	Type	Required	Description	Schema
scoreLevel	string	false	Indicator for general prediction. Possible values are: `LOW`, `MEDIUM`, `HIGH`, `VERY_HIGH`, `NOT_APPLICABLE`

GroupReconviction

Name	Type	Required	Description	Schema
scoreLevel	string	false	Indicator for risk of group reconviction. Possible values are: `LOW`, `MEDIUM`, `HIGH`, `VERY_HIGH`, `NOT_APPLICABLE`

PaginatedResponseRiskPredictorScore

Name	Type	Required	Description	Schema
data	array	true		RiskPredictorScore
pagination	object	true		Pagination

RiskOfSeriousRecidivism

Name	Type	Required	Description	Schema
scoreLevel	string	false	Indicator for risk of serious recidivism. Possible values are: `LOW`, `MEDIUM`, `HIGH`, `VERY_HIGH`, `NOT_APPLICABLE`

RiskPredictorScore

Name	Type	Required	Description	Schema
completedDate	string	false	Risk scores calculation completion date
assessmentStatus	string	false	Whether the risk score calculation is complete. Possible values are: `COMPLETE`, `LOCKED_INCOMPLETE`
generalPredictor	object	true		GeneralPredictor
violencePredictor	object	true		ViolencePredictor
groupReconviction	object	true		GroupReconviction
riskOfSeriousRecidivism	object	true		RiskOfSeriousRecidivism
sexualPredictor	object	true		SexualPredictor

SexualPredictor

Name Type Required Description Schema

indecentScoreLevel

string

false

  Indicator for risk of sexual indecency. Possible values are:
  `LOW`,
  `MEDIUM`,
  `HIGH`,
  `VERY_HIGH`,
  `NOT_APPLICABLE`,

contactScoreLevel

string

false

  Indicator for risk of sexual contact. Possible values are:
  `LOW`,
  `MEDIUM`,
  `HIGH`,
  `VERY_HIGH`,
  `NOT_APPLICABLE`,

ViolencePredictor

Name	Type	Required	Description	Schema
scoreLevel	string	false	Indicator for risk of violence. Possible values are: `LOW`, `MEDIUM`, `HIGH`, `VERY_HIGH`, `NOT_APPLICABLE`

DataResponseMappaDetail

Name	Type	Required	Description	Schema
data	object	true		MappaDetail

MappaDetail

Name	Type	Required
level	number	false
levelDescription	string	false
category	number	false
categoryDescription	string	false
startDate	string	false
reviewDate	string	false
notes	string	false

DynamicRisk

Name	Type	Required
code	string	false
description	string	false
startDate	string	false
reviewDate	string	false
notes	string	false

PaginatedResponseDynamicRisk

Name	Type	Required	Description	Schema
data	array	true		DynamicRisk
pagination	object	true		Pagination

PaginatedResponseRiskManagementPlan

Name	Type	Required	Description	Schema
data	array	true		RiskManagementPlan
pagination	object	true		Pagination

RiskManagementPlan

Name	Type	Required	Description
assessmentId	string	true	The unique ID of the risk management plan
dateCompleted	string	true	The date that the risk management plan was completed
initiationDate	string	true	The date of plan initiation
assessmentStatus	string	true	The status of the plan
assessmentType	string	true	The type of assessment
keyInformationCurrentSituation	string	true	Key information about the current situation of the subject being assessed
furtherConsiderationsCurrentSituation	string	true	Further considerations about the situation of the subject being assessed
supervision	string	true	Who they see, when and why, any support they get from their community, and how well they’re desisting from problematic behaviour
monitoringAndControl	string	true	Information on restrictions in place to prevent reoffending, what steps have been taken to monitor potential reoffending, including license conditions, community order requirements, PPM restrictions and such.
interventionsAndTreatment	string	true	Interventions delivered to develop controls and protective factors to reduce risk of reoffending, including practical support, requirements to support interventions and details of who and where these interventions will be administered.
victimSafetyPlanning	string	true	Restrictions in place to specifically protect victims of, adults known to, and children potentially at risk from the offender.
contingencyPlans	string	true	Future plans in the form “If X happens, we will do Y….” for if parts of the risk management plan break down or requirements or restrictions are breached by the offender.
latestSignLockDate	string	true	An assessment is considered ‘Signed and locked’ once it is signed by the assessor, making the plan read-only. This is the date the plan has been signed by the assessor.
latestCompleteDate	string	true	Once a countersignature has been applied to the plan, the plan is considered complete. This is the date the plan has been countersigned.

CommunityOffenderManager

Name	Type	Required	Schema
name	object	true	PersonResponsibleOfficerName
email	string	false
telephoneNumber	string	false
team	object	true	PersonResponsibleOfficerTeam

DataResponsePersonResponsibleOfficer

Name	Type	Required	Description	Schema
data	object	true		PersonResponsibleOfficer

PersonResponsibleOfficer

Name	Type	Required	Description	Schema
prisonOffenderManager	object	true		PrisonOffenderManager
communityOffenderManager	object	true		CommunityOffenderManager

PersonResponsibleOfficerName

Name	Type	Required	Description	Schema
forename	string	false
surname	string	false

PersonResponsibleOfficerTeam

Name	Type	Required
code	string	false
description	string	false
email	string	false
telephoneNumber	string	false

Prison

Name	Type	Required	Description	Schema
code	string	false	The prison code, which is usually short for the prison name.

PrisonOffenderManager

Name	Type	Required	Schema
forename	string	false
surname	string	false
prison	object	true	Prison

PaginatedResponse

Name	Type	Required	Description	Schema
data	array	true
pagination	object	true		Pagination

DataResponseNeeds

Name	Type	Required	Description	Schema
data	object	true		Needs

Need

Name	Type	Required	Description
type	string	false	The type of need
riskOfHarm	boolean	false	Risk of harm
riskOfReoffending	boolean	false	Risk of reoffending
severity	string	false	Severity of need

Needs

Name	Type	Required	Description	Schema
assessedOn	string	false	Needs assessment completion date
identifiedNeeds	array	true		Need
notIdentifiedNeeds	array	true		Need
unansweredNeeds	array	true		Need

DataResponsePersonLicences

Name	Type	Required	Description	Schema
data	object	true		PersonLicences

Licence

Name	Type	Required	Schema
status	string	false
typeCode	string	false
createdDate	string	false
approvedDate	string	false
updatedDate	string	false
conditions	array	true	LicenceCondition

LicenceCondition

Name	Type	Required
type	string	false
code	string	false
category	string	false
condition	string	false

PersonLicences

Name	Type	Required	Schema
hmppsId	string	true
offenderNumber	string	false
licences	array	true	Licence

ImageMetadata

Name	Type	Required	Description
id	integer	true	The Image ID, in reference to a unique identifier.
active	boolean	true	A flag to indicate whether an image is in active use. It is no guarantee that the latest uploaded image will be the active one.
captureDateTime	string	true	The Date and Time of when the image was captured.
view	string	true	View is the subject focus; describing the inner focus or subject of the image, normally referring to a marking, tattoo or deeper level focus of the orientation. In practise this is the interior foci of what is captured in the 'orientation' field. Possible values are: `FACE` - Facing, `TAT` - Tattoo, `OTH` - Other, `SCAR` - Scar, `MARK` - Mark, `OIC` - Offence in Custody
orientation	string	true	Orientation is the scope focus; describing the scope or outer focus of the image, normally referring to the highest level object of interest within the bounds of the photo itself. This is normally a body part or an angle of photography, such as a photo of someone’s facial view (`FRONT`) or arm (`ARM`). Possible values are: `ANKLE` - Ankle, `ARM` - Arm, `DAMAGE` - Damage, `EAR` - Ear, `ELBOW` - Elbow, `FACE` - Face, `FIGHT` - Fight, `FINGER` - Finger, `FOOT` - Foot, `FRONT` - Front Facial View, `HAND` - Hand, `HEAD` - Head, `INCIDENT` - Incident, `INJURY` - Injury, `KNEE` - Knee, `LEG` - Leg, `LIP` - Lip, `NECK` - Neck, `NOSE` - Nose, `SHOULDER` - Shoulder, `THIGH` - Thigh, `TOE` - Toe, `TORSO` - Torso
type	string	true	Type is the contextual focus; describing the context or scenario the image was taken within. It could be for a particular purpose or capturing the results of a particular type of incident. Possible values are: `OFF_BKG` - Offender Booking, `OFF_IDM` - Offender Identification Marks, `OIC` - Offence In Custody, `PPTY` - Property Image

PaginatedResponseImageMetadata

Name	Type	Required	Description	Schema
data	array	true		ImageMetadata
pagination	object	true		Pagination

CaseNote

Name	Type	Required	Description	Schema
caseNoteId	string	false
offenderIdentifier	string	false
type	string	false
typeDescription	string	false
subType	string	false
subTypeDescription	string	false
creationDateTime	string	false	Date and Time of Case Note creation
occurrenceDateTime	string	false	Date and Time of when case note contact with offender was made
text	string	false
locationId	string	false
sensitive	boolean	true
amendments	array	true	List of amendments to the case note	CaseNoteAmendment

CaseNoteAmendment

List of amendments to the case note

Name	Type	Required	Description
caseNoteAmendmentId	integer	false
creationDateTime	string	false	Date and Time of Case Note creation
additionalNoteText	string	false

PaginatedResponseCaseNote

Name	Type	Required	Description	Schema
data	array	true		CaseNote
pagination	object	true		Pagination

Response

Name	Type	Required	Description	Schema
data	object	true
errors	array	true		UpstreamApiError

DataResponseNomisNumber

Name	Type	Required	Description	Schema
data	object	true		NomisNumber

NomisNumber

Name	Type	Required	Description	Schema
nomisNumber	string	false

DataResponseHmppsId

Name	Type	Required	Description	Schema
data	object	true		HmppsId

HmppsId

Name	Type	Required	Description	Schema
hmppsId	string	false

CaseDetail

Name	Type	Required	Schema
nomsId	string	false
name	object	false	Name
dateOfBirth	string	false
gender	string	false
courtAppearance	object	false	CourtAppearance
sentence	object	false	CaseSentence
responsibleProvider	object	false	ResponsibleProvider
ogrsScore	integer	false
rsrScore	number	false
age	integer	false
ageAtRelease	integer	false

CaseSentence

Name	Type	Required	Schema
date	string	false
sentencingCourt	object	false	SentencingCourt
releaseDate	string	false
expectedReleaseDate	string	false

CourtAppearance

Name	Type	Required	Description	Schema
date	string	false
court	object	false		CourtDetails

CourtDetails

Name	Type	Required	Description	Schema
name	string	false	The name of the court

Name

Name	Type	Required
forename	string	false
middleName	string	false
surname	string	false

ResponseCaseDetail

Name	Type	Required	Description	Schema
data	object	true		CaseDetail
errors	array	true		UpstreamApiError

ResponsibleProvider

Name	Type	Required	Description	Schema
code	string	false
name	string	false

SentencingCourt

Name	Type	Required	Description	Schema
name	string	false

ContactAddress

All addresses for the contact

Name	Type	Required	Description	Schema
addressType	string	false	The type of the address
addressTypeDescription	string	false	The description of the address type
primaryAddress	boolean	true	True if this is the primary address otherwise false
flat	string	false	Flat number or name
property	string	false	Building or house number or name
street	string	false	Street or road name
area	string	false	Area
cityCode	string	false	City code
cityDescription	string	false	The description of the city code
countyCode	string	false	County code
countyDescription	string	false	The description of county code
postcode	string	false	Postcode
countryCode	string	false	Country code
countryDescription	string	false	The description of country code
verified	boolean	true	Whether the address has been verified by postcode lookup
verifiedBy	string	false	Which username ran the postcode lookup check
verifiedTime	string	false	The timestamp of when the postcode lookup was done
mailFlag	boolean	true	Flag to indicate whether mail is allowed to be sent to this address
startDate	string	false	The start date when this address is to be considered active from
endDate	string	false	The end date when this address is to be considered active from
noFixedAddress	boolean	true	Flag to indicate whether this address indicates no fixed address
comments	string	false	Any additional information or comments about the address
phoneNumbers	array	true	Phone numbers that are related to this address	ContactPhoneNumber
createdBy	string	true	The id of the user who created the contact
createdTime	string	true	The timestamp of when the contact was created
updatedBy	string	false	The id of the user who created the contact address
updatedTime	string	false	The timestamp of when the contact address was last updated

ContactEmailAddress

All email addresses for the contact

Name	Type	Required	Description	Schema
emailAddress	string	true	Email address

ContactPhoneNumber

All phone numbers for the contact

Name	Type	Required	Description
phoneType	string	true	Type of phone
phoneTypeDescription	string	true	Description of the type of phone
phoneNumber	string	true	Phone number
extNumber	string	false	Extension number

DetailedContact

Name	Type	Required	Description	Schema
contactId	integer	true	The ID of the contact
titleCode	string	false	The title code for the contact
titleDescription	string	false	The description of the title code, if present
lastName	string	true	The last name of the contact
firstName	string	true	The first name of the contact
middleNames	string	false	The middle names of the contact, if any
dateOfBirth	string	false	The date of birth of the contact, if known
isStaff	boolean	true	Whether the contact is a staff member
deceasedDate	string	false	The date the contact deceased, if known
languageCode	string	false	The NOMIS code for the contacts language
languageDescription	string	false	The description of the language code
interpreterRequired	boolean	true	Whether an interpreter is required for this contact
addresses	array	true	All addresses for the contact	ContactAddress
phoneNumbers	array	true	All phone numbers for the contact	ContactPhoneNumber
emailAddresses	array	true	All email addresses for the contact	ContactEmailAddress
genderCode	string	true	The NOMIS code for the contacts gender. See reference data with group code ‘GENDER’
genderDescription	string	true	The description of gender code. See reference data with group code ‘GENDER’

ResponseDetailedContact

Name	Type	Required	Description	Schema
data	object	true		DetailedContact
errors	array	true		UpstreamApiError

DlqMessage

Name	Type	Required	Description	Schema
body	object	true
messageId	string	true

GetDlqResult

Name	Type	Required	Schema
messagesFoundCount	integer	true
messagesReturnedCount	integer	true
messages	array	true	DlqMessage

BadRequest

Name	Type	Required
status	number	false
userMessage	string	false
developerMessage	string	false

PersonNotFound

Failed to find a person with the provided HMPPS ID.

Name	Type	Required
status	number	false
userMessage	string	false
developerMessage	string	false

InternalServerError

An upstream service was not responding, so we cannot verify the accuracy of any data we did get.

Name	Type	Required
status	number	false
userMessage	string	false
developerMessage	string	false

TransactionConflict

Duplicate post - The clientuniqueref has been used before

Name	Type	Required
status	number	false
userMessage	string	false
developerMessage	string	false

ForbiddenResponse

Forbidden to complete action by upstream service

Name	Type	Required
status	number	false
userMessage	string	false
developerMessage	string	false

OpenAPI Specification

View our OpenAPI specification file in JSON format.

This page was last reviewed on 7 January 2025. It needs to be reviewed again on 7 April 2025 by the page owner #hmpps-integration-api-alerts (Slack Channel) .