ZippedScript Verification API

openapi: 3.2.0
info:
  title: ZippedScript Verification 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: Verification
paths:
  /verification/:
    parameters: []
    get:
      operationId: verification_list
      summary: List verifications
      description: List all verifications
      parameters:
      - name: request_id
        in: query
        description: Filter by request_id
        schema:
          type: string
      - name: email
        in: query
        description: Filter by email
        schema:
          type: string
      - name: institution
        in: query
        description: Filter by institution name
        schema:
          type: string
      - name: country
        in: query
        description: Filter by country
        schema:
          type: string
      - name: page
        in: query
        description: Page number for pagination
        schema:
          type: integer
      - name: page_size
        in: query
        description: Number of items per page
        schema:
          type: integer
      - name: status
        in: query
        description: Filter by status
        schema:
          type: string
      - name: start_date
        in: query
        description: Filter by start date (inclusive) for verification creation time
        schema:
          type: string
          format: date
      - name: end_date
        in: query
        description: Filter by end date (inclusive) for verification creation time
        schema:
          type: string
          format: date
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedReadVerificationSerializer'
      tags:
      - Verification
    post:
      operationId: verification_create
      summary: Create verifications
      description: Create a new verification or multiple verifications
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ReadVerification'
      tags:
      - Verification
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateVerification'
        required: true
  /verification/cancel/{verification_id}:
    parameters:
    - name: verification_id
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: verification_cancel_create
      summary: Cancel verification request
      description: Cancel a specific education verification request that is in progress.
      parameters:
      - name: verification_id
        in: path
        description: The unique identifier of the verification record
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '403':
          description: Permission denied
        '404':
          description: Not found
      tags:
      - Verification
  /verification/restart/{verification_id}:
    parameters:
    - name: verification_id
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: verification_restart_create
      summary: Restart verification
      description: Restart a verification's input process
      parameters:
      - name: verification_id
        in: path
        description: The verification ID for which to restart the input process
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Verification restarted successfully
      tags:
      - Verification
  /verification/submit/{verification_id}:
    parameters:
    - name: verification_id
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: verification_submit_create
      summary: Submit verification
      description: Submit requested information about a verification. The body is shown as JSON, but the endpoint also accepts `multipart/form-data` (and `application/x-www-form-urlencoded`) with one form field per requested field - multipart is required when any requested field is a file. (Swagger 2.0 cannot describe both a JSON body and form fields whose names depend on the verification.)
      responses:
        '200':
          description: Inputs submitted successfully
        '404':
          description: Verification not found
      tags:
      - Verification
      requestBody:
        content:
          application/json:
            schema:
              title: Verification Submission
              description: Submit the requested field data for a verification
              type: object
              properties:
                key:
                  title: input
                  description: The input field name and value to submit. The key should match the name of one of the form fields described in the form_data.field_data parameter of the associated verification. The value should be the value of that form field. There should be one of these key value pairs for each requested field_data field
                  type: string
                  example: value
                ip:
                  description: Optional. The IP address of the candidate submitting the inputs (IPv4 or IPv6). It is saved on the verification and never returned by the API
                  type: string
                  example: 203.0.113.7
        required: true
  /verification/{verification_id}:
    parameters:
    - name: verification_id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: verification_read
      summary: Get verification
      description: Get a specific verification
      parameters:
      - name: verbose
        in: query
        description: Enable verbose details of the verification. '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'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadVerification'
        '404':
          description: Verification not found
      tags:
      - Verification
    put:
      operationId: verification_update
      summary: Update verification
      description: Update a specific verification
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadVerification'
        '400':
          description: Invalid data, or verification has already been initialized
        '404':
          description: Verification not found
      tags:
      - Verification
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateVerification'
        required: true
    delete:
      operationId: verification_delete
      summary: Delete verification
      description: Delete a specific verification
      responses:
        '204':
          description: Verification deleted successfully
        '404':
          description: Verification not found
      tags:
      - Verification
