--- updatedAt: 2025-06-05T01:09:09.000Z agentTools: projectIndex: https://developers.7shifts.com/v2.2023.0501/llms.txt --- # Retrieve Engagement Overview Beta # OpenAPI definition ```json { "openapi": "3.0.2", "info": { "title": "7shifts API", "contact": { "email": "api-support@7shifts.com" }, "version": "2023-05-01" }, "servers": [ { "url": "https://api.7shifts.com", "description": "Production server" } ], "paths": { "/v2/company/{company_id}/locations/{location_id}/engage_overview": { "get": { "tags": [ "Engage" ], "summary": "Retrieve Engagement Overview", "operationId": "getEngageOverviewByLocationId", "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": 384 }, { "name": "location_id", "in": "path", "description": "Location ID", "required": true, "schema": { "type": "integer", "format": "int64" }, "example": 408 }, { "name": "date", "in": "query", "description": "A date with YYYY-MM-DD format", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "example": "2022-11-22" }, { "name": "frequency", "in": "query", "description": "Length of the engage data set", "required": false, "schema": { "type": "string", "enum": [ "week", "month" ] }, "example": "week" }, { "name": "user_type", "in": "query", "description": "select user type for engage data", "required": false, "schema": { "type": "string", "enum": [ "employees", "managers", "assistant_managers" ] }, "example": "managers" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "engage_overview" ] }, "data": { "type": "object", "properties": { "location_stats": { "type": "object", "properties": { "lates": { "type": "object", "properties": { "current": { "type": "integer" }, "previous": { "type": "integer" } }, "required": [ "current", "previous" ] }, "no_shows": { "type": "object", "properties": { "current": { "type": "integer" }, "previous": { "type": "integer" } }, "required": [ "current", "previous" ] }, "sick_shifts": { "type": "object", "properties": { "current": { "type": "integer" }, "previous": { "type": "integer" } }, "required": [ "current", "previous" ] }, "shift_bids": { "type": "object", "properties": { "current": { "type": "integer" }, "previous": { "type": "integer" } }, "required": [ "current", "previous" ] }, "shift_drops": { "type": "object", "properties": { "current": { "type": "integer" }, "previous": { "type": "integer" } }, "required": [ "current", "previous" ] } }, "required": [ "lates", "no_shows", "sick_shifts", "shift_bids", "shift_drops" ] }, "employee_stats": { "type": "object", "properties": { "most_reliable": { "type": "object", "properties": { "id": { "type": "integer" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "photo_url": { "type": "string" }, "primary_role": { "type": "string", "nullable": true } }, "required": [ "id", "first_name", "last_name", "photo_url", "primary_role" ] }, "most_eager": { "type": "object", "properties": { "id": { "type": "integer" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "photo_url": { "type": "string" }, "primary_role": { "type": "string", "nullable": true } }, "required": [ "id", "first_name", "last_name", "photo_url", "primary_role" ] }, "most_sick": { "type": "object", "properties": { "id": { "type": "integer" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "photo_url": { "type": "string" }, "primary_role": { "type": "string", "nullable": true } }, "required": [ "id", "first_name", "last_name", "photo_url", "primary_role" ] }, "most_late": { "type": "object", "properties": { "id": { "type": "integer" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "photo_url": { "type": "string" }, "primary_role": { "type": "string", "nullable": true } }, "required": [ "id", "first_name", "last_name", "photo_url", "primary_role" ] }, "most_drops": { "type": "object", "properties": { "id": { "type": "integer" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "photo_url": { "type": "string" }, "primary_role": { "type": "string", "nullable": true } }, "required": [ "id", "first_name", "last_name", "photo_url", "primary_role" ] } }, "required": [ "most_reliable", "most_eager", "most_sick", "most_late", "most_drops" ] }, "engagement_scores": { "type": "object", "properties": { "most_engaged": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "photo_url": { "type": "string" }, "primary_role": { "type": "string", "nullable": true } }, "required": [ "id", "first_name", "last_name", "photo_url", "primary_role" ] }, "current_score": { "type": "integer" }, "metrics": { "type": "object", "properties": { "shift_bids": { "type": "object", "properties": { "stat": { "type": "integer" }, "ranking": { "type": "integer" } }, "required": [ "stat", "ranking" ] }, "dropped_shifts": { "type": "object", "properties": { "stat": { "type": "integer" }, "ranking": { "type": "integer" } }, "required": [ "stat", "ranking" ] }, "no_shows": { "type": "object", "properties": { "stat": { "type": "integer" }, "ranking": { "type": "integer" } }, "required": [ "stat", "ranking" ] }, "lates": { "type": "object", "properties": { "stat": { "type": "integer" }, "ranking": { "type": "integer" } }, "required": [ "stat", "ranking" ] }, "total_shifts": { "type": "integer" } }, "required": [ "shift_bids", "dropped_shifts", "no_shows", "lates", "total_shifts" ] } }, "required": [ "user", "current_score", "metrics" ] } }, "least_engaged": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "photo_url": { "type": "string" }, "primary_role": { "type": "string", "nullable": true } }, "required": [ "id", "first_name", "last_name", "photo_url", "primary_role" ] }, "current_score": { "type": "integer" }, "metrics": { "type": "object", "properties": { "shift_bids": { "type": "object", "properties": { "stat": { "type": "integer" }, "ranking": { "type": "integer" } }, "required": [ "stat", "ranking" ] }, "dropped_shifts": { "type": "object", "properties": { "stat": { "type": "integer" }, "ranking": { "type": "integer" } }, "required": [ "stat", "ranking" ] }, "no_shows": { "type": "object", "properties": { "stat": { "type": "integer" }, "ranking": { "type": "integer" } }, "required": [ "stat", "ranking" ] }, "lates": { "type": "object", "properties": { "stat": { "type": "integer" }, "ranking": { "type": "integer" } }, "required": [ "stat", "ranking" ] }, "total_shifts": { "type": "integer" } }, "required": [ "shift_bids", "dropped_shifts", "no_shows", "lates", "total_shifts" ] } }, "required": [ "user", "current_score", "metrics" ] } } }, "required": [ "most_engaged", "least_engaged" ] }, "shift_feedback": { "type": "object", "properties": { "current": { "type": "number", "nullable": true }, "previous": { "type": "number", "nullable": true } }, "required": [ "current", "previous" ] }, "tenure": { "type": "object", "properties": { "average_tenure": { "type": "integer", "nullable": true } }, "required": [ "average_tenure" ] } }, "required": [ "location_stats", "employee_stats", "engagement_scores", "shift_feedback", "tenure" ] } }, "required": [ "object", "data" ] } } } }, "400": { "description": "Not found", "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" ] } } } }, "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" ] } } } }, "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" ] } } } }, "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" ] } } } } } } } }, "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": "Engage" } ], "x-readme": { "explorer-enabled": true, "proxy-enabled": true } } ```