Teachworks Employees API

openapi: 3.0.3
info:
  title: Teachworks Availabilities Employees API
  description: 'The Teachworks API is a REST API that lets Teachworks users build custom integrations against the data in their Teachworks account - customers (families and independent students), students, employees (teachers and staff), lessons and events, services, invoices, payments, and teacher wages. Teachworks is business management software for tutoring companies, music schools, and test-prep centers. The API is available on the Growth and Premium plans. All requests are made over HTTPS to https://api.teachworks.com/v1 and authenticated with an account API token passed in the Authorization header using the scheme "Authorization: Token token=API_TOKEN". Responses are JSON. List endpoints are paginated (20 records per page by default, up to 80 via per_page) and support field-based search and id range filters. The API is rate limited to 4 requests per second per token. There is no native webhook or WebSocket surface; event-driven integrations are handled through Zapier, Make, and Integrately polling. All paths in this document are confirmed against the official Teachworks Postman API reference.'
  version: '1.0'
  contact:
    name: Teachworks Support
    url: https://teachworks.com/addons/api
    email: support@teachworks.com
servers:
- url: https://api.teachworks.com/v1
  description: Teachworks API
security:
- tokenAuth: []
tags:
- name: Employees
  description: Teachers and staff, their status, earnings, and lesson totals.
paths:
  /employees:
    get:
      operationId: listEmployees
      tags:
      - Employees
      summary: List all Employees
      parameters:
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          $ref: '#/components/responses/CollectionOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createEmployee
      tags:
      - Employees
      summary: Create an Employee
      requestBody:
        $ref: '#/components/requestBodies/GenericJson'
      responses:
        '200':
          $ref: '#/components/responses/ResourceOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /employees/{id}:
    parameters:
    - $ref: '#/components/parameters/Id'
    get:
      operationId: getEmployee
      tags:
      - Employees
      summary: Retrieve an Employee
      responses:
        '200':
          $ref: '#/components/responses/ResourceOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateEmployee
      tags:
      - Employees
      summary: Update an Employee
      requestBody:
        $ref: '#/components/requestBodies/GenericJson'
      responses:
        '200':
          $ref: '#/components/responses/ResourceOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /employees/{id}/earnings:
    parameters:
    - $ref: '#/components/parameters/Id'
    get:
      operationId: getEmployeeEarnings
      tags:
      - Employees
      summary: Retrieve Employee Earnings
      responses:
        '200':
          $ref: '#/components/responses/ResourceOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /employees/{id}/lesson_totals:
    parameters:
    - $ref: '#/components/parameters/Id'
    get:
      operationId: getEmployeeLessonTotals
      tags:
      - Employees
      summary: Retrieve Employee Lesson Totals
      responses:
        '200':
          $ref: '#/components/responses/ResourceOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /employees/{id}/set_status:
    parameters:
    - $ref: '#/components/parameters/Id'
    put:
      operationId: setEmployeeStatus
      tags:
      - Employees
      summary: Set Employee Status
      requestBody:
        $ref: '#/components/requestBodies/GenericJson'
      responses:
        '200':
          $ref: '#/components/responses/ResourceOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /employees/{id}/custom_fields:
    parameters:
    - $ref: '#/components/parameters/Id'
    put:
      operationId: setEmployeeCustomFields
      tags:
      - Employees
      summary: Set Custom Field Values
      requestBody:
        $ref: '#/components/requestBodies/GenericJson'
      responses:
        '200':
          $ref: '#/components/responses/ResourceOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
components:
  requestBodies:
    GenericJson:
      required: true
      content:
        application/json:
          schema:
            type: object
            additionalProperties: true
  parameters:
    Page:
      name: page
      in: query
      required: false
      description: 1-based page number for pagination. Defaults to 1.
      schema:
        type: integer
        default: 1
    Id:
      name: id
      in: path
      required: true
      description: The ID of the resource.
      schema:
        type: integer
    PerPage:
      name: per_page
      in: query
      required: false
      description: Number of records per page. Defaults to 20, maximum 80.
      schema:
        type: integer
        default: 20
        maximum: 80
  responses:
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    CollectionOk:
      description: A paginated list of resources.
      content:
        application/json:
          schema:
            type: array
            items:
              type: object
              additionalProperties: true
    Unauthorized:
      description: Missing or invalid API token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ResourceOk:
      description: A single resource.
      content:
        application/json:
          schema:
            type: object
            additionalProperties: true
    UnprocessableEntity:
      description: Validation failed for the submitted attributes.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
        errors:
          type: array
          items:
            type: string
  securitySchemes:
    tokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Account API token passed in the Authorization header using the scheme "Authorization: Token token=API_TOKEN". Generate a token on the Integrations and Add-ons page in Teachworks. All requests must be over HTTPS.'