components:
  schemas:
    UpdateVerification:
      type: object
      properties:
        email:
          title: Email
          description: The email of the candidate whose education is being verified
          type: string
          format: email
          minLength: 1
        graduated:
          title: Graduated
          description: Whether the candidate has graduated or not
          type: boolean
        degree_level:
          title: Degree level
          description: The level of degree that is being verified
          type: string
          minLength: 1
        graduation_year:
          title: Graduation year
          description: The year the candidate graduated or is expected to graduate
          type: integer
        institution:
          title: Institution
          description: The institution the verification is being performed for
          type: integer
    FieldDataItem:
      required:
      - label
      - element
      - name
      type: object
      properties:
        label:
          title: Label
          description: The label of the field
          type: string
          maxLength: 255
          minLength: 1
        placeholder:
          title: Placeholder
          description: The placeholder of the field
          type: string
          maxLength: 255
          minLength: 1
        type:
          title: Type
          description: The type of the input field. This is only provided if the HTML element is an input
          type: string
          enum:
          - text
          - password
          - select
          - email
          - number
          - textarea
          - date
          - datetime-local
          - url
          - checkbox
          - radio
          - file
        element:
          title: Element
          description: The type of HTML element
          type: string
          enum:
          - input
          - select
        required:
          title: Required
          description: Whether the field is required or not
          type: boolean
          default: true
        name:
          title: Name
          description: The name of the field
          type: string
          maxLength: 255
          minLength: 1
        choices:
          description: The choices of the field. This is only provided if the HTML element is a select
          type: array
          items:
            type: string
            maxLength: 255
            minLength: 1
        allowed_files:
          description: The allowed file extensions of the field. This is only provided if the input type is file
          type: array
          items:
            type: string
            maxLength: 255
            minLength: 1
        value:
          title: Value
          description: The initial value of the field
          type: string
          minLength: 1
    Status:
      description: The most recent status of the verification
      required:
      - status
      type: object
      properties:
        status:
          title: Status
          description: The current status of the verification
          type: string
          enum:
          - Awaiting credentials
          - Processing
          - Institution unreachable
          - Temporary outage
          - False positive
          - Credentials received
          - Credentials valid
          - Credentials invalid
          - Further input required
          - Login complete
          - Completed
          - Unable to verify
          - Validation in progress
          - Resubmitted credentials
          - Restarted
          - Not delivered
          - Stale
          - Legacy
          - Cancelled
        created_at:
          title: Created at
          type: string
          format: date-time
          readOnly: true
    ReadVerification:
      description: A list of the returned records
      required:
      - request_id
      type: object
      properties:
        created_at:
          title: Created at
          type: string
          format: date-time
          readOnly: true
        verification_id:
          title: Verification id
          type: string
          readOnly: true
          minLength: 1
        request_id:
          title: Request id
          description: A unique ID, used to help search for verifications
          type: string
          maxLength: 64
          minLength: 1
        email:
          title: Email
          description: The email of the candidate whose education is being verified
          type:
          - string
          - 'null'
          format: email
          maxLength: 254
        graduated:
          title: Graduated
          description: Whether the candidate has graduated or not
          type:
          - boolean
          - 'null'
        degree_level:
          title: Degree level
          description: The level of degree that is being verified
          type:
          - string
          - 'null'
          enum:
          - Certificate / Diploma or Equivalent
          - Associate / Technical or Equivalent
          - Bachelor's or equivalent
          - Master's or equivalent
          - Doctorate or equivalent
          - null
        graduation_year:
          title: Graduation year
          description: The year the candidate graduated
          type:
          - integer
          - 'null'
          maximum: 2036
          minimum: 1900
        institution:
          $ref: '#/components/schemas/ReadInstitution'
        current_status:
          $ref: '#/components/schemas/Status'
        form_data:
          $ref: '#/components/schemas/FormData'
        degrees:
          description: The degrees that are returned back when the verification is completed, if any
          type: array
          items:
            $ref: '#/components/schemas/ReadDegree'
          readOnly: true
        company_id:
          title: Company id
          type: string
          readOnly: true
        phone_number:
          title: Phone number
          description: The phone number of the end user
          type:
          - string
          - 'null'
          maxLength: 16
        phone_country_code:
          title: Phone country code
          description: The country code of the phone number
          type:
          - string
          - 'null'
          maxLength: 7
        client_name:
          title: Client name
          description: The name of the client the verification is being performed on behalf of
          type:
          - string
          - 'null'
          maxLength: 255
    FormData:
      description: The information that is required to be submitted in order to verify the candidates education. Null when complete
      required:
      - header
      - field_data
      type: object
      properties:
        header:
          title: Header
          description: The header of the form
          type: string
          maxLength: 255
          minLength: 1
        description:
          title: Description
          description: The description/sub-header of the form
          type: string
          maxLength: 255
          minLength: 1
        error:
          title: Error
          description: A descriptive error message to be displayed with the form
          type: string
          maxLength: 255
          minLength: 1
        field_data:
          description: Details about the HTML input elements that will pass the required information
          type: array
          items:
            $ref: '#/components/schemas/FieldDataItem'
        forgot_password_label:
          title: Forgot password label
          description: The forgot password label to be displayed with the form
          type: string
          maxLength: 255
          minLength: 1
        forgot_password:
          title: Forgot password
          description: The forgot password link to be stored underneath the forgot password label
          type: string
          maxLength: 255
          minLength: 1
    PaginatedReadVerificationSerializer:
      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/ReadVerification'
    ReadDegree:
      required:
      - degree
      - student_name
      - graduated
      type: object
      properties:
        id:
          title: Id
          type: integer
          readOnly: true
        level:
          title: Level
          description: The level (bachelor, master, etc) of the degree
          type:
          - string
          - 'null'
          maxLength: 255
        degree:
          title: Degree
          description: The name of the degree
          type: string
          maxLength: 255
          minLength: 1
        school_name:
          title: School name
          description: The name of the school. If null, it is the same as the requested institution name
          type:
          - string
          - 'null'
          maxLength: 255
        student_name:
          title: Student name
          type: string
          maxLength: 255
          minLength: 1
        graduated:
          title: Graduated
          type: boolean
        major:
          title: Major
          type:
          - string
          - 'null'
          maxLength: 255
        minor:
          title: Minor
          type:
          - string
          - 'null'
          maxLength: 255
        student_id:
          title: Student id
          description: The student ID/number of the user
          type:
          - string
          - 'null'
          maxLength: 255
        graduation_date:
          title: Graduation date
          type:
          - string
          - 'null'
          maxLength: 255
        last_semester_date:
          title: Last semester date
          type:
          - string
          - 'null'
          maxLength: 255
        award_number:
          title: Award number
          type:
          - string
          - 'null'
          maxLength: 255
        created_at:
          title: Created at
          type: string
          format: date-time
          readOnly: true
        additional_information:
          title: Additional information
          description: Any additional information about the degree will be return in a json object
          type:
          - object
          - 'null'
        sources:
          type: array
          items:
            type: integer
          readOnly: true
          uniqueItems: true
    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
    CreateVerification:
      required:
      - request_id
      type: object
      properties:
        request_id:
          title: Request id
          description: A unique ID, used to help search for verifications
          type: string
          maxLength: 64
          minLength: 1
        email:
          title: Email
          description: The email of the candidate whose education is being verified
          type:
          - string
          - 'null'
          format: email
          maxLength: 254
        graduated:
          title: Graduated
          description: Whether the candidate has graduated or not
          type:
          - boolean
          - 'null'
        degree_level:
          title: Degree level
          description: The level of degree that is being verified
          type:
          - string
          - 'null'
          enum:
          - Certificate / Diploma or Equivalent
          - Associate / Technical or Equivalent
          - Bachelor's or equivalent
          - Master's or equivalent
          - Doctorate or equivalent
          - null
        institution:
          title: Institution
          type: integer
        graduation_year:
          title: Graduation year
          description: The year the candidate graduated
          type:
          - integer
          - 'null'
          maximum: 2036
          minimum: 1900
        phone_number:
          title: Phone number
          description: The phone number of the end user
          type:
          - string
          - 'null'
          maxLength: 16
        phone_country_code:
          title: Phone country code
          description: The country code of the phone number
          type:
          - string
          - 'null'
          maxLength: 7
        client_name:
          title: Client name
          description: The name of the client the verification is being performed on behalf of
          type:
          - string
          - 'null'
          maxLength: 255
  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.'