openapi: 3.2.0
info:
  title: Hmcts Standard Applicants API
  version: '@version@'
  contact:
    name: HMCTS AppReg Team
    url: https://github.com/hmcts/appreg-api
  description: 'Operations tagged standard-applicants across 2 of this provider''s published API definitions: appreg-api-openapi.yaml, hmcts-applications-register-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: /
tags:
- description: Standard Applicants are reference data, not managed in App Reg. Only code, name and usage dates are exposed by reference-data endpoints and exports. Personal and contact details are excluded, including when Standard Applicants appear in application responses and reports. Ordinary applicants and respondents are unaffected.
  name: standard-applicants
paths:
  /standard-applicants:
    get:
      description: 'Returns a paginated list of Standard Applicants.

        - Filters:

        - `code` – case-insensitive partial match

        - `name` – case-insensitive partial match against organisation/name, surname and forenames 1-3'
      operationId: getStandardApplicants
      parameters:
      - description: Filter by code (contains, case-insensitive).
        example: SA
        in: query
        name: code
        schema:
          maxLength: 10
          type: string
      - description: Filter by name (contains, case-insensitive). Searches organisation/name, surname, forename 1, forename 2 and forename 3.
        in: query
        name: name
        schema:
          example: Innovative Solutions Inc
          maxLength: 100
          type: string
      - description: Filter by address line 1 (contains, case-insensitive).
        example: 1 High Street
        in: query
        name: addressLine1
        schema:
          maxLength: 255
          type: string
      - description: Filter by from date. If supplied after `to`, the API normalises the range before searching.
        example: 2026-04-01
        in: query
        name: from
        schema:
          format: date
          type: string
      - description: Filter by to date. If supplied before `from`, the API normalises the range before searching.
        example: 2026-12-31
        in: query
        name: to
        schema:
          format: date
          type: string
      - description: Zero-based page index.
        in: query
        name: pageNumber
        schema:
          default: 0
          format: int32
          minimum: 0
          type: integer
      - description: Page size.
        in: query
        name: pageSize
        schema:
          default: 10
          format: int32
          maximum: 100
          minimum: 1
          type: integer
      - description: "Sort parameter. Format: `property,(asc|desc)`. Currently only a single sort value is supported. Example: `?sort=name,asc`.\nSupported properties:\n  - `code`\n  - `name`\n  - `addressLine1`\n  - `from`\n  - `to`\n"
        explode: true
        in: query
        name: sort
        schema:
          example:
          - name,asc
          items:
            type: string
          type: array
        style: form
      responses:
        '200':
          content:
            application/vnd.hmcts.appreg.v1+json:
              schema:
                $ref: '#/components/schemas/standard-applicant-page'
          description: Page of Standard Applicants.
          headers:
            Vary:
              description: Response varies by Accept for media-type versioning.
              schema:
                example: Accept
                type: string
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problem'
          description: Invalid request parameters.
        '401':
          content:
            application/problem+json:
              examples:
                unauthenticated:
                  value:
                    type: https://errors.hmcts.net/common/unauthorized
                    title: Unauthorized
                    status: 401
                    detail: Missing or invalid credentials
              schema:
                $ref: '#/components/schemas/problem'
          description: Authentication required or token invalid.
        '403':
          content:
            application/problem+json:
              examples:
                forbidden:
                  value:
                    type: https://errors.hmcts.net/common/forbidden
                    title: Forbidden
                    status: 403
                    detail: You do not have permission to access this resource
              schema:
                $ref: '#/components/schemas/problem'
          description: Authenticated but not permitted to perform this action.
        '406':
          content:
            application/problem+json:
              examples:
                notAcceptable:
                  value:
                    type: https://errors.hmcts.net/common/not-acceptable
                    title: Not Acceptable
                    status: 406
                    detail: Requested media type/version not acceptable
              schema:
                $ref: '#/components/schemas/problem'
          description: Requested media type/version not acceptable.
        '500':
          content:
            application/problem+json:
              examples:
                generic:
                  value:
                    type: https://errors.hmcts.net/common/internal-error
                    title: Internal Server Error
                    status: 500
                    detail: An unexpected error occurred
              schema:
                $ref: '#/components/schemas/problem'
          description: Unexpected server error.
      summary: Get Standard Applicants (paginated, filterable)
      tags:
      - standard-applicants
    servers:
    - url: /
  /standard-applicants/reports/print:
    get:
      description: Returns all data required for printing Standard Applicants filtered by the supported print criteria; code, name, addressLine1, from and to. Dates are returned in ISO format; frontend PDF rendering should display dates as dd/MM/yyyy for legacy parity. Code and name are optional and may be combined; both must match when supplied together. Without date filters, only currently active records are returned, as for search. Returns all matching pages in the requested order (default code ascending). Results exceeding appreg.standard-applicants.max-print-rows (default 1000) are rejected with HTTP 400; results are never silently truncated.
      operationId: printStandardApplicants
      parameters:
      - description: Filter by code.
        in: query
        name: code
        schema:
          maxLength: 10
          type: string
      - description: Filter by applicant name.
        in: query
        name: name
        schema:
          maxLength: 100
          type: string
      - description: Filter by from date.
        in: query
        name: from
        schema:
          format: date
          type: string
      - description: Filter by to date.
        in: query
        name: to
        schema:
          format: date
          type: string
      - description: Filter by address line 1.
        in: query
        name: addressLine1
        schema:
          maxLength: 255
          type: string
      - description: Sort parameter. Format `property,(asc|desc)`.
        in: query
        name: sort
        schema:
          items:
            type: string
          type: array
      responses:
        '200':
          content:
            application/vnd.hmcts.appreg.v1+json:
              schema:
                $ref: '#/components/schemas/standard-applicant-print-dto'
          description: Print-ready Standard Applicants payload.
          headers:
            Vary:
              description: Response varies by Accept for media-type versioning.
              schema:
                example: Accept
                type: string
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problem'
          description: Invalid request parameters.
        '401':
          content:
            application/problem+json:
              examples:
                unauthenticated:
                  value:
                    type: https://errors.hmcts.net/common/unauthorized
                    title: Unauthorized
                    status: 401
                    detail: Missing or invalid credentials
              schema:
                $ref: '#/components/schemas/problem'
          description: Authentication required or token invalid.
        '403':
          content:
            application/problem+json:
              examples:
                forbidden:
                  value:
                    type: https://errors.hmcts.net/common/forbidden
                    title: Forbidden
                    status: 403
                    detail: You do not have permission to access this resource
              schema:
                $ref: '#/components/schemas/problem'
          description: Authenticated but not permitted to perform this action.
        '406':
          content:
            application/problem+json:
              examples:
                notAcceptable:
                  value:
                    type: https://errors.hmcts.net/common/not-acceptable
                    title: Not Acceptable
                    status: 406
                    detail: Requested media type/version not acceptable
              schema:
                $ref: '#/components/schemas/problem'
          description: Requested media type/version not acceptable.
        '500':
          content:
            application/problem+json:
              examples:
                generic:
                  value:
                    type: https://errors.hmcts.net/common/internal-error
                    title: Internal Server Error
                    status: 500
                    detail: An unexpected error occurred
              schema:
                $ref: '#/components/schemas/problem'
          description: Unexpected server error.
      summary: Get a print-ready JSON payload for a Standard Applicants
      tags:
      - standard-applicants
    servers:
    - url: /
  /standard-applicants/{code}:
    get:
      description: 'Returns a Standard Applicant record matching the supplied code without applying

        lodgement-date effective filtering. Where multiple records share the same code,

        the current active or latest record is selected using deterministic reference-data ordering.'
      operationId: getStandardApplicantByCode
      parameters:
      - description: Code used to identify the Standard Applicant (case-insensitive).
        example: SA
        in: path
        name: code
        required: true
        schema:
          maxLength: 10
          type: string
      responses:
        '200':
          content:
            application/vnd.hmcts.appreg.v1+json:
              schema:
                $ref: '#/components/schemas/standard-applicant-get-detail-dto'
          description: Standard Applicant found
          headers:
            Vary:
              description: Response varies by Accept for media-type versioning.
              schema:
                example: Accept
                type: string
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problem'
          description: Invalid request parameters.
        '401':
          content:
            application/problem+json:
              examples:
                unauthenticated:
                  value:
                    type: https://errors.hmcts.net/common/unauthorized
                    title: Unauthorized
                    status: 401
                    detail: Missing or invalid credentials
              schema:
                $ref: '#/components/schemas/problem'
          description: Authentication required or token invalid.
        '403':
          content:
            application/problem+json:
              examples:
                forbidden:
                  value:
                    type: https://errors.hmcts.net/common/forbidden
                    title: Forbidden
                    status: 403
                    detail: You do not have permission to access this resource
              schema:
                $ref: '#/components/schemas/problem'
          description: Authenticated but not permitted to perform this action.
        '404':
          content:
            application/problem+json:
              examples:
                missing:
                  value:
                    type: https://errors.hmcts.net/appreg/not-found
                    title: Not Found
                    status: 404
                    detail: Result code with id=123 was not found
              schema:
                $ref: '#/components/schemas/problem'
          description: The requested resource was not found.
        '406':
          content:
            application/problem+json:
              examples:
                notAcceptable:
                  value:
                    type: https://errors.hmcts.net/common/not-acceptable
                    title: Not Acceptable
                    status: 406
                    detail: Requested media type/version not acceptable
              schema:
                $ref: '#/components/schemas/problem'
          description: Requested media type/version not acceptable.
        '500':
          content:
            application/problem+json:
              examples:
                generic:
                  value:
                    type: https://errors.hmcts.net/common/internal-error
                    title: Internal Server Error
                    status: 500
                    detail: An unexpected error occurred
              schema:
                $ref: '#/components/schemas/problem'
          description: Unexpected server error.
      summary: Get a specific Standard Applicant by code
      tags:
      - standard-applicants
    servers:
    - url: /
  /standard-applicants/export:
    get:
      description: 'Export all matching currently active Standard Applicants, across all pages, to a CSV file.

        Contains exactly four columns: Applicant Code, Name, Use From and Use To.

        Personal names, titles, addresses, postcodes, email and telephone/mobile numbers are never exported.

        Uses the same code/name matching and ordering as search without date filters.

        Code and name are optional and may be combined; both must match when supplied together.

        Omitting both returns all currently active applicants. Defaults to code ascending.

        - Filters:

        - `code` – case-insensitive partial match.

        - `name` – case-insensitive partial match against organisation/name, surname and forenames 1-3.'
      operationId: standardApplicantsExport
      parameters:
      - description: Filter by code (contains, case-insensitive). May be combined with name.
        example: SA
        in: query
        name: code
        schema:
          maxLength: 10
          type: string
      - description: Filter by organisation or person name (contains, case-insensitive). May be combined with code.
        in: query
        name: name
        schema:
          example: Innovative Solutions Inc
          maxLength: 100
          type: string
      - description: 'One sort value: code, name, addressLine1, from or to, followed by asc or desc (for example name,desc). Defaults to code,asc.'
        in: query
        name: sort
        schema:
          items:
            type: string
          type: array
      responses:
        '200':
          content:
            text/csv:
              schema:
                type: string
          description: A CSV file containing the filtered list of Standard Applicants.
          headers:
            Vary:
              description: Response varies by Accept for media-type versioning.
              schema:
                example: Accept
                type: string
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problem'
          description: Invalid request parameters.
        '401':
          content:
            application/problem+json:
              examples:
                unauthenticated:
                  value:
                    type: https://errors.hmcts.net/common/unauthorized
                    title: Unauthorized
                    status: 401
                    detail: Missing or invalid credentials
              schema:
                $ref: '#/components/schemas/problem'
          description: Authentication required or token invalid.
        '403':
          content:
            application/problem+json:
              examples:
                forbidden:
                  value:
                    type: https://errors.hmcts.net/common/forbidden
                    title: Forbidden
                    status: 403
                    detail: You do not have permission to access this resource
              schema:
                $ref: '#/components/schemas/problem'
          description: Authenticated but not permitted to perform this action.
        '404':
          content:
            application/problem+json:
              examples:
                missing:
                  value:
                    type: https://errors.hmcts.net/appreg/not-found
                    title: Not Found
                    status: 404
                    detail: Result code with id=123 was not found
              schema:
                $ref: '#/components/schemas/problem'
          description: The requested resource was not found.
        '500':
          content:
            application/problem+json:
              examples:
                generic:
                  value:
                    type: https://errors.hmcts.net/common/internal-error
                    title: Internal Server Error
                    status: 500
                    detail: An unexpected error occurred
              schema:
                $ref: '#/components/schemas/problem'
          description: Unexpected server error.
      tags:
      - standard-applicants
      summary: Standard applicants export
      x-summary-source: derived
    servers:
    - url: /
