{"components":{"schemas":{"Incident":{"properties":{"id":{"type":"string"},"label":{"examples":["INC-0042"],"type":"string"},"notified_at":{"format":"date-time","type":["string","null"]},"notify_by":{"format":"date-time","type":["string","null"]},"occurred_at":{"format":"date-time","type":"string"},"reportable":{"type":"boolean"},"severity":{"enum":["low","medium","high","critical"],"type":"string"},"status":{"enum":["reported","reviewing","investigating","closed"],"type":"string"},"title":{"type":"string"}},"type":"object"},"NewShift":{"properties":{"assignee_ids":{"items":{"type":"string"},"type":"array"},"break_minutes":{"type":"integer"},"draft":{"type":"boolean"},"ends_at":{"format":"date-time","type":"string"},"location_id":{"type":"string"},"notes":{"type":"string"},"participant_id":{"type":"string"},"slots":{"minimum":1,"type":"integer"},"starts_at":{"format":"date-time","type":"string"},"title":{"type":"string"},"urgent":{"type":"boolean"}},"required":["title","starts_at","ends_at"],"type":"object"},"Person":{"properties":{"email":{"type":"string"},"employment_type":{"type":["string","null"]},"id":{"type":"string"},"name":{"type":"string"},"phone":{"type":["string","null"]},"role":{"type":"string"},"status":{"type":"string"}},"type":"object"},"Shift":{"properties":{"assignees":{"items":{"properties":{"id":{"type":"string"},"name":{"type":"string"}},"type":"object"},"type":"array"},"break_minutes":{"type":"integer"},"ends_at":{"format":"date-time","type":"string"},"hours":{"type":"number"},"id":{"format":"uuid","type":"string"},"location_id":{"type":["string","null"]},"participant_id":{"type":["string","null"]},"published":{"type":"boolean"},"slots":{"type":"integer"},"starts_at":{"format":"date-time","type":"string"},"status":{"enum":["open","assigned","in_progress","completed","cancelled"],"type":"string"},"title":{"type":"string"},"urgent":{"type":"boolean"}},"type":"object"},"TimesheetLine":{"properties":{"break_minutes":{"type":"integer"},"checked_in_at":{"format":"date-time","type":"string"},"checked_out_at":{"format":"date-time","type":["string","null"]},"id":{"type":"string"},"mileage_km":{"type":["number","null"]},"person_id":{"type":"string"},"shift_id":{"type":"string"},"status":{"enum":["checked_in","submitted","approved"],"type":"string"},"worked_minutes":{"type":["integer","null"]}},"type":"object"}},"securitySchemes":{"oauth":{"flows":{"clientCredentials":{"scopes":{"incidents:read":"Read incidents","people:read":"Read the organisation's people","shifts:read":"Read shifts","shifts:write":"Create shifts","timesheets:read":"Read timesheet lines"},"tokenUrl":"https://api.hellomapper.com/oauth/token"}},"type":"oauth2"}}},"info":{"description":"Read and write rosters, people, timesheets and incidents for one organisation. Authenticate with OAuth 2.0 client credentials (create a client under Settings → Integrations), then send `Authorization: Bearer <access_token>`. Times are ISO 8601 in UTC. Webhooks: register an https endpoint for event types; deliveries are JSON `{id, type, created_at, data: {object, id}}` signed with `HelloMapper-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, \"t.body\")>`, fetch the object through this API.","title":"HelloMapper API","version":"1.0.0"},"openapi":"3.1.0","paths":{"/incidents":{"get":{"parameters":[{"description":"open, reported, reviewing, investigating or closed","in":"query","name":"status","required":false,"schema":{"type":"string"}},{"description":"true for regulator-reportable only","in":"query","name":"reportable","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Incident"},"type":"array"}},"type":"object"}}},"description":"OK"},"401":{"description":"Missing or expired token"},"402":{"description":"The organisation's plan doesn't include this"},"403":{"description":"The token lacks the required scope"},"422":{"description":"Validation failed; `error.fields` lists problems"},"429":{"description":"Rate limited (600 requests a minute per client)"}},"security":[{"oauth":["incidents:read"]}],"summary":"Incidents, newest first"}},"/incidents/{id}":{"get":{"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"$ref":"#/components/schemas/Incident"}},"type":"object"}}},"description":"OK"},"401":{"description":"Missing or expired token"},"402":{"description":"The organisation's plan doesn't include this"},"403":{"description":"The token lacks the required scope"},"404":{"description":"Not found"},"422":{"description":"Validation failed; `error.fields` lists problems"},"429":{"description":"Rate limited (600 requests a minute per client)"}},"security":[{"oauth":["incidents:read"]}],"summary":"Get an incident"}},"/people":{"get":{"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Person"},"type":"array"}},"type":"object"}}},"description":"OK"},"401":{"description":"Missing or expired token"},"402":{"description":"The organisation's plan doesn't include this"},"403":{"description":"The token lacks the required scope"},"422":{"description":"Validation failed; `error.fields` lists problems"},"429":{"description":"Rate limited (600 requests a minute per client)"}},"security":[{"oauth":["people:read"]}],"summary":"The organisation's people (staff and workers)"}},"/shifts":{"get":{"parameters":[{"description":"Start (default now)","in":"query","name":"from","required":false,"schema":{"type":"string"}},{"description":"End (default from + 14 days)","in":"query","name":"to","required":false,"schema":{"type":"string"}},{"description":"Filter by status","in":"query","name":"status","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Shift"},"type":"array"}},"type":"object"}}},"description":"OK"},"401":{"description":"Missing or expired token"},"402":{"description":"The organisation's plan doesn't include this"},"403":{"description":"The token lacks the required scope"},"422":{"description":"Validation failed; `error.fields` lists problems"},"429":{"description":"Rate limited (600 requests a minute per client)"}},"security":[{"oauth":["shifts:read"]}],"summary":"List shifts starting in a window (max 62 days)"},"post":{"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewShift"}}}},"responses":{"201":{"content":{"application/json":{"schema":{"properties":{"data":{"$ref":"#/components/schemas/Shift"}},"type":"object"}}},"description":"Created"},"401":{"description":"Missing or expired token"},"402":{"description":"The organisation's plan doesn't include this"},"403":{"description":"The token lacks the required scope"},"409":{"description":"Clash, leave or eligibility conflict"},"422":{"description":"Validation failed; `error.fields` lists problems"},"429":{"description":"Rate limited (600 requests a minute per client)"}},"security":[{"oauth":["shifts:write"]}],"summary":"Create a shift (assignments go through the usual clash, leave and eligibility checks)"}},"/shifts/{id}":{"get":{"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"$ref":"#/components/schemas/Shift"}},"type":"object"}}},"description":"OK"},"401":{"description":"Missing or expired token"},"402":{"description":"The organisation's plan doesn't include this"},"403":{"description":"The token lacks the required scope"},"404":{"description":"Not found"},"422":{"description":"Validation failed; `error.fields` lists problems"},"429":{"description":"Rate limited (600 requests a minute per client)"}},"security":[{"oauth":["shifts:read"]}],"summary":"Get a shift"}},"/timesheets":{"get":{"parameters":[{"description":"Start, ISO 8601","in":"query","name":"from","required":true,"schema":{"type":"string"}},{"description":"End, ISO 8601","in":"query","name":"to","required":true,"schema":{"type":"string"}},{"description":"approved (default), submitted or checked_in","in":"query","name":"status","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/TimesheetLine"},"type":"array"}},"type":"object"}}},"description":"OK"},"401":{"description":"Missing or expired token"},"402":{"description":"The organisation's plan doesn't include this"},"403":{"description":"The token lacks the required scope"},"422":{"description":"Validation failed; `error.fields` lists problems"},"429":{"description":"Rate limited (600 requests a minute per client)"}},"security":[{"oauth":["timesheets:read"]}],"summary":"Timesheet lines checked in within a window, approved only by default (for payroll)"}}},"servers":[{"url":"https://api.hellomapper.com/public/v1"}],"webhooks":{"incident.reported":{"post":{"requestBody":{"content":{"application/json":{"schema":{"properties":{"created_at":{"format":"date-time","type":"string"},"data":{"properties":{"id":{"type":"string"},"object":{"type":"string"}},"type":"object"},"id":{"type":"string"},"type":{"const":"incident.reported","type":"string"}},"type":"object"}}}},"responses":{"2XX":{"description":"Received; anything else is retried with backoff"}},"summary":"incident.reported, fetch the object with its id"}},"shift.assigned":{"post":{"requestBody":{"content":{"application/json":{"schema":{"properties":{"created_at":{"format":"date-time","type":"string"},"data":{"properties":{"id":{"type":"string"},"object":{"type":"string"}},"type":"object"},"id":{"type":"string"},"type":{"const":"shift.assigned","type":"string"}},"type":"object"}}}},"responses":{"2XX":{"description":"Received; anything else is retried with backoff"}},"summary":"shift.assigned, fetch the object with its id"}},"shift.cancelled":{"post":{"requestBody":{"content":{"application/json":{"schema":{"properties":{"created_at":{"format":"date-time","type":"string"},"data":{"properties":{"id":{"type":"string"},"object":{"type":"string"}},"type":"object"},"id":{"type":"string"},"type":{"const":"shift.cancelled","type":"string"}},"type":"object"}}}},"responses":{"2XX":{"description":"Received; anything else is retried with backoff"}},"summary":"shift.cancelled, fetch the object with its id"}},"shift.claimed":{"post":{"requestBody":{"content":{"application/json":{"schema":{"properties":{"created_at":{"format":"date-time","type":"string"},"data":{"properties":{"id":{"type":"string"},"object":{"type":"string"}},"type":"object"},"id":{"type":"string"},"type":{"const":"shift.claimed","type":"string"}},"type":"object"}}}},"responses":{"2XX":{"description":"Received; anything else is retried with backoff"}},"summary":"shift.claimed, fetch the object with its id"}},"shift.created":{"post":{"requestBody":{"content":{"application/json":{"schema":{"properties":{"created_at":{"format":"date-time","type":"string"},"data":{"properties":{"id":{"type":"string"},"object":{"type":"string"}},"type":"object"},"id":{"type":"string"},"type":{"const":"shift.created","type":"string"}},"type":"object"}}}},"responses":{"2XX":{"description":"Received; anything else is retried with backoff"}},"summary":"shift.created, fetch the object with its id"}},"shift.unassigned":{"post":{"requestBody":{"content":{"application/json":{"schema":{"properties":{"created_at":{"format":"date-time","type":"string"},"data":{"properties":{"id":{"type":"string"},"object":{"type":"string"}},"type":"object"},"id":{"type":"string"},"type":{"const":"shift.unassigned","type":"string"}},"type":"object"}}}},"responses":{"2XX":{"description":"Received; anything else is retried with backoff"}},"summary":"shift.unassigned, fetch the object with its id"}},"timesheet.approved":{"post":{"requestBody":{"content":{"application/json":{"schema":{"properties":{"created_at":{"format":"date-time","type":"string"},"data":{"properties":{"id":{"type":"string"},"object":{"type":"string"}},"type":"object"},"id":{"type":"string"},"type":{"const":"timesheet.approved","type":"string"}},"type":"object"}}}},"responses":{"2XX":{"description":"Received; anything else is retried with backoff"}},"summary":"timesheet.approved, fetch the object with its id"}}}}