Skedulo Offers API

openapi: 3.0.0
info:
  title: Authentication Admin Offers API
  description: Skedulo Authentication API
  version: 1.0.0
servers:
- url: https://api.skedulo.com/auth
- url: https://api.uk.skedulo.com/auth
- url: https://api.ca.skedulo.com/auth
- url: https://api.au.skedulo.com/auth
tags:
- name: Offers
paths:
  /offer/job/resource/{resource_job_offer_id}/accept:
    post:
      security:
      - Authorization: []
      summary: Accept a job offer
      tags:
      - Offers
      description: The offered job will be automatically allocated if the `autoAllocateJobOffers` org preference is enabled. Schedulers and Admins can accept any offer. Resources can only accept an offer that is assigned to them. Stores the time the response was sent as either the given timestamp or the current time if a time is not provided.
      parameters:
      - name: resource_job_offer_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AllocationActionTimestamp'
        required: true
      responses:
        '200':
          description: Result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessAndStatus'
        default:
          description: 'Error. '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /offer/job/resource/{resource_job_offer_id}/decline:
    post:
      security:
      - Authorization: []
      summary: Decline a job offer
      tags:
      - Offers
      description: Closes the offer. After an offer is declined, it cannot be subsequently accepted. Schedulers and Admins can decline any offer. Resources can only decline an offer that is assigned to them. Stores the time the response was sent as either the given timestamp or the current time if a time is not provided.
      parameters:
      - name: resource_job_offer_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AllocationActionTimestamp'
        required: true
      responses:
        '200':
          description: Result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessAndStatus'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /offer/job/{job_offer_id}/notify:
    post:
      security:
      - Authorization: []
      summary: Notify associated resources about a job offer
      tags:
      - Offers
      description: Send a notification to some or all resources who have an open offer on the given job. Resources who have declined will not be notified. Each resource's preferred notification method (push or SMS) will be used, if set. If job offer notifications are disabled then no notifications will be sent and an appropriate message will be returned in the response.
      parameters:
      - name: job_offer_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        description: List of Resource Job Offer IDs to notify. This is optional -- if not present, all resources will be notified.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotifyResources'
        required: false
      responses:
        '200':
          description: The results of notifying each resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotifyResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /offer/shift/resource/{resource_shift_offer_id}/accept:
    post:
      security:
      - Authorization: []
      summary: Accept a shift offer
      tags:
      - Offers
      description: The offered shift will be automatically allocated if the `autoAllocateShiftOffers` org preference is enabled. Schedulers and Admins can accept any offer. Resources can only accept an offer that is assigned to them. Stores the time the response was sent as either the given timestamp or the current time if a time is not provided.
      parameters:
      - name: resource_shift_offer_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AllocationActionTimestamp'
        required: true
      responses:
        '200':
          description: Result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessAndStatus'
        default:
          description: 'Error. '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /offer/job/{job_offer_id}/cancel:
    post:
      security:
      - Authorization: []
      summary: Cancel a job offer
      tags:
      - Offers
      description: Cancels the job offer. After an offer is cancelled, it cannot be subsequently accepted. Also cancels any associated pending resource jobs offers
      parameters:
      - name: job_offer_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The IDs of the ResourceJobOffers that were cancelled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelOfferResponse'
        default:
          description: 'Error. '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /offer/shift/resource/{resource_shift_offer_id}/decline:
    post:
      security:
      - Authorization: []
      summary: Decline a shift offer
      tags:
      - Offers
      description: Closes the offer. After an offer is declined, it cannot be subsequently accepted. Schedulers and Admins can decline any offer. Resources can only decline an offer that is assigned to them. Stores the time the response was sent as either the given timestamp or the current time if a time is not provided.
      parameters:
      - name: resource_shift_offer_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AllocationActionTimestamp'
        required: true
      responses:
        '200':
          description: Result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessAndStatus'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /offer/shift/{shift_offer_id}/notify:
    post:
      security:
      - Authorization: []
      summary: Notify associated resources about a shift offer
      tags:
      - Offers
      description: Send a notification to some or all resources who have an open offer on the given shift. Resources who have declined will not be notified. Each resource's preferred notification method (push or SMS) will be used, if set.
      parameters:
      - name: shift_offer_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        description: 'List of Resource Shift Offer IDs to notify. This is optional: if not present, all resources will be notified.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotifyResources'
        required: false
      responses:
        '200':
          description: The results of notifying each resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotifyResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    CancelOfferResponse:
      type: object
      properties:
        result:
          type: object
          required:
          - result
          properties:
            cancelledResourceJobOfferIds:
              type: array
              items:
                type: string
              example:
              - 001449b0-1130-4e8c-9b8d-d30d812db84b
              - 001334b0-1130-5e8c-9b8d-d30d812db84b
    NotifyResources:
      type: object
      properties:
        resourceOfferIds:
          type: array
          items:
            type: string
    ResourceResult:
      type: object
      properties:
        resourceId:
          type: string
        protocol:
          type: string
        error:
          description: null if the notification was sent successfully
          $ref: '#/components/schemas/Error'
    NotifyResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/ResourceResult'
    Error:
      type: object
      required:
      - errorType
      - message
      properties:
        errorType:
          type: string
        message:
          type: string
    AllocationActionTimestamp:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
    SuccessAndStatus:
      type: object
      properties:
        success:
          type: boolean
          default: true
        status:
          type: string
          enum:
          - Accepted
          - Declined
          - Allocated
  securitySchemes:
    Authorization:
      type: http
      scheme: bearer
      bearerFormat: JWT