--- title: "List the calling customer's producers" url: "https://developer.agentsync.io/apis/contracting-hierarchies-api/versions/40f58935-396e-4da4-8f47-1587041e1b16/operations/listProducersV2" --- > Full API specification: https://developer.agentsync.io/apis/contracting-hierarchies-api/versions/40f58935-396e-4da4-8f47-1587041e1b16.md # List the calling customer's producers `GET` `/v2/producers` Operation ID: `listProducersV2` Returns the producers (individuals and firms) in the calling customer's organization as a token-paginated collection. Results are scoped to the caller; another customer's producers are never returned. This collection carries each producer's contracting record only. Phone numbers, the federated username, and bank accounts are returned by [the by-id endpoint](#operation/getProducerV2), not here, because each one requires a per-producer lookup that cannot be performed economically across a full page. `middleName` is served here from the contracting record's own copy, which can lag the Identity API. The by-id endpoint reads it live and is the accurate source. ## 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 producers. - `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/producers: get: tags: - Producers operationId: listProducersV2 summary: List the calling customer's producers description: > Returns the producers (individuals and firms) in the calling customer's organization as a token-paginated collection. Results are scoped to the caller; another customer's producers are never returned. This collection carries each producer's contracting record only. Phone numbers, the federated username, and bank accounts are returned by [the by-id endpoint](#operation/getProducerV2), not here, because each one requires a per-producer lookup that cannot be performed economically across a full page. `middleName` is served here from the contracting record's own copy, which can lag the Identity API. The by-id endpoint reads it live and is the accurate source. security: - oauth2: - contracting.producers.read parameters: - $ref: "#/components/parameters/PageToken" - $ref: "#/components/parameters/PageSize" - $ref: "#/components/parameters/UpdatedSince" responses: "200": description: A page of producers. content: application/json: schema: $ref: "#/components/schemas/ProducerV2Page" "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.producers.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: ProducerV2Page: type: object description: A token-paginated page of producers (plain envelope, no HAL wrappers). properties: items: type: array items: $ref: "#/components/schemas/ProducerV2" 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 ProducerV2: type: object description: > A producer in the calling customer's organization. A producer is either an individual (`type` = `AGENT`, identified by `personId`) or a firm (`type` = `FIRM`, identified by `firmId`); fields that do not apply to the other kind are null. properties: type: type: string description: The producer kind. enum: - AGENT - FIRM personId: type: string format: uuid description: The individual's id (null for firms). firmId: type: string format: uuid description: The firm's id (null for individuals). firstName: type: string description: The individual's first name (null for firms). middleName: type: string description: > The individual's middle name (null for firms). On this list item it comes from the contracting record's own copy, which can lag the Identity API; the by-id endpoint reads it live. lastName: type: string description: The individual's last name (null for firms). suffix: type: string firmName: type: string description: The firm's name (null for individuals). npn: type: string description: National Producer Number. email: type: string description: The individual's email (null for firms). organizationId: type: string format: uuid organizationName: type: string roleName: type: string statusId: type: string format: uuid statusName: type: string description: The human-readable producer status (inlined). Null for firms, which carry no status. active: type: boolean description: Whether the producer is active. Always true for firms. divisions: type: array items: type: string 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 createdAt: type: string format: date-time description: RFC3339 UTC creation timestamp. updatedAt: type: string format: date-time description: RFC3339 UTC last-modified timestamp. required: - type 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 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. ```