---
swagger: "2.0"
info:
  description: <p>Welcome to the ACC Medical Certificate API. This is a secondary interaction (linked to a Claim) if:<br>1. A patient:<br>• Needs time off work beyond the first two weeks;<br>• Needs additional support to operate in life or getting to / from work;<br>• Presents additional complications that need to be considered;<br>2. The Provider:<br>• Needs extra support services to assist with diagnosis.<br>This can only be generated by a Doctor or Nurse Practitioner. They are mostly generated with the claim at the patient first visit but can be generated as part of a subsequent visit or by a different registered provider at a subsequent visit.</p>
  version: 2.0.0
  title: ACC Medical Certificate API
  termsOfService: https://developer.acc.co.nz/terms-conditions
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
host: apiservicesnpe.acc.co.nz
basePath: /api/v2
tags:
- name: Medical Certificates
  description: Medical Certificates Controller
schemes:
  - https
securityDefinitions:
  apiKeyHeader:
    type: apiKey
    name: apikey
    in: header
security:
  - apiKeyHeader: []
paths:
  /claims/medical-certificates:
    post:
      tags:
      - Medical Certificates
      summary: Create a new Medical Certificate.
      description: '<p><b>Allows software vendors to create a medical certificate with ACC.</b><br> The medical certificate is a secondary interaction (linked to a Claim) if<br>1. A patient:<br>• Needs time off work beyond the first two weeks;<br>• Needs additional support to operate in life or getting to / from work;<br>• Presents additional complications that need to be considered;<br>2. The Provider:<br>• Needs extra support services to assist with diagnosis.<br>This can only be generated by a Doctor or Nurse Practitioner. They are mostly generated with the claim at the patient first visit but can be generated as part of a subsequent visit or by a different registered provider at a subsequent visit.</p>'
      operationId: medical-certificates
      consumes:
      - application/json
      produces:
      - application/json
      - '*/*'
      parameters:
      - in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/MedicalCertificate'
      responses:
        200:
          description: OK
          schema:
            $ref: '#/definitions/MedicalCertificateCreatedResponse'
        202:
          description: Accepted
          schema:
            $ref: '#/definitions/MedicalCertificateCreatedResponse'
        400:
          description: 'Bad Request: invalid data'
          schema:
            $ref: '#/definitions/ApiException'
        401:
          description: 'Unauthorized: authentication error'
          schema:
            $ref: '#/definitions/ApiException'
        403:
          description: 'Forbidden: authorization error'
          schema:
            $ref: '#/definitions/ApiException'
        404:
          description: Not Found
          schema:
            $ref: '#/definitions/ApiException'
        500:
          description: Internal Server Error
          schema:
            $ref: '#/definitions/ApiException'
