Skip to main content

HMPPS External Events

The HMPPS External API (formerly HMPPS Integration API) uses an events based system which processes upstream MoJ domain events related to the information served by the API endpoints. This allows the clients of our API to be notified when a change occurs to a domain that is of interest to them.

Consumers who want to be notified of these events, will be provided with a dedicated AWS SQS queue that will receive notifications for the API endpoints they have access to.

Email hmpps-external-api@justice.gov.uk to request access to this service.

The notification message is wrapped in a JSON structure with the actual notification message content held in the Message attribute. The fields noted as deprecated should not be used by consumers.

For example: { "Type" : DEPRECATED, "MessageId" : bbf92ab9-9540-5c0c-83b0-48e80e6f24d3, "TopicArn" : DEPRECATED, "Message" : "See notification message content below", "Timestamp" : "2026-04-09T12:17:51.384Z", "SignatureVersion" : DEPRECATED, "Signature" : DEPRECATED, "SigningCertURL" : DEPRECATED, "UnsubscribeURL" : DEPRECATED, "MessageAttributes" : DEPRECATED }

Notification Message Structure

The notification message content (held in the wrappers Message attribute) is a JSON structure containing an event ID, an event type, the URL at which the updated data is available and potentially some additional metadata.

For example:

{
  "eventId":123456,
  "hmppsId":"X688624",
  "eventType":"PERSON_NAME_CHANGED",
  "prisonId":null,
  "url":"http://{api-domain}/events/person-name-changed/X688624",
  "lastModifiedDateTime":"2025-10-13T12:42:00.002387"
}

Available Events

Below is a list of all the events that you can currently receive notifications about if something changes. It details the endpoints the events relate to, and information about what triggers an event to be sent.

Dynamic Risks Changed

  • Endpoint: /v1/persons/{hmppsId}/risks/dynamic
  • Event ID: DYNAMIC_RISKS_CHANGED

Probation Status Changed

  • Endpoint: /v1/persons/{hmppsId}/status-information
  • Event ID: PROBATION_STATUS_CHANGED

MAPPA Detail Changed

  • Endpoint: /v1/persons/{hmppsId}/risks/mappadetail
  • Event ID: MAPPA_DETAIL_CHANGED

Risk Score Changed

  • Endpoint: /v1/persons/{hmppsId}/risks/scores
  • Event ID: RISK_SCORE_CHANGED

Prisoner Base Location Changed

  • Endpoint: /v1/persons/{hmppsId}/prisoner-base-location
  • Event ID: PRISONER_BASE_LOCATION_CHANGED

Key Dates and Adjustments Prisoner Release

  • Endpoint: /v1/persons/{hmppsId}/sentences/latest-key-dates-and-adjustments
  • Event ID: KEY_DATES_AND_ADJUSTMENTS_PRISONER_RELEASE

Licence Condition Changed

  • Endpoint: /v1/persons/{hmppsId}/licences/conditions
  • Event ID: LICENCE_CONDITION_CHANGED

Risk of Serious Harm Changed

  • Endpoint: /v1/persons/{hmppsId}/risks/serious-harm
  • Event ID: RISK_OF_SERIOUS_HARM_CHANGED

Assessment Summary Changed

  • Endpoint: /v1/persons/{hmppsId}/assessment-summary
  • Event ID: ASSESSMENT_SUMMARY_CHANGE

Needs Changed

  • Endpoint: /v1/persons/{hmppsId}/needs
  • Event ID: NEEDS_CHANGED

PLP Induction Schedule Changed

  • Endpoint: /v1/persons/{hmppsId}/plp-induction-schedule/history
  • Event ID: PLP_INDUCTION_SCHEDULE_CHANGED

PLP Review Schedule Changed

  • Endpoint: /v1/persons/{hmppsId}/plp-review-schedule
  • Event ID: PLP_REVIEW_SCHEDULE_CHANGED

SAN Plan Creation Schedule Changed

  • Endpoint: /v1/persons/{hmppsId}/education/san/plan-creation-schedule
  • Event ID: SAN_PLAN_CREATION_SCHEDULE_CHANGED

SAN Review Schedule Changed

  • Endpoint: /v1/persons/{hmppsId}/education/san/review-schedule
  • Event ID: SAN_REVIEW_SCHEDULE_CHANGED

Person Status Changed

  • Endpoint: /v1/persons/{hmppsId}
  • Event ID: PERSON_STATUS_CHANGED

Person Address Changed

  • Endpoint: /v1/persons/{hmppsId}/addresses
  • Event ID: PERSON_ADDRESS_CHANGED

Person Contacts Changed

  • Endpoint: /v1/persons/{hmppsId}/contacts
  • Event ID: PERSON_CONTACTS_CHANGED

Person IEP Level Changed

  • Endpoint: /v1/persons/{hmppsId}/iep-level
  • Event ID: PERSON_IEP_LEVEL_CHANGED

Person Visitor Restrictions Changed

  • Endpoint: /v1/persons/{hmppsId}/visitor/{contactId}/restrictions
  • Event ID: PERSON_VISITOR_RESTRICTIONS_CHANGED

