swagger.yml

swagger: "2.0"
info:
  description: "Responsible for the persistence and retrieval of Claims (and Claimants)\
    \ for Help To Buy Healthy Food"
  version: "1.0"
  title: "Claimant Service"
  contact:
    name: "Department Of Health"
    url: "https://github.com/DepartmentOfHealth-htbhf"
    email: "dh-htbhf-team@equalexperts.com"
  license:
    name: "MIT"
    url: "https://opensource.org/licenses/MIT"
host: "localhost:8090"
basePath: "/"
tags:
- name: "claim-controller"
  description: "Endpoints for dealing with claims, e.g. persisting a claim."
paths:
  /v3/claims:
    post:
      tags:
      - "claim-controller"
      summary: "Create a claim."
      operationId: "createClaimUsingPOST"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "body"
        name: "newClaimDTO"
        description: "The claim to persist"
        required: false
        schema:
          $ref: "#/definitions/NewClaimDTO"
      responses:
        "200":
          description: "OK"
          schema:
            $ref: "#/definitions/ClaimResultDTO"
        "201":
          description: "Created"
        "400":
          description: "Bad request"
          schema:
            $ref: "#/definitions/ErrorResponse"
        "401":
          description: "Unauthorized"
        "403":
          description: "Forbidden"
        "404":
          description: "Not Found"
      deprecated: false
  /v3/claims/{id}:
    get:
      tags:
      - "claim-controller"
      summary: "Retrieve a claim by id."
      operationId: "retrieveClaimByIdUsingGET"
      produces:
      - "application/json"
      parameters:
      - name: "id"
        in: "path"
        description: "id"
        required: true
        type: "string"
        format: "uuid"
      responses:
        "200":
          description: "OK"
          schema:
            $ref: "#/definitions/ClaimDTO"
        "401":
          description: "Unauthorized"
        "403":
          description: "Forbidden"
        "404":
          description: "Claim not found"
          schema:
            $ref: "#/definitions/ErrorResponse"
      deprecated: false
