AlayaCare Form Submissions API

openapi: 3.2.0
info:
  version: 1.0.0
  title: AlayaCare Forms Form Submissions API
  description: "**Internal IDs:**\nThe following terms are used to reference IDs that identify resources in AlayaCare:\n- account_id\n- client_user_id\n\n**External IDs:**\nExternal IDs are required to be unique.\nNo other assumptions are made regarding their form; they are treated as strings. \n\nThe following terms are used to reference IDs that identify resources in systems external to AlayaCare:\n- external_client_id\n- external_employee_id\n\n**Remarks**\n- All dates must be in ISO 8601 format.\n- Required fields marked with `*` cannot be null.\n"
servers:
- url: https://homecare.alayacare.ca/ext/api/v2/tasks/forms20
security:
- basicAuth: []
tags:
- name: Form Submissions
paths:
  /submissions:
    get:
      tags:
      - Form Submissions
      summary: 'Get a list of submissions.

        '
      description: "* Only form submissions that the current user can view will be returned.\n* Results are ordered by the form submission ID in ascending order by default.\n* Requires one of the following ACLs:\n  - `ACL_PATROL_CLIENT_REPORTS_VIEW`\n  - `ACL_CLIENT_SHIFTREPORT_VIEW`\n  - `ACL_CLIENT_REPORTS_VIEW`\n  - `ACL_CLIENT_REPORTS_HISTORICAL_VIEW`\n* `account_id` and `external_client_id` are mutually exclusive.\n* `create_user_id` and `external_employee_id` are mutually exclusive.\n* Can return only up to 2 weeks data.\n"
      parameters:
      - name: create_user_id
        in: query
        description: Filter by create user ID
        schema:
          type: integer
      - name: external_employee_id
        in: query
        description: Filter by external employee ID
        schema:
          type: string
      - name: account_id
        in: query
        description: Filter by AlayaCare client or facility ID
        schema:
          type: integer
      - name: external_client_id
        in: query
        description: Filter by external client ID
        schema:
          type: string
      - name: submitted_from
        in: query
        description: Filter by creation date greater or equal than specified value. If not specified, the default date will be today.
        schema:
          type: string
          format: date-time
      - name: submitted_to
        in: query
        description: Filter by creation date less or equal than specified value. If not specified, the default date will be 2 weeks from the start date
        schema:
          type: string
          format: date-time
      - name: form_id
        in: query
        description: Filter by form ID
        schema:
          type: integer
      - name: schema_id
        in: query
        description: Filter by the `schema_id` to get submissions of all versions of the same form
        schema:
          type: string
      - name: with_fields
        in: query
        description: Include the submission fields in the response. By default fields are not included
        schema:
          type: boolean
      - name: work_session_id
        in: query
        description: Filter by work session ID
        schema:
          type: integer
      - name: client_group_id[]
        in: query
        description: Filter by client's group ID
        schema:
          type: integer
      - name: client_group_id_mode
        in: query
        description: 'The logical mode to use for client_group_id.

          ''all'' results in a logical ''and''

          ''any'' results in a logical ''or''

          '
        schema:
          type: string
          default: any
          enum:
          - all
          - any
      - name: visit_id
        in: query
        description: Filter by visit ID
        schema:
          type: integer
      - name: form_type
        in: query
        description: Filter by form type
        schema:
          type: string
      - name: asc
        in: query
        description: Order for sorting
        schema:
          type: boolean
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/count'
      responses:
        '200':
          description: A list of form submissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmissionList'
        '400':
          $ref: '#/components/responses/ErrorResponseInvalidRequest'
        '401':
          $ref: '#/components/responses/AuthChallenge'
        '403':
          $ref: '#/components/responses/PermissionError'
  /submissions/{submission_id}:
    get:
      tags:
      - Form Submissions
      summary: 'Get form submission details by form submission ID.

        '
      description: "* Requires one of the following ACLs:\n  - `ACL_PATROL_CLIENT_REPORTS_VIEW`\n  - `ACL_CLIENT_SHIFTREPORT_VIEW`\n  - `ACL_CLIENT_REPORTS_VIEW`\n  - `ACL_CLIENT_REPORTS_HISTORICAL_VIEW`\n"
      parameters:
      - name: submission_id
        description: AlayaCare ID of the submission
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: The content of the submission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Submission'
        '401':
          $ref: '#/components/responses/AuthChallenge'
        '403':
          $ref: '#/components/responses/PermissionError'
        '404':
          $ref: '#/components/responses/ErrorResponseNotFound'
  /submissions/count_visit_submissions:
    get:
      tags:
      - Form Submissions
      summary: 'Get the count of approved form submissions and the total count of form submissions by work session.

        '
      description: "* Requires one of the following ACLs:\n  - `ACL_PATROL_REPORT_VISIT_VIEW`\n  - `ACL_CLIENT_SHIFTREPORT_VIEW`\n* `user_id` and `external_employee_id` are mutually exclusive.\n"
      parameters:
      - name: work_session_id
        description: One or more work_session_ids. Use parameter multiple times for multiple work_session_ids
        in: query
        required: true
        schema:
          type: array
          format: multi
          minItems: 1
          items:
            type: integer
      - name: include_admin
        description: Include in the count all submissions linked with a form that has the flag `admin_eye_only` set
        schema:
          type: boolean
          default: false
        in: query
      - name: user_id
        description: Include in the count only submissions that have the `created_user_id` match the `user_id` argument
        schema:
          type: integer
        in: query
      - name: external_employee_id
        description: Include in the count only submissions created by an employee matching the external employee id
        schema:
          type: string
        in: query
      responses:
        '200':
          description: An object with work_session_id counts. Uses `work_session_id` as key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VisitSubmissionCountResponse'
        '400':
          $ref: '#/components/responses/ErrorResponseInvalidRequest'
        '401':
          $ref: '#/components/responses/AuthChallenge'
        '403':
          $ref: '#/components/responses/PermissionError'
  /submissions/{submission_id}/submission_revision:
    get:
      tags:
      - Form Submissions
      summary: 'Get form submission change logs.

        '
      description: "* Requires one of the following ACLs:\n  - `ACL_PATROL_CLIENT_REPORTS_VIEW`\n  - `ACL_CLIENT_SHIFTREPORT_VIEW`\n  - `ACL_CLIENT_REPORTS_VIEW`\n  - `ACL_CLIENT_REPORTS_HISTORICAL_VIEW`\n"
      parameters:
      - name: submission_id
        description: Form submission ID
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Get the status changes for a form submission.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    form_id:
                      type: integer
                      example: 1
                    id:
                      type: integer
                      example: 123
                    revision:
                      type: integer
                      example: 1
                    status:
                      type: string
                      example: unapproved
                    update_user:
                      type: object
                      properties:
                        full_name:
                          type: string
                          example: John Doe
                        id:
                          type: integer
                          example: 101
                    updated_at:
                      type: string
        '401':
          $ref: '#/components/responses/AuthChallenge'
        '403':
          $ref: '#/components/responses/PermissionError'
        '404':
          $ref: '#/components/responses/ErrorResponseNotFound'