definitions:
  AccAssistance:
    type: object
    properties:
      issuesDetails:
        type: string
        description: What complications or other issues are affecting recovery or rehabilitation?
      otherComments:
        type: string
        description: What other assistance (equipment, home help, transport) should the patient discuss with a case manager?
    example:
      issuesDetails: issuesDetails
      otherComments: otherComments
  AccContact:
    type: object
    properties:
      anyDay:
        type: boolean
        description: Only required when contactRequired is true.
      preferredContactDay:
        type: array
        description: Only required when contactRequired is true and anyDay is false.
        items:
          type: string
          enum:
          - Monday
          - Tuesday
          - Wednesday
          - Thursday
          - Friday
      contactComments:
        type: string
        description: Optional when contactRequired is true.
    example:
      contactComments: contactComments
      preferredContactDay:
      - Monday
      - Monday
      anyDay: True
  Address:
    type: object
    required:
    - city
    - country
    - line1
    - postCode
    - type
    properties:
      type:
        type: string
        enum:
        - Home
        - Postal
      line1:
        type: string
      line2:
        type: string
      suburb:
        type: string
      city:
        type: string
      postCode:
        type: string
      country:
        type: string
    example:
      country: country
      city: city
      suburb: suburb
      postCode: postCode
      type: Home
      line2: line2
      line1: line1
  ApiError:
    type: object
    properties:
      field:
        type: string
      message:
        type: string
  ApiException:
    type: object
    properties:
      errors:
        type: array
        items:
          $ref: '#/definitions/ApiError'
  Contact:
    type: object
    properties:
      emailAddress:
        type: string
      mobilePhone:
        type: string
      homePhone:
        type: string
      workPhone:
        type: string
    example:
      emailAddress: emailAddress
      mobilePhone: mobilePhone
      homePhone: homePhone
      workPhone: workPhone
  DateRange:
    type: object
    required:
    - fromDate
    - toDate
    properties:
      fromDate:
        type: string
        format: date
        description: Date ranges must have no gaps and no overlaps.
      toDate:
        type: string
        format: date
        description: Date ranges must have no gaps and no overlaps.
    description: A valid date is required for each incapacity type selected.
    example:
      fromDate: 2000-01-23
      toDate: 2000-01-23
  Declaration:
    type: object
    required:
    - providerDeclaration
    properties:
      providerDeclaration:
        type: string
        format: date
        description: The date the form was submitted.
    example:
      providerDeclaration: 2000-01-23
  Diagnosis:
    type: object
    required:
    - diagnosisAction
    - diagnosisCode
    - diagnosisCodeType
    - diagnosisDescription
    - diagnosisSide
    - primaryDiagnosisIndicator
    properties:
      diagnosisCodeType:
        type: string
        description: See the DiagnosisCodingSystem code tables for valid values.
      diagnosisCode:
        type: string
        description: Alphanumeric, can include '.'
      diagnosisDescription:
        type: string
      diagnosisSide:
        type: string
        enum:
        - left
        - right
        - notApplicable
      diagnosisComment:
        type: string
      diagnosisAction:
        type: string
        enum:
        - add
        - modify
        - delete
      primaryDiagnosisIndicator:
        type: boolean
        description: Select exactly one diagnosis in a request as primary.
    example:
      diagnosisCodeType: diagnosisCodeType
      diagnosisComment: diagnosisComment
      diagnosisAction: add
      diagnosisSide: left
      diagnosisCode: diagnosisCode
      primaryDiagnosisIndicator: True
      diagnosisDescription: diagnosisDescription
  Incapacity:
    type: object
    required:
    - incapacityDateRange
    - incapacityType
    - selectedAlternativeWork
    properties:
      incapacityType:
        type: string
        description: You can select 'fully unfit' no more than once, and 'fit for selected' no more than twice.
        enum:
        - Fitforselectedwork
        - Fullyunfitforwork
      incapacityDateRange:
        $ref: '#/definitions/DateRange'
      incapacityComments:
        type: string
        description: Only required when Fullyunfitforwork is true.
      selectedAlternativeWork:
        $ref: '#/definitions/SelectedAlternativeWork'
    example:
      selectedAlternativeWork:
        restrictedHoursPerDay: 0.8008281904610115
        restrictionComment: restrictionComment
        restrictedDaysPerWeek: 6
        physicalRestrictions:
        - restriction: Lifting
        - restriction: Lifting
      incapacityDateRange:
        fromDate: 2000-01-23
        toDate: 2000-01-23
      incapacityComments: incapacityComments
      incapacityType: Fitforselectedwork
  MedicalCertificate:
    type: object
    required:
    - diagnosis
    - pmsSoftwareName
    - pmsSoftwareVersion
    properties:
      pmsSoftwareName:
        type: string
      pmsSoftwareVersion:
        type: string
      claimNumber:
        type: string
        description: '1-12 alphanumeric characters. Examples: A123456, AA12345, 1234567,
          12345678901, A1234567890 where A represents an alphabetic character and
          each digit represents any digit.'
      declaration:
        $ref: '#/definitions/Declaration'
      diagnosis:
        type: array
        description: If present, this must contain at least one diagnosis. 20 diagnoses permitted.
        items:
          $ref: '#/definitions/Diagnosis'
      patient:
        $ref: '#/definitions/Patient'
      provider:
        $ref: '#/definitions/Provider'
      vendor:
        $ref: '#/definitions/Vendor'
      workCapacity:
        $ref: '#/definitions/WorkCapacity'
    example:
      workCapacity:
        accContact:
          contactComments: contactComments
          preferredContactDay:
          - Monday
          - Monday
          anyDay: True
        incapacity:
        - selectedAlternativeWork:
            restrictedHoursPerDay: 0.8008281904610115
            restrictionComment: restrictionComment
            restrictedDaysPerWeek: 6
            physicalRestrictions:
            - restriction: Lifting
            - restriction: Lifting
          incapacityDateRange:
            fromDate: 2000-01-23
            toDate: 2000-01-23
          incapacityComments: incapacityComments
          incapacityType: Fitforselectedwork
        - selectedAlternativeWork:
            restrictedHoursPerDay: 0.8008281904610115
            restrictionComment: restrictionComment
            restrictedDaysPerWeek: 6
            physicalRestrictions:
            - restriction: Lifting
            - restriction: Lifting
          incapacityDateRange:
            fromDate: 2000-01-23
            toDate: 2000-01-23
          incapacityComments: incapacityComments
          incapacityType: Fitforselectedwork
        contactRequired: True
        reviewIncapacityDate: 2000-01-23
        returnToWork:
          assistanceType: needSupport
          assistanceRequired: True
        accAssistance:
          issuesDetails: issuesDetails
          otherComments: otherComments
      pmsSoftwareVersion: pmsSoftwareVersion
      provider:
        address:
          country: country
          city: city
          suburb: suburb
          postCode: postCode
          type: Home
          line2: line2
          line1: line1
        contact:
          emailAddress: emailAddress
          mobilePhone: mobilePhone
          homePhone: homePhone
          workPhone: workPhone
        details:
          firstName: firstName
          providerId: providerId
          providerTypeCode: providerTypeCode
          surname: surname
          middleName: middleName
      patient:
        address:
          country: country
          city: city
          suburb: suburb
          postCode: postCode
          type: Home
          line2: line2
          line1: line1
        contact:
          emailAddress: emailAddress
          mobilePhone: mobilePhone
          homePhone: homePhone
          workPhone: workPhone
        details:
          accidentDate: 2000-01-23
          firstName: firstName
          surname: surname
          dateOfBirth: 2000-01-23
          middleName: middleName
          nhi: nhi
      vendor:
        hpiOrganisationNumber: hpiOrganisationNumber
        practiceName: practiceName
        hpiFacilityNumber: F2C051, 87
      diagnosis:
      - diagnosisCodeType: diagnosisCodeType
        diagnosisComment: diagnosisComment
        diagnosisAction: add
        diagnosisSide: left
        diagnosisCode: diagnosisCode
        primaryDiagnosisIndicator: True
        diagnosisDescription: diagnosisDescription
      - diagnosisCodeType: diagnosisCodeType
        diagnosisComment: diagnosisComment
        diagnosisAction: add
        diagnosisSide: left
        diagnosisCode: diagnosisCode
        primaryDiagnosisIndicator: True
        diagnosisDescription: diagnosisDescription
      pmsSoftwareName: pmsSoftwareName
      declaration:
        providerDeclaration: 2000-01-23
      claimNumber: claimNumber
  MedicalCertificateCreatedResponse:
    type: object
    properties:
      medicalCertificateId:
        type: string
      medicalCertificate:
        $ref: '#/definitions/MedicalCertificate'
      createdAt:
        type: string
        format: date
      lastUpdate:
        type: string
        format: date
    example:
      createdAt: 2000-01-23
      medicalCertificate:
        workCapacity:
          accContact:
            contactComments: contactComments
            preferredContactDay:
            - Monday
            - Monday
            anyDay: True
          incapacity:
          - selectedAlternativeWork:
              restrictedHoursPerDay: 0.8008281904610115
              restrictionComment: restrictionComment
              restrictedDaysPerWeek: 6
              physicalRestrictions:
              - restriction: Lifting
              - restriction: Lifting
            incapacityDateRange:
              fromDate: 2000-01-23
              toDate: 2000-01-23
            incapacityComments: incapacityComments
            incapacityType: Fitforselectedwork
          - selectedAlternativeWork:
              restrictedHoursPerDay: 0.8008281904610115
              restrictionComment: restrictionComment
              restrictedDaysPerWeek: 6
              physicalRestrictions:
              - restriction: Lifting
              - restriction: Lifting
            incapacityDateRange:
              fromDate: 2000-01-23
              toDate: 2000-01-23
            incapacityComments: incapacityComments
            incapacityType: Fitforselectedwork
          contactRequired: True
          reviewIncapacityDate: 2000-01-23
          returnToWork:
            assistanceType: needSupport
            assistanceRequired: True
          accAssistance:
            issuesDetails: issuesDetails
            otherComments: otherComments
        pmsSoftwareVersion: pmsSoftwareVersion
        provider:
          address:
            country: country
            city: city
            suburb: suburb
            postCode: postCode
            type: Home
            line2: line2
            line1: line1
          contact:
            emailAddress: emailAddress
            mobilePhone: mobilePhone
            homePhone: homePhone
            workPhone: workPhone
          details:
            firstName: firstName
            providerId: providerId
            providerTypeCode: providerTypeCode
            surname: surname
            middleName: middleName
        patient:
          address:
            country: country
            city: city
            suburb: suburb
            postCode: postCode
            type: Home
            line2: line2
            line1: line1
          contact:
            emailAddress: emailAddress
            mobilePhone: mobilePhone
            homePhone: homePhone
            workPhone: workPhone
          details:
            accidentDate: 2000-01-23
            firstName: firstName
            surname: surname
            dateOfBirth: 2000-01-23
            middleName: middleName
            nhi: nhi
        vendor:
          hpiOrganisationNumber: hpiOrganisationNumber
          practiceName: practiceName
          hpiFacilityNumber: F2C051, 87
        diagnosis:
        - diagnosisCodeType: diagnosisCodeType
          diagnosisComment: diagnosisComment
          diagnosisAction: add
          diagnosisSide: left
          diagnosisCode: diagnosisCode
          primaryDiagnosisIndicator: True
          diagnosisDescription: diagnosisDescription
        - diagnosisCodeType: diagnosisCodeType
          diagnosisComment: diagnosisComment
          diagnosisAction: add
          diagnosisSide: left
          diagnosisCode: diagnosisCode
          primaryDiagnosisIndicator: True
          diagnosisDescription: diagnosisDescription
        pmsSoftwareName: pmsSoftwareName
        declaration:
          providerDeclaration: 2000-01-23
        claimNumber: claimNumber
      lastUpdate: 2000-01-23
      medicalCertificateId: medicalCertificateId
  Patient:
    type: object
    required:
    - address
    - details
    properties:
      address:
        $ref: '#/definitions/Address'
      contact:
        $ref: '#/definitions/Contact'
      details:
        $ref: '#/definitions/PatientDetails'
    example:
      address:
        country: country
        city: city
        suburb: suburb
        postCode: postCode
        type: Home
        line2: line2
        line1: line1
      contact:
        emailAddress: emailAddress
        mobilePhone: mobilePhone
        homePhone: homePhone
        workPhone: workPhone
      details:
        accidentDate: 2000-01-23
        firstName: firstName
        surname: surname
        dateOfBirth: 2000-01-23
        middleName: middleName
        nhi: nhi
  PatientDetails:
    type: object
    required:
    - accidentDate
    - dateOfBirth
    - firstName
    - surname
    properties:
      accidentDate:
        type: string
        format: date
      dateOfBirth:
        type: string
        format: date
      nhi:
        type: string
      firstName:
        type: string
      middleName:
        type: string
      surname:
        type: string
    example:
      accidentDate: 2000-01-23
      firstName: firstName
      surname: surname
      dateOfBirth: 2000-01-23
      middleName: middleName
      nhi: nhi
  PhysicalRestrictions:
    type: object
    properties:
      restriction:
        type: string
        enum:
        - Lifting
        - Posture
        - Heavy Physical
        - Repetition
        - Vibration
        - Temperature
        - Driving
        - Prolonged Sitting
        - Prolonged Walking
        - Prolonged Standing
        - Other
    example:
      restriction: Lifting
  Provider:
    type: object
    required:
    - address
    - details
    properties:
      address:
        $ref: '#/definitions/Address'
      contact:
        $ref: '#/definitions/Contact'
      details:
        $ref: '#/definitions/ProviderDetails'
    example:
      address:
        country: country
        city: city
        suburb: suburb
        postCode: postCode
        type: Home
        line2: line2
        line1: line1
      contact:
        emailAddress: emailAddress
        mobilePhone: mobilePhone
        homePhone: homePhone
        workPhone: workPhone
      details:
        firstName: firstName
        providerId: providerId
        providerTypeCode: providerTypeCode
        surname: surname
        middleName: middleName
  ProviderDetails:
    type: object
    required:
    - firstName
    - providerId
    - providerTypeCode
    - surname
    properties:
      providerId:
        type: string
        description: The provider's ACC or HPI number, 1-8 characters.
      providerTypeCode:
        type: string
        description: See the ProviderType code tables for valid values.
      firstName:
        type: string
      middleName:
        type: string
      surname:
        type: string
    example:
      firstName: firstName
      providerId: providerId
      providerTypeCode: providerTypeCode
      surname: surname
      middleName: middleName
  ReturnToWork:
    type: object
    required:
    - assistanceRequired
    properties:
      assistanceRequired:
        type: boolean
        description: Is return to work assistance required?
      assistanceType:
        type: string
        description: Only required when assistanceRequired is true.
        enum:
        - needSupport
        - needClinicalReview
    example:
      assistanceType: needSupport
      assistanceRequired: True
  SelectedAlternativeWork:
    type: object
    properties:
      restrictionComment:
        type: string
        description: Optional if Fitforselectedwork is true.
      restrictedHoursPerDay:
        type: number
        format: double
        description: Optional, values 0.50 through 16.00
      restrictedDaysPerWeek:
        type: integer
        format: int32
        description: Optional, values 1 through 7
      physicalRestrictions:
        type: array
        description: Optional if Fitforselectedwork is true, otherwise not permitted. Any of the listed items can be selected once, up to 11 choices.
        items:
          $ref: '#/definitions/PhysicalRestrictions'
    example:
      restrictedHoursPerDay: 0.8008281904610115
      restrictionComment: restrictionComment
      restrictedDaysPerWeek: 6
      physicalRestrictions:
      - restriction: Lifting
      - restriction: Lifting
  Vendor:
    type: object
    required:
    - hpiOrganisationNumber
    - practiceName
    properties:
      hpiFacilityNumber:
        type: string
        example: F2C051, 87
        description: ID of the facility where the service was provided.
      hpiOrganisationNumber:
        type: string
        description: 1-12 alphanumeric characters, can include '\\'
      practiceName:
        type: string
        description: 1-40 characters.
    example:
      hpiOrganisationNumber: hpiOrganisationNumber
      practiceName: practiceName
      hpiFacilityNumber: F2C051, 87
  WorkCapacity:
    type: object
    required:
    - contactRequired
    - returnToWork
    properties:
      incapacity:
        type: array
        description: You can define up to 3 periods of incapacity. Each one must have a type and a date range.
        items:
          $ref: '#/definitions/Incapacity'
      reviewIncapacityDate:
        type: string
        format: date
        description: The date when ACC should check whether the patient is recovering as expected.
      returnToWork:
        $ref: '#/definitions/ReturnToWork'
      accAssistance:
        $ref: '#/definitions/AccAssistance'
      contactRequired:
        type: boolean
        description: True if the provider wants an ACC case manager to get in touch.
      accContact:
        $ref: '#/definitions/AccContact'
    example:
      accContact:
        contactComments: contactComments
        preferredContactDay:
        - Monday
        - Monday
        anyDay: True
      incapacity:
      - selectedAlternativeWork:
          restrictedHoursPerDay: 0.8008281904610115
          restrictionComment: restrictionComment
          restrictedDaysPerWeek: 6
          physicalRestrictions:
          - restriction: Lifting
          - restriction: Lifting
        incapacityDateRange:
          fromDate: 2000-01-23
          toDate: 2000-01-23
        incapacityComments: incapacityComments
        incapacityType: Fitforselectedwork
      - selectedAlternativeWork:
          restrictedHoursPerDay: 0.8008281904610115
          restrictionComment: restrictionComment
          restrictedDaysPerWeek: 6
          physicalRestrictions:
          - restriction: Lifting
          - restriction: Lifting
        incapacityDateRange:
          fromDate: 2000-01-23
          toDate: 2000-01-23
        incapacityComments: incapacityComments
        incapacityType: Fitforselectedwork
      contactRequired: True
      reviewIncapacityDate: 2000-01-23
      returnToWork:
        assistanceType: needSupport
        assistanceRequired: True
      accAssistance:
        issuesDetails: issuesDetails
        otherComments: otherComments
