Interfolio Units API

openapi: 3.2.0
info:
  title: Interfolio Units API
  version: 1.0.0
  x-logo:
    url: /images/logo_faculty180_intf.png
  description: 'Operations tagged Units across 2 of this provider''s published API definitions: faculty180-swagger.json, interfolio-faculty180-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://faculty180.interfolio.com
tags:
- name: Units
  description: Create & retrieve details of academic units.
paths:
  /api.php/units:
    get:
      tags:
      - Units
      summary: Retrieves a listing of academic units
      description: 'Description


        Retrieve academic units within your institution. A count of units will be returned if no parameters are specified.


        Example URL(s)


        https://faculty180.interfolio.com/api.php/units?data=detailed


        https://faculty180.interfolio.com/api.php/units?data=detailed&unitid=2'
      operationId: units
      parameters:
      - $ref: '#/components/parameters/unitid'
      - name: data
        in: query
        description: "Determines the extent of data that will be returned.\n  *  **Count:** Returns count of number of units found.\n  *  **Summary:** Returns an array containing a subset of values for all units.\n  *  **Detailed:** Returns an array of values for all units."
        schema:
          type: string
          enum:
          - count
          - summary
          - detailed
          default: count
      - $ref: '#/components/parameters/q'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/depth'
      responses:
        '200':
          description: A list with units.
          content:
            application/json:
              example:
              - unit_id: 2
                unit_name: College of Business
                unit_prefix: COB
                unit_level: 2
                parent_unitid: 1
                external_id: '1'
        default:
          description: an "unexpected" error
    post:
      tags:
      - Units
      summary: Create a new unit
      description: 'Description


        Creates units. Creating units via the API does not show any indication of the creation of units in the Bulk Data Uploads administrative interface within Faculty180. This call is not a bulk call and can only handle one unit at a time.


        Example URL(s)


        https://faculty180.interfolio.com/api.php/units'
      operationId: unitCreate
      responses:
        '200':
          description: Unit inserted successfully.
        '400':
          description: "Possible errors include:\n  *  Unable to parse request data.\n  *  Required field <field> not provided.\n  *  Unit Level must be an integer between 2 and 8.\n  *  Unit Level does not exist.\n  *  Parent Unit must be an integer.\n  *  Unit Name already exists.\n  *  Unit Prefix already exists.\n  *  Parent unit does not exist at unit level <unit_level>."
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/unitPost'
        required: true
    servers:
    - url: https://faculty180.interfolio.com
  /api.php/units/{unitid}:
    get:
      tags:
      - Units
      summary: Retrieves details on the specific unit
      description: 'Description


        Retrieve a single academic unit within your institution. A count of the unit will be returned if no parameters are specified.


        Example URL(s)


        https://faculty180.interfolio.com/api.php/units/2?data=detailed'
      operationId: unitDetails
      parameters:
      - name: unitid
        in: path
        description: Retrieve a unit by unitid.
        required: true
        schema:
          type: integer
      - name: data
        in: query
        description: "Determines the extent of data that will be returned.\n  *  **Count:** Returns value of 1 if desired resource exists or 0 otherwise.\n  *  **Summary:** Returns an array containing a subset of values for the unit.\n  *  **Detailed:** Returns an array of values for the unit."
        schema:
          type: string
          enum:
          - count
          - summary
          - detailed
          default: count
      - $ref: '#/components/parameters/q'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: A specified unit.
          content:
            application/json:
              example:
              - unit_id: 1
                unit_name: University
                unit_prefix: UNIV
                unit_level: 1
                external_id: '1'
                parent_unitid: 0
        default:
          description: an "unexpected" error
    servers:
    - url: https://faculty180.interfolio.com
components:
  schemas:
    unitPost:
      required:
      - unit_name
      - unit_prefix
      - unit_level
      - parent_unitid
      properties:
        unit_name:
          type: string
        unit_prefix:
          type: string
        unit_level:
          type: integer
        parent_unitid:
          type: integer
        external_id:
          type: string
      type: object
  parameters:
    unitid:
      name: unitid
      in: query
      description: 'Retrieve a unit with specific unitid(s).

        *  When defined, the unit specified and any sub-units are returned down the whole depth of the unit tree.

        *  When undefined, highest unit accessible and any sub-units are returned.

        *  Multiple values can be sent as a comma separated list.'
      schema:
        type: array
        items:
          type: integer
    q:
      name: q
      in: query
      description: Search term. Use '*' as wildcard.
      schema:
        type: string
    depth:
      name: depth
      in: query
      description: When defined, specifies how deep to recurse down the unit tree to find subunits.
      schema:
        type: integer
    limit:
      name: limit
      in: query
      description: Limit query to specified number of records.
      schema:
        type: integer
    offset:
      name: offset
      in: query
      description: Used to offset queries that are segmented into chunks with limit.
      schema:
        type: integer
x-refined-from:
- faculty180-swagger.json
- interfolio-faculty180-openapi.yml