openapi: 3.0.3
info:
  title: Seamless.AI Companies Job Changes API
  description: The Seamless.AI Companies API enables programmatic search and research of company data including firmographics, revenue, employee count, technology stack, and company intelligence for sales and marketing use cases.
  version: 1.0.0
  contact:
    url: https://docs.seamless.ai/
servers:
- url: https://api.seamless.ai
  description: Seamless.AI API
security:
- apiKey: []
tags:
- name: Job Changes
paths:
  /v1/contacts/job-changes:
    get:
      operationId: listContactJobChanges
      summary: List Contact Job Changes
      description: Retrieve contacts that have recently changed jobs within your contact database. Returns job-change intelligence including previous and current roles to help identify warm outreach opportunities.
      tags:
      - Job Changes
      parameters:
      - name: page
        in: query
        description: Page number for paginated results
        schema:
          type: integer
          default: 1
      - name: per_page
        in: query
        description: Number of results per page (max 100)
        schema:
          type: integer
          default: 25
          maximum: 100
      - name: days
        in: query
        description: Number of days to look back for job changes
        schema:
          type: integer
          default: 30
      responses:
        '200':
          description: List of contacts with recent job changes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobChangesResponse'
        '401':
          description: Unauthorized
        '429':
          description: Rate limit exceeded
components:
  schemas:
    PaginationMeta:
      type: object
      properties:
        page:
          type: integer
        per_page:
          type: integer
        total:
          type: integer
        total_pages:
          type: integer
    JobChangesResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              contactId:
                type: string
              name:
                type: string
              previousCompany:
                type: string
              previousTitle:
                type: string
              currentCompany:
                type: string
              currentTitle:
                type: string
              changeDate:
                type: string
                format: date
        meta:
          $ref: '#/components/schemas/PaginationMeta'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Authorization
      description: API key in the format "Bearer {api_key}"