Skip to main content

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

/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

ParameterInTypeRequiredDescription
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

StatusDescriptionSchema
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": [
          {
          }
        ]
      }
    }
  ],
  "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/{encodedHmppsId}

get

Returns a person.

Parameters

ParameterInTypeRequiredDescription
encodedHmppsId path string true

A URL-encoded HMPPS identifier

Responses

StatusDescriptionSchema
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": [
          {
          }
        ]
      }
    },
    "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": [
            {
            }
          ]
        }
      },
      "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": [
          {
          }
        ]
      }
    }
  }
}
 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

ParameterInTypeRequiredDescription
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

StatusDescriptionSchema
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

get

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

Parameters

ParameterInTypeRequiredDescription
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

StatusDescriptionSchema
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
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.

Parameters

ParameterInTypeRequiredDescription
encodedHmppsId path string true

A URL-encoded HMPPS identifier

Responses

StatusDescriptionSchema
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
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

ParameterInTypeRequiredDescription
encodedHmppsId path string true

A URL-encoded HMPPS identifier

Responses

StatusDescriptionSchema
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

ParameterInTypeRequiredDescription
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

StatusDescriptionSchema
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

ParameterInTypeRequiredDescription
encodedHmppsId path string true

A URL-encoded HMPPS identifier

Responses

StatusDescriptionSchema
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

ParameterInTypeRequiredDescription
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

StatusDescriptionSchema
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}/risks/categories

get

Returns the categories related to an offender.

Parameters

ParameterInTypeRequiredDescription
encodedHmppsId path string true

A URL-encoded HMPPS identifier

Responses

StatusDescriptionSchema
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
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

ParameterInTypeRequiredDescription
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

StatusDescriptionSchema
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
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}/reported-adjudications

get

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

Parameters

ParameterInTypeRequiredDescription
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

StatusDescriptionSchema
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
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}/protected-characteristics

get

Returns protected characteristics of a person.

Parameters

ParameterInTypeRequiredDescription
encodedHmppsId path string true

A URL-encoded HMPPS identifier

Responses

StatusDescriptionSchema
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
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

ParameterInTypeRequiredDescription
encodedHmppsId path string true

A URL-encoded HMPPS identifier

Responses

StatusDescriptionSchema
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

ParameterInTypeRequiredDescription
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

StatusDescriptionSchema
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

ParameterInTypeRequiredDescription
encodedHmppsId path string true

A URL-encoded HMPPS identifier

Responses

StatusDescriptionSchema
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}/name

get

Returns a person’s name

Parameters

ParameterInTypeRequiredDescription
encodedHmppsId path string true

A URL-encoded HMPPS identifier

Responses

StatusDescriptionSchema
200

Successfully found a person with the provided HMPPS ID.

{
  "data": {
    "firstName": "string",
    "lastName": "string"
  }
}
 DataResponsePersonName
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

ParameterInTypeRequiredDescription
encodedHmppsId path string true

A URL-encoded HMPPS identifier

Responses

StatusDescriptionSchema
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

ParameterInTypeRequiredDescription
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

StatusDescriptionSchema
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}/cell-location

get

Parameters

ParameterInTypeRequiredDescription
encodedHmppsId path string true

A URL-encoded HMPPS identifier

Responses

StatusDescriptionSchema
200

OK

{
  "data": {
    "prisonCode": "string",
    "prisonName": "string",
    "cell": "string"
  }
}
 DataResponseCellLocation

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

get

Returns case notes associated with a person.

Parameters

ParameterInTypeRequiredDescription
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

StatusDescriptionSchema
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
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

get

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

Parameters

ParameterInTypeRequiredDescription
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

StatusDescriptionSchema
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/{encodedHmppsId}/alerts/pnd

get

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

Parameters

ParameterInTypeRequiredDescription
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

StatusDescriptionSchema
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/{encodedHmppsId}/addresses

get

Returns addresses associated with a person, ordered by startDate.

Parameters

ParameterInTypeRequiredDescription
encodedHmppsId path string true

A URL-encoded HMPPS identifier

Responses

StatusDescriptionSchema
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": "BUS",
          "description": "Business Address"
        }
      ],
      "notes": "This is their partner's address."
    }
  ]
}
 DataResponseListAddress
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

ParameterInTypeRequiredDescription
id path integer true

Responses

StatusDescriptionSchema
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

StatusDescriptionSchema
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/{encodedHmppsId}/nomis-number

get

Return NOMS number for a given hmpps Id

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

Parameters

ParameterInTypeRequiredDescription
encodedHmppsId path string true

Responses

StatusDescriptionSchema
200

OK

