ZippedScript Employment API

openapi: 3.2.0
info:
  title: ZippedScript Employment 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: employment
paths:
  /employment/:
    parameters: []
    get:
      operationId: employment_list
      summary: List Employment Records
      description: Retrieve a paginated list of employment records which can be optionally filtered by candidate and employer names. Ordered by creation time (most recent first) by default; pass ordering=last_activity to instead order by the latest status change (e.g. a status update triggered by a response or an information request).
      parameters:
      - name: ordering
        in: query
        description: Set to 'last_activity' to order by the most recent status change instead of creation time
        schema:
          type: string
      - name: candidate_name
        in: query
        description: Filter by candidate name (case insensitive)
        schema:
          type: string
      - name: request_id
        in: query
        description: Filter by employment request ID
        schema:
          type: string
      - name: employer_name
        in: query
        description: Filter by employer name (case insensitive)
        schema:
          type: string
      - name: employer_email
        in: query
        description: Filter by employer email
        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
      - name: start_date
        in: query
        description: Filter by start date (inclusive) for employment verification creation time
        schema:
          type: string
      - name: end_date
        in: query
        description: Filter by end date (inclusive) for employment verification creation time
        schema:
          type: string
      - name: status
        in: query
        description: Filter by employment status
        schema:
          type: string
      responses:
        '200':
          description: A paginated list of employment records
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedReadEmploymentSerializer'
      tags:
      - employment
    post:
      operationId: employment_create
      summary: Create Employment Record
      description: Create a new employment record or multiple employment records. If employer_email is not provided, company_name, company_domain, and country_code must be provided to search for contacts. The record's company is automatically set to the authenticated user's company. The body may be a single object or an array of objects; a single object is treated as an array of one, and the response is always an array.
      responses:
        '201':
          description: Employment record(s) created successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ReadEmployment'
        '400':
          description: Bad Request
      tags:
      - employment
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateEmployment'
        required: true
  /employment/check_request_id/{request_id}:
    parameters:
    - name: request_id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: employment_check_request_id_read
      summary: Check Request ID
      description: Check if a request ID is already used for the company.
      responses:
        '200':
          description: Existence status of the request ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  exists:
                    type: boolean
      tags:
      - employment
  /employment/contacts/search:
    parameters: []
    get:
      operationId: employment_contacts_search_list
      summary: Search employment contacts
      description: Search for employment contacts using fuzzy search on the source name.
      parameters:
      - name: source_name
        in: query
        description: The name of the source to search for (fuzzy search)
        schema:
          type: string
      - name: country
        in: query
        description: Filter by country ISO 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/PaginatedContactSerializer'
      tags:
      - employment
  /employment/emails/search:
    parameters: []
    get:
      operationId: employment_emails_search_list
      summary: Check email availability for a search
      description: Check whether any employer emails can be found for the given company_name, company_domain, and country_code before submitting an employment request.
      parameters:
      - name: company_name
        in: query
        description: The name of the company to search for (e.g., 'Apple')
        required: true
        schema:
          type: string
      - name: company_domain
        in: query
        description: The domain of the company to search for (e.g., 'apple.com')
        required: true
        schema:
          type: string
      - name: country_code
        in: query
        description: The ISO country code of the company (e.g., 'US')
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Whether any emails were found for the search
          content:
            application/json:
              schema:
                type: object
                properties:
                  emails_found:
                    type: boolean
        '400':
          description: Missing required search parameters
      tags:
      - employment
  /employment/unlockable:
    parameters: []
    get:
      operationId: employment_unlockable_list
      summary: List unlockable stale employment verifications
      description: Retrieve a paginated list of stale employment verifications whose employer submitted results after they went stale, and which have not been unlocked yet (`is_unlockable` is true). Ordered by when the results were submitted, most recent first. Unlock one with POST /employment//unlock.
      parameters:
      - 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: A paginated list of unlockable employment records
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedReadEmploymentSerializer'
      tags:
      - employment
  /employment/{employment_id}:
    parameters:
    - name: employment_id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: employment_read
      summary: Retrieve employment details
      description: Retrieve details of a specific employment record. The record's company must match the authenticated user's company.
      parameters:
      - name: employment_id
        in: path
        description: The unique identifier of the employment record
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadEmployment'
      tags:
      - employment
    delete:
      operationId: employment_delete
      summary: Delete employment record
      description: Delete a specific employment record. The record's company must match the authenticated user's company.
      parameters:
      - name: employment_id
        in: path
        description: The unique identifier of the employment record
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No Content
      tags:
      - employment
  /employment/{employment_id}/cancel:
    parameters:
    - name: employment_id
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: employment_cancel_create
      summary: Cancel employment verification request
      description: Cancel a specific employment verification request that is in progress.
      parameters:
      - name: employment_id
        in: path
        description: The unique identifier of the employment record
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmploymentStatus'
        '403':
          description: Permission denied
        '404':
          description: Not found
      tags:
      - employment
  /employment/{employment_id}/consent:
    parameters:
    - name: employment_id
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: employment_consent_create
      summary: Upload end-user consent file(s)
      description: Upload one or more PDF files containing the end-user's consent for employment verification. You can upload multiple files using any field name in the multipart form.
      parameters:
      - name: employment_id
        in: path
        description: The unique identifier of the employment record
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Consent file(s) uploaded successfully
        '400':
          description: Invalid file or request
        '404':
          description: Employment record not found
      tags:
      - employment
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                end_user_consent_file:
                  type: string
                  description: One or more PDF files to upload
                  format: binary
              required:
              - end_user_consent_file
  /employment/{employment_id}/unlock:
    parameters:
    - name: employment_id
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: employment_unlock_create
      summary: Unlock stale employment verification
      description: Unlock the results of a stale employment verification that the employer submitted after it went stale. Charges a credit and marks the verification Completed. Only available when `is_unlockable` is true.
      parameters:
      - name: employment_id
        in: path
        description: The unique identifier of the employment record
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadEmployment'
        '400':
          description: Already unlocked, or not unlockable
        '402':
          description: Company has no credits and no payment method
        '403':
          description: Permission denied
        '404':
          description: Not found
      tags:
      - employment
  /employment/{employment_id}/verify:
    parameters:
    - name: employment_id
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: employment_verify_create
      summary: Submit employment verification
      description: Creates an employment verification using the provided employment_id and payload.
      parameters:
      - name: employment_id
        in: path
        description: The unique identifier of the employment record
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Employment verification created successfully
        '400':
          description: Invalid input data
        '403':
          description: Permission denied
      tags:
      - employment
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEmploymentVerification'
        required: true