components:
  schemas:
    SubmissionList:
      description: A list of form submissions
      type: object
      required:
      - count
      - page
      - total_pages
      - items_per_page
      - items
      properties:
        count:
          description: Number of items in the response
          type: integer
          example: 10
        page:
          description: Current page number
          type: integer
          example: 1
        total_pages:
          description: Total number of pages available
          type: integer
          example: 1
        items_per_page:
          description: Maximum number of item per page
          type: integer
          example: 10
        items:
          type: array
          items:
            $ref: '#/components/schemas/Submission'
    SubmissionFieldRead:
      description: The submission field schema containing the form values.
      type: object
      required:
      - field_id
      - field_value
      properties:
        field_id:
          description: Unique ID of the field
          type: integer
          example: 1
        field_label:
          description: The name of the field
          type: string
          example: Agency Name
        field_type:
          description: The type of the field
          type: string
          example: textarea
        field_value:
          description: "An object containing the field value.\nThis is a polymorphic field and the schema changes with the type.\n\n checkbox => boolean\n \n date => string (format: date)\n \n demographics => uses simple type schemas: autocomplete, boolean, list, list_multiple, number, text, textarea, autocomplete\n \n drawing => string (format: url)\n \n hyperlink => string (format: url)\n \n list => FieldValueList\n \n list_multiple => FieldValueListMultiple\n \n grid_fixed => FieldValueListMultiple\n \n grid_flexible => FieldValueListMultiple\n \n medication => FieldValueEntity\n \n medical_history => FieldValueEntity\n \n number => number\n \n picture => string (format: url)\n \n progress_notes => string\n \n risk => FieldValueEntity\n \n signature => string (format: url)\n \n text => string\n \n textarea => string\n \n time => string (format: time)\n \n vital => FieldValueEntity\n"
          type: string
          example: Text field value
    ErrorResponse:
      description: Error response
      type: object
      properties:
        code:
          type: integer
          description: Response code
        message:
          type: string
          description: Detailed error message
      required:
      - code
      - message
    Submission:
      description: The full content of a submission
      type: object
      required:
      - id
      - form_id
      - account_id
      - status
      - crated_at
      - create_user_id
      - updated_at
      - update_user_id
      properties:
        id:
          description: AlayaCare ID of a submission
          type: integer
          example: 1
        guid:
          description: AlayaCare guid of a submission
          type: integer
          example: 1
        created_at:
          description: Timestamp of form creation (ISO 8061).
          type: string
          format: date-time
        create_user_id:
          description: AlayaCare employee ID of form author
          type: integer
          example: 101
        form_id:
          description: The form ID this submission corresponds to
          type: integer
          example: 100
        account_id:
          description: The client or facility ID the submission is attached to
          type: integer
          example: 1001
        service_id:
          description: The service ID the submission is attached to
          type: integer
          example: 1317
        visit_id:
          description: The visit ID associated to the submission
          type: integer
          example: 1
        is_visit_linked_manually:
          description: Whether or not the associated visit_id is added manually
          type: boolean
        status:
          $ref: '#/components/schemas/SubmissionStatus'
        updated_at:
          description: Timestamp of form update (ISO 8061).
          type: string
          format: date-time
        update_user_id:
          description: AlayaCare ID of employee who made the update
          type: integer
          example: 101
        coords:
          $ref: '#/components/schemas/SubmissionCoord'
        work_session_id:
          description: The ID of the work session in which the submission was created.
          type: integer
          example: 2
        task_id:
          description: The ID of the task to which the form submission was attached.
          type: integer
        form_name:
          description: The name of the form
          type: string
          example: Wound Care Assessment
        approved_at:
          description: Timestamp of form approval (ISO 8061).
          type: string
          format: date-time
        approved_by:
          description: AlayaCare ID of employee who approved the form
          type: integer
          example: 101
        pdf_url:
          description: 'URL of the PDF version of the submission. After the submission is created or

            updated, this property is `null` while the PDF is being created. The status

            of the print job can be queried at the printing service using `print_job_id`.

            '
          type: string
          example: https://tenant.alayacare.ca/api/v1/files/documents/19fa5d46-d33f-43a6-9750-6823226afdf7.
          format: url
        print_job_id:
          description: 'ID of the print job that''s generating the PDF version of this submission.

            This should be `null` if no printing job is currently active, but a stale ID

            here is possible and it should be then ignored.

            '
          type: string
          format: uuid
        fields:
          description: The fields and their assigned value
          type: array
          items:
            $ref: '#/components/schemas/SubmissionFieldRead'
        hidden_fields:
          type: array
          description: Array of field IDs of the form that were not shown to the user.
          items:
            type: object
            required:
            - field_id
            properties:
              field_id:
                description: ID of the form field
                type: integer
                example: 99
        create_user:
          $ref: '#/components/schemas/UserShortSchema'
        update_user:
          $ref: '#/components/schemas/UserShortSchema'
        approved_user:
          $ref: '#/components/schemas/UserShortSchema'
        account:
          $ref: '#/components/schemas/AccountShortSchema'
        branch:
          $ref: '#/components/schemas/BranchSchema'
        visit:
          $ref: '#/components/schemas/VisitSchema'
    UserShortSchema:
      description: A user
      type: object
      properties:
        id:
          type: integer
          description: The ID of the user
          example: 1
        guid:
          type: integer
          description: The guid of the user
          example: 100
        profile_id:
          type: integer
          description: The guid of the user
          example: 123
        name:
          type: string
          description: The name of the user
          example: John Snow
        roles:
          type: array
          description: roles of the user
          items:
            type: object
            properties:
              id:
                type: integer
                description: The ID of the role
                example: 1
              name:
                type: string
                description: The name of the role
                example: admin
    SubmissionStatus:
      description: The status of a form submission
      type: string
      default: unapproved
      enum:
      - draft
      - unapproved
      - approved
      - verification
      - job_pending
      - to_delete
      - correcting
      - sent
      - inactive
      - correction_number_reqquired
      - sent_inactive
    BranchSchema:
      type: object
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: Branch A
    VisitSubmissionCount:
      description: Count of form submissions for a visit.
      type: object
      properties:
        approved_count:
          description: Count of approved form submissions for a visit.
          type: integer
        total_count:
          description: Count of total form submissions for a visit.
          type: integer
    VisitSubmissionCountResponse:
      description: Schema for the visit submission count response.
      properties:
        default:
          $ref: '#/components/schemas/VisitSubmissionCount'
      additionalProperties:
        $ref: '#/components/schemas/VisitSubmissionCount'
      example:
        submission_counts:
          12345:
            approved_count: 2
            total_count: 5
          12346:
            approved_count: 0
            total_count: 2
    VisitSchema:
      type: object
      properties:
        start_at:
          type: integer
          example: 1642053489
        end_at:
          type: integer
          example: 1642053489
        employee_name:
          type: string
          example: John Doe
    SubmissionCoord:
      description: Create a record of the GPS coordinates of the user when the submission was created.
      type: object
      required:
      - lat
      - lng
      - measured_at
      properties:
        accuracy:
          description: The accuracy of the GPS coordinates, in meters.
          type: number
          example: 123.4
        lat:
          description: The GPS latitude.
          type: number
          example: 45.516136
        lng:
          description: The GPS longitude.
          type: number
          example: -73.65683
        measured_at:
          description: The date-time at which the coordinates were measured.
          type: string
          format: date-time
          example: '2017-07-08T13:30:00+00:00'
    AccountShortSchema:
      type: object
      description: A client
      properties:
        id:
          type: integer
          description: The ID of the client or facility
          example: 10
        guid:
          type: integer
          description: The guid of the client or facility
          example: 12345
        profile_id:
          type: integer
          description: The profile ID of the client or facility
          example: 120
        name:
          type: string
          description: The name of the client or facility
          example: Mary Jane
        external_id:
          type: string
          description: The external ID of the client or facility
          example: ex-123
  responses:
    PermissionError:
      description: Permission error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 403
            message: You do not have the required permissions to perform this action.
    AuthChallenge:
      description: Authentication required.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 401
            message: Please verify your access level for this url.
    ErrorResponseInvalidRequest:
      description: Invalid request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 400
            message: Only one of either `account_id` or `external_client_id` should be specified.
    ErrorResponseNotFound:
      description: Not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 404
            message: Form Submission not found.
  parameters:
    page:
      name: page
      description: Filter by page number. If not specified will default to 1
      in: query
      schema:
        type: integer
        default: 1
    count:
      name: count
      description: Number of items per page. If not specified will default to 100
      in: query
      schema:
        type: integer
        default: 100
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Basic HTTP auth over https