--- title: "Get one of the calling customer's producers by personId or firmId" url: "https://developer.agentsync.io/apis/contracting-hierarchies-api/versions/40f58935-396e-4da4-8f47-1587041e1b16/operations/getProducerV2" --- > 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 producers by personId or firmId `GET` `/v2/producers/{producerId}` Operation ID: `getProducerV2` Returns a single producer owned by the calling customer. A producer 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 producers. Beyond the fields on the list item, this response adds: - `phones` — the producer's phone numbers, in full. Empty when none are on file. - `bankAccounts` — with both the account `number` and the `routingNumber` masked to `****`. The unmasked values are never returned. - `federatedUsername` — the producer's federated login, as issued for the calling customer. Null for firms, and null where the producer has no federated login with you. - `middleName` — read live from the Identity API here, so it is current even when the contracting record's own copy (served by the list endpoint) has not caught up. ## Details this endpoint does not return This endpoint returns a producer's contracting record. Personal and demographic details are owned by the **Identity API** (`https://api.agentsync.io/identity`) and retrieved there using the `personId` or `firmId` from this response: | What you need | Where to retrieve it | |---|---| | `dateOfBirth`, `gender`, `preferredFirstName`, `citizenshipCountry`, `residentState`, `finraCrdNumber`, `ssnLast4` | `GET /v2/persons/{personId}` | | Full, unmasked `ssn` | `GET /v2/persons/{personId}/ssn` | | Firm `fein` | `GET /v2/firms/{firmId}/fein` | | Mailing and business addresses | `GET /v2/persons/{personId}/addresses`, `GET /v2/firms/{firmId}/addresses` | | Insurance policies (E&O) | `GET /v2/persons/{personId}/insurance-policies` | The full SSN is deliberately a separate call rather than a field on this response: it is released only on an explicit request for it, and every access is recorded. ## Path parameters - `producerId` (string, uuid, required) - The producer's `personId` (for individuals) or `firmId` (for firms), as returned by the list endpoint. ## Responses - `200` - The producer. - `401` - Missing or invalid bearer token. - `403` - The bearer token is not authorized for this resource. - `404` - No such producer 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/producers/{producerId}: get: tags: - Producers operationId: getProducerV2 summary: Get one of the calling customer's producers by personId or firmId description: > Returns a single producer owned by the calling customer. A producer 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 producers. Beyond the fields on the list item, this response adds: - `phones` — the producer's phone numbers, in full. Empty when none are on file. - `bankAccounts` — with both the account `number` and the `routingNumber` masked to `****`. The unmasked values are never returned. - `federatedUsername` — the producer's federated login, as issued for the calling customer. Null for firms, and null where the producer has no federated login with you. - `middleName` — read live from the Identity API here, so it is current even when the contracting record's own copy (served by the list endpoint) has not caught up. ## Details this endpoint does not return This endpoint returns a producer's contracting record. Personal and demographic details are owned by the **Identity API** (`https://api.agentsync.io/identity`) and retrieved there using the `personId` or `firmId` from this response: | What you need | Where to retrieve it | |---|---| | `dateOfBirth`, `gender`, `preferredFirstName`, `citizenshipCountry`, `residentState`, `finraCrdNumber`, `ssnLast4` | `GET /v2/persons/{personId}` | | Full, unmasked `ssn` | `GET /v2/persons/{personId}/ssn` | | Firm `fein` | `GET /v2/firms/{firmId}/fein` | | Mailing and business addresses | `GET /v2/persons/{personId}/addresses`, `GET /v2/firms/{firmId}/addresses` | | Insurance policies (E&O) | `GET /v2/persons/{personId}/insurance-policies` | The full SSN is deliberately a separate call rather than a field on this response: it is released only on an explicit request for it, and every access is recorded. security: - oauth2: - contracting.producers.read parameters: - name: producerId in: path required: true description: The producer's `personId` (for individuals) or `firmId` (for firms), as returned by the list endpoint. schema: type: string format: uuid responses: "200": description: The producer. content: application/json: schema: $ref: "#/components/schemas/ProducerDetailV2" "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 producer for this customer. content: application/json: schema: $ref: "#/components/schemas/ApiError" security: - oauth2: - contracting.producers.read components: schemas: ProducerDetailV2: description: > A single producer in the calling customer's organization. Carries the same fields as the list item plus `phones`, `federatedUsername`, and `bankAccounts`, and serves a live `middleName`. Personal and demographic details such as date of birth, SSN, and addresses are not part of a contracting record and are retrieved from the Identity API. allOf: - $ref: "#/components/schemas/ProducerV2" - type: object properties: middleName: type: string description: > The individual's middle name (null for firms), read live from the Identity API so it is current even when the contracting record's own copy has not caught up. bankAccounts: type: array description: The producer's bank accounts. Account and routing numbers are masked. items: $ref: "#/components/schemas/ProducerBankAccountV2" phones: type: array description: The producer's phone numbers. items: $ref: "#/components/schemas/ProducerPhoneV2" federatedUsername: type: string description: > The producer's federated login username for the calling customer. Null when the producer has no federated login, and always null for firms. 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 ProducerBankAccountV2: type: object description: A producer's bank account. The account and routing numbers are masked to `****`. properties: id: type: string format: uuid type: type: string description: The account type. enum: - CHECKING - SAVINGS - CREDIT_UNION bankName: type: string nickname: type: string holderName: type: string number: type: string description: Account number masked to `****`. example: "****7890" routingNumber: type: string description: Routing number masked to `****`. example: "****0021" ProducerPhoneV2: type: object description: A producer's phone number. properties: id: type: string format: uuid number: type: string example: "5551234567" extension: type: string type: type: string description: The phone kind. enum: - CELL - BUSINESS - RESIDENT - FAX preferred: type: boolean description: Whether this is the producer's preferred number. 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. ```