{
  "data": {
    "nomisNumber": "string"
  }
}
 DataResponseNomisNumber
404

NOMS number could not be found.

{
  "data": {
    "nomisNumber": "string"
  }
}
 DataResponseNomisNumber
400

Invalid hmppsId.

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

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

get

Parameters

ParameterInTypeRequiredDescription
encodedNomisNumber path string true

Responses

StatusDescriptionSchema
200

OK

{
  "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

ParameterInTypeRequiredDescription
hmppsId path string true
eventNumber path integer true

Responses

StatusDescriptionSchema
200

OK

{
  "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

Schemas

Alias

NameTypeRequiredDescriptionSchema
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

ContactDetailsWithEmailAndPhone

NameTypeRequiredDescriptionSchema
phoneNumbers array false PhoneNumber
emails array false

A list of email addresses

Identifiers

Other unique identifiers for a person.

NameTypeRequiredDescriptionSchema
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.

PaginatedResponsePerson

NameTypeRequiredDescriptionSchema
data array true Person
pagination object true Pagination

Pagination

NameTypeRequiredDescriptionSchema
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

Person

NameTypeRequiredDescriptionSchema
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

PhoneNumber

NameTypeRequiredDescriptionSchema
number string false

A phone number
type string false

The type of number

DataResponseOffenderSearchResponse

NameTypeRequiredDescriptionSchema
data object true OffenderSearchResponse

OffenderSearchResponse

NameTypeRequiredDescriptionSchema
prisonerOffenderSearch object false Person
probationOffenderSearch object false PersonOnProbation

PersonOnProbation

NameTypeRequiredDescriptionSchema
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

PaginatedResponseStatusInformation

NameTypeRequiredDescriptionSchema
data array true StatusInformation
pagination object true Pagination

StatusInformation

NameTypeRequiredDescriptionSchema
code string false
description string false
startDate string false
reviewDate string false
notes string false

PaginatedResponseSentence

NameTypeRequiredDescriptionSchema
data array true Sentence
pagination object true Pagination

Sentence

NameTypeRequiredDescriptionSchema
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

NameTypeRequiredDescriptionSchema
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

NameTypeRequiredDescriptionSchema
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

DataResponseLatestSentenceKeyDatesAndAdjustments

NameTypeRequiredDescriptionSchema
data object true LatestSentenceKeyDatesAndAdjustments

HomeDetentionCurfewDate

NameTypeRequiredDescriptionSchema
actualDate string false
eligibilityCalculatedDate string false
eligibilityDate string false
eligibilityOverrideDate string false
endDate string false

LatestSentenceKeyDatesAndAdjustments

NameTypeRequiredDescriptionSchema
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

NameTypeRequiredDescriptionSchema
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

NameTypeRequiredDescriptionSchema
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

NameTypeRequiredDescriptionSchema
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

NameTypeRequiredDescriptionSchema
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

NameTypeRequiredDescriptionSchema
date string false

release date for offender
overrideDate string false

release override date for offender

SentenceKeyDateWithCalculatedDate

NameTypeRequiredDescriptionSchema
date string false

release date for offender
overrideDate string false

release override date for offender
calculatedDate string false

release calculated date for offender

TopupSupervision

NameTypeRequiredDescriptionSchema
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

NameTypeRequiredDescriptionSchema
data object true Risks

OtherRisks

NameTypeRequiredDescriptionSchema
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

NameTypeRequiredDescriptionSchema
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

NameTypeRequiredDescriptionSchema
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

NameTypeRequiredDescriptionSchema
suicide object true Risk
selfHarm object true Risk
custody object true Risk
hostelSetting object true Risk
vulnerability object true Risk

Risks

NameTypeRequiredDescriptionSchema
assessedOn string false

Date of risk assessment
riskToSelf object true RiskToSelf
otherRisks object true OtherRisks
summary object true RiskSummary

GeneralPredictor

NameTypeRequiredDescriptionSchema
scoreLevel string false 
Indicator for general prediction. Possible values are:
`LOW`,
`MEDIUM`,
`HIGH`,
`VERY_HIGH`,
`NOT_APPLICABLE`

GroupReconviction

NameTypeRequiredDescriptionSchema
scoreLevel string false 
  Indicator for risk of group reconviction. Possible values are:
  `LOW`,
  `MEDIUM`,
  `HIGH`,
  `VERY_HIGH`,
  `NOT_APPLICABLE`

PaginatedResponseRiskPredictorScore

NameTypeRequiredDescriptionSchema
data array true RiskPredictorScore
pagination object true Pagination

RiskOfSeriousRecidivism

NameTypeRequiredDescriptionSchema
scoreLevel string false 
    Indicator for risk of serious recidivism. Possible values are:
    `LOW`,
    `MEDIUM`,
    `HIGH`,
    `VERY_HIGH`,
    `NOT_APPLICABLE`

RiskPredictorScore

NameTypeRequiredDescriptionSchema
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

NameTypeRequiredDescriptionSchema
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

NameTypeRequiredDescriptionSchema
scoreLevel string false 
Indicator for risk of violence. Possible values are:
`LOW`,
`MEDIUM`,
`HIGH`,
`VERY_HIGH`,
`NOT_APPLICABLE`

DataResponseMappaDetail

NameTypeRequiredDescriptionSchema
data object true MappaDetail

MappaDetail

NameTypeRequiredDescriptionSchema
level number false
levelDescription string false
category number false
categoryDescription string false
startDate string false
reviewDate string false
notes string false

DynamicRisk

NameTypeRequiredDescriptionSchema
code string false
description string false
startDate string false
reviewDate string false
notes string false

PaginatedResponseDynamicRisk

NameTypeRequiredDescriptionSchema
data array true DynamicRisk
pagination object true Pagination

DataResponseRiskCategory

NameTypeRequiredDescriptionSchema
data object true RiskCategory

RiskAssessment

NameTypeRequiredDescriptionSchema
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

NameTypeRequiredDescriptionSchema
offenderNo string false
assessments array true RiskAssessment
category string false
categoryCode string false

PaginatedResponseRiskManagementPlan

NameTypeRequiredDescriptionSchema
data array true RiskManagementPlan
pagination object true Pagination

RiskManagementPlan

NameTypeRequiredDescriptionSchema
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.

Adjudication

NameTypeRequiredDescriptionSchema
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

NameTypeRequiredDescriptionSchema
outcome object false OutcomeDto
referralOutcome object false OutcomeDto

HearingDto

NameTypeRequiredDescriptionSchema
dateTimeOfHearing string false
oicHearingType string false
outcome object false HearingOutcomeDto

HearingOutcomeDto

NameTypeRequiredDescriptionSchema
code string false
reason string false
details string false
plea string false

IncidentDetailsDto

NameTypeRequiredDescriptionSchema
dateTimeOfIncident string false

IncidentRoleDto

NameTypeRequiredDescriptionSchema
roleCode string false
offenceRule object false OffenceRuleDetailsDto

OffenceDto

NameTypeRequiredDescriptionSchema
offenceCode number false
offenceRule object false OffenceRuleDto

OffenceRuleDetailsDto

NameTypeRequiredDescriptionSchema
paragraphNumber string false
paragraphDescription string false

OffenceRuleDto

NameTypeRequiredDescriptionSchema
paragraphNumber string false
paragraphDescription string false

OutcomeDto

NameTypeRequiredDescriptionSchema
code string false
details string false
reason string false
quashedReason string false
canRemove boolean false

OutcomeHistoryDto

NameTypeRequiredDescriptionSchema
hearing object false HearingDto
outcome object false CombinedOutcomeDto

PaginatedResponseAdjudication

NameTypeRequiredDescriptionSchema
data array true Adjudication
pagination object true Pagination

PunishmentCommentDto

NameTypeRequiredDescriptionSchema
comment string false
reasonForChange string false
dateTime string false

PunishmentDto

NameTypeRequiredDescriptionSchema
type string false
privilegeType string false
otherPrivilege string false
schedule object false PunishmentScheduleDto

PunishmentScheduleDto

NameTypeRequiredDescriptionSchema
days number false
startDate string false
endDate string false
suspendedUntil string false

DataResponsePersonProtectedCharacteristics

NameTypeRequiredDescriptionSchema
data object true PersonProtectedCharacteristics

Disability

NameTypeRequiredDescriptionSchema
disabilityType object false KeyValue
condition object false KeyValue
startDate string false
endDate string false
notes string false

KeyValue

NameTypeRequiredDescriptionSchema
code string false
description string false

PersonProtectedCharacteristics

NameTypeRequiredDescriptionSchema
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

NameTypeRequiredDescriptionSchema
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

CommunityOffenderManager

NameTypeRequiredDescriptionSchema
name object true PersonResponsibleOfficerName
email string false
telephoneNumber string false
team object true PersonResponsibleOfficerTeam

DataResponsePersonResponsibleOfficer

NameTypeRequiredDescriptionSchema
data object true PersonResponsibleOfficer

PersonResponsibleOfficer

NameTypeRequiredDescriptionSchema
prisonOffenderManager object true PrisonOffenderManager
communityOffenderManager object true CommunityOffenderManager

PersonResponsibleOfficerName

NameTypeRequiredDescriptionSchema
forename string false
surname string false

PersonResponsibleOfficerTeam

NameTypeRequiredDescriptionSchema
code string false
description string false
email string false
telephoneNumber string false

Prison

NameTypeRequiredDescriptionSchema
code string false

The prison code, which is usually short for the prison name.

PrisonOffenderManager

NameTypeRequiredDescriptionSchema
forename string false
surname string false
prison object true Prison

PaginatedResponse

NameTypeRequiredDescriptionSchema
data array true
pagination object true Pagination

DataResponseNeeds

NameTypeRequiredDescriptionSchema
data object true Needs

Need

NameTypeRequiredDescriptionSchema
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

NameTypeRequiredDescriptionSchema
assessedOn string false

Needs assessment completion date
identifiedNeeds array true Need
notIdentifiedNeeds array true Need
unansweredNeeds array true Need

DataResponsePersonName

NameTypeRequiredDescriptionSchema
data object true PersonName

PersonName

NameTypeRequiredDescriptionSchema
firstName string false
lastName string false

DataResponsePersonLicences

NameTypeRequiredDescriptionSchema
data object true PersonLicences

Licence

NameTypeRequiredDescriptionSchema
status string false
typeCode string false
createdDate string false
approvedDate string false
updatedDate string false
conditions array true LicenceCondition

LicenceCondition

NameTypeRequiredDescriptionSchema
type string false
code string false
category string false
condition string false

PersonLicences

NameTypeRequiredDescriptionSchema
hmppsId string true
offenderNumber string false
licences array true Licence

ImageMetadata

NameTypeRequiredDescriptionSchema
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

NameTypeRequiredDescriptionSchema
data array true ImageMetadata
pagination object true Pagination

CellLocation

NameTypeRequiredDescriptionSchema
prisonCode string false
prisonName string false
cell string false

DataResponseCellLocation

NameTypeRequiredDescriptionSchema
data object true CellLocation

CaseNote

NameTypeRequiredDescriptionSchema
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

NameTypeRequiredDescriptionSchema
caseNoteAmendmentId integer false
creationDateTime string false

Date and Time of Case Note creation
additionalNoteText string false

PaginatedResponseCaseNote

NameTypeRequiredDescriptionSchema
data array true CaseNote
pagination object true Pagination

Alert

NameTypeRequiredDescriptionSchema
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

NameTypeRequiredDescriptionSchema
data array true Alert
pagination object true Pagination

Address

NameTypeRequiredDescriptionSchema
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

NameTypeRequiredDescriptionSchema
data array true Address

Type

Type or usage of address, for example Business Address, Home Address, Work Address.

NameTypeRequiredDescriptionSchema
code string false

Address type code, for example: BUS, HOME, WORK.
description string false

Description of address type, for example: Business Address, Home Address, Work Address.

Response

NameTypeRequiredDescriptionSchema
data object true
errors array true UpstreamApiError

UpstreamApiError

NameTypeRequiredDescriptionSchema
causedBy string true
type string true
description string false

DataResponseNomisNumber

NameTypeRequiredDescriptionSchema
data object true NomisNumber

NomisNumber

NameTypeRequiredDescriptionSchema
nomisNumber string false

DataResponseHmppsId

NameTypeRequiredDescriptionSchema
data object true HmppsId

HmppsId

NameTypeRequiredDescriptionSchema
hmppsId string false

CaseDetail

NameTypeRequiredDescriptionSchema
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

NameTypeRequiredDescriptionSchema
date string false
sentencingCourt object false SentencingCourt
releaseDate string false
expectedReleaseDate string false

CourtAppearance

NameTypeRequiredDescriptionSchema
date string false
court object false CourtDetails

CourtDetails

NameTypeRequiredDescriptionSchema
name string false

The name of the court

Name

NameTypeRequiredDescriptionSchema
forename string false
middleName string false
surname string false

ResponseCaseDetail

NameTypeRequiredDescriptionSchema
data object true CaseDetail
errors array true UpstreamApiError

ResponsibleProvider

NameTypeRequiredDescriptionSchema
code string false
name string false

SentencingCourt

NameTypeRequiredDescriptionSchema
name string false

BadRequest

NameTypeRequiredDescriptionSchema
status number false
userMessage string false
developerMessage string false

PersonNotFound

Failed to find a person with the provided HMPPS ID.

NameTypeRequiredDescriptionSchema
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.

NameTypeRequiredDescriptionSchema
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 3 September 2024. It needs to be reviewed again on 3 December 2024 by the page owner #hmpps-integration-api-alerts (Slack Channel) .