openapi: 3.0.3
info:
  title: CaptivateIQ Attribute Worksheets Employees API
  version: v1
  description: The CaptivateIQ REST API (ciq/v1) for managing employees, hierarchies, data worksheets, commission plans, payouts, reports, and related sales-compensation resources. Harvested from the public developer reference (developers.captivateiq.com).
  x-apievangelist-provenance:
    generated: '2026-07-18'
    method: searched
    source: https://developers.captivateiq.com/reference (per-operation OpenAPI defs merged)
servers:
- url: https://api.captivateiq.com
  description: Production
security:
- tokenAuth: []
tags:
- name: Employees
paths:
  /ciq/v1/employee-visibilities/:
    post:
      operationId: employee_visibilities_create
      summary: Create Employee Visibility
      tags:
      - Employees
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmployeeVisibilityCreateUpdate'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/EmployeeVisibilityCreateUpdate'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/EmployeeVisibilityCreateUpdate'
        required: true
      security:
      - tokenAuth: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeVisibility'
          description: ''
    get:
      operationId: employee_visibilities_list
      description: Hierarchy visibilities include an extra field, `managing_employee` which contains the UUID of the managing employee.
      summary: List Employee Visibilities
      parameters:
      - in: query
        name: hierarchy_group_name
        schema:
          type: string
        description: Filter visibilities by a hierarchy group name.
      - in: query
        name: hierarchy_id
        schema:
          type: string
          format: uuid
        description: Filter visibilities by hierarchy id.
      - name: limit
        required: false
        in: query
        description: Number of results to return per page.
        schema:
          type: integer
      - name: offset
        required: false
        in: query
        description: The initial index from which to return the results.
        schema:
          type: integer
      - in: query
        name: ordering
        schema:
          type: string
        description: Use `start_date` or `end_date` to order by start or end date, and `-start_date` or `-end_date` to reverse them respectively. Defaults to `start_date`.
      - in: query
        name: user_id
        schema:
          type: string
          format: uuid
        description: Filter visibilities by user_id.
      - in: query
        name: visible_employee_id
        schema:
          type: string
          format: uuid
        description: Filter visibilities by an employee_id.
      tags:
      - Employees
      security:
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedEmployeeVisibilityList'
          description: ''
  /ciq/v1/employee-visibilities/{id}/:
    delete:
      operationId: employee_visibilities_destroy
      summary: Delete Employee Visibility
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        description: Primary key, a UUID.
        required: true
      tags:
      - Employees
      security:
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAPIDelete'
          description: ''
    get:
      operationId: employee_visibilities_retrieve
      description: 'Retrieves Employee Visibilities with the `object: "employee visibility"` field. To retrieve Hierarchies, see the Hierarchies documentation.'
      summary: Get Employee Visibility
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        description: Primary key, a UUID.
        required: true
      tags:
      - Employees
      security:
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeVisibility'
          description: ''
    put:
      operationId: employee_visibilities_update
      summary: Update Employee Visibility
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        description: Primary key, a UUID.
        required: true
      tags:
      - Employees
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmployeeVisibilityCreateUpdate'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/EmployeeVisibilityCreateUpdate'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/EmployeeVisibilityCreateUpdate'
        required: true
      security:
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeVisibility'
          description: ''
  /ciq/v1/employees/:
    post:
      operationId: employees_create
      summary: Create Employee
      tags:
      - Employees
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmployeeCreate'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/EmployeeCreate'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/EmployeeCreate'
        required: true
      security:
      - tokenAuth: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Employee'
          description: ''
    get:
      operationId: employees_list
      summary: List Employees
      parameters:
      - in: query
        name: employee_id
        schema:
          type: string
        description: Filter by employee id
      - in: query
        name: first_name
        schema:
          type: string
        description: Filter by first name
      - in: query
        name: last_name
        schema:
          type: string
        description: Filter by last name
      - name: limit
        required: false
        in: query
        description: Number of results to return per page.
        schema:
          type: integer
      - name: offset
        required: false
        in: query
        description: The initial index from which to return the results.
        schema:
          type: integer
      - name: ordering
        required: false
        in: query
        description: 'Optional. Which field to use when ordering the results. By default we assume [`employee_id`]. Available fields for ordering: [`(-)employee_id`, `(-)first_name`, `(-)last_name`]. See the [FAQs](https://developers.captivateiq.com/docs/faqs) page for tips.'
        schema:
          type: string
      tags:
      - Employees
      security:
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedEmployeeList'
          description: ''
  /ciq/v1/employees/{id}/:
    delete:
      operationId: employees_destroy
      summary: Delete Employee
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        description: Primary key, a UUID.
        required: true
      tags:
      - Employees
      security:
      - tokenAuth: []
      responses:
        '204':
          description: No response body
    get:
      operationId: employees_retrieve
      summary: Get Employee
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        description: Primary key, a UUID.
        required: true
      tags:
      - Employees
      security:
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Employee'
          description: ''
    put:
      operationId: employees_update
      summary: Update Employee
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        description: Primary key, a UUID.
        required: true
      tags:
      - Employees
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmployeeUpdate'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/EmployeeUpdate'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/EmployeeUpdate'
        required: true
      security:
      - tokenAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Employee'
          description: ''