components:
  schemas:
    standard-applicant-page:
      allOf:
      - $ref: '#/components/schemas/page'
      - properties:
          content:
            items:
              $ref: '#/components/schemas/standard-applicant-get-summary-dto'
            type: array
        type: object
    standard-applicant-print-search-criteria-dto:
      description: Search criteria used for the Standard Applicants print report.
      properties:
        code:
          type:
          - string
          - 'null'
        name:
          type:
          - string
          - 'null'
        from:
          format: date
          type:
          - string
          - 'null'
        to:
          format: date
          type:
          - string
          - 'null'
      required:
      - code
      - from
      - name
      - to
      type: object
    standard-applicant-get-detail-dto:
      description: Standard Applicant reference data. Only code, name and usage dates are exposed; personal and contact details are excluded.
      properties:
        code:
          description: Code that identifies the Standard Applicant.
          example: STANDARD-1
          type: string
        name:
          description: Name of the Standard Applicant.
          example: Standard Applicant 1
          type: string
        startDate:
          description: Date the applicant record became active.
          example: 2025-12-01
          format: date
          type: string
        endDate:
          description: Date the applicant became inactive. `null` indicates that this row is still active.
          example: 2025-12-01
          format: date
          type:
          - string
          - 'null'
      required:
      - code
      - endDate
      - startDate
      type: object
    standard-applicant-get-summary-dto:
      description: Standard Applicant reference data. Only code, name and usage dates are exposed; personal and contact details are excluded.
      properties:
        code:
          description: Code that identifies the Standard Applicant.
          example: STANDARD-1
          type: string
        name:
          description: Standard Applicant name. Never derived from personal name fields.
          example: Standard Applicant 1
          type: string
        startDate:
          description: Date the applicant record became active.
          example: 2025-12-01
          format: date
          type: string
        endDate:
          description: Date the applicant record became inactive, or null if still active.
          example: 2025-12-01
          format: date
          type:
          - string
          - 'null'
      required:
      - code
      - endDate
      - startDate
      type: object
    standard-applicant-print-dto:
      description: Print-ready Standard Applicans report payload.
      properties:
        reportTitle:
          example: Standard Applicants Report
          type: string
        searchCriteria:
          $ref: '#/components/schemas/standard-applicant-print-search-criteria-dto'
        generatedAt:
          format: date-time
          type: string
        recordCount:
          format: int32
          type: integer
        applicants:
          items:
            $ref: '#/components/schemas/standard-applicant-print-row-dto'
          type: array
      required:
      - applicants
      - generatedAt
      - recordCount
      - reportTitle
      - searchCriteria
      type: object
    sort_orders_inner:
      properties:
        property:
          description: Property name used for sorting.
          example: title
          type: string
        direction:
          description: Sort direction.
          enum:
          - asc
          - desc
          example: asc
          type: string
      required:
      - direction
      - property
      type: object
    page:
      description: Generic Spring Data page.
      properties:
        pageNumber:
          description: Zero-based page index.
          format: int32
          type: integer
        pageSize:
          description: Page size.
          format: int32
          type: integer
        totalElements:
          description: Total number of elements across all pages.
          format: int64
          type: integer
        totalPages:
          description: Total number of pages.
          format: int32
          type: integer
        sort:
          $ref: '#/components/schemas/sort'
        first:
          type: boolean
        last:
          type: boolean
        elementsOnPage:
          description: Total number of elements in the current page.
          format: int32
          type: integer
      required:
      - content
      - elementsOnPage
      - pageNumber
      - pageSize
      - totalElements
      type: object
    sort:
      description: Sorting state for the returned page.
      example:
        orders:
        - property: title
          direction: asc
        - property: code
          direction: desc
      properties:
        orders:
          description: Active sort orders in priority order.
          items:
            $ref: '#/components/schemas/sort_orders_inner'
          type: array
      type: object
    problem:
      description: RFC 9457/7807 problem details.
      properties:
        type:
          description: Problem type identifier (URI).
          example: https://errors.hmcts.net/appreg/bad-request
          format: uri
          type: string
        title:
          description: Short, human-readable summary.
          example: Invalid request parameters
          type: string
        status:
          description: HTTP status code.
          example: 400
          format: int32
          type: integer
        detail:
          description: Human-readable explanation specific to this occurrence.
          example: startDateFrom must be on or before startDateTo
          type: string
        instance:
          description: URI reference to the specific occurrence (if applicable).
          example: urn:request:2f9c3d8a-1b3a-4a1e-9b7f-6b2a6a0a2b2f
          format: uri
          type: string
        correlationId:
          description: Server-side correlation ID for tracing.
          example: 3e1a2c95a7d84a5fb3e1a2c95a7d84a5
          type: string
      required:
      - status
      - title
      - type
      type: object
    standard-applicant-print-row-dto:
      description: Standard Applicant print row containing only code, name and usage dates. Personal and contact details are excluded.
      properties:
        code:
          type:
          - string
          - 'null'
        useFrom:
          format: date
          type:
          - string
          - 'null'
        name:
          type:
          - string
          - 'null'
        useTo:
          format: date
          type:
          - string
          - 'null'
      required:
      - code
      - name
      - useFrom
      - useTo
      type: object
x-refined-from:
- appreg-api-openapi.yaml
- hmcts-applications-register-openapi.yml