--- updatedAt: 2026-06-12T23:00:16.000Z --- Fetch the complete documentation index at: https://developers.7shifts.com/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version. # List Time Punches **[Minimum Plan Required](/docs/plan-requirements):** Entrée #### Sample Response ```json { "data": [ { "id": 85452022, "company_id": 1234, "shift_id": 185404, "user_id": 555, "editable_punch": false, "role_id": 2583, "location_id": 4569, "department_id": 7890, "hourly_wage": 1550, "approved": true, "clocked_in": "2021-11-26T15:12:00+00:00", "clocked_out": "2021-11-26T20:47:00+00:00", "notes": "", "auto_clocked_out": false, "clocked_in_offline": false, "clocked_out_offline": false, "tips": 0, "created": "2021-11-26T15:16:29+00:00", "modified": "2021-11-26T20:51:41+00:00", "deleted": false, "pos_type": "toast", "breaks": [] }, { "id": 85452023, "company_id": 1234, "shift_id": 185438, "user_id": 555, "editable_punch": false, "role_id": 2583, "location_id": 4569, "department_id": 7890, "hourly_wage": 0, "approved": true, "clocked_in": "2021-11-26T20:50:00+00:00", "clocked_out": "2021-11-26T20:50:00+00:00", "notes": "", "auto_clocked_out": false, "clocked_in_offline": false, "clocked_out_offline": false, "tips": 0, "created": "2021-11-26T20:51:41+00:00", "modified": "2021-11-26T20:51:41+00:00", "deleted": false, "pos_type": "toast", "breaks": [] } ], "meta": { "cursor": { "current": null, "prev": null, "next": "eyJpZCI6ODU0NTIwMjMsIm5leHQiOnRydWV9", "count": 2 } }, "object": "time_punches" } ``` # OpenAPI definition ```json { "openapi": "3.0.2", "info": { "title": "7shifts API", "contact": { "email": "api-support@7shifts.com" }, "version": "2026-06-01" }, "servers": [ { "url": "https://api.7shifts.com", "description": "Production server" } ], "paths": { "/v2/company/{company_id}/time_punches": { "get": { "tags": [ "Time Punches" ], "summary": "List Time Punches", "operationId": "getTimePunches", "x-public-api": true, "parameters": [ { "name": "x-api-version", "in": "header", "description": "7shifts API version", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "An API version", "example": "2022-05-01" } }, { "name": "x-company-guid", "in": "header", "description": "Company GUID", "required": false, "schema": { "type": "string", "format": "uuid" }, "example": "1310bfe1-cb3f-4f24-98a2-fde2bc504108" }, { "name": "company_id", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "integer", "format": "int64" }, "example": 1234 }, { "name": "location_id", "in": "query", "description": "Location ID", "schema": { "type": "integer" } }, { "name": "department_id", "in": "query", "description": "Department ID", "schema": { "type": "integer" } }, { "name": "role_id", "in": "query", "description": "Role ID", "schema": { "type": "integer" } }, { "name": "user_id", "in": "query", "description": "User ID", "schema": { "type": "integer" } }, { "name": "approved", "in": "query", "required": false, "description": "Returns time punches that have been approved. Default null, returns both approved and unapproved punches. If true returns only approved punches. If false returns only unapproved punches.", "schema": { "type": "boolean", "default": null, "nullable": true } }, { "name": "limit", "in": "query", "required": false, "description": "The limit of results that will be returned.", "schema": { "type": "integer", "default": 20 } }, { "name": "modified_since", "in": "query", "required": false, "description": "Return time punches that have been modified after the specified date time. UTC in ISO8601 Format", "schema": { "type": "string", "format": "date-time" }, "example": "2020-12-30T15:00:00.000Z" }, { "name": "clocked_in[lte]", "in": "query", "description": "Return time punches with clocked in before or on the specified date. UTC in ISO8601 format", "schema": { "type": "string", "format": "date-time" } }, { "name": "clocked_in[gte]", "in": "query", "description": "Return time punches with clocked in after or on the specified date. UTC in ISO8601 format", "schema": { "type": "string", "format": "date-time" } }, { "name": "clocked_out[lte]", "in": "query", "description": "Return time punches with clocked out before or on the specified date. UTC in ISO8601 format", "schema": { "type": "string", "format": "date-time" } }, { "name": "clocked_out[gte]", "in": "query", "description": "Return time punches with clocked out after or on the specified date. UTC in ISO8601 format", "schema": { "type": "string", "format": "date-time" } }, { "name": "include_deleted", "in": "query", "description": "Deprecated, see 'deleted'", "schema": { "type": "boolean", "default": false }, "deprecated": true }, { "name": "deleted", "in": "query", "description": "Returns punches filtered by deleted status. Default false, returns undeleted punches. If true returns only deleted punches. if value is null then returns both deleted and undeleted punches.", "schema": { "type": "boolean", "default": false, "nullable": true }, "required": false }, { "name": "localize_search_time", "in": "query", "description": "If true, convert any date ranges to consider the local timezone of the punches. If false, date ranges will be in UTC", "schema": { "type": "boolean", "default": false } }, { "name": "flags", "in": "query", "description": "A comma separated list of flags to filter time punches by.", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "late", "auto_clocked_out", "missed_break" ] }, "nullable": true, "example": "late,auto_clocked_out,missed_break" } }, { "name": "employee_approval_statuses", "in": "query", "description": "A comma-separated list of employee approval statuses to filter time punches by.", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "pending", "approved", "disputed" ] }, "nullable": true, "example": "pending,disputed" } }, { "name": "cursor", "in": "query", "description": "Cursor for the next or previous page of results.", "required": false, "schema": { "type": "string" } }, { "name": "sort_by", "in": "query", "description": "The name of the field and direction you want the results ordered by.", "schema": { "type": "string", "pattern": "^(,?[a-zA-Z_]*(\\.(asc|desc))?){1,}$", "example": "location.desc" } }, { "name": "business_date_start", "in": "query", "description": "Return time punches with business date (based on clocked in date) after or on the specified date. UTC in ISO8601 format. If used, it will take priority over all other clocked in/out date filters.", "example": "2024-03-17", "schema": { "type": "string" } }, { "name": "business_date_end", "in": "query", "description": "Return time punches with business date (based on clocked in date) before or on the specified date. UTC in ISO8601 format. If used, it will take priority over all other clocked in/out date filters.", "example": "2024-03-17", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32", "description": "Time punch ID" }, "shift_id": { "type": "integer", "description": "Shift ID. Can be unassigned" }, "user_id": { "type": "integer", "description": "The 7shifts ID of the user who is clocking in." }, "editable_punch": { "type": "boolean", "description": "If true the time punch can be edited by a manager. Set to false via POS integrations" }, "role_id": { "type": "integer", "description": "Role ID" }, "company_id": { "type": "integer", "description": "Company ID" }, "location_id": { "type": "integer", "description": "Location ID" }, "department_id": { "type": "integer", "nullable": true, "description": "Department ID. Defaults to 0 if not defined." }, "hourly_wage": { "type": "integer", "minimum": 0, "description": "Calculated hourly wage. Use the users_wages endpoint value for accuracy" }, "approved": { "type": "boolean", "description": "If true the time punch is approved" }, "clocked_in": { "type": "string", "format": "date-time", "description": "The start date and time when the user clocked in. Formatted as ISO8601 datetime in UTC timezone.", "example": "2020-01-20T12:00:00.000Z" }, "clocked_out": { "type": "string", "format": "date-time", "description": "The start date and time when the user clocked out. Formatted as ISO8601 datetime in UTC timezone.", "example": "2020-01-20T12:00:00.000Z", "nullable": true }, "notes": { "type": "string", "description": "Additional notes for a shift" }, "auto_clocked_out": { "type": "boolean", "description": "If true the time punch was auto clocked out" }, "clocked_in_offline": { "type": "boolean", "description": "If true the time punch was clocked in offline" }, "clocked_out_offline": { "type": "boolean", "description": "If true the time punch was clocked out offline" }, "tips": { "type": "integer", "description": "Tips declared for the shift in cents" }, "pos_type": { "type": "string", "nullable": true, "description": "The source of the time punch. 7shift apps will be web", "example": "web" }, "breaks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "user_id": { "type": "integer" }, "custom_break_id": { "type": "integer" }, "paid": { "type": "boolean" }, "in": { "type": "string", "format": "date-time", "example": "2020-01-20T12:00:00-0400" }, "out": { "type": "string", "format": "date-time", "nullable": true, "example": "2020-01-20T12:00:00-0400" } }, "required": [ "id", "user_id", "custom_break_id", "paid", "in", "out" ] } }, "created": { "type": "string", "format": "date-time", "description": "The date and time when created. Formatted as ISO8601 datetime in UTC timezone.", "example": "2020-01-20T12:00:00.000Z", "nullable": true }, "modified": { "type": "string", "format": "date-time", "description": "The date and time when last modified. Formatted as ISO8601 datetime in UTC timezone.", "example": "2020-01-20T12:00:00.000Z", "nullable": true }, "deleted": { "type": "boolean", "description": "If true the time punch is deleted" } }, "required": [ "id", "shift_id", "user_id", "editable_punch", "role_id", "location_id", "company_id", "approved", "hourly_wage", "clocked_in", "clocked_out", "notes", "auto_clocked_out", "clocked_in_offline", "clocked_out_offline", "tips", "created", "modified" ] } }, "meta": { "type": "object", "properties": { "cursor": { "type": "object", "properties": { "current": { "type": "string", "description": "The current cursor.", "nullable": true }, "prev": { "type": "string", "description": "A cursor for navigating to the previous page.", "nullable": true }, "next": { "type": "string", "description": "A cursor for navigating to the next page.", "nullable": true }, "count": { "type": "integer", "description": "The total items in the current cursor.", "nullable": true } }, "required": [ "current", "prev", "next", "count" ] } }, "required": [ "cursor" ] }, "object": { "type": "string", "enum": [ "time_punches" ] } }, "required": [ "data", "meta", "object" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "The primary identifier for the problem type (URI reference)." }, "title": { "type": "string", "description": "A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization." }, "status": { "type": "integer", "description": "The HTTP status code." }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence of the problem." }, "code": { "type": "integer", "description": "The error code can be used to look up the reason why the request failed." }, "param": { "type": "string", "description": "The request parameter that this error is related to." } }, "required": [ "type", "title", "status", "detail" ] }, "examples": { "401": { "summary": "An example of a 401 response", "value": { "type": "basic", "title": "This is a Unauthorized error message", "status": 401, "detail": "A human-readable explanation specific to this occurrence of the problem.", "code": 401, "param": "param" } } } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "The primary identifier for the problem type (URI reference)." }, "title": { "type": "string", "description": "A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization." }, "status": { "type": "integer", "description": "The HTTP status code." }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence of the problem." }, "code": { "type": "integer", "description": "The error code can be used to look up the reason why the request failed." }, "param": { "type": "string", "description": "The request parameter that this error is related to." } }, "required": [ "type", "title", "status", "detail" ] }, "examples": { "403": { "summary": "An example of a 403 response", "value": { "type": "basic", "title": "This is a Forbidden error message", "status": 403, "detail": "A human-readable explanation specific to this occurrence of the problem.", "code": 403, "param": "param" } } } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "The primary identifier for the problem type (URI reference)." }, "title": { "type": "string", "description": "A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization." }, "status": { "type": "integer", "description": "The HTTP status code." }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence of the problem." }, "code": { "type": "integer", "description": "The error code can be used to look up the reason why the request failed." }, "param": { "type": "string", "description": "The request parameter that this error is related to." } }, "required": [ "type", "title", "status", "detail" ] }, "examples": { "422": { "summary": "An example of a 422 response", "value": { "type": "basic", "title": "This is a Unprocessable Entity error message", "status": 422, "detail": "A human-readable explanation specific to this occurrence of the problem.", "code": 422, "param": "param" } } } } } }, "500": { "description": "Server Error", "content": { "application/problem+json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "The primary identifier for the problem type (URI reference)." }, "title": { "type": "string", "description": "A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization." }, "status": { "type": "integer", "description": "The HTTP status code." }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence of the problem." }, "code": { "type": "integer", "description": "The error code can be used to look up the reason why the request failed." }, "param": { "type": "string", "description": "The request parameter that this error is related to." } }, "required": [ "type", "title", "status", "detail" ] }, "examples": { "500": { "summary": "An example of a 500 response", "value": { "type": "basic", "title": "This is a Server error message", "status": 500, "detail": "A human-readable explanation specific to this occurrence of the problem.", "code": 500, "param": "param" } } } } } } } } } }, "components": { "securitySchemes": { "OAuth2": { "type": "oauth2", "flows": { "clientCredentials": { "tokenUrl": "https://app.7shifts.com/oauth2/token", "refreshUrl": "https://app.7shifts.com/oauth2/token", "scopes": { "v1_access": "Required to access APIv1 endpoints." } }, "password": { "tokenUrl": "https://app.7shifts.com/oauth2/token", "refreshUrl": "https://app.7shifts.com/oauth2/token", "scopes": { "v1_access": "Required to access APIv1 endpoints." } }, "authorizationCode": { "authorizationUrl": "https://app.7shifts.com/oauth2/authorize", "tokenUrl": "https://app.7shifts.com/oauth2/token", "refreshUrl": "https://app.7shifts.com/oauth2/token", "scopes": { "v1_access": "Required to access APIv1 endpoints." } } } }, "cookieAuth": { "type": "apiKey", "in": "cookie", "name": "7session" } } }, "security": [ { "OAuth2": [] }, { "cookieAuth": [] } ], "tags": [ { "name": "Time Punches" } ] } ```