Teachworks Locations API

openapi: 3.0.3
info:
  title: Teachworks Availabilities Locations 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: Locations
  description: Physical or virtual locations where lessons are delivered.
paths:
  /locations:
    get:
      operationId: listLocations
      tags:
      - Locations
      summary: List all Locations
      parameters:
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          $ref: '#/components/responses/CollectionOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createLocation
      tags:
      - Locations
      summary: Create a Location
      requestBody:
        $ref: '#/components/requestBodies/GenericJson'
      responses:
        '200':
          $ref: '#/components/responses/ResourceOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /locations/{id}:
    parameters:
    - $ref: '#/components/parameters/Id'
    get:
      operationId: getLocation
      tags:
      - Locations
      summary: Retrieve a Location
      responses:
        '200':
          $ref: '#/components/responses/ResourceOk'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateLocation
      tags:
      - Locations
      summary: Update a Location
      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.'