openapi: 3.2.0
info:
  title: Hostfully Jobs API
  license:
    name: Apache 2.0
    url: https://www.hostfully.com/
  version: v3.0.1
servers:
- url: https://sandbox-api.hostfully.com
security:
- JWT-Authentication: []
- Agency-API-key: []
tags:
- name: Jobs
paths:
  /api/v3.3/jobs/{jobUid}:
    get:
      tags:
      - Jobs
      summary: Get a job
      description: Retrieve the job identified by the provided UID.
      operationId: getOne_11
      parameters:
      - name: jobUid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/JobApiResponseWrapperJobApi3_1Dto'
    put:
      tags:
      - Jobs
      summary: Update a job
      description: Update the job identified by the provided UID using the given request data.
      operationId: put_11
      parameters:
      - name: jobUid
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobApi3_1UpdatingDto'
        required: true
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/JobApiResponseWrapperJobApi3_1Dto'
    delete:
      tags:
      - Jobs
      summary: Delete a job
      description: Delete the job identified by the given UID.
      operationId: delete_14
      parameters:
      - name: jobUid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                type: object
  /api/v3.3/jobs/{jobUid}/mark-as-done:
    post:
      tags:
      - Jobs
      summary: Mark job as done
      description: Changes the status of the job to 'DONE'.
      operationId: markAsDone
      parameters:
      - name: jobUid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
  /api/v3.3/jobs/{jobUid}/decline:
    post:
      tags:
      - Jobs
      summary: Decline a job
      description: Changes the status of the job to 'DECLINED'.
      operationId: declineJob
      parameters:
      - name: jobUid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
  /api/v3.3/jobs/{jobUid}/accept:
    post:
      tags:
      - Jobs
      summary: Accept a job
      description: Changes the status of the job to 'ACCEPTED'.
      operationId: acceptJob
      parameters:
      - name: jobUid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
  /api/v3.3/jobs:
    get:
      tags:
      - Jobs
      summary: Fetches jobs by provided filter
      description: Sorts by jobStartDate in ascending order
      operationId: getAll_18
      parameters:
      - name: propertiesUids
        in: query
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
      - name: statuses
        in: query
        required: false
        schema:
          uniqueItems: true
          type: array
          items:
            type: string
            enum:
            - NEW
            - SCHEDULED
            - DONE
            - CANCELLED
      - name: from
        in: query
        required: true
        schema:
          type: string
          format: date
        example: '2025-01-01'
      - name: to
        in: query
        required: true
        schema:
          type: string
          format: date
        example: '2025-01-10'
      - name: modifiedSince
        in: query
        required: true
        schema:
          type: string
          format: date
        example: '2025-01-10'
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/JobsApiResponseWrapperJobApi3_1Dto'
    post:
      tags:
      - Jobs
      summary: Create a new job
      description: Create a job using the provided request data.
      operationId: post_15
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobApi3_1AddingDto'
        required: true
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/JobApiResponseWrapperJobApi3_1Dto'
components:
  schemas:
    JobsApiResponseWrapperJobApi3_1Dto:
      type: object
      properties:
        jobs:
          type: array
          items:
            $ref: '#/components/schemas/JobApi3_1Dto'
        _metadata:
          $ref: '#/components/schemas/Api3ResponseMetadata'
    JobApiResponseWrapperJobApi3_1Dto:
      type: object
      properties:
        job:
          $ref: '#/components/schemas/JobApi3_1Dto'
    JobApi3_1UpdatingDto:
      type: object
      properties:
        status:
          type: string
          enum:
          - NEW
          - SCHEDULED
          - DONE
          - CANCELLED
        startLocalDateTime:
          type: string
          example: '2026-04-20T11:52:36'
        endLocalDateTime:
          type: string
          example: '2026-04-20T11:52:36'
        notes:
          type: string
        unitUid:
          type: string
    Api3ResponseMetadata:
      type: object
      properties:
        count:
          type: integer
          format: int32
        totalCount:
          type: integer
          format: int32
    JobApi3_1AddingDto:
      required:
      - endLocalDateTime
      - propertyUid
      - serviceUid
      - startLocalDateTime
      - status
      type: object
      properties:
        status:
          type: string
          enum:
          - NEW
          - SCHEDULED
          - DONE
          - CANCELLED
        propertyUid:
          type: string
        serviceUid:
          type: string
        leadUid:
          type: string
        startLocalDateTime:
          type: string
          example: '2026-04-20T11:52:36'
        endLocalDateTime:
          type: string
          example: '2026-04-20T11:52:36'
        notes:
          type: string
        unitUid:
          type: string
    JobApi3_1Dto:
      type: object
      properties:
        uid:
          type: string
        status:
          type: string
          enum:
          - NEW
          - SCHEDULED
          - DONE
          - CANCELLED
        propertyUid:
          type: string
        serviceUid:
          type: string
        leadUid:
          type: string
        startZonedDateTime:
          type: string
          format: date-time
        endZonedDateTime:
          type: string
          format: date-time
        startLocalDateTime:
          type: string
          example: '2026-04-20T11:52:36'
        endLocalDateTime:
          type: string
          example: '2026-04-20T11:52:36'
        notes:
          type: string
        modified:
          type: string
          example: '2026-04-20T11:52:36'
        unitUid:
          type: string
        acceptedLocalDateTime:
          type: string
          example: '2026-04-20T11:52:36'
        statusUpdateUtcDateTime:
          type: string
          example: '2026-04-20T11:52:36'
  securitySchemes:
    JWT-Authentication:
      type: apiKey
      description: OAuth Access Token
      name: Authorization
      in: header
    Agency-API-key:
      type: apiKey
      description: API Key
      name: X-HOSTFULLY-APIKEY
      in: header
externalDocs:
  description: Hostfully Documentation
  url: https://dev.hostfully.com/v3.0/reference
x-readme:
  explorer-enabled: true
  proxy-enabled: true