BigChange Job Types API

openapi: 3.2.0
info:
  title: BigChange DX Job Types API
  description: Developer Experience API
  version: '1.0'
servers:
- url: https://api.bigchange.com
security:
- bearer: []
tags:
- name: JobTypes
paths:
  /v1/jobTypes:
    get:
      tags:
      - JobTypes
      summary: Get a list of job types
      description: Retrieve a paged collection of job types (required scope jobs:read)
      parameters:
      - name: Customer-Id
        in: header
        description: The customer identifier
        required: true
        schema:
          type: integer
          format: int64
      - name: sortBy
        in: query
        description: The field to sort items in the page by
        schema:
          $ref: '#/components/schemas/JobTypeSortOptions'
      - name: direction
        in: query
        description: The direction to apply the sort
        schema:
          $ref: '#/components/schemas/SortDirection'
      - name: id
        in: query
        description: 'Only return job types where `id` matches the value(s) provided (Max items: 50)'
        schema:
          type: array
          items:
            type: integer
            format: int64
      - name: isTasksEnabled
        in: query
        description: Only return job types where the 'isTaskEnabled' matches the provided value
        schema:
          type: boolean
      - name: pageNumber
        in: query
        description: 'The page number being requested (minimum: 1, maximum: 2147483)'
        schema:
          maximum: 2147483
          minimum: 1
          type: integer
          format: int32
      - name: pageSize
        in: query
        description: 'The page size being requested (minimum: 1, maximum: 1000)'
        schema:
          maximum: 1000
          minimum: 1
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedResponseReadJobTypeModel'
        '400':
          description: Bad Request
          content:
            application/problem+json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ProblemDetails'
                - $ref: '#/components/schemas/HttpValidationProblemDetails'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ProblemDetails'
                - $ref: '#/components/schemas/HttpValidationProblemDetails'
        '500':
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ProblemDetails'
                - $ref: '#/components/schemas/HttpValidationProblemDetails'
      operationId: getV1JobTypes
      x-operation-id-source: derived
  /v1/jobTypes/{jobTypeId}:
    get:
      tags:
      - JobTypes
      summary: Get a job type
      description: Retrieve the details of a single job type (required scope jobs:read)
      parameters:
      - name: Customer-Id
        in: header
        description: The customer identifier
        required: true
        schema:
          type: integer
          format: int64
      - name: jobTypeId
        in: path
        description: The unique identifer of the job type
        required: true
        schema:
          maximum: 9223372036854776000
          minimum: 1
          type: integer
          format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadJobTypeModel'
        '400':
          description: Bad Request
          content:
            application/problem+json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ProblemDetails'
                - $ref: '#/components/schemas/HttpValidationProblemDetails'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ProblemDetails'
                - $ref: '#/components/schemas/HttpValidationProblemDetails'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ProblemDetails'
                - $ref: '#/components/schemas/HttpValidationProblemDetails'
        '500':
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ProblemDetails'
                - $ref: '#/components/schemas/HttpValidationProblemDetails'
      operationId: getV1JobTypesByJobTypeId
      x-operation-id-source: derived
