--- title: "List the calling customer's contracts" url: "https://developer.agentsync.io/apis/contracting-hierarchies-api/versions/40f58935-396e-4da4-8f47-1587041e1b16/operations/listContractsV2" --- > Full API specification: https://developer.agentsync.io/apis/contracting-hierarchies-api/versions/40f58935-396e-4da4-8f47-1587041e1b16.md # List the calling customer's contracts `GET` `/v2/contracts` Operation ID: `listContractsV2` Returns the contracts sent from the calling customer's organization as a token-paginated collection. Results are scoped to the caller; another customer's contracts 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 contracts. - `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/contracts: get: tags: - Contracts operationId: listContractsV2 summary: List the calling customer's contracts description: > Returns the contracts sent from the calling customer's organization as a token-paginated collection. Results are scoped to the caller; another customer's contracts are never returned. security: - oauth2: - contracting.contracts.read parameters: - $ref: "#/components/parameters/PageToken" - $ref: "#/components/parameters/PageSize" - $ref: "#/components/parameters/UpdatedSince" responses: "200": description: A page of contracts. content: application/json: schema: $ref: "#/components/schemas/ContractV2Page" "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.contracts.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: ContractV2Page: type: object description: A token-paginated page of contracts (plain envelope, no HAL wrappers). properties: items: type: array items: $ref: "#/components/schemas/ContractV2" 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 ContractV2: type: object description: A contract sent from an agency to a carrier on behalf of a producer. properties: id: type: string format: uuid description: The contract id. agencyOrganizationId: type: string format: uuid description: The agency organization the contract is sent from. carrierOrganizationId: type: string format: uuid description: The carrier organization the contract is sent to. personId: type: string format: uuid description: The individual producer the contract is on behalf of. firmId: type: string format: uuid description: The firm the contract is on behalf of, if any. responsibleUplineFirmId: type: string format: uuid description: The upline firm responsible for the contract, if any. assignmentStatusId: type: string format: uuid description: The contract's assignment status id. assignmentStatusName: type: string description: The human-readable assignment status (inlined so no follow-up lookup is needed). active: type: boolean description: Whether the contract is currently active based on its assignments. effectiveDate: type: string format: date description: The effective date of the contract (yyyy-MM-dd). endDate: type: string format: date description: The end date of the contract (yyyy-MM-dd). displayNumber: type: string description: The human-readable contract number. parentContractId: type: string format: uuid description: The parent contract id, if this is a subsidiary contract. contractResponsibleParties: type: array description: > The contract's responsible-party windows, ordered by `startDate` ascending. An empty array when the contract has no responsible party. This is the contract's full responsible-party history, which is expected to stay small (a handful of windows per contract) and is embedded rather than paginated. items: $ref: "#/components/schemas/ContractResponsiblePartyV2" 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 - agencyOrganizationId - carrierOrganizationId - personId - active - displayNumber - contractResponsibleParties 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 ContractResponsiblePartyV2: type: object description: > One responsible-party window on a contract. Both bounds are inclusive. Windows do not overlap, with two exceptions: two windows may meet on a single shared day (one window's `endDate` equal to the next window's `startDate`), and a window whose `startDate` equals its `endDate` is a retired record rather than a live one-day assignment. To resolve who is responsible on a given day, ignore windows where `startDate` equals `endDate`, and on a shared boundary day prefer the window that starts that day over the one that ends it. The current window is the one with no `endDate`; there is at most one per contract. properties: id: type: string format: uuid description: The responsible-party window id. responsiblePartyId: type: string format: uuid description: The person responsible for the contract during this window. startDate: type: string format: date description: The first day the responsible party is responsible (yyyy-MM-dd). endDate: type: - string - "null" format: date description: > The last day the responsible party is responsible (yyyy-MM-dd). Absent on the current, open-ended window. required: - id - responsiblePartyId - startDate 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. ```