---
title: "Get one of the calling customer's contract assignments by id"
url: "https://developer.agentsync.io/apis/contracting-hierarchies-api/versions/40f58935-396e-4da4-8f47-1587041e1b16/operations/getContractAssignmentV2"
---

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

# Get one of the calling customer's contract assignments by id

`GET` `/v2/contract-assignments/{id}`

Operation ID: `getContractAssignmentV2`

Returns a single contract assignment owned by the calling customer. An assignment that does not exist or belongs to another customer returns `404` (never `403`), so the endpoint does not reveal the existence of out-of-scope assignments.

## Path parameters

- `id` (string, uuid, required) - The contract assignment id.

## Responses

- `200` - The contract assignment.
- `401` - Missing or invalid bearer token.
- `403` - The bearer token is not authorized for this resource.
- `404` - No such contract assignment for this customer.

## 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-assignments/{id}:
    get:
      tags:
        - Contract Assignments
      operationId: getContractAssignmentV2
      summary: Get one of the calling customer's contract assignments by id
      description: >
        Returns a single contract assignment owned by the calling customer. An
        assignment that does

        not exist or belongs to another customer returns `404` (never `403`), so
        the endpoint does not

        reveal the existence of out-of-scope assignments.
      security:
        - oauth2:
            - contracting.contractassignments.read
      parameters:
        - name: id
          in: path
          required: true
          description: The contract assignment id.
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: The contract assignment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContractAssignmentV2"
        "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"
        "404":
          description: No such contract assignment for this customer.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiError"
security:
  - oauth2:
      - contracting.contractassignments.read
components:
  schemas:
    ContractAssignmentV2:
      type: object
      description: A producer's assignment to a carrier product, with its commission
        level and status.
      properties:
        id:
          type: string
          format: uuid
          description: The contract assignment id.
        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).
        commissionLevelId:
          type: string
          format: uuid
        commissionLevelName:
          type: string
          description: The commission level name (inlined).
        assignmentStatusId:
          type: string
          format: uuid
        assignmentStatusName:
          type: string
          description: The human-readable assignment status (the event names this
            `assignmentStatus`).
        displayNumber:
          type: string
          description: The human-readable assignment number.
        writingNumber:
          type: string
        effectiveOn:
          type: string
          format: date
          description: The effective date (yyyy-MM-dd).
        requestedEffectiveOn:
          type: string
          format: date
          description: The requested effective date (yyyy-MM-dd).
        expiresOn:
          type: string
          format: date
          description: The expiration date (yyyy-MM-dd). Renamed from the entity's `expiry`.
        responsiblePartyId:
          type: string
          format: uuid
        responsibleUplineFirmId:
          type: string
          format: uuid
        responsiblePartyStartOn:
          type: string
          format: date
        responsiblePartyEndOn:
          type: string
          format: date
        referralCodes:
          type: array
          items:
            type: string
        debitBalance:
          type: number
        externalNotes:
          type: string
        uplineContractAssignment:
          $ref: "#/components/schemas/UplineContractAssignmentV2"
        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
        - contractId
        - agencyOrganizationId
        - carrierOrganizationId
        - personId
        - productId
        - commissionLevelId
        - displayNumber
    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
    UplineContractAssignmentV2:
      type: object
      description: >
        Identity of the assignment's upline, surfaced as part of the caller's
        own hierarchy.
      properties:
        id:
          type: string
          format: uuid
          description: The upline contract assignment id.
        displayNumber:
          type: string
          description: The upline assignment'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.
```