> ## Documentation Index
> Fetch the complete documentation index at: https://docs.api.tamtam.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List job changes for companies

> List job changes (INCOMING / PROMOTION / OUTGOING) at the given LinkedIn companies, with cursor-based pagination.

**Filters:** `linkedin_company_ids` (1–100) and `min_change_date` are required. For INCOMING / PROMOTION the date filters by the new job's start_date; for OUTGOING by the old job's end_date.

**Pagination:** save `next_cursor` from the response and pass it back as `cursor` on the next call. Use the same filters across calls — behavior is undefined if filters change mid-pagination.

**Note on dates:** LinkedIn provides month precision; experience start/end dates always fall on the 1st of the month.



## OpenAPI

````yaml /reference/openapi.yaml post /v2/companies/job-changes
openapi: 3.1.0
info:
  title: Tamtam Public API
  version: 2.0.0
servers:
  - url: https://api.tamtam.ai/api
security: []
paths:
  /v2/companies/job-changes:
    post:
      tags:
        - Companies
      summary: List job changes for companies
      description: >-
        List job changes (INCOMING / PROMOTION / OUTGOING) at the given LinkedIn
        companies, with cursor-based pagination.


        **Filters:** `linkedin_company_ids` (1–100) and `min_change_date` are
        required. For INCOMING / PROMOTION the date filters by the new job's
        start_date; for OUTGOING by the old job's end_date.


        **Pagination:** save `next_cursor` from the response and pass it back as
        `cursor` on the next call. Use the same filters across calls — behavior
        is undefined if filters change mid-pagination.


        **Note on dates:** LinkedIn provides month precision; experience
        start/end dates always fall on the 1st of the month.
      operationId: list-job-changes
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListJobChangesV2InputBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListJobChangesV2OutputBody'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Error
      security:
        - apikeyAuth: []
        - bearerAuth: []
components:
  schemas:
    ListJobChangesV2InputBody:
      additionalProperties: false
      properties:
        cursor:
          description: >-
            Pagination cursor returned by a previous call. To paginate, save the
            next_cursor and pass it back unchanged on the next call. Use the
            same filters across calls — do not change filters mid-pagination.
            Cursors remain valid indefinitely unless this endpoint returns a
            400.
          type: string
        limit:
          description: Maximum number of results per page (1–500). Defaults to 100.
          examples:
            - 100
          format: int64
          type: integer
        linkedin_company_ids:
          description: LinkedIn company IDs to look up job changes for. Up to 100.
          examples:
            - - '104924588'
          items:
            type: string
          maxItems: 100
          minItems: 1
          type:
            - array
            - 'null'
        min_change_date:
          description: >-
            Earliest job change date (inclusive). Job change dates always fall
            on the first day of the month (LinkedIn provides month precision).
          examples:
            - '2026-01-01'
          type: string
      required:
        - linkedin_company_ids
        - min_change_date
      type: object
    ListJobChangesV2OutputBody:
      additionalProperties: false
      properties:
        next_cursor:
          description: >-
            Pass back unchanged to fetch the next page. Null when there are no
            more results.
          type: string
        results:
          description: Job changes for this page
          items:
            $ref: '#/components/schemas/ListJobChangesV2ItemDto'
          type:
            - array
            - 'null'
        total_count:
          description: >-
            Total number of job changes matching the filters at query time. May
            grow on subsequent polls as new changes are discovered.
          examples:
            - 487
          format: int32
          type: integer
      required:
        - results
        - total_count
      type: object
    ErrorModel:
      additionalProperties: false
      properties:
        detail:
          description: >-
            A human-readable explanation specific to this occurrence of the
            problem.
          examples:
            - Property foo is required but is missing.
          type: string
        errors:
          description: Optional list of individual error details
          items:
            $ref: '#/components/schemas/ErrorDetail'
          type:
            - array
            - 'null'
        instance:
          description: >-
            A URI reference that identifies the specific occurrence of the
            problem.
          examples:
            - https://example.com/error-log/abc123
          format: uri
          type: string
        status:
          description: HTTP status code
          examples:
            - 400
          format: int64
          type: integer
        title:
          description: >-
            A short, human-readable summary of the problem type. This value
            should not change between occurrences of the error.
          examples:
            - Bad Request
          type: string
        type:
          default: about:blank
          description: A URI reference to human-readable documentation for the error.
          examples:
            - https://example.com/errors/example
          format: uri
          type: string
      type: object
    ListJobChangesV2ItemDto:
      additionalProperties: false
      properties:
        change_type:
          description: Type of job change
          enum:
            - INCOMING
            - PROMOTION
            - OUTGOING
          examples:
            - INCOMING
          type: string
        company_name:
          description: Company name
          examples:
            - TAMTAM
          type: string
        end_date:
          description: Job end date (only set for OUTGOING)
          examples:
            - '2026-04-01'
          type: string
        first_name:
          description: First name
          examples:
            - Elliot
          type: string
        job_change_id:
          description: >-
            Stable identifier for this job change. Use it to deduplicate across
            paginated calls.
          type: string
        job_title:
          description: Job title
          examples:
            - Head of Sales
          type: string
        last_name:
          description: Last name
          examples:
            - Alderson
          type: string
        linkedin_company_id:
          description: LinkedIn company ID
          examples:
            - '104924588'
          type: string
        linkedin_url:
          description: LinkedIn profile URL
          examples:
            - https://www.linkedin.com/in/elliot-alderson
          type: string
        related_experience:
          $ref: '#/components/schemas/ListJobChangesV2RelatedExperienceDto'
          description: >-
            For INCOMING/PROMOTION: the previous experience. For OUTGOING: the
            next experience, if known.
        start_date:
          description: Job start date (always 1st of month)
          examples:
            - '2026-02-01'
          type: string
      required:
        - change_type
        - job_change_id
        - linkedin_company_id
        - job_title
      type: object
    ErrorDetail:
      additionalProperties: false
      properties:
        location:
          description: >-
            Where the error occurred, e.g. 'body.items[3].tags' or
            'path.thing-id'
          type: string
        message:
          description: Error message text
          type: string
        value:
          description: The value at the given location
      type: object
    ListJobChangesV2RelatedExperienceDto:
      additionalProperties: false
      properties:
        company_name:
          description: Company name of the related experience
          examples:
            - Previous Co
          type: string
        job_title:
          description: Job title of the related experience
          examples:
            - Account Executive
          type: string
        linkedin_company_id:
          description: LinkedIn company ID of the related experience
          examples:
            - '104924588'
          type: string
      type: object
  securitySchemes:
    apikeyAuth:
      description: Account API key passed in the Authorization header
      in: header
      name: Authorization
      type: apiKey
    bearerAuth:
      description: Bearer JWT obtained via the OAuth 2.1 authorization flow
      scheme: bearer
      type: http

````