--- updatedAt: 2025-06-05T01:08:58.000Z agentTools: projectIndex: https://developers.7shifts.com/v2.2023.0401/llms.txt --- # List Availabilities # OpenAPI definition ```json { "openapi": "3.0.2", "info": { "title": "7shifts API", "contact": { "email": "api-support@7shifts.com" }, "version": "2023-04-01" }, "servers": [ { "url": "https://api.7shifts.com", "description": "Production server" } ], "paths": { "/v2/company/{company_id}/availabilities": { "get": { "tags": [ "Availability" ], "summary": "List Availabilities", "operationId": "ListAvailabilities", "x-public-api": true, "parameters": [ { "name": "company_id", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "integer", "format": "int64" }, "example": 1234 }, { "name": "cursor", "in": "query", "description": "Cursor for the next or previous page of results.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "The number results desired per page.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100, "format": "int64" } }, { "name": "location_id", "in": "query", "description": "Location ID", "required": false, "schema": { "type": "integer", "format": "int64" }, "example": 1234 }, { "name": "user_id", "in": "query", "description": "User ID", "required": false, "schema": { "type": "integer", "format": "int64" }, "example": 1234 }, { "name": "status", "in": "query", "description": "Return availabilities for a specified status (pending = 0, approved = 1, declined = 2).", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "repeating", "in": "query", "description": "Return repeating or weekly availabilities.", "required": false, "schema": { "type": "boolean" } }, { "name": "week_gte", "in": "query", "description": "Return availabilities for a specific week.", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "A date with YYYY-MM-DD format", "example": "2020-01-01" } }, { "name": "week_to_include_repeating_gte", "in": "query", "description": "Return repeating availabilities that end before or on a specified week.", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "A date with YYYY-MM-DD format", "example": "2020-01-01" } }, { "name": "order_field", "in": "query", "description": "The field that availabilities will be sorted by.", "schema": { "type": "string" } }, { "name": "order_dir", "in": "query", "description": "The direction that availabilities will be sorted by.", "schema": { "type": "string", "pattern": "^(,?[a-zA-Z_]*(\\.(asc|desc))?){1,}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "availability" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Availability ID" }, "user_id": { "type": "integer", "description": "User ID" }, "company_id": { "type": "integer", "description": "Company ID" }, "week": { "type": "string", "nullable": true, "description": "Week date of the availability" }, "week_to": { "type": "string", "nullable": true, "description": "Week to date of the availability" }, "repeat": { "type": "boolean", "description": "If true, availability is repeating" }, "status": { "type": "integer", "description": "Indicates the status of the availability" }, "status_action_user_id": { "type": "integer", "nullable": true, "description": "The user ID of the user that approved/declined the availability" }, "status_action_message": { "type": "string", "nullable": true, "description": "The message when the availability was approved/declined" }, "mon": { "type": "integer", "description": "The availability status for the day" }, "mon_from": { "type": "string", "format": "time", "description": "The start time of the availability for the day" }, "mon_to": { "type": "string", "format": "time", "description": "The end time of the availability for the day" }, "mon_comments": { "type": "string", "nullable": true, "description": "Comments included in the days availability" }, "mon_reason": { "type": "string", "description": "The reason ID for the day" }, "tue": { "type": "integer", "description": "The availability status for the day" }, "tue_from": { "type": "string", "format": "time", "description": "The start time of the availability for the day" }, "tue_to": { "type": "string", "format": "time", "description": "The end time of the availability for the day" }, "tue_comments": { "type": "string", "nullable": true, "description": "Comments included in the days availability" }, "tue_reason": { "type": "string", "description": "The reason ID for the day" }, "wed": { "type": "integer", "description": "The availability status for the day" }, "wed_from": { "type": "string", "format": "time", "description": "The start time of the availability for the day" }, "wed_to": { "type": "string", "format": "time", "description": "The end time of the availability for the day" }, "wed_comments": { "type": "string", "nullable": true, "description": "Comments included in the days availability" }, "wed_reason": { "type": "string", "description": "The reason ID for the day" }, "thu": { "type": "integer", "description": "The availability status for the day" }, "thu_from": { "type": "string", "format": "time", "description": "The start time of the availability for the day" }, "thu_to": { "type": "string", "format": "time", "description": "The end time of the availability for the day" }, "thu_comments": { "type": "string", "nullable": true, "description": "Comments included in the days availability" }, "thu_reason": { "type": "string", "description": "The reason ID for the day" }, "fri": { "type": "integer", "description": "The availability status for the day" }, "fri_from": { "type": "string", "format": "time", "description": "The start time of the availability for the day" }, "fri_to": { "type": "string", "format": "time", "description": "The end time of the availability for the day" }, "fri_comments": { "type": "string", "nullable": true, "description": "Comments included in the days availability" }, "fri_reason": { "type": "string", "description": "The reason ID for the day" }, "sat": { "type": "integer", "description": "The availability status for the day" }, "sat_from": { "type": "string", "format": "time", "description": "The start time of the availability for the day" }, "sat_to": { "type": "string", "format": "time", "description": "The end time of the availability for the day" }, "sat_comments": { "type": "string", "nullable": true, "description": "Comments included in the days availability" }, "sat_reason": { "type": "string", "description": "The reason ID for the day" }, "sun": { "type": "integer", "description": "The availability status for the day" }, "sun_from": { "type": "string", "format": "time", "description": "The start time of the availability for the day" }, "sun_to": { "type": "string", "format": "time", "description": "The end time of the availability for the day" }, "sun_comments": { "type": "string", "nullable": true, "description": "Comments included in the days availability" }, "sun_reason": { "type": "string", "description": "The reason ID for the day" }, "created": { "type": "string", "nullable": true, "description": "The created date of the shift in UTC" }, "modified": { "type": "string", "nullable": true, "description": "The last modified date of the shift in UTC" }, "old_approved_data": { "nullable": true, "type": "object", "properties": { "id": { "type": "integer", "description": "Availability ID" }, "user_id": { "type": "integer", "description": "User ID" }, "company_id": { "type": "integer", "description": "Company ID" }, "week": { "type": "string", "nullable": true, "description": "Week date of the availability" }, "week_to": { "type": "string", "nullable": true, "description": "Week to date of the availability" }, "repeat": { "type": "boolean", "description": "If true, availability is repeating" }, "status": { "type": "integer", "description": "Indicates the status of the availability" }, "mon": { "type": "integer", "description": "The availability status for the day" }, "mon_from": { "type": "string", "format": "time", "description": "The start time of the availability for the day" }, "mon_to": { "type": "string", "format": "time", "description": "The end time of the availability for the day" }, "mon_comments": { "type": "string", "nullable": true, "description": "Comments included in the days availability" }, "mon_reason": { "type": "string", "description": "The reason ID for the day" }, "tue": { "type": "integer", "description": "The availability status for the day" }, "tue_from": { "type": "string", "format": "time", "description": "The start time of the availability for the day" }, "tue_to": { "type": "string", "format": "time", "description": "The end time of the availability for the day" }, "tue_comments": { "type": "string", "nullable": true, "description": "Comments included in the days availability" }, "tue_reason": { "type": "string", "description": "The reason ID for the day" }, "wed": { "type": "integer", "description": "The availability status for the day" }, "wed_from": { "type": "string", "format": "time", "description": "The start time of the availability for the day" }, "wed_to": { "type": "string", "format": "time", "description": "The end time of the availability for the day" }, "wed_comments": { "type": "string", "nullable": true, "description": "Comments included in the days availability" }, "wed_reason": { "type": "string", "description": "The reason ID for the day" }, "thu": { "type": "integer", "description": "The availability status for the day" }, "thu_from": { "type": "string", "format": "time", "description": "The start time of the availability for the day" }, "thu_to": { "type": "string", "format": "time", "description": "The end time of the availability for the day" }, "thu_comments": { "type": "string", "nullable": true, "description": "Comments included in the days availability" }, "thu_reason": { "type": "string", "description": "The reason ID for the day" }, "fri": { "type": "integer", "description": "The availability status for the day" }, "fri_from": { "type": "string", "format": "time", "description": "The start time of the availability for the day" }, "fri_to": { "type": "string", "format": "time", "description": "The end time of the availability for the day" }, "fri_comments": { "type": "string", "nullable": true, "description": "Comments included in the days availability" }, "fri_reason": { "type": "string", "description": "The reason ID for the day" }, "sat": { "type": "integer", "description": "The availability status for the day" }, "sat_from": { "type": "string", "format": "time", "description": "The start time of the availability for the day" }, "sat_to": { "type": "string", "format": "time", "description": "The end time of the availability for the day" }, "sat_comments": { "type": "string", "nullable": true, "description": "Comments included in the days availability" }, "sat_reason": { "type": "string", "description": "The reason ID for the day" }, "sun": { "type": "integer", "description": "The availability status for the day" }, "sun_from": { "type": "string", "format": "time", "description": "The start time of the availability for the day" }, "sun_to": { "type": "string", "format": "time", "description": "The end time of the availability for the day" }, "sun_comments": { "type": "string", "nullable": true, "description": "Comments included in the days availability" }, "sun_reason": { "type": "string", "description": "The reason ID for the day" }, "created": { "type": "string", "format": "date-time", "nullable": true, "description": "The created date of the shift in UTC" } }, "required": [ "id", "user_id", "company_id", "week", "week_to", "repeat", "status", "mon", "mon_from", "mon_to", "mon_comments", "mon_reason", "tue", "tue_from", "tue_to", "tue_comments", "tue_reason", "wed", "wed_from", "wed_to", "wed_comments", "wed_reason", "thu", "thu_from", "thu_to", "thu_comments", "thu_reason", "fri", "fri_from", "fri_to", "fri_comments", "fri_reason", "sat", "sat_from", "sat_to", "sat_comments", "sat_reason", "sun", "sun_from", "sun_to", "sun_comments", "sun_reason", "created" ] } }, "required": [ "id", "user_id", "company_id", "week", "week_to", "repeat", "status", "status_action_user_id", "status_action_message", "mon", "mon_from", "mon_to", "mon_comments", "mon_reason", "tue", "tue_from", "tue_to", "tue_comments", "tue_reason", "wed", "wed_from", "wed_to", "wed_comments", "wed_reason", "thu", "thu_from", "thu_to", "thu_comments", "thu_reason", "fri", "fri_from", "fri_to", "fri_comments", "fri_reason", "sat", "sat_from", "sat_to", "sat_comments", "sat_reason", "sun", "sun_from", "sun_to", "sun_comments", "sun_reason", "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" ] } }, "required": [ "object", "data", "meta" ] } } } }, "400": { "description": "Bad Request", "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" ] } } } } } } } }, "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" }, "basicAuth": { "type": "http", "scheme": "basic" } } }, "security": [ { "OAuth2": [] }, { "basicAuth": [] }, { "cookieAuth": [] } ], "tags": [ { "name": "Availability" } ], "x-readme": { "explorer-enabled": true, "proxy-enabled": true } } ```