openapi: 3.1.0
info:
  title: 7shifts Availability Users API
  version: '2.0'
  description: 7shifts is a restaurant employee scheduling, time-tracking, and team management platform. The 7shifts API v2 is a REST API for managing companies, locations, departments, roles, users (employees), schedules, shifts, time punches, wages, time off, availability, sales receipts, forecasts, tasks, tip pools, and webhooks. Authentication uses Bearer access tokens for internal access or OAuth 2.0 client credentials for partner integrations. Endpoints documented here were confirmed from the 7shifts developer reference (developers.7shifts.com) and its llms.txt index. Most resources are scoped to a company via the /v2/company/{company_id} path prefix. Collection endpoints use cursor-based pagination via the cursor and limit query parameters. Date-based API versions are selected with the x-api-version header (YYYY-MM-DD).
  contact:
    name: 7shifts Developer Portal
    url: https://developers.7shifts.com/reference/introduction
  license:
    name: 7shifts API Terms
    url: https://www.7shifts.com/legal/terms-of-service
servers:
- url: https://api.7shifts.com
  description: 7shifts API production base URL
tags:
- name: Users
  description: Users (employees) scoped to a company.
paths:
  /v2/company/{company_id}/users:
    get:
      tags:
      - Users
      operationId: listUsers
      summary: List Users
      parameters:
      - $ref: '#/components/parameters/CompanyIdPath'
      - name: modified_since
        in: query
        required: false
        description: Filter by modification date (YYYY-MM-DD).
        schema:
          type: string
      - name: location_id
        in: query
        required: false
        description: Filter by location (mutually exclusive with department_id and role_id).
        schema:
          type: integer
          format: int64
      - name: department_id
        in: query
        required: false
        description: Filter by department (mutually exclusive with location_id and role_id).
        schema:
          type: integer
          format: int64
      - name: role_id
        in: query
        required: false
        description: Filter by role (mutually exclusive with location_id and department_id).
        schema:
          type: integer
          format: int64
      - name: status
        in: query
        required: false
        description: User status filter.
        schema:
          type: string
          enum:
          - active
          - inactive
      - name: name
        in: query
        required: false
        description: Partial or full employee name filter.
        schema:
          type: string
      - name: sort_by
        in: query
        required: false
        description: Sort field and direction (e.g. firstname.asc,lastname.desc).
        schema:
          type: string
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/ApiVersionHeader'
      - $ref: '#/components/parameters/CompanyGuidHeader'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  meta:
                    $ref: '#/components/schemas/CursorMeta'
        '403':
          description: Forbidden
      security:
      - bearerAuth: []
    post:
      tags:
      - Users
      operationId: createUser
      summary: Create User
      parameters:
      - $ref: '#/components/parameters/CompanyIdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '201':
          description: Created
        '400':
          description: Bad request
      security:
      - bearerAuth: []
  /v2/company/{company_id}/users/{identifier}:
    get:
      tags:
      - Users
      operationId: retrieveUser
      summary: Retrieve User
      parameters:
      - $ref: '#/components/parameters/CompanyIdPath'
      - name: identifier
        in: path
        required: true
        description: User identifier. Accepts either a 7shifts user ID or a punch ID with the prefix "punch:".
        schema:
          type: string
      - name: include_inactive
        in: query
        required: false
        description: Include inactive users in the response.
        schema:
          type: boolean
      - $ref: '#/components/parameters/ApiVersionHeader'
      - $ref: '#/components/parameters/CompanyGuidHeader'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/User'
        '400':
          description: Bad request
        '403':
          description: Forbidden
        '404':
          description: Not found
      security:
      - bearerAuth: []
    put:
      tags:
      - Users
      operationId: updateUser
      summary: Update User
      parameters:
      - $ref: '#/components/parameters/CompanyIdPath'
      - name: identifier
        in: path
        required: true
        description: User identifier.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        '200':
          description: Updated
        '400':
          description: Bad request
        '404':
          description: Not found
      security:
      - bearerAuth: []
components:
  parameters:
    Cursor:
      name: cursor
      in: query
      required: false
      description: Pagination cursor for the next or previous page.
      schema:
        type: string
    CompanyIdPath:
      name: company_id
      in: path
      required: true
      description: Company identifier.
      schema:
        type: integer
        format: int64
    ApiVersionHeader:
      name: x-api-version
      in: header
      required: false
      description: 7shifts API version (YYYY-MM-DD).
      schema:
        type: string
    Limit:
      name: limit
      in: query
      required: false
      description: Results per page (1-500, default 100; 20 for some collections).
      schema:
        type: integer
        minimum: 1
        maximum: 500
        default: 100
    CompanyGuidHeader:
      name: x-company-guid
      in: header
      required: false
      description: Company GUID.
      schema:
        type: string
        format: uuid
  schemas:
    CursorMeta:
      title: Cursor Meta
      type: object
      description: Cursor-based pagination metadata.
      properties:
        cursor:
          type: object
          properties:
            current:
              type: string
            next:
              type: string
              nullable: true
            prev:
              type: string
              nullable: true
        count:
          type: integer
    User:
      title: User
      type: object
      properties:
        id:
          type: integer
          format: int64
        first_name:
          type: string
          maxLength: 80
        last_name:
          type: string
          maxLength: 80
        email:
          type: string
          format: email
          maxLength: 155
        mobile_number:
          type: string
          description: Phone number for notifications.
        active:
          type: boolean
          description: Login permission status.
        type:
          type: string
          enum:
          - employee
          - asst_manager
          - manager
          - employer
        invite_status:
          type: string
          enum:
          - accepted
          - pending
          - required
          - missing_contact_info
        employee_id:
          type: string
          description: Company-assigned employee identifier.
        hourly_wage:
          type: integer
          description: Wage in cents.
        skill_level:
          type: integer
        created:
          type: string
          format: date-time
        modified:
          type: string
          format: date-time
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Access token obtained from /oauth2/token passed as a Bearer token.
    oauth2:
      type: oauth2
      description: OAuth 2.0 with client_credentials, password, authorization_code, and refresh_token grant types.
      flows:
        clientCredentials:
          tokenUrl: https://api.7shifts.com/oauth2/token
          scopes: {}