ZippedScript Institution API

openapi: 3.2.0
info:
  title: ZippedScript Institution API
  description: ZippedScript's enterprise education verification API
  termsOfService: https://zippedscript.com/privacy
  contact:
    email: support@zippedscript.com
  version: v1
servers:
- url: http://app.zippedscript.com/api/v1
security:
- apiKeyAuth: []
tags:
- name: Institution
paths:
  /institution/:
    parameters: []
    get:
      operationId: institution_list
      summary: List all institutions
      description: Retrieve a paginated list of institutions. The results can be filtered by name or country.
      parameters:
      - name: name
        in: query
        description: Filter by institution name
        schema:
          type: string
      - name: native_name
        in: query
        description: Filter by institution native name
        schema:
          type: string
      - name: country
        in: query
        description: Filter by institution country code
        schema:
          type: string
      - name: page
        in: query
        description: Page number
        schema:
          type: integer
      - name: page_size
        in: query
        description: The number of records to include on each page
        schema:
          type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedReadInstitutionSerializer'
      tags:
      - Institution
  /institution/countries:
    parameters: []
    get:
      operationId: institution_countries_list
      summary: List all countries
      description: Retrieve a list of all supported countries for institutions.
      responses:
        '200':
          description: A list of ISO country codes containing supported institutions
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
      tags:
      - Institution
  /institution/{institution_id}:
    parameters:
    - name: institution_id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: institution_read
      summary: Get a specific institution
      description: Retrieve details for a specific institution. The institution must be identified by its ID. If the 'verbose' parameter is set to 'true', additional details will be returned, including the institution's scripts.
      parameters:
      - name: verbose
        in: query
        description: Enable verbose details of the institution. 'true', '1' and 'yes' enable it; any other value disables it. Default is true.
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
          - '1'
          - '0'
          - 'yes'
          - 'no'
          default: 'true'
      - name: institution_id
        in: path
        description: The ID of the institution to retrieve
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadInstitution'
        '404':
          description: An institution with this ID does not exist
      tags:
      - Institution
components:
  schemas:
    DegreeDirectInstitution:
      description: A list of the returned records
      required:
      - country
      - name
      type: object
      properties:
        id:
          title: Id
          type: integer
          readOnly: true
        year_limits:
          title: Year limits
          type:
          - array
          - 'null'
          description: Valid graduation year ranges for this institution. A null start or end leaves that side open.
          items:
            type: object
            properties:
              start:
                type:
                - integer
                - 'null'
                example: 1990
              end:
                type:
                - integer
                - 'null'
                example: 2010
        country:
          title: Country
          description: The country code for the search (e.g., US)
          type: string
          maxLength: 32
          minLength: 1
        name:
          title: Name
          description: The name of the institution
          type: string
          maxLength: 255
          minLength: 1
        native_name:
          title: Native name
          type:
          - string
          - 'null'
          maxLength: 255
        additional_request_details:
          title: Additional request details
          type:
          - object
          - 'null'
    ReadInstitution:
      required:
      - name
      - country
      type: object
      properties:
        id:
          title: Id
          description: ID of the institution to be used in verification requests
          type: integer
          readOnly: true
        name:
          title: Name
          description: The name of the institution
          type: string
          maxLength: 255
          minLength: 1
        native_name:
          title: Native name
          description: The native name of the institution
          type:
          - string
          - 'null'
          maxLength: 255
        country:
          title: Country
          description: ISO Country Code
          type: string
          maxLength: 3
          minLength: 1
        city:
          title: City
          type:
          - string
          - 'null'
          maxLength: 255
        state:
          title: State
          description: This can also be a province, territory, etc.
          type:
          - string
          - 'null'
          maxLength: 255
        logo:
          title: Logo
          description: URL of the institution's logo
          type:
          - string
          - 'null'
          maxLength: 255
        year_limits:
          title: Year limits
          type:
          - array
          - 'null'
          description: Valid graduation year ranges for this institution. A null start or end leaves that side open.
          items:
            type: object
            properties:
              start:
                type:
                - integer
                - 'null'
                example: 1990
              end:
                type:
                - integer
                - 'null'
                example: 2010
        is_working:
          title: Is working
          type: boolean
    PaginatedReadInstitutionSerializer:
      required:
      - count
      - next
      - previous
      - results
      type: object
      properties:
        count:
          title: Count
          description: Total number of records able to be retrieved
          type: integer
        next:
          title: Next
          description: A link to the next page of records
          type:
          - string
          - 'null'
        previous:
          title: Previous
          description: A link to the previous page of records
          type:
          - string
          - 'null'
        results:
          description: A list of the returned records
          type: array
          items:
            $ref: '#/components/schemas/DegreeDirectInstitution'
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      name: Authorization
      in: header
      description: 'Enter the full header value, including the prefix: `Token <api_key>` for an API key from `GET /user/api-key`, or `Bearer <access>` for a JWT from `POST /user/login`. A bare key without the prefix is rejected with 403.'