Forms Query

Note: The Teachify Admin API is currently under development and not yet available for public use. This documentation is provided for preview purposes only.

Endpoint and authentication. All admin queries are sent to POST /admin/graphql — not /graphql, which is the public school API. Authenticate with an sk_live_… API key in the X-Teachify-API-Key header. See the API Overview for details.

Overview

The Forms API lets you list the forms in your school and read their fields. Its primary use is to look up a form’s id so you can bind it to a consulting service as a rating form — pass that id as ratingFormId to the consultingServiceUpdate mutation.

Only general forms are returned. Auto-generated profile forms (student and lecturer profile forms) are excluded, as they are not intended to be used as rating forms.

The query requires the forms:read scope.

Available Queries

forms

Returns a paginated list of general forms for the authenticated school, ordered by creation time (newest first) — createdAt DESC, id DESC. The id tiebreak keeps paging stable when two forms share a creation timestamp.

Parameters:

Parameter	Type	Description
filter	AdminFormFilter	Filter criteria (see Filtering)
page	Int	Page number for pagination
perPage	Int	Number of items per page (default: 20, max: 50)
limit	Int	Alternative to perPage

Returns:

• A page object with:
  • nodes: Array of Form objects
  • currentPage: Current page number
  • hasNextPage: Whether there are more pages
  • hasPreviousPage: Whether there are previous pages
  • nodesCount: Total number of items matching the query
  • totalPages: Total number of pages

Example:

query {
  forms(
    page: 1,
    perPage: 10
  ) {
    nodes {
      id
      name
      description
      slug
      fields {
        id
        label
        fieldType
      }
    }
    currentPage
    hasNextPage
    hasPreviousPage
    nodesCount
    totalPages
  }
}

Form Object

The Form object contains the following fields:

Field	Type	Description
id	String!	Unique identifier. Pass this as ratingFormId when updating a consulting service
name	String	Display name of the form
description	String	Description of the form
slug	String	URL-friendly identifier. Often null — prefer id for lookups
fields	[FormField!]	The form’s fields. These define what an integrator must submit when rating a meeting bound to this form

Filtering

The forms query accepts a filter parameter of type AdminFormFilter.

Available Filters

Filter Field	Type	Description
keyword	String	Case-insensitive substring match against name or slug

Filter Example

Search forms by keyword:

query {
  forms(
    filter: {
      keyword: "rating"
    }
  ) {
    nodes {
      id
      name
    }
    nodesCount
  }
}