Availability

Hotpot uses availability records to determine when someone doesn't want to be on-call, can't be on-call, or wants to take the pager. This API endpoint is currently under development.

Bulk upload Unavailability

POST https://app.hotpot.works/api/availabilities/upload

Heads up! This uses a different URL because of the file uploads. These requests will not work against api.hotpot.works!

If you have employee time off managed in an external system and want to sync that data into Hotpot but only have batch systems, export the data as a CSV and import it into Hotpot with this endpoint.

curl -H "Authorization: Bearer <token>" https://api.hotpot.works/availabilities/upload -F "file=@YOURFILE.csv"

The CSV file has a flexible format, but it must include headers.

email,start_time,end_time
[e-mail],2024-11-07T00:00:00,2024-11-08T00:00:00

The email and start_time columns are the only required columns. If no end_time is specified, Hotpot will enter unavailability for 1 day. If the email is not found in Hotpot, the entire run will fail. You can pass in an optional name column to name the availability as well.

The initial run will give you a report of what would be created. You have to pass in commit=save as parameter values to save the values to the database.

Headers

Name	Value
Content-Type	application/x-www-form-urlencoded
Authorization	Bearer <token>

Parameters

Name	Type	Description
commit	string	Pass in save to save the uploaded availability records

Response

200

{
  "ok": true,
  "message": "previewing availability records, send with a commit=save parameter to make them real",
  "availabilities": [
    {
      "name": "Record created from CSV import",
      "time_range_start": "2024-11-08T00:00:00.000Z",
      "time_range_end": "2024-11-10T00:00:00.000Z",
      "organization_user": {
        "id": "orguser_01jc3td7czf6dsg9111bec8x9n",
        "username": "Neva Streich",
        "email": "[e-mail]"
      }
    }
  ]
}

With commit=save provided, it will save the records:

{
  "ok": true,
  "message": "created availability records",
  "availabilities": [
    {
      "id": "avail_01jbz45y53eags7v2bwy6ztv28",
      "organization_user_id": "orguser_01jbz45x59eynayzndz0jp10dz",
      "availability_type": "hard_unavailable",
      "name": "Record created from CSV import",
      "time_range_start": "2024-11-06T00:00:00.000Z",
      "time_range_end": "2024-11-08T00:00:00.000Z",
      "created_at": "2024-11-05T21:37:34.900Z",
      "updated_at": "2024-11-05T21:37:34.900Z",
      "organization_user": {
        "id": "orguser_01jbz45x59eynayzndz0jp10dz",
        "name": "Rep. Gregg Gerlach",
        "email": "[e-mail]"
      }
    }
  ]
}

400

{
  "ok": false,
  "message": "Must provide a CSV with acceptable headers, check our docs!"
}

If an email address cannot be found, the response will be:

{
  "ok": false,
  "message": "Upload contains unmatched users, remove from the CSV or update email addresses",
  "availabilities": [
    {
      "name": "Record created from CSV import",
      "email": "[e-mail]",
      "start_time": "2024-11-27T00:00:00.000Z",
      "end_time": "2024-11-28T00:00:00.000Z",
      "id": null,
      "username": null
    },
  ],
  "invalid": [ "[e-mail]" ]
}