HM Courts & Tribunals Service Internal API

openapi: 3.2.0
info:
  title: Hmcts Internal API
  version: 1.0.0
  contact:
    name: HMCTS API Marketplace
    email: no-reply@hmcts.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  description: 'Operations tagged Internal across 2 of this provider''s published API definitions: api-cp-crime-hearing-results-document-subscription-openapi-spec.yml, hmcts-crime-hearing-results-document-subscription-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- description: Crime Hearing Results Document Subscription API
  url: https://api-cp-crime-hearing-results-document-subscription.net/{version}
  variables:
    version:
      default: 1.0.0
      description: API version; matches the spec info.version
security:
- bearerAuth: []
  subscriptionKey: []
tags:
- name: Internal
paths:
  /notifications:
    post:
      summary: Create a client notification
      description: Creates a client notification for given material id and event type
      operationId: createNotification
      tags:
      - Internal
      parameters:
      - $ref: '#/components/parameters/XCorrelationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventPayload'
            examples:
              PCR:
                $ref: '#/components/examples/PCR'
              NowsCustodialSentence:
                $ref: '#/components/examples/NowsCustodialSentence'
      responses:
        '202':
          description: accepted
          headers:
            X-Correlation-Id:
              $ref: '#/components/headers/XCorrelationId'
        '401':
          description: Unauthorized - missing or invalid authentication credentials
          headers:
            X-Correlation-Id:
              $ref: '#/components/headers/XCorrelationId'
        '403':
          description: Forbidden - valid subscription key required but not subscribed to this API
          headers:
            X-Correlation-Id:
              $ref: '#/components/headers/XCorrelationId'
    servers:
    - description: Crime Hearing Results Document Subscription API
      url: https://api-cp-crime-hearing-results-document-subscription.net/{version}
      variables:
        version:
          default: 1.0.0
          description: API version; matches the spec info.version