components:
  schemas:
    PagedResponseReadJobTypeModel:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ReadJobTypeModel'
          description: The items returned for the requested page
        pageNumber:
          type: integer
          description: The page number of the response where 1 is the first page
          format: int32
          example: 2
        pageSize:
          type: integer
          description: The number of items requested for the current page
          format: int32
          example: 100
        pageItemCount:
          type: integer
          description: The number of items returned in the current page
          format: int32
          readOnly: true
          example: 55
      additionalProperties: false
      description: A paged collection of items
    JobTypeSortOptions:
      enum:
      - name
      type: string
      description: 'Represents the fields that can be used to sort job types<p>Possible values:</p><ul><li><b>name</b>: The name of the job type</li></ul>'
      example: name
    ReadJobTypeModel:
      type: object
      properties:
        id:
          type: integer
          description: The unique identifier of the job type
          format: int64
          example: 5514123
        name:
          type: string
          description: The name of the job type
          example: Combi boiler installation
        description:
          type: string
          description: The default textual description for jobs of this type
          example: New boiler install - please remove and retain the old boiler
        plannedDuration:
          type: integer
          description: The default planned duration for jobs of this type, specified in minutes
          format: int32
          example: 90
        categoryId:
          type:
          - integer
          - 'null'
          description: The unique identifier of default category for jobs of this type
          format: int32
          example: 5514123
        isArchived:
          type: boolean
          description: A flag determining if a type is archived - new jobs cannot be created against archived job types
          example: false
        isOrderNumberRequired:
          type: boolean
          description: A flag determining if an order number is required for jobs of this type
          example: true
        isTasksEnabled:
          type: boolean
          description: A flag determining if tasks are used for this job type
          example: true
        positiveResults:
          type:
          - array
          - 'null'
          items:
            type: string
          description: The result options for when a job is completed successfully
        negativeResults:
          type:
          - array
          - 'null'
          items:
            type: string
          description: The result options for when a job is completed with issues. If null then jobs of this type will not be allowed to have the status of completedWithIssues
        taskDefinitionIds:
          type: array
          items:
            type: string
          description: The identifiers of the task definitions that are added by default to jobs of this type.<br/>Always present, and empty when the job type has none. Each identifier is a lower-case hexadecimal string, the same form<br/>the Tasks service uses. They are not checked against the Tasks service, so one may refer to a task definition that<br/>has since been deleted
        customFieldDefinitions:
          type: array
          items:
            $ref: '#/components/schemas/CustomFieldDefinitionReadModel'
          description: The custom field definitions associated with this job type
      additionalProperties: false
      description: Represents a model that holds information about a job type
    ProblemDetails:
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
          description: A URI reference [RFC3986] that identifies the problem type
          example: https://example.com/probs/out-of-credit
        title:
          type:
          - string
          - 'null'
          description: A short, human-readable summary of the problem type
          example: You do not have enough credit
        status:
          type:
          - integer
          - 'null'
          description: The HTTP status code([RFC7231], Section 6) generated by the origin server for this occurrence of the problem
          format: int32
          example: 403
        detail:
          type:
          - string
          - 'null'
          description: A human-readable explanation specific to this occurrence of the problem
          example: Your current balance is 30, but that costs 50
        instance:
          type:
          - string
          - 'null'
          description: A URI reference that identifies the specific occurrence of the problem
          example: /account/12345/msgs/abc
      additionalProperties: {}
    HttpValidationProblemDetails:
      type: object
      allOf:
      - $ref: '#/components/schemas/ProblemDetails'
      properties:
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
      additionalProperties: {}
    SortDirection:
      enum:
      - ascending
      - descending
      type: string
      description: 'Represents the direction in which sorting should be applied<p>Possible values:</p><ul><li><b>ascending</b>: Indicates ascending sorting order</li><li><b>descending</b>: Indicates descending sorting order</li></ul>'
      example: ascending
    CustomFieldDefinitionReadModel:
      type: object
      properties:
        id:
          type: integer
          description: The unique identifier of the custom field definition
          format: int64
          example: 12345
        caption:
          type: string
          description: The caption of a custom field
          example: Favourite colour
        type:
          $ref: '#/components/schemas/CustomFieldType'
        listOptions:
          type:
          - array
          - 'null'
          items:
            type: string
          description: Shows the possible values for a list type custom field. Value will be null if type is not list
          example:
          - Red
          - Blue
          - Green
          - Purple
        isRequired:
          type: boolean
          description: Indicates if the field is required in the UI. This is NOT enforced in the API
          example: true
        isEditable:
          type: boolean
          description: Indicates if the field is editable
          example: true
        default:
          type:
          - string
          - 'null'
          description: The default value of a custom field. Formatted in accordance with the rules of the field type
          example: '10'
      additionalProperties: false
      description: Represents the full definition of a custom field including its unique identifier
    CustomFieldType:
      enum:
      - boolean
      - integer
      - decimal
      - text
      - list
      - statement
      - date
      - note
      - time
      - systemList
      type: string
      description: 'The type of the custom field. New field types may be added in the future, so integrations should be resilient to this<p>Possible values:</p><ul><li><b>boolean</b>: Indicates a boolean field <i>(Example: "false")</i></li><li><b>integer</b>: Indicates an integer numeric field <i>(Example: "1001")</i></li><li><b>decimal</b>: Indicates a floating point numeric field <i>(Example: "1.42")</i></li><li><b>text</b>: Indicates an editable text field <i>(Example: "Purple")</i></li><li><b>list</b>: Indicates a field with a single value from a predefined list of options <i>(Example: "Purple")</i></li><li><b>statement</b>: Indicates a text field that cannot be edited. The value is always equal to the default value <i>(Example: "By signing this you agree to the following...")</i></li><li><b>date</b>: Indicates a date field, which will be represented as an RFC3339 formatted date string. The default value is not supported for this type and will always be null <i>(Example: "2024-01-31")</i></li><li><b>note</b>: Indicates a multiline, editable text field. Lines are seperated with a line feed character <i>(Example: "This is a note.")</i></li><li><b>time</b>: Indicates a time field, formatted as HH:mm. The default value is not supported for this type and will always be null <i>(Example: "10:30")</i></li><li><b>systemList</b>: Indicates the ID of a related resource, vehicle or web user <i>(Example: "228007")</i></li></ul>'
      example: boolean
  securitySchemes:
    bearer:
      type: http
      description: Enter the access token only.
      scheme: bearer
      bearerFormat: JWT