---
title: "List the calling customer's contract assignment changes"
url: "https://developer.agentsync.io/apis/contracting-hierarchies-api/versions/40f58935-396e-4da4-8f47-1587041e1b16/operations/listContractAssignmentChangesV2"
---

> Full API specification: https://developer.agentsync.io/apis/contracting-hierarchies-api/versions/40f58935-396e-4da4-8f47-1587041e1b16.md

# List the calling customer's contract assignment changes

`GET` `/v2/contract-assignment-changes`

Operation ID: `listContractAssignmentChangesV2`

Returns the contract assignment changes for the calling customer's organization as a token-paginated collection. A change is a point-in-time snapshot of an assignment and carries the before/after status pair explicitly. Results are scoped to the caller; another customer's changes are never returned.

## Query parameters

- `page_token` (string, optional) - Opaque continuation token from a previous response's `page.nextToken`. Omit for the first page.
- `page_size` (integer, optional) - Maximum number of items to return. Defaults to 25; values outside `[1, 250]` are rejected with `400` (not clamped).
- `updated_since` (string, date-time, optional) - Return only contracts modified at or after this RFC3339 UTC timestamp (inclusive). Modified time tracks any column change, so "modified" does not necessarily mean a business-meaningful change. Best used as a high-water mark for incremental sync: a pagination run is not a point-in-time snapshot, so records updated mid-run may first appear on a later poll.

## Responses

- `200` - A page of contract assignment changes.
- `400` - Invalid `page_token`, `page_size`, or `updated_since`.
- `401` - Missing or invalid bearer token.
- `403` - The bearer token is not authorized for this resource.

## OpenAPI definition

