{
  "openapi": "3.0.3",
  "info": {
    "title": "PunchDesk Attendance API",
    "version": "1.1.0",
    "description": "Read-only location-scoped attendance. Dates use Asia/Kolkata; timestamps are ISO 8601 UTC. Keep API keys on your server."
  },
  "servers": [
    {
      "url": "https://punchdesk.in/api/v1"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Create an API key in API integrations."
      }
    }
  },
  "paths": {
    "/locations": {
      "get": {
        "summary": "List permitted locations",
        "description": "Returns data: an array of id, name, timezone, attendance_rule and weekend_day. No unassigned locations are returned. Includes contractual_enabled (0 or 1); contractual staffing is optional per location.",
        "operationId": "locations",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Returns data: an array of id, name, timezone, attendance_rule and weekend_day. No unassigned locations are returned.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "meta": {
                      "type": "object",
                      "additionalProperties": true
                    },
                    "totals": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Request failed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Request failed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Request failed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Request failed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Request failed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/attendance": {
      "get": {
        "summary": "Attendance over an inclusive date range",
        "description": "Up to 366 days and 200,000 employee-days. data is paginated daily rows. totals and by_date cover the entire filtered roster and range; employees contains all per-employee summaries. Totals count employee-days. Daily rows include employee_id, employee_code, name, location_id, location, day, presence, status, punches, first_in, last_out, span_hours, provisional, attendance_rule and leave_type. meta includes total, total_pages, page, page_size, timezone and generated_at.",
        "operationId": "attendance",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "location_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 100
            }
          },
          {
            "name": "include_inactive",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Up to 366 days and 200,000 employee-days. data is paginated daily rows. totals and by_date cover the entire filtered roster and range; employees contains all per-employee summaries. Totals count employee-days. Daily rows include employee_id, employee_code, name, location_id, location, day, presence, status, punches, first_in, last_out, span_hours, provisional, attendance_rule and leave_type. meta includes total, total_pages, page, page_size, timezone and generated_at.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "meta": {
                      "type": "object",
                      "additionalProperties": true
                    },
                    "totals": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Request failed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Request failed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Request failed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Request failed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Request failed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/presence": {
      "get": {
        "summary": "Current-day attendance and inferred occupancy",
        "description": "Active employees only. data is paginated. totals includes employees, present_today (any attendance punch, including holidays), absent (no punch on a working day without leave; provisional), on_leave, holiday, in_office, out, unknown and no_punch. office_status is in/out for the latest unambiguous directional punch today, unknown for first/last rules or conflicting simultaneous punches, and no_punch when none is available. This is inferred occupancy, not a guaranteed live headcount. devices supplies last_seen_at for freshness.",
        "operationId": "presence",
        "parameters": [
          {
            "name": "location_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Active employees only. data is paginated. totals includes employees, present_today (any attendance punch, including holidays), absent (no punch on a working day without leave; provisional), on_leave, holiday, in_office, out, unknown and no_punch. office_status is in/out for the latest unambiguous directional punch today, unknown for first/last rules or conflicting simultaneous punches, and no_punch when none is available. This is inferred occupancy, not a guaranteed live headcount. devices supplies last_seen_at for freshness.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "meta": {
                      "type": "object",
                      "additionalProperties": true
                    },
                    "totals": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Request failed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Request failed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Request failed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Request failed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Request failed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/contract-staffing": {
      "get": {
        "summary": "Current contractual staffing and today\u2019s attendance",
        "operationId": "contractStaffing",
        "description": "Same calculation as the PunchDesk contractual dashboard. Only enabled, permitted locations are returned. Disabled locations return an empty locations array. All timestamps are ISO 8601 UTC; schedules and attendance day use IST. Coverage is an estimate, not confirmed occupancy. required, covered and shortfall sum active shifts; covered is capped per requirement. people counts distinct active-shift contributors. Daily present/absent lists are disjoint active employees with/without attendance punches today, including holidays and leave. Grace is 30 minutes before and after shifts, capped at the next same-role shift. Single-role employees cannot carry over; multi-role employees need a fresh punch for another shift. Refresh no faster than every 30 seconds.",
        "parameters": [
          {
            "name": "location_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "Omit for all permitted enabled locations. A location outside the key scope returns 403."
          }
        ],
        "responses": {
          "200": {
            "description": "Current scoped staffing snapshot",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "generated_at",
                    "timezone",
                    "locations"
                  ],
                  "properties": {
                    "generated_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "timezone": {
                      "type": "string",
                      "enum": [
                        "Asia/Kolkata"
                      ]
                    },
                    "locations": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "id",
                          "name",
                          "required",
                          "covered",
                          "shortfall",
                          "people",
                          "requirements",
                          "attendance"
                        ],
                        "properties": {
                          "id": {
                            "type": "integer"
                          },
                          "name": {
                            "type": "string"
                          },
                          "required": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "covered": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "shortfall": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "people": {
                            "type": "integer",
                            "minimum": 0
                          },
                          "requirements": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "required": [
                                "role_id",
                                "role",
                                "start",
                                "end",
                                "required",
                                "active",
                                "shift_day",
                                "shift_start",
                                "shift_end",
                                "coverage_until",
                                "present",
                                "shortfall",
                                "employees"
                              ],
                              "properties": {
                                "role_id": {
                                  "type": "integer"
                                },
                                "role": {
                                  "type": "string"
                                },
                                "start": {
                                  "type": "string",
                                  "example": "09:00"
                                },
                                "end": {
                                  "type": "string",
                                  "example": "18:00"
                                },
                                "required": {
                                  "type": "integer",
                                  "minimum": 0
                                },
                                "active": {
                                  "type": "boolean"
                                },
                                "shift_day": {
                                  "type": "string",
                                  "format": "date"
                                },
                                "shift_start": {
                                  "type": "string",
                                  "format": "date-time"
                                },
                                "shift_end": {
                                  "type": "string",
                                  "format": "date-time"
                                },
                                "coverage_until": {
                                  "type": "string",
                                  "format": "date-time"
                                },
                                "present": {
                                  "type": "integer",
                                  "minimum": 0
                                },
                                "shortfall": {
                                  "type": "integer",
                                  "minimum": 0
                                },
                                "employees": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "id": {
                                        "type": "integer"
                                      },
                                      "name": {
                                        "type": "string"
                                      },
                                      "last_punch": {
                                        "type": "string",
                                        "format": "date-time"
                                      },
                                      "roles": {
                                        "type": "array",
                                        "items": {
                                          "type": "string"
                                        }
                                      }
                                    }
                                  }
                                }
                              }
                            }
                          },
                          "attendance": {
                            "type": "object",
                            "properties": {
                              "day": {
                                "type": "string",
                                "format": "date"
                              },
                              "present": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "required": [
                                    "id",
                                    "name",
                                    "employee_code",
                                    "job_roles",
                                    "punches",
                                    "first_punch",
                                    "last_punch"
                                  ],
                                  "properties": {
                                    "id": {
                                      "type": "integer"
                                    },
                                    "name": {
                                      "type": "string"
                                    },
                                    "employee_code": {
                                      "type": "string"
                                    },
                                    "job_roles": {
                                      "type": "array",
                                      "items": {
                                        "type": "object",
                                        "required": [
                                          "id",
                                          "name"
                                        ],
                                        "properties": {
                                          "id": {
                                            "type": "integer"
                                          },
                                          "name": {
                                            "type": "string"
                                          }
                                        }
                                      }
                                    },
                                    "punches": {
                                      "type": "integer",
                                      "minimum": 0
                                    },
                                    "first_punch": {
                                      "type": "string",
                                      "format": "date-time",
                                      "nullable": true
                                    },
                                    "last_punch": {
                                      "type": "string",
                                      "format": "date-time",
                                      "nullable": true
                                    }
                                  }
                                }
                              },
                              "absent": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "required": [
                                    "id",
                                    "name",
                                    "employee_code",
                                    "job_roles",
                                    "punches",
                                    "first_punch",
                                    "last_punch"
                                  ],
                                  "properties": {
                                    "id": {
                                      "type": "integer"
                                    },
                                    "name": {
                                      "type": "string"
                                    },
                                    "employee_code": {
                                      "type": "string"
                                    },
                                    "job_roles": {
                                      "type": "array",
                                      "items": {
                                        "type": "object",
                                        "required": [
                                          "id",
                                          "name"
                                        ],
                                        "properties": {
                                          "id": {
                                            "type": "integer"
                                          },
                                          "name": {
                                            "type": "string"
                                          }
                                        }
                                      }
                                    },
                                    "punches": {
                                      "type": "integer",
                                      "minimum": 0
                                    },
                                    "first_punch": {
                                      "type": "string",
                                      "format": "date-time",
                                      "nullable": true
                                    },
                                    "last_punch": {
                                      "type": "string",
                                      "format": "date-time",
                                      "nullable": true
                                    }
                                  }
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid query"
          },
          "401": {
            "description": "Missing, expired or revoked key"
          },
          "403": {
            "description": "Location outside permitted access"
          },
          "429": {
            "description": "Rate limit exceeded"
          }
        }
      }
    }
  }
}
