Availability

Hotpot uses availability records to determine when someone doesn't want to be on-call, can't be on-call, or requests to take the pager.

Bulk upload unavailability

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

warning

Heads up! This endpoint uses a different URL to support file uploads. Note app.hotpot.works, not 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 https://api.hotpot.works/api/availabilities/upload 
  -H "Authorization: Bearer <your API key>" 
  -F "file=@YOURFILE.csv"

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

email,start_time,end_time
user1@domain.com,2025-11-07T00:00:00,2025-11-08T00:00:00

The email and start_time columns are required. If no end_time is specified, Hotpot enters unavailability for 1 day. If the email isn't found in Hotpot, the entire run fails.

You can pass in an optional name column to label the availability.

The initial run reports what would be created by the CSV. Pass commit=save as a parameter to commit the values to the database.

Headers

Name	Value
Content-Type	application/x-www-form-urlencoded
Authorization	Bearer <your API key>

Parameters

Name	Type	Description
commit	string	Pass 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": "dominique@ratke.example"
      }
    }
  ]
}

With commit=save provided, it saves 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": "george.anderson@collier.example"
      }
    }
  ]
}

400

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

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

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