```yaml
openapi: 3.1.0
info:
  title: AgentSync Contracting & Hierarchies API
  version: v1.7.6
servers:
  - url: https://api.sandbox.agentsync.io/contracting
    description: Sandbox
  - url: https://api.agentsync.io/contracting
    description: Production
paths:
  /v2/contract-assignment-changes:
    get:
      tags:
        - Assignment Changes
      operationId: listContractAssignmentChangesV2
      summary: List the calling customer's contract assignment changes
      description: >
        Returns the contract assignment changes for the calling customer's
        organization as a

        token-paginated collection. A change is a point-in-time snapshot of an
        assignment and carries

        the before/after status pair explicitly. Results are scoped to the
        caller; another customer's

        changes are never returned.
      security:
        - oauth2:
            - contracting.contractassignments.read
      parameters:
        - $ref: "#/components/parameters/PageToken"
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/UpdatedSince"
      responses:
        "200":
          description: A page of contract assignment changes.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContractAssignmentChangeV2Page"
        "400":
          description: Invalid `page_token`, `page_size`, or `updated_since`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
        "401":
          description: Missing or invalid bearer token.
        "403":
          description: The bearer token is not authorized for this resource.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
security:
  - oauth2:
      - contracting.contractassignments.read
components:
  parameters:
    PageToken:
      name: page_token
      in: query
      required: false
      description: >
        Opaque continuation token from a previous response's `page.nextToken`.
        Omit for the first

        page.
      schema:
        type: string
    PageSize:
      name: page_size
      in: query
      required: false
      description: >
        Maximum number of items to return. Defaults to 25; values outside `[1,
        250]` are rejected

        with `400` (not clamped).
      schema:
        type: integer
        minimum: 1
        maximum: 250
        default: 25
    UpdatedSince:
      name: updated_since
      in: query
      required: false
      description: >
        Return only contracts modified at or after this RFC3339 UTC timestamp
        (inclusive). Modified

        time tracks any column change, so "modified" does not necessarily mean a

        business-meaningful change. Best used as a high-water mark for
        incremental sync: a pagination

        run is not a point-in-time snapshot, so records updated mid-run may
        first appear on a later poll.
      schema:
        type: string
        format: date-time
        example: 2026-06-01T00:00:00Z
  schemas:
    ContractAssignmentChangeV2Page:
      type: object
      description: A token-paginated page of contract assignment changes (plain
        envelope, no HAL wrappers).
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/ContractAssignmentChangeV2"
        page:
          $ref: "#/components/schemas/PageInfo"
      required:
        - items
        - page
    ApiError:
      type: object
      description: The AgentSync error shape.
      properties:
        message:
          type: string
          description: A human-readable description of the error.
        details:
          type: array
          description: Optional field-level details.
          items:
            type: object
            properties:
              param:
                type: string
              message:
                type: string
      required:
        - message
    ContractAssignmentChangeV2:
      type: object
      description: >
        A point-in-time change to a contract assignment. `assignmentStatus*` is
        the change's own

        status. `effectiveOn`/`expiresOn` are the assignment's contractual
        terms, while

        `snapshotStartOn`/`snapshotEndOn` are the window during which this
        change represented the

        assignment's state.
      properties:
        id:
          type: string
          format: uuid
          description: The contract assignment change id.
        contractAssignmentId:
          type: string
          format: uuid
          description: The assignment this change applies to.
        contractId:
          type: string
          format: uuid
          description: The parent contract id.
        agencyOrganizationId:
          type: string
          format: uuid
          description: The agency organization the assignment is sent from.
        carrierOrganizationId:
          type: string
          format: uuid
          description: The carrier organization the assignment is sent to.
        personId:
          type: string
          format: uuid
          description: The individual producer the assignment is on behalf of.
        firmId:
          type: string
          format: uuid
          description: The firm the assignment is on behalf of, if any.
        productId:
          type: string
          format: uuid
        productName:
          type: string
          description: The product name (inlined so no follow-up lookup is needed).
        assignmentStatusId:
          type: string
          format: uuid
          description: The change's status.
        assignmentStatusName:
          type: string
          description: The human-readable change status (inlined).
        newCommissionLevelId:
          type: string
          format: uuid
        newCommissionLevelName:
          type: string
          description: The new commission level name (inlined).
        newAnnualizationId:
          type: string
          format: uuid
        contractPacketId:
          type: string
          format: uuid
        taskTypeName:
          type: string
          description: The task type intended by this change.
        displayNumber:
          type: string
          description: The human-readable change number.
        writingNumber:
          type: string
        effectiveOn:
          type: string
          format: date
          description: The assignment's contractual effective date (yyyy-MM-dd).
        expiresOn:
          type: string
          format: date
          description: The assignment's contractual expiration date (yyyy-MM-dd).
        snapshotStartOn:
          type: string
          format: date
          description: Start of the window this change represented the assignment's state
            (yyyy-MM-dd).
        snapshotEndOn:
          type: string
          format: date
          description: End of the window this change represented the assignment's state
            (yyyy-MM-dd).
        referralCodes:
          type: array
          items:
            type: string
        title:
          type: string
        externalNotes:
          type: string
        uplineContractAssignmentChange:
          $ref: "#/components/schemas/UplineContractAssignmentChangeV2"
        createdAt:
          type: string
          format: date-time
          description: RFC3339 UTC creation timestamp.
        updatedAt:
          type: string
          format: date-time
          description: RFC3339 UTC last-modified timestamp.
        userDefined1:
          type: string
        userDefined2:
          type: string
        userDefined3:
          type: string
        userDefined4:
          type: string
        userDefined5:
          type: string
        userDefined6:
          type: string
        userDefined7:
          type: string
        userDefined8:
          type: string
        userDefined9:
          type: string
        userDefined10:
          type: string
      required:
        - id
        - contractAssignmentId
        - contractId
        - agencyOrganizationId
        - carrierOrganizationId
        - personId
        - productId
        - displayNumber
    PageInfo:
      type: object
      description: Pagination metadata for a V2 list response.
      properties:
        size:
          type: integer
          description: Number of items returned in this response (equal to items.length).
        nextToken:
          type:
            - string
            - "null"
          description: Opaque continuation token for the next page, or null on the last
            page.
      required:
        - size
        - nextToken
    UplineContractAssignmentChangeV2:
      type: object
      description: >
        Identity of the change's upline change, surfaced as part of the caller's
        own hierarchy.
      properties:
        id:
          type: string
          format: uuid
          description: The upline contract assignment change id.
        displayNumber:
          type: string
          description: The upline change's human-readable number.
        firmName:
          type: string
          description: The upline's firm name, if the upline is a firm.
        personName:
          type: string
          description: The upline's person name, if the upline is an individual producer.
      required:
        - id
  securitySchemes:
    oauth2:
      type: oauth2
      description: >
        OAuth2 client credentials. The `tokenUrl` below is the SANDBOX token
        endpoint; for production use `https://auth.agentsync.io/oauth2/token`.
        OpenAPI 3.1 permits only one token URL per flow, so both cannot be
        expressed here - see https://developer.agentsync.io/api-authentication
        for the full environment table, how to request credentials, and worked
        token-retrieval examples.
      flows:
        clientCredentials:
          tokenUrl: https://auth.sandbox.agentsync.io/oauth2/token
          scopes:
            contracting.producers.read: Read producers.
            contracting.contracts.read: Read contracts.
            contracting.contractassignments.read: >
              Read contract assignments, assignment changes, assigned carriers,
              products and commission levels, available uplines, responsible
              upline firms, and hierarchies.
```