components:
  schemas:
    PaginatedReadEmploymentSerializer:
      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/ReadEmployment'
    CreateEmploymentPosition:
      description: The positions the candidate is claimed to have held at this employer. Multiple positions at the same company can be verified in one request.
      required:
      - start_date
      type: object
      properties:
        position:
          title: Position
          type:
          - string
          - 'null'
          maxLength: 255
        employment_status:
          title: Employment status
          type:
          - string
          - 'null'
          maxLength: 255
        start_date:
          title: Start date
          type: string
          format: date
        end_date:
          title: End date
          type:
          - string
          - 'null'
          format: date
        current:
          title: Current
          type:
          - boolean
          - 'null'
        eligible_for_rehire:
          title: Eligible for rehire
          type: boolean
    PaginatedContactSerializer:
      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/Contact'
    ReadEmployment:
      description: A list of the returned records
      required:
      - request_id
      - candidate_name
      - employer_name
      - employer_email
      - employer_country_code
      - company
      type: object
      properties:
        verified:
          title: Verified
          type: string
          readOnly: true
        current_status:
          title: Current status
          description: The most recent status of the employment verification
          type: string
          readOnly: true
        end_user_consent_file_download_urls:
          title: End user consent file download urls
          description: URLs to download all end-user consent files
          type: string
          readOnly: true
        email_sent_times:
          title: Email sent times
          description: The times that emails were sent out for this record
          type: string
          readOnly: true
        requested_information:
          type: array
          items:
            $ref: '#/components/schemas/RequestedInformation'
          readOnly: true
        positions:
          type: array
          items:
            $ref: '#/components/schemas/EmploymentPosition'
          readOnly: true
        is_unlockable:
          title: Is unlockable
          description: Whether the employer submitted results after this verification went stale, which the client can unlock via POST /employment/<employment_id>/unlock
          type: string
          readOnly: true
        created_at:
          title: Created at
          type: string
          format: date-time
          readOnly: true
        request_id:
          title: Request id
          type: string
          maxLength: 256
          minLength: 1
        employment_id:
          title: Employment id
          type: string
          readOnly: true
          minLength: 1
        candidate_name:
          title: Candidate name
          type: string
          maxLength: 255
          minLength: 1
        employer_name:
          title: Employer name
          type: string
          maxLength: 255
          minLength: 1
        employer_email:
          title: Employer email
          description: A list of employer emails to send the verification request to.
          type: object
        rocketreach_emails:
          title: Rocketreach emails
          description: A list of emails found via RocketReach that need to be validated.
          type: object
        employer_country_code:
          title: Employer country code
          type: string
          maxLength: 3
          minLength: 1
        employee_id:
          title: Employee id
          type:
          - string
          - 'null'
          maxLength: 255
        phone_country_code:
          title: Phone country code
          description: The country code of the phone number
          type:
          - string
          - 'null'
          maxLength: 7
        phone_number:
          title: Phone number
          description: The phone number of the employer contact
          type:
          - string
          - 'null'
          maxLength: 16
        manual_phone_verification:
          title: Manual phone verification
          description: The manual phone verification is enabled
          type: boolean
        additional_details:
          title: Additional details
          type:
          - object
          - 'null'
        end_user_consent_files:
          title: End user consent files
          type:
          - object
          - 'null'
        lang:
          title: Lang
          type: string
          maxLength: 10
        initial_email_sent:
          title: Initial email sent
          type: boolean
        poc_email_sent:
          title: Poc email sent
          type: boolean
        cadence_emails_sent:
          title: Cadence emails sent
          type: integer
          maximum: 2147483647
          minimum: -2147483648
        last_cadence_email_sent:
          title: Last cadence email sent
          type:
          - string
          - 'null'
          format: date-time
        stale_extension_days:
          title: Stale extension days
          type: integer
          maximum: 2147483647
          minimum: -2147483648
        unlocked_at:
          title: Unlocked at
          description: When the client unlocked the results of this verification after it went stale. Null if it was never unlocked.
          type:
          - string
          - 'null'
          format: date-time
        company:
          title: Company
          type: integer
    RequestedInformation:
      required:
      - name
      - label
      type: object
      properties:
        id:
          title: Id
          type: integer
          readOnly: true
        name:
          title: Name
          description: Machine name of the requested item, e.g. 'employee_id'
          type: string
          maxLength: 255
          minLength: 1
        label:
          title: Label
          description: Human-readable label, e.g. 'Employee ID'
          type: string
          maxLength: 255
          minLength: 1
        type:
          title: Type
          description: The expected type of the requested information
          type: string
          enum:
          - text
          - date
          - number
          - file
        required:
          title: Required
          description: Whether the employer requires this to complete the verification
          type: boolean
        value:
          title: Value
          description: The client-submitted value
          type:
          - string
          - 'null'
        not_available:
          title: Not available
          description: Set by the client when the information cannot be provided
          type: boolean
        status:
          title: Status
          description: Derived state of the requested item
          type: string
          readOnly: true
        file_download_urls:
          title: File download urls
          description: Presigned URLs for uploaded files
          type: string
          readOnly: true
        created_at:
          title: Created at
          type: string
          format: date-time
          readOnly: true
    EmploymentStatus:
      required:
      - status
      type: object
      properties:
        status:
          title: Status
          description: The current status of the verification
          type: string
          enum:
          - Awaiting results
          - Awaiting POC
          - Awaiting information
          - Completed
          - Unable to verify
          - Stale
          - User did not provide requested information
          - Not delivered
          - Cancelled
          - Verification in progress
          - Double send
        created_at:
          title: Created at
          type: string
          format: date-time
          readOnly: true
    Contact:
      description: A list of the returned records
      required:
      - source_name
      - country
      - contact_email
      type: object
      properties:
        source_name:
          title: Source name
          type: string
          maxLength: 255
          minLength: 1
        country:
          title: Country
          type: string
          maxLength: 3
          minLength: 1
        contact_name:
          title: Contact name
          type:
          - string
          - 'null'
          maxLength: 255
        contact_title_dept:
          title: Contact title dept
          type:
          - string
          - 'null'
          maxLength: 255
        contact_email:
          title: Contact email
          type: string
          maxLength: 255
          minLength: 1
    CreateEmploymentVerification:
      required:
      - employment
      - positions
      - verified_by
      - verified_by_position
      type: object
      properties:
        employment:
          title: Employment
          type: string
        token:
          title: Token
          type: string
          minLength: 1
        positions:
          type: array
          items:
            $ref: '#/components/schemas/CreateEmploymentPositionVerification'
        candidate_name:
          title: Candidate name
          type:
          - string
          - 'null'
          maxLength: 255
        employer_name:
          title: Employer name
          type:
          - string
          - 'null'
          maxLength: 255
        employer_country_code:
          title: Employer country code
          type:
          - string
          - 'null'
          maxLength: 3
        verified_by:
          title: Verified by
          type: string
          maxLength: 255
          minLength: 1
        verified_by_position:
          title: Verified by position
          type: string
          maxLength: 255
          minLength: 1
        verified_by_email:
          title: Verified by email
          type:
          - string
          - 'null'
          format: email
          maxLength: 254
        contact_source:
          title: Contact source
          description: 'The source of verified_by_email: a previously-known contact for this employer, an automated search, or directly provided by the client. Null when verified_by_email wasn''t set via a recognized contact email.'
          type:
          - string
          - 'null'
          enum:
          - client_provided
          - database_contact
          - sourced_contact
          - null
        additional_details:
          title: Additional details
          type:
          - object
          - 'null'
        ip:
          title: Ip
          description: The IP address the verification was submitted from. Never returned by the API
          type:
          - string
          - 'null'
          minLength: 1
    CreateEmploymentPositionVerification:
      required:
      - employment_position
      type: object
      properties:
        employment_position:
          title: Employment position
          type: string
        position:
          title: Position
          type:
          - string
          - 'null'
          maxLength: 255
        start_date:
          title: Start date
          type:
          - string
          - 'null'
          format: date
        end_date:
          title: End date
          type:
          - string
          - 'null'
          format: date
        current:
          title: Current
          type:
          - boolean
          - 'null'
        eligible_for_rehire:
          title: Eligible for rehire
          type:
          - boolean
          - 'null'
        employment_status:
          title: Employment status
          type:
          - string
          - 'null'
          maxLength: 255
    EmploymentPosition:
      required:
      - start_date
      type: object
      properties:
        position_id:
          title: Position id
          type: string
          readOnly: true
          minLength: 1
        position:
          title: Position
          type:
          - string
          - 'null'
          maxLength: 255
        employment_status:
          title: Employment status
          type:
          - string
          - 'null'
          maxLength: 255
        start_date:
          title: Start date
          type: string
          format: date
        end_date:
          title: End date
          type:
          - string
          - 'null'
          format: date
        current:
          title: Current
          type:
          - boolean
          - 'null'
        eligible_for_rehire:
          title: Eligible for rehire
          type: boolean
        created_at:
          title: Created at
          type: string
          format: date-time
          readOnly: true
        verified:
          title: Verified
          type: string
          readOnly: true
    CreateEmployment:
      required:
      - request_id
      - candidate_name
      - employer_name
      - employer_country_code
      type: object
      properties:
        request_id:
          title: Request id
          type: string
          maxLength: 256
          minLength: 1
        candidate_name:
          title: Candidate name
          type: string
          maxLength: 255
          minLength: 1
        employer_name:
          title: Employer name
          type: string
          maxLength: 255
          minLength: 1
        employer_email:
          description: A list of employer emails to send the verification request to.
          type: array
          items:
            type: string
            format: email
            minLength: 1
          default: []
        employer_country_code:
          title: Employer country code
          type: string
          maxLength: 3
          minLength: 1
        employee_id:
          title: Employee id
          type:
          - string
          - 'null'
          maxLength: 255
        phone_country_code:
          title: Phone country code
          description: The country code of the phone number
          type:
          - string
          - 'null'
          maxLength: 7
        phone_number:
          title: Phone number
          description: The phone number of the employer contact
          type:
          - string
          - 'null'
          maxLength: 16
        manual_phone_verification:
          title: Manual phone verification
          description: The manual phone verification is enabled
          type: boolean
        additional_details:
          title: Additional details
          type:
          - object
          - 'null'
        lang:
          title: Lang
          type: string
          maxLength: 10
        company_name:
          title: Company name
          type: string
          minLength: 1
        company_domain:
          title: Company domain
          type: string
          minLength: 1
        country_code:
          title: Country code
          type: string
          minLength: 1
        positions:
          description: The positions the candidate is claimed to have held at this employer. Multiple positions at the same company can be verified in one request.
          type: array
          items:
            $ref: '#/components/schemas/CreateEmploymentPosition'
        position:
          title: Position
          type:
          - string
          - 'null'
          minLength: 1
        employment_status:
          title: Employment status
          type:
          - string
          - 'null'
          minLength: 1
        start_date:
          title: Start date
          type:
          - string
          - 'null'
          format: date
        end_date:
          title: End date
          type:
          - string
          - 'null'
          format: date
        current:
          title: Current
          type:
          - boolean
          - 'null'
        eligible_for_rehire:
          title: Eligible for rehire
          type: boolean
  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.'