components:
  examples:
    NowsCustodialSentence:
      summary: Nows example
      value:
        eventId: b37c7a93-4063-40e5-9b0a-0230a3cc2005
        materialId: 297b5c16-0983-405c-9128-614554b1c4fe
        hearingId: a4c1e832-df72-4b3a-9cc5-ee1981dcaf17
        eventType: WEE_CustodialSentence
        timestamp: '2025-02-15T10:40:00Z'
        defendant:
          masterDefendantId: 8b8f1c3a-9a41-4f0f-b8a0-1c23d9e8a111
          name: John Doe
          dateOfBirth: '1990-01-01'
          custodyEstablishmentDetails:
            emailAddress: prison@example.com
          cases:
          - urn: CT98KRYCAP
        payload:
          amendmentDate: '2020-04-15'
          cases:
          - reference: TFL15746USFY2
            defendantCaseOffences:
            - title: Custodial Sentence
              legislation: Contrary to section 152 of the Criminal Justice Act 2003.
              civilOffence: false
              convictionDate: '2025-02-15'
              startDate: '2025-02-15'
              results:
              - label: Custodial Sentence
                welshLabel: Dedfryd Garchardol
                primary: true
                publishedForNows: true
                resultIdentifier: '1081'
                resultDefinitionGroup: Custodial
                resultText: Custodial sentence imposed
                resultWording: The defendant is sentenced to 6 months imprisonment.
                sequence: 1
                prompts:
                - label: Length of sentence
                  value: 6 months
                  promptIdentifier: SENTENCE_LENGTH
          civilNow: false
          courtClerkName: Erica Wilson
          defendant:
            name: John Doe
            dateOfBirth: '1990-01-01'
            address:
              line1: Flat 1, Armageddon House
              line2: 13 Old Road
              line3: Giggleswick
              postCode: SW11 1AB
          orderDate: '2025-02-15'
          orderName: Warrant for Custodial Sentence
          orderingCourt:
            ljaCode: '2577'
            courtCentreName: Lavender Hill Magistrates' Court
            welshCourtCentre: false
            address:
              line1: 176A Lavender Hill
              line2: London
              postCode: SW11 1JU
    PCR:
      summary: Prison court register example
      value:
        eventId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        materialId: 123e4567-e89b-12d3-a456-426614174000
        hearingId: 7f3b0726-ab6e-8579-2bb4-dd0870bcbf5a
        eventType: PRISON_COURT_REGISTER_GENERATED
        timestamp: '2024-01-15T10:30:00Z'
        defendant:
          masterDefendantId: 8b8f1c3a-9a41-4f0f-b8a0-1c23d9e8a111
          name: John Doe
          dateOfBirth: '1990-01-01'
          custodyEstablishmentDetails:
            emailAddress: prison@example.com
          cases:
          - urn: CT98KRYCAP
          - urn: AB75123123
        payload:
          amendmentDate: '2020-04-15'
          applicants:
          - title: Mr
            firstName: Crown
            lastName: Prosecution Service
            name: Crown Prosecution Service
            landlineNumber: 01632 960000
            address:
              line1: Rose Court
              line2: 2 Southwark Bridge
              line3: London
              postCode: SE1 9HS
          caseApplicationReferences:
          - CPS/2020/001234
          cases:
          - reference: TFL15746USFY2
            defendantCaseOffences:
            - title: Use / install a television set without a licence
              legislation: Contrary to section 363(2) and (4) of the Communications Act 2003.
              civilOffence: false
              convictionDate: '2020-03-09'
              startDate: '2020-01-01'
              results:
              - label: Fine
                welshLabel: Dirwy
                primary: true
                publishedForNows: true
                resultIdentifier: '1002'
                resultDefinitionGroup: Financial
                resultText: Fine imposed
                resultWording: The defendant is fined £12.
                sequence: 1
                prompts:
                - label: Amount of fine
                  value: £12
                  promptIdentifier: FINE_AMOUNT
          civilNow: false
          courtClerkName: Erica Wilson
          defendant:
            name: John Doe
            dateOfBirth: '1990-01-01'
            address:
              line1: Flat 1, Armageddon House
              line2: 13 Old Road
              line3: Giggleswick
              postCode: SW11 1AB
          financialOrderDetails:
            paymentTerms: Instalments only with instalment amount 20, monthly, instalment start date 2020-07-11
            enforcementPhoneNumber: 020 7556 8500
            totalAmountImposed: £12
            totalBalance: £12
          orderDate: '2024-01-15'
          orderName: Prison Court Register
          orderingCourt:
            ljaCode: '2577'
            courtCentreName: Lavender Hill Magistrates' Court
            welshCourtCentre: false
            address:
              line1: 176A Lavender Hill
              line2: London
              postCode: SW11 1JU
  headers:
    XCorrelationId:
      description: Correlation identifier for this request/response, used for end-to-end tracing.
      schema:
        type: string
        format: uuid
        example: bf931a90-3e3f-4e8e-a8e4-a4ca9ac07830
  schemas:
    EventPayload:
      type: object
      description: Payload representing a stored PCR/Nows document event with defendant and case details.
      required:
      - eventId
      - materialId
      - hearingId
      - eventType
      - timestamp
      - defendant
      properties:
        eventType:
          type: string
          description: Type of the event, e.g., PRISON_COURT_REGISTER_GENERATED
          $ref: '#/components/schemas/EventType'
        eventId:
          type: string
          format: uuid
          description: Unique identifier of the stored PCR/Nows document event
        hearingId:
          type: string
          format: uuid
          description: Unique identifier of the hearing associated with this event
          example: 7f3b0726-ab6e-8579-2bb4-dd0870bcbf5a
        materialId:
          type: string
          format: uuid
          description: Unique identifier of the stored PCR/Nows document
        timestamp:
          type: string
          format: date-time
          description: Timestamp when the event occurred
        defendant:
          type: object
          required:
          - masterDefendantId
          - name
          properties:
            masterDefendantId:
              type: string
              format: uuid
              description: Unique identifier for the master defendant
            name:
              type: string
              description: Full name of the defendant
            dateOfBirth:
              type: string
              format: date
              description: Date of birth of the defendant
            custodyEstablishmentDetails:
              type: object
              description: Details of the custody establishment
              properties:
                emailAddress:
                  type: string
                  format: email
                  description: Email address of the prison
            cases:
              type: array
              description: List of cases associated with the defendant
              items:
                type: object
                required:
                - urn
                properties:
                  urn:
                    type: string
                    description: Case URN associated with the defendant
        payload:
          type: object
          additionalProperties: true
          description: Full structured document payload, when provided.
    EventType:
      type: string
      description: "Possible values:\n  - PRISON_COURT_REGISTER_GENERATED\n  - WEE_Layout5\n  - NEE_DetentionOnRecommendationForDeportation\n  - OEE_MedicalRemandAdditionalDetails\n  - WEE_RemandAfterBailAppealByProsecutor\n  - WEE_CustodialSentence\n  - WEE_CustodialSentenceWitness\n  - WEE_CommittalToCrownCourtForConsiderationOfTheQuestionOfBailOnAChargeOfMurder\n  - WEE_CommittalToCrownCourtForSentence\n  - WEE_SendingToCrownCourtForTrial\n  - OEE_BailAppealEndOfCustody\n  - WEE_CommitmentPendingTransferToServiceCustody\n  - WEE_NonPaymentOfMoneyOwedCivilDebt\n  - WEE_CustodyWarrantOnDischargeOfExtraditionPendingAppeal\n  - WEE_CustodyWarrantOnDischargeOfExtraditionPendingAppealPart2\n  - WEE_CustodyWarrantOnExtradition\n  - WEE_CustodyWarrantOnExtraditionCategory2Territory\n  - WEE_CustodyWarrantOnExtraditionWithConsent\n  - WEE_CustodyWarrantOnExtraditionWithBailDirection\n  - WEE_CustodyWarrantOnExtraditionWithBailDirectionWithConsent\n  - WEE_CustodyWarrantOnExtraditionWithBailDirectionCategory2Territory\n  - WEE_CustodyWarrantSendingToSecretaryOfStateCategory2Territory\n  - WEE_CustodyWarrantSendingToSecretaryOfStateOnConsentCategory2Territory\n  - WEE_CustodyWarrantWithBailDirectionOnDischargeOfExtraditionPendingAppeal\n  - WEE_CustodyWarrantWithBailDirectionOnDischargeOfExtraditionPendingAppealPart2\n  - WEE_CustodyWarrantWithBailDirectionSendingToSecretaryOfStateCategory2Territory\n  - WEE_CustodyWarrantWithBailDirectionSendingToSecretaryOfStateOnConsentCategory2Territory\n  - WEE_ExtraditionRemandAfterBailAppealByProsecutor\n  - WEE_ExtraditionSupplementToCustodyWarrant\n  - OBE_TerminationOfFootballBanning\n  - OBE_ChangeOfFootballBanning\n  - NEE_FootballBanning\n  - WEE_Remand\n  - WXE_RemandWarrantYouthDetentionAccommodation\n  - OXE_DetentionAndTraining\n  - WEE_InjunctionDetention\n  - OPE_SupervisionOnBreachOfDetentionAndTraining\n  - WEE_CommittalToCrownCourtAuthorityToHoldInYouthDetentionAccommodation\n  - WEE_Detention\n  - WEE_DetentionInYouthDetentionAccommodationBreach\n  - WEE_SendingToCrownCourtAuthorityToHoldInYouthDetentionAccommodation\n"
  parameters:
    XCorrelationId:
      name: X-Correlation-Id
      in: header
      required: false
      description: Optional correlation identifier for end-to-end tracing.
      schema:
        type: string
        format: uuid
        example: d679fd61-061f-4440-9623-36280f0807b7
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    subscriptionKey:
      type: apiKey
      in: header
      name: Ocp-Apim-Subscription-Key
      description: Subscription key for API access
x-refined-from:
- api-cp-crime-hearing-results-document-subscription-openapi-spec.yml
- hmcts-crime-hearing-results-document-subscription-openapi.yml