Skip to main content

[API Endpoint] Forms

Samantha L Cook
Updated 
https://teachboost.com/api/v1/forms

  • 15 requests are allowed every 60 seconds.

Options

offset: Integer

  • You can filter results by setting a starting point using this "offset" option; for instance, to return "only forms after the 1000th form"
    Default is 0
    Format: --data "offset=1000"

limit: Integer

  • Set the total number of forms to return using the "limit" option; for instance, to return only the first 100 forms
  • Default and max is 100
  • Format: --data "limit=100"

template_id: Integer

  • Limit the result set to only forms with specific template IDs (integers)
  • Format: --data: "template_id=[34,56,133]"

start_date: DateTime

  • This option sets the beginning of a time bound with which to filter results
  • Format: --data "start_date=2017-01-01 00:00:00"

end_date: DateTime

  • Similar to start_date, use this option to set the end of a time bound with which to filter your results
  • Format: --data "end_date=2017-01-31 23:59:59"

Sample Object

{
    id: 420313,
    status: 'complete',
    date: '2016-01-02 10:00:00',
    type: 'informal_obs',
    type_label: 'Informal Observation',
    group_ids: [
        15501, 16540
    ],
    topic_ids: [
        142145
    ],
    author_ids: [
        133456
    ],
    cycle_id: 0,
    parent_id: 0,
    start_time: '10:00 am',
    end_time: '11:00 am',
    template_id: 1501,
    template_name: 'Classroom Observation - Sketch',
    hidden_from: [
        142145
    ],
    is_subform: false,
    last_modified: '2016-10-27 18:26:24',
    topic_notified_on: null,
    topic_released_on: null
}

Returned Global Fields

The following data fields are returned at the beginning of every Forms API response:

  • type: String, this will always be "forms" for this call
  • limit: Integer, number of form objects returned
  • offset: Integer, starting offset
  • total: Integer, total number of form objects; you can use this to determine how many calls to make when pulling down every form in your organization
  • time: String, execution time for this query (e.g., 0.064s)
  • items: the container object for the forms returned

Returned Form Fields

The following data fields are returned for every form object within items:

  • id: Integer, internal ID for the object
  • status: String, one of 'complete', 'in_progress', or 'scheduled'
  • date: DateTime, the date and time of the Form
  • type: String, internal identifier for the Form's type
  • type_label: String, human-readable label for the type
  • group_ids: Array of Integers, collection of all Groups that have access to this Form
  • topic_ids: Array of Integers, collection of User IDs who are topics of this Form
  • author_ids: Array of Integers, collection of User IDs who are authors of this Form
  • cycle_id: Integer, if this Form is the Cycle Bundle, this is the ID of the corresponding Cycle configuration
  • parent_id: Integer, if this Form belongs to a Cycle, this is the ID of the Cycle Bundle Form
  • start_time: String, user-supplied string for the start time
  • end_time: String, user-supplied string for the end time
  • template_id, Integer, internal ID of the Template this Form utilizes
  • template_name: String, name of the Template this Form utilizes
  • hidden_from: Array of Integers, collection of User IDs who explicity do not have access to this Form. Usually the topics of the Form if the Form is not shared to the topics.
  • is_subform: Bool, whether the form belongs to a Cycle Bundle. Used with parent_id above.
  • last_modified: DateTime, when the Form was last updated by a User
  • topic_notified_on: DateTime, if the topics were sent an email through Boost about this form, this is the date the email was sent
  • topic_released_on: DateTime, if the Form was released to the topics, this is the date it was released

Related articles