Person Visit Restrictions Changed

  • Endpoint: /v1/persons/{hmppsId}/visit-restrictions
  • Event ID: PERSON_VISIT_RESTRICTIONS_CHANGED

Person Future Visits Changed

  • Endpoint: /v1/persons/{hmppsId}/visit/future
  • Event ID: PERSON_FUTURE_VISITS_CHANGED

Person Alerts Changed

  • Endpoint: /v1/persons/{hmppsId}/alerts
  • Event ID: PERSON_ALERTS_CHANGED

Person Case Notes Changed

  • Endpoint: /v1/persons/{hmppsId}/case-notes
  • Event ID: PERSON_CASE_NOTES_CHANGED

Person Name Changed

  • Endpoint: /v1/persons/{hmppsId}/name
  • Event ID: PERSON_NAME_CHANGED

Person Cell Location Changed

  • Endpoint: /v1/persons/{hmppsId}/cell-location
  • Event ID: PERSON_CELL_LOCATION_CHANGED

Person Sentences Changed

  • Endpoint: /v1/persons/{hmppsId}/sentences
  • Event ID: PERSON_SENTENCES_CHANGED

Person Responsible Officer Changed

  • Endpoint: /v1/persons/{hmppsId}/person-responsible-officer
  • Event ID: PERSON_RESPONSIBLE_OFFICER_CHANGED

Person Protected Characteristics Changed

  • Endpoint: /v1/persons/{hmppsId}/protected-characteristics
  • Event ID: PERSON_PROTECTED_CHARACTERISTICS_CHANGED

Person Reported Adjudications Changed

  • Endpoint: /v1/persons/{hmppsId}/reported-adjudications
  • Event ID: PERSON_REPORTED_ADJUDICATIONS_CHANGED

Person Number of Children Changed

  • Endpoint: /v1/persons/{hmppsId}/number-of-children
  • Event ID: PERSON_NUMBER_OF_CHILDREN_CHANGED

Person Physical Characteristics Changed

  • Endpoint: /v1/persons/{hmppsId}/physical-characteristics
  • Event ID: PERSON_PHYSICAL_CHARACTERISTICS_CHANGED

Person Images Changed

  • Endpoint: /v1/persons/{hmppsId}/images
  • Event ID: PERSON_IMAGES_CHANGED

Prisoners Changed

  • Endpoint: /v1/prison/prisoners
  • Event ID: PRISONERS_CHANGED

Prisoner Changed

  • Endpoint: /v1/prison/prisoners/{hmppsId}
  • Event ID: PRISONER_CHANGED

Person Education Assessments Changed

  • Endpoint: /v1/persons/{hmppsId}/education/assessments
  • Event ID: PERSON_EDUCATION_ASSESSMENTS_CHANGED

Prisoner Non-Associations Changed

  • Endpoint: /v1/prison/{prisonId}/prisoners/{hmppsId}/non-associations
  • Event ID: PRISONER_NON_ASSOCIATIONS_CHANGED

Prison Visits Changed

  • Endpoint: /v1/prison/{prisonId}/visit/search
  • Event ID: PRISON_VISITS_CHANGED

Prison Residential Hierarchy Changed

  • Endpoint: /v1/prison/{prisonId}/residential-hierarchy
  • Event ID: PRISON_RESIDENTIAL_HIERARCHY_CHANGED

Prison Location Changed

  • Endpoint: /v1/prison/{prisonId}/location/{locationKey}
  • Event ID: PRISON_LOCATION_CHANGED

Prison Residential Details Changed

  • Endpoint: /v1/prison/{prisonId}/residential-details
  • Event ID: PRISON_RESIDENTIAL_DETAILS_CHANGED

Prison Capacity Changed

  • Endpoint: /v1/prison/{prisonId}/capacity
  • Event ID: PRISON_CAPACITY_CHANGED

Visit Changed

  • Endpoint: /v1/visit/{visitReference}
  • Event ID: VISIT_CHANGED

Contact Event Created

  • Endpoint: /v1/persons/{hmppsId}/contact-events/{contactEventId}
  • Event ID: CONTACT_EVENT_CREATED

Contact Event Changed

  • Endpoint: /v1/persons/{hmppsId}/contact-events/{contactEventId}
  • Event ID: CONTACT_EVENT_CHANGED

Person Health and Diet Changed

  • Endpoint: /v1/persons/{hmppsId}/health-and-diet
  • Event ID: PERSON_HEALTH_AND_DIET_CHANGED

Person Care Needs Changed

  • Endpoint: /v1/persons/{hmppsId}/care-needs
  • Event ID: PERSON_CARE_NEEDS_CHANGED

Person Languages Changed

  • Endpoint: /v1/persons/{hmppsId}/languages
  • Event ID: PERSON_LANGUAGES_CHANGED

Prisoner Merged

  • Endpoint: /v1/persons/{hmppsId}
  • Event ID: PRISONER_MERGED

Person Access Limitations Changed

  • Endpoint: /v1/persons/{hmppsId}/access-limitations
  • Event ID: PERSON_ACCESS_LIMITATIONS_CHANGED
This page was last reviewed on 21 August 2026. It needs to be reviewed again on 21 October 2026 by the page owner #hmpps-integration-api-alerts .