definitions:
  AddressDTO:
    type: "object"
    properties:
      addressLine1:
        type: "string"
        example: "Flat B"
        description: "First line of the address"
        minLength: 1
        maxLength: 500
      addressLine2:
        type: "string"
        example: "221 Baker Street"
        description: "Second line of the address"
        minLength: 0
        maxLength: 500
      county:
        type: "string"
        example: "Devon"
        description: "County of the address"
        minLength: 0
        maxLength: 500
      postcode:
        type: "string"
        example: "AA1 1AA"
        description: "The postcode of the address."
        pattern: "^(GIR ?0AA|[A-PR-UWYZ]([0-9]{1,2}|([A-HK-Y][0-9]([0-9ABEHMNPRV-Y])?)|[0-9][A-HJKPS-UW])\
          \ ?[0-9][ABD-HJLNP-UW-Z]{2})$"
      townOrCity:
        type: "string"
        example: "London"
        description: "Town or city of the address"
        minLength: 1
        maxLength: 500
    title: "AddressDTO"
    description: "Multi purpose address object"
  ClaimDTO:
    type: "object"
    properties:
      cardAccountId:
        type: "string"
        example: "8b66a86f-778e-47f9-b998-a042476ef2c0"
        description: "Card id returned from the card provider"
      cardStatus:
        type: "string"
        description: "The current card status"
        enum:
        - "ACTIVE"
        - "PENDING_CANCELLATION"
        - "SCHEDULED_FOR_CANCELLATION"
        - "CANCELLED"
      cardStatusTimestamp:
        type: "string"
        format: "date-time"
        example: "2020/01/06T14:00:00.352"
        description: "Time of when the card status was last updated"
      claimStatus:
        type: "string"
        description: "The claim's current status"
        enum:
        - "REJECTED"
        - "NEW"
        - "PENDING"
        - "ACTIVE"
        - "PENDING_EXPIRY"
        - "EXPIRED"
        - "ERROR"
      claimStatusTimestamp:
        type: "string"
        format: "date-time"
        example: "2020/01/06T14:00:00.352"
        description: "Timestamp of when the claim status was last updated"
      claimant:
        $ref: "#/definitions/ClaimantDTO"
      currentIdentityAndEligibilityResponse:
        description: "The current identity and eligibility response when processing\
          \ the last payment cycle."
        $ref: "#/definitions/CombinedIdentityAndEligibilityResponse"
      dwpHouseholdIdentifier:
        type: "string"
        example: "dd77e887-49cf-43cd-b974-b17273602018"
        description: "Household identifier returned from DWP"
      eligibilityOverride:
        description: "An override of the DWP/HMRC eligibility decision"
        $ref: "#/definitions/EligibilityOverrideDTO"
      eligibilityStatus:
        type: "string"
        description: "The claim's eligibility status"
        enum:
        - "ELIGIBLE"
        - "INELIGIBLE"
        - "PENDING"
        - "NO_MATCH"
        - "ERROR"
        - "DUPLICATE"
      eligibilityStatusTimestamp:
        type: "string"
        format: "date-time"
        example: "2020/01/06T14:00:00.352"
        description: "Timestamp of when the eligibility status was last updated"
      hmrcHouseholdIdentifier:
        type: "string"
        example: "4c697b0a-5709-423b-8e31-b63796cdca7f"
        description: "Household identifier returned from HMRC"
      id:
        type: "string"
        format: "uuid"
        example: "96c3f8c0-f6d9-4ad4-9ed9-72fcbd8d692d"
        description: "The claim's unique id."
      initialIdentityAndEligibilityResponse:
        description: "The initial identity and eligibility response that was performed\
          \ when the claimant first applied."
        $ref: "#/definitions/CombinedIdentityAndEligibilityResponse"
    title: "ClaimDTO"
    description: "An existing claim for Apply for healthy start."
  ClaimResultDTO:
    type: "object"
    properties:
      claimStatus:
        type: "string"
        description: "The status of the claim"
        enum:
        - "REJECTED"
        - "NEW"
        - "PENDING"
        - "ACTIVE"
        - "PENDING_EXPIRY"
        - "EXPIRED"
        - "ERROR"
      claimUpdated:
        type: "boolean"
        description: "True if an existing, active, claim was updated. May be null\
          \ if a new claim is created."
      eligibilityStatus:
        type: "string"
        description: "The eligibility status of the claim"
        enum:
        - "ELIGIBLE"
        - "INELIGIBLE"
        - "PENDING"
        - "NO_MATCH"
        - "ERROR"
        - "DUPLICATE"
      updatedFields:
        type: "array"
        description: "List of fields that were updated in the existing claim. May\
          \ be null if a new claim is created."
        items:
          type: "string"
      verificationResult:
        description: "The result of verifying the claimant's details"
        $ref: "#/definitions/VerificationResult"
      voucherEntitlement:
        description: "Details of the vouchers that the claimant is entitled to"
        $ref: "#/definitions/VoucherEntitlementDTO"
    title: "ClaimResultDTO"
  ClaimantDTO:
    type: "object"
    properties:
      address:
        description: "The address of the claimant"
        $ref: "#/definitions/AddressDTO"
      dateOfBirth:
        type: "string"
        format: "date"
        example: "1985-12-30"
        description: "The date of birth, in the format YYYY-MM-DD"
      emailAddress:
        type: "string"
        example: "test@email.com"
        description: "The claimant's email address. e.g. test@email.com"
        minLength: 0
        maxLength: 256
        pattern: "(^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\\.[a-zA-Z0-9-.]+$)"
      expectedDeliveryDate:
        type: "string"
        format: "date"
        example: "2020-06-28"
        description: "If the claimant is pregnant, this is the expected date of delivery\
          \ (due date) of their baby, in the format YYYY-MM-DD. The due date must\
          \ be between one month in the past and 8 months in the future."
      firstName:
        type: "string"
        example: "Jo"
        description: "First (given) name"
        minLength: 1
        maxLength: 500
      initiallyDeclaredChildrenDob:
        type: "array"
        example:
        - "2018-01-30"
        - "2019-12-31"
        description: "The dates of birth of the claimant's declared children (if they\
          \ have any)"
        items:
          type: "string"
      lastName:
        type: "string"
        example: "Bloggs"
        description: "Last (surname or family) name"
        minLength: 1
        maxLength: 500
      nino:
        type: "string"
        example: "QQ123456C"
        description: "National Insurance number"
        pattern: "^(?!BG|GB|NK|KN|TN|NT|ZZ)[A-CEGHJ-PR-TW-Z][A-CEGHJ-NPR-TW-Z](\\\
          d{6})[A-D]$"
      phoneNumber:
        type: "string"
        example: "+447123456789"
        description: "The claimant's UK phone number. Must be in +44 format, e.g.\
          \ +447123456789"
        pattern: "^\\+44\\d{9,10}$"
    title: "ClaimantDTO"
    description: "A claimant for help to buy healthy foods."
  CombinedIdentityAndEligibilityResponse:
    type: "object"
    properties:
      addressLine1Match:
        type: "string"
        enum:
        - "matched"
        - "not_matched"
        - "not_held"
        - "not_supplied"
        - "invalid_format"
        - "not_set"
      deathVerificationFlag:
        type: "string"
        enum:
        - "n/a"
        - "death_not_verified"
        - "limited_supporting_documentation"
        - "partial_supporting_documentation"
        - "full_supporting_documentation"
      dobOfChildrenUnder4:
        type: "array"
        items:
          type: "string"
      dwpHouseholdIdentifier:
        type: "string"
      eligibilityStatus:
        type: "string"
        enum:
        - "confirmed"
        - "not_confirmed"
        - "not_set"
      emailAddressMatch:
        type: "string"
        enum:
        - "matched"
        - "not_matched"
        - "not_held"
        - "not_supplied"
        - "invalid_format"
        - "not_set"
      hmrcHouseholdIdentifier:
        type: "string"
      identityStatus:
        type: "string"
        enum:
        - "matched"
        - "not_matched"
      mobilePhoneMatch:
        type: "string"
        enum:
        - "matched"
        - "not_matched"
        - "not_held"
        - "not_supplied"
        - "invalid_format"
        - "not_set"
      postcodeMatch:
        type: "string"
        enum:
        - "matched"
        - "not_matched"
        - "not_held"
        - "not_supplied"
        - "invalid_format"
        - "not_set"
      pregnantChildDOBMatch:
        type: "string"
        enum:
        - "matched"
        - "not_matched"
        - "not_held"
        - "not_supplied"
        - "invalid_format"
        - "not_set"
      qualifyingBenefits:
        type: "string"
        enum:
        - "universal_credit"
        - "employment_and_support_allowance"
        - "income_support"
        - "jobseekers_allowance"
        - "pension_credit"
        - "child_tax_credit"
        - "not_set"
    title: "CombinedIdentityAndEligibilityResponse"
  EligibilityOverrideDTO:
    type: "object"
    properties:
      childrenDob:
        type: "array"
        example:
        - "2018-01-30"
        - "2019-12-31"
        description: "The dates of birth of the claimant's children (if none then\
          \ an empty list must be passed)"
        items:
          type: "string"
      eligibilityOutcome:
        type: "string"
        example: "confirmed"
        description: "Overrides the eligibility outcome from eligibility service"
        enum:
        - "confirmed"
        - "not_confirmed"
        - "not_set"
      overrideUntil:
        type: "string"
        format: "date"
        example: "2025-05-17"
        description: "The date at which the override expires"
    title: "EligibilityOverrideDTO"
    description: "Used to override eligibility decision from eligibility service"
  ErrorResponse:
    type: "object"
    properties:
      fieldErrors:
        type: "array"
        items:
          $ref: "#/definitions/FieldError"
      message:
        type: "string"
      requestId:
        type: "string"
      status:
        type: "integer"
        format: "int32"
      timestamp:
        type: "string"
    title: "ErrorResponse"
    description: "The format of all error responses"
  FieldError:
    type: "object"
    properties:
      field:
        type: "string"
      message:
        type: "string"
    title: "FieldError"
  NewClaimDTO:
    type: "object"
    properties:
      claimant:
        description: "The person making the claim"
        $ref: "#/definitions/ClaimantDTO"
      deviceFingerprint:
        type: "object"
        description: "The fingerprint of the device used to make the claim, as best\
          \ it can be identified. Probably a collection of header values."
      eligibilityOverride:
        description: "Eligibility override decision based on eligibility outcome and\
          \ until date"
        $ref: "#/definitions/EligibilityOverrideDTO"
      webUIVersion:
        type: "string"
        example: 1.0
        description: "The version of the web-ui application used to create this request.\
          \ Identifies which version of the Terms and Conditions the applicant accepted."
    title: "NewClaimDTO"
    description: "A claim (application) for help to buy healthy foods. Contains all\
      \ details that need to be persisted as part of the application."
  VerificationResult:
    type: "object"
    properties:
      addressLine1Match:
        type: "string"
        enum:
        - "matched"
        - "not_matched"
        - "not_held"
        - "not_supplied"
        - "invalid_format"
        - "not_set"
      deathVerificationFlag:
        type: "string"
        enum:
        - "n/a"
        - "death_not_verified"
        - "limited_supporting_documentation"
        - "partial_supporting_documentation"
        - "full_supporting_documentation"
      eligibilityOutcome:
        type: "string"
        enum:
        - "confirmed"
        - "not_confirmed"
        - "not_set"
      emailAddressMatch:
        type: "string"
        enum:
        - "matched"
        - "not_matched"
        - "not_held"
        - "not_supplied"
        - "invalid_format"
        - "not_set"
      identityOutcome:
        type: "string"
        enum:
        - "matched"
        - "not_matched"
      isPregnantOrAtLeast1ChildMatched:
        type: "boolean"
      mobilePhoneMatch:
        type: "string"
        enum:
        - "matched"
        - "not_matched"
        - "not_held"
        - "not_supplied"
        - "invalid_format"
        - "not_set"
      postcodeMatch:
        type: "string"
        enum:
        - "matched"
        - "not_matched"
        - "not_held"
        - "not_supplied"
        - "invalid_format"
        - "not_set"
      pregnantChildDOBMatch:
        type: "string"
        enum:
        - "matched"
        - "not_matched"
        - "not_held"
        - "not_supplied"
        - "invalid_format"
        - "not_set"
      qualifyingBenefits:
        type: "string"
        enum:
        - "universal_credit"
        - "employment_and_support_allowance"
        - "income_support"
        - "jobseekers_allowance"
        - "pension_credit"
        - "child_tax_credit"
        - "not_set"
    title: "VerificationResult"
    description: "The result of verifying the claimant's details"
  VoucherEntitlementDTO:
    type: "object"
    properties:
      singleVoucherValueInPence:
        type: "integer"
        format: "int32"
        example: 310
        description: "The financial value of a single voucher"
      totalVoucherEntitlement:
        type: "integer"
        format: "int32"
        example: 4
        description: "The total number of vouchers the claimant is entitled to"
      totalVoucherValueInPence:
        type: "integer"
        format: "int32"
        example: 1240
        description: "The sum total value of all vouchers the claimant is entitled\
          \ to"
      vouchersForChildrenBetweenOneAndFour:
        type: "integer"
        format: "int32"
        example: 1
        description: "The number of vouchers for children between one and 4 years\
          \ old"
      vouchersForChildrenUnderOne:
        type: "integer"
        format: "int32"
        example: 2
        description: "The number of vouchers for children under one year old"
      vouchersForPregnancy:
        type: "integer"
        format: "int32"
        example: 1
        description: "The number of vouchers for pregnancy"
    title: "VoucherEntitlementDTO"