components:
  schemas:
    NullEnum:
      enum:
      - null
    EmployeeVisibility:
      type: object
      properties:
        object:
          type: string
          readOnly: true
          default: employee visibility
          description: Optional. Object type name.
        id:
          type: string
          readOnly: true
          description: Primary key, a UUID.
        user:
          type: string
          format: uuid
          description: Required. The uuid of the user.
        visible_employee:
          type: string
          format: uuid
          description: Required. The uuid of the visible employee.
        start_date:
          type: string
          format: date
          nullable: true
          description: Required. The visibility start date.
        end_date:
          type: string
          format: date
          nullable: true
          description: Required. The visibility end date.
        source:
          type: object
          additionalProperties: {}
          description: Nested object containing the id and name of the hierarchy group if the visibility originated from a hierarchy. Otherwise values default to null and 'Manual'.
        created_at:
          type: string
          format: date-time
          readOnly: true
          description: Date and time of creation.
        updated_at:
          type: string
          format: date-time
          readOnly: true
          description: Date and time of last update.
      required:
      - user
      - visible_employee
    EmployeeUpdate:
      type: object
      properties:
        id:
          type: string
          readOnly: true
          description: Primary key, a UUID.
        employee_id:
          type: string
          description: Required, must be unique. Your unique identifier for the employee within your organization.
        email:
          type: string
          format: email
          nullable: true
          description: Required, can be `null`. The employee's email address.
        login_id:
          type: string
          nullable: true
          description: Optional. Only used when an organization uses freeform login_id type as the user's unique identifier (all organizations use email as a unique identifier by default) and the employee has a linked_user value. If linked_user has a value, then login_id will be used to update the login_id of the linked_user.
        first_name:
          type: string
          nullable: true
          description: Required, can be `null`. The employee's first name.
        last_name:
          type: string
          nullable: true
          description: Required, can be `null`. The employee's last name.
        final_process_date:
          type: string
          format: date
          nullable: true
          description: Required, can be `null`. YYYY-MM-DD format. Payouts will no longer be processed for this employee after this date.
        employee_license_automated_deactivation_date:
          type: string
          format: date
          nullable: true
          description: Optional, can be `null`. YYYY-MM-DD format. The employee will be automatically deactivated on this date.
        is_active:
          type: boolean
          description: Required. Active employees count towards your seat count.
        linked_user:
          type: string
          format: uuid
          readOnly: true
          description: Employee's linked User, which they may use to access the system.
      required:
      - email
      - employee_id
      - final_process_date
      - first_name
      - is_active
      - last_name
    PaginatedEmployeeVisibilityList:
      type: object
      properties:
        object:
          type: string
          example: list
        total_count:
          type: integer
          example: 123
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?offset=400&limit=100
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?offset=200&limit=100
        data:
          type: array
          items:
            $ref: '#/components/schemas/EmployeeVisibility'
    EmployeeOptionalUserSettings:
      type: object
      properties:
        enable_inquiry_notifications:
          type: boolean
          default: false
          description: Optional, default to your "Organization User Settings" value. If an "Organization User Settings" value is not set will fallback to `false`.
        enable_statement_notifications:
          type: boolean
          default: true
          description: Optional, default to your "Organization User Settings" value. If an "Organization User Settings" value is not set will fallback to `true`.
        eligible_to_receive_inquiries:
          type: boolean
          default: true
          description: Optional, default to your "Organization User Settings" value. If an "Organization User Settings" value is not set will fallback to `true`.
        eligible_to_submit_inquiries:
          type: boolean
          default: true
          description: Optional, default to your "Organization User Settings" value. If an "Organization User Settings" value is not set will fallback to `true`. Enable user to submit inquiries.
        enable_payout_processing_notifications:
          type: boolean
          default: false
          description: Optional, default to your "Organization User Settings" value. If an "Organization User Settings" value is not set will fallback to `false`.
        enable_connector_sync_email_notifications:
          type: boolean
          default: true
          description: Optional, default to your "Organization User Settings" value. If an "Organization User Settings" value is not set will fallback to `true`.
        enable_scim_email_notifications:
          type: boolean
          default: false
          description: Optional, default to your "Organization User Settings" value. If an "Organization User Settings" value is not set will fallback to `false`.
        enable_audit_log_export_notifications:
          type: boolean
          default: false
          description: Optional, default to your "Organization User Settings" value. If an "Organization User Settings" value is not set will fallback to `false`.
        is_organization_admin:
          type: boolean
          default: false
          description: Optional, defaults to `false`.
        send_initial_email:
          type: boolean
          default: false
          description: Optional, default to your "Organization User Settings" value. If an "Organization User Settings" value is not set will fallback to `false`. Send the user a welcome email.
        login_access:
          type: boolean
          default: false
          description: Optional, defaults to `false`.
        role:
          type: string
          description: Name of the role to apply to the user.
          maxLength: 255
    Employee:
      type: object
      properties:
        object:
          type: string
          readOnly: true
          default: employee
          description: Optional. Object type name.
        id:
          type: string
          readOnly: true
          description: Primary key, a UUID.
        employee_id:
          type: string
          description: Required, must be unique. Your unique identifier for the employee within your organization.
        email:
          type: string
          format: email
          nullable: true
          description: Required if `linked_user` not provided, otherwise optional. The employee's email address.
        first_name:
          type: string
          nullable: true
          description: Required if `linked_user` not provided, otherwise optional. The employee's first name.
        last_name:
          type: string
          nullable: true
          description: Required if `linked_user` not provided, otherwise optional. The employee's last name.
        final_process_date:
          type: string
          format: date
          nullable: true
          description: Optional. YYYY-MM-DD format. Payouts will no longer be processed for this employee after this date.
        is_active:
          type: boolean
          description: Active employees count towards your seat count.
        linked_user:
          type: string
          format: uuid
          readOnly: true
          description: Employee's linked User, which they may use to access the system.
        created_at:
          type: string
          format: date-time
          readOnly: true
          description: Date and time of creation.
        updated_at:
          type: string
          format: date-time
          readOnly: true
          description: Date and time of last update.
      required:
      - employee_id
      - is_active
    PaginatedEmployeeList:
      type: object
      properties:
        object:
          type: string
          example: list
        total_count:
          type: integer
          example: 123
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?offset=400&limit=100
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?offset=200&limit=100
        data:
          type: array
          items:
            $ref: '#/components/schemas/Employee'
    EmployeeCreate:
      type: object
      properties:
        employee_id:
          type: string
          description: Required, must be unique. Your unique identifier for the employee within your organization.
        email:
          type: string
          format: email
          nullable: true
          description: Required if `linked_user` not provided, otherwise optional. The employee's email address.
        first_name:
          type: string
          nullable: true
          description: Required if `linked_user` not provided, otherwise optional. The employee's first name.
        last_name:
          type: string
          nullable: true
          description: Required if `linked_user` not provided, otherwise optional. The employee's last name.
        final_process_date:
          type: string
          format: date
          nullable: true
          description: Optional. YYYY-MM-DD format. Payouts will no longer be processed for this employee after this date.
        is_active:
          type: boolean
          default: true
          description: Optional, defaults to `true`. Active employees count towards your seat count.
        linked_user:
          type: string
          format: uuid
          nullable: true
          description: Optional. Pass in a UUID to link to an existing User, otherwise a new User will be automatically created for this employee.
        user_settings:
          allOf:
          - $ref: '#/components/schemas/EmployeeOptionalUserSettings'
          nullable: true
          description: Optional. Values to be passed through if creating a new user
        timezone:
          type: string
          nullable: true
          default: America/Los_Angeles
          description: Optional, default to your "Organization User Settings" value. If an "Organization User Settings" value is not set will fallback to `America/Los_Angeles`. Used only if creating a new linked user. User timezone name. Accepts [tz database names](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones), e.g. `America/Los_Angeles`.
        locale:
          nullable: true
          description: Optional, default to your "Organization User Settings" value. If an "Organization User Settings" value is not set will fallback to `None`. The employee's locale. Accepts [locale names](https://support.captivateiq.com/hc/en-us/articles/4418762747796-User-locale-settings-beta-), e.g. `en_US`.
          oneOf:
          - $ref: '#/components/schemas/LocaleEnum'
          - $ref: '#/components/schemas/BlankEnum'
          - $ref: '#/components/schemas/NullEnum'
        login_id:
          type: string
          nullable: true
          description: Optional. This field is only used if an organization uses freeform login_id type as the user's unique identifier (all organizations use email as a unique identifier by default) and if linked_user does not have a value. If this is the case then login_id value will be used in creating the linked_user. If login_id is blank, the linked user will be created as a placeholder user.
      required:
      - employee_id
    OpenAPIDelete:
      type: object
      properties:
        object:
          type: string
          readOnly: true
          description: Type of the object.
        id:
          type: string
          format: uuid
          readOnly: true
          description: UUID of the object deleted.
        deleted:
          type: boolean
          readOnly: true
          description: Has the object been deleted.
    EmployeeVisibilityCreateUpdate:
      type: object
      properties:
        object:
          type: string
          readOnly: true
          default: employee visibility
          description: Optional. Object type name.
        id:
          type: string
          readOnly: true
          description: Primary key, a UUID.
        user:
          type: string
          format: uuid
          description: Required. The uuid of the user.
        visible_employee:
          type: string
          format: uuid
          description: Required. The uuid of the visible employee.
        start_date:
          type: string
          format: date
          nullable: true
          description: Required. The visibility start date.
        end_date:
          type: string
          format: date
          nullable: true
          description: Required. The visibility end date.
        created_at:
          type: string
          format: date-time
          readOnly: true
          description: Date and time of creation.
        updated_at:
          type: string
          format: date-time
          readOnly: true
          description: Date and time of last update.
      required:
      - user
      - visible_employee
    LocaleEnum:
      enum:
      - cs_CZ
      - de_DE
      - en_AU
      - en_CA
      - en_GB
      - en_SG
      - en_US
      - es_ES
      - es_US
      - fr_CA
      - fr_FR
      - hu_HU
      - it_IT
      - ja_JP
      - ms_MY
      - pl_PL
      - pt_PT
      - ru_RU
      - sk_SK
      - zh_CN
      - zh_SG
      type: string
    BlankEnum:
      enum:
      - ''
  securitySchemes:
    tokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Token-based authentication with required prefix "Token"