Bids API Design Documentation

Revision L: November 2022

This document sets out the basis for individual department rota systems provided by Rotamap to interact with locum providers (the 'provider') through an API. The API allows departments to publish vacancies requiring cover through the 'bids' feature of their rotas. These vacancies are referred to as 'bid offers'. A provider is then able to send a person booking against a bid offer, known as a 'response'. The bid offers listing is provider-specific.

Authentication and security

All API interactions should happen over https with valid certificates.

Rotamap's API for Locums is an extension of Rotamap's current Public API which is provided in XML. However a JSON data format is used for the bids integration described in this document.

Rotamap's calls to the provider's systems should be done through Rotamap authentication with the provider and the use of a UUID token.

Sessions

Rotamap's systems presently report bid offers in sessions, typically resolving to "am", "pm", "evening" and "night" sessions. Joining sessions into a single contiguous shift is not presently supported.

Bid offers

Each locum provider will view its own list of bid offers. Each provider should be aware that it may be possible for another provider's response, or an internal response, to be chosen to cover the session, or that the list may be cancelled or the requirement for cover nullified.

The states of an bid offer, from the perspective of a provider, is therefore:

open | closed

Bid offers with the status "open" represent sessions requiring cover; "closed" bid offers are bid offers that have closed due to the session being covered or no longer requiring cover.

Responses

Each response against a bid offer has its own state.

pending | successful | unsuccessful | withdrawn | withdraw requested

A "pending" response will be updated to be either "successful" or "unsuccessful" when the bid offer itself has been changed from "open" to "closed". A "successful" response will have been selected by the department. Any unselected responses for the bid offer will be marked as "unsuccessful".

The provider is also able to retract a response against a given bid offer. If the response is currently "pending", this will update the response to "withdrawn". If the response is "successful", this will update the response to "withdraw requested", for confirmation by the department. Upon confirmation the state will then move to either "withdrawn" or back to "successful" depending on the decision. "unsuccessful" responses cannot be withdrawn.

Each "person" object within a response contains a "current locations" list. This will be populated if the person associated with the response has been assigned to the rota at the same time as the bid offer. This will allow the provider to compare the location they have been assigned to to the location of the bid offer. This can additionally allow the provider to determine if a person responding is already undertaking activity at the time of the bid offer upon submission of the response.

Endpoints and data structure

Examples below use urls rooted at a department's site url, for example https://exampledept.medirota.com.

A. Authentication

Allow the provider to authenticate to Rotamap's service, receiving a UUID token in response.


/publicapi/login/ POST

Response: HTTP code and token.

B. Bid offers (GET)

List bid offers from yesterday onwards for this department. The data structure may contain additional fields as required by the provider.


/{token}/bid_offers GET
/{token}/bid_offers?since={timestamp} GET

Call with "Accept: application/json" header.

Response: HTTP code and JSON data structure as follows:


{
  "bid_offers": [
    {
      "end_time": "2021-05-31T12:00:00", 
      "location_id": 8, 
      "location_name": "Theatre 1", 
      "location_uuid": "dc43bc4a-da08-4851-b4b0-886b5c891006", 
      "responses": [
        {
          "person": {
            "current_locations": [
              {
                "id": 8, 
                "name": "Theatre 1", 
                "uuid": "dc43bc4a-da08-4851-b4b0-886b5c891006"
              }
            ], 
            "id": "XX123"
          }
          "status": "successful", 
          "uuid": "e977513f-7315-4573-84d8-fd61d0c4072b"
        }
      ],
      "role": "Consultant", 
      "session": "am", 
      "start_time": "2021-05-31T08:00:00", 
      "status": "closed", 
      "updated": "2021-05-21T09:45:59.715001", 
      "uuid": "f2fd539f-015a-4465-8e39-a501727ecf38"
    }, 
    {
      "end_time": "2021-06-01T12:00:00", 
      "location_id": 8, 
      "location_name": "Ward 5", 
      "location_uuid": "dc43bc4a-da08-4851-b4b0-886b5c891006", 
      "responses": [], 
      "role": "Registrar", 
      "session": "am", 
      "start_time": "2021-06-01T08:00:00", 
      "status": "open", 
      "updated": "2021-05-21T09:41:49.821342", 
      "uuid": "4cc633c5-c4f4-4539-b0c2-d3ee3d0bf546"
    }
  ], 
  "metadata": {
    "last_updated": "2021-05-21T09:45:59.715001", 
    "uri": "https://exampledept.medirota.com/{token}/bid_offers/"
  }
}

C. Bid offer (GET)

Show a particular bid offer for this department.


/{token}/bid_offer/{uuid} GET

Call with "Accept: application/json" header.

Response: HTTP code and JSON data structure as follows:


{
  "metadata": {
    "uri": "https://exampledept.medirota.com/{token}/bid_offers/",
    "last_updated": "2020-01-17T10:01:22",
  },
  "bid_offers": [
    {
      "id": "e0d24e81-952b-4880-ba19-a695ed83fca3",
      "updated": "2020-01-17T10:01:22",
      "start_time": "2020-02-01T12:00:00",
      "end_time": "2020-02-01T16:00:00",
      "session": "am",
      "location_id": "8",
      "location_uuid": "dc43bc4a-da08-4851-b4b0-886b5c891006",
      "location_name": "Theatre 1",
      "role": "Consultant",
      "status": "open"
    }
  ]
    }

D. Bid offer (POST)

Submit a response against a particular bid offer for this department.


/{token}/bid_offer/{id} POST

Call with "Content-type: application/json" header with a JSON payload

POST parameters:


uuid : uuid # the uuid of the bid offer * required
person_id : string # provider local person ID * required
person_first_name : string # * required
person_last_name : string # * required
person_email : string # * required
person_mobile : string #
person_grade : string #
notes : string #
url : string # unique url for this booking
Response: HTTP code and JSON data structure as follows: 

{
  "response_uuid": {uuid}
}

E. Withdraw (POST)

Withdraw a response against a particular bid offer for this department.


/{token}/withdraw/{uuid} POST

Response: HTTP code and JSON data structure as follows:


{
  "response_status": "withdrawn"
}