@producerflow/producerflowapi 1.0.16 → 1.0.21

package/dist/producerflow/producer/v1/producer_pb.d.ts

@@ -143,8 +143,10 @@ export type CreateAgencyOnboardingURLRequest_Agency = Message<"producerflow.prod
     tenantAgencyId: string;
     /**
      * DocuSign template id is the id of the docusign template used to send the contract to the agency
+     * Deprecated: Use signature_template_id instead. This field will be removed in a future version.
      *
-     * @generated from field: string docusign_template_id = 4;
+     * @generated from field: string docusign_template_id = 4 [deprecated = true];
+     * @deprecated
      */
     docusignTemplateId: string;
     /**
@@ -182,7 +184,15 @@ export type CreateAgencyOnboardingURLRequest_Agency = Message<"producerflow.prod
      */
     website: string;
     /**
-     * NPN of the agency. Note that if the entity type is Sole Proprietor the NPN will be ignored
+     * National Producer Number (NPN) of the agency.
+     * A unique NAIC identifier assigned to business entities during the
+     * licensing application process and stored in the NIPR Producer Database
+     * (PDB).
+     * Format: 1-10 digit numeric string.
+     * Example: "1234567890"
+     * Note: If the entity type is Sole Proprietor, the NPN will be ignored
+     * since sole proprietors use the principal's NPN.
+     * Reference: https://nipr.com
      *
      * @generated from field: string npn = 10;
      */
@@ -212,6 +222,14 @@ export type CreateAgencyOnboardingURLRequest_Agency = Message<"producerflow.prod
      * @generated from field: string organization_id = 15;
      */
     organizationId: string;
+    /**
+     * An optional signature template ID to be used to send the agency agreement through
+     * the configured e-signature provider (Docusign or Adobe Sign).
+     * The system will automatically detect the signature provider based on tenant configuration.
+     *
+     * @generated from field: optional string signature_template_id = 16;
+     */
+    signatureTemplateId?: string;
     /**
      * @generated from field: producerflow.producer.v1.CreateAgencyOnboardingURLRequest.Agency.Principal principal = 14;
      */
@@ -266,7 +284,12 @@ export type CreateAgencyOnboardingURLRequest_Agency_Principal = Message<"produce
      */
     phone: string;
     /**
-     * NPN of the principal
+     * National Producer Number (NPN) of the principal.
+     * A unique NAIC identifier assigned to individuals during the licensing
+     * application process and stored in the NIPR Producer Database (PDB).
+     * Format: 1-10 digit numeric string.
+     * Example: "1234567890"
+     * Reference: https://nipr.com
      *
      * @generated from field: string npn = 7;
      */
@@ -328,6 +351,16 @@ export declare const CreateProducerOnboardingURLRequestSchema: GenMessage<Create
  */
 export type ProducerData = Message<"producerflow.producer.v1.ProducerData"> & {
     /**
+     * National Producer Number (NPN) of the producer.
+     * A unique NAIC identifier assigned to individuals during the licensing
+     * application process and stored in the NIPR Producer Database (PDB).
+     * Format: 1-10 digit numeric string.
+     * Example: "1234567890"
+     * If provided, must be between 1 and 10 characters.
+     * Note: NPN validation against NIPR occurs during onboarding, not during URL
+     * generation.
+     * Reference: https://nipr.com
+     *
      * @generated from field: optional string npn = 1;
      */
     npn?: string;
@@ -475,9 +508,17 @@ export type NewAgencyRequest_Agency = Message<"producerflow.producer.v1.NewAgenc
      */
     email: string;
     /**
-     * National Producer Number for the agency
-     * Required for ENTITY_TYPE_AGENCY if FEIN is not provided
-     * Not allowed for ENTITY_TYPE_SOLE_PROPRIETOR
+     * National Producer Number (NPN) for the agency.
+     * A unique NAIC identifier assigned to business entities during the
+     * licensing application process and stored in the NIPR Producer Database
+     * (PDB).
+     * Format: 1-10 digit numeric string.
+     * Example: "1234567890"
+     * Required for ENTITY_TYPE_AGENCY if FEIN is not provided.
+     * Not allowed for ENTITY_TYPE_SOLE_PROPRIETOR (sole proprietors use the
+     * principal's NPN).
+     * Validated against NIPR's database via free NIPR NPN Lookup API.
+     * Reference: https://nipr.com
      *
      * @generated from field: string npn = 3;
      */
@@ -599,6 +640,13 @@ export type NewAgencyRequest_Agency = Message<"producerflow.producer.v1.NewAgenc
     tenantAdditionalQuestions: {
         [key: string]: string;
     };
+    /**
+     * IVANS account information for electronic carrier communication.
+     * This is optional and only used if the agency uses IVANS.
+     *
+     * @generated from field: producerflow.producer.v1.NewAgencyRequest.Agency.IvansAccount ivans_account = 23;
+     */
+    ivansAccount?: NewAgencyRequest_Agency_IvansAccount;
 };
 /**
  * Describes the message producerflow.producer.v1.NewAgencyRequest.Agency.
@@ -644,7 +692,13 @@ export type NewAgencyRequest_Agency_Principal = Message<"producerflow.producer.v
      */
     phone?: string;
     /**
-     * The National Producer Number (NPN) of the principal.
+     * National Producer Number (NPN) of the principal.
+     * A unique NAIC identifier assigned to individuals during the licensing
+     * application process and stored in the NIPR Producer Database (PDB).
+     * Format: 1-10 digit numeric string.
+     * Example: "1234567890"
+     * Required. Validated against NIPR's database via free NIPR NPN Lookup API.
+     * Reference: https://nipr.com
      *
      * @generated from field: string npn = 5;
      */
@@ -919,6 +973,44 @@ export declare enum NewAgencyRequest_Agency_PointOfContact_CommunicationRole {
  * Describes the enum producerflow.producer.v1.NewAgencyRequest.Agency.PointOfContact.CommunicationRole.
  */
 export declare const NewAgencyRequest_Agency_PointOfContact_CommunicationRoleSchema: GenEnum<NewAgencyRequest_Agency_PointOfContact_CommunicationRole>;
+/**
+ * IvansAccount contains IVANS (Insurance Value Added Network Services) account information.
+ * IVANS is used for electronic communication between insurance agencies and carriers.
+ *
+ * @generated from message producerflow.producer.v1.NewAgencyRequest.Agency.IvansAccount
+ */
+export type NewAgencyRequest_Agency_IvansAccount = Message<"producerflow.producer.v1.NewAgencyRequest.Agency.IvansAccount"> & {
+    /**
+     * Account number for the IVANS service.
+     *
+     * @generated from field: string account_number = 1;
+     */
+    accountNumber: string;
+    /**
+     * Software used for IVANS communication (AMS - Agency Management System).
+     *
+     * @generated from field: string ams_software = 2;
+     */
+    amsSoftware: string;
+    /**
+     * Version of the AMS software.
+     *
+     * @generated from field: string ams_version = 3;
+     */
+    amsVersion: string;
+    /**
+     * Mailbox number for the IVANS service.
+     * Used for routing electronic messages.
+     *
+     * @generated from field: string mailbox_number = 4;
+     */
+    mailboxNumber: string;
+};
+/**
+ * Describes the message producerflow.producer.v1.NewAgencyRequest.Agency.IvansAccount.
+ * Use `create(NewAgencyRequest_Agency_IvansAccountSchema)` to create a new message.
+ */
+export declare const NewAgencyRequest_Agency_IvansAccountSchema: GenMessage<NewAgencyRequest_Agency_IvansAccount>;
 /**
  * NewAgencyResponse contains the IDs of created resources after a successful agency creation
  *
@@ -956,8 +1048,8 @@ export type NewAgencyResponse = Message<"producerflow.producer.v1.NewAgencyRespo
  */
 export declare const NewAgencyResponseSchema: GenMessage<NewAgencyResponse>;
 /**
- * GetProducerRequest allows retrieving producer information through one of three
- * possible lookup methods: by ID, by NPN, or by email address.
+ * GetProducerRequest allows retrieving producer information through one of four
+ * possible lookup methods: by ID, by NPN, by email address, or by external ID.
  *
  * @generated from message producerflow.producer.v1.GetProducerRequest
  */
@@ -991,6 +1083,14 @@ export type GetProducerRequest = Message<"producerflow.producer.v1.GetProducerRe
          */
         value: GetProducerRequest_EmailLookup;
         case: "emailLookup";
+    } | {
+        /**
+         * Look up producer by external ID set via SetExternalID.
+         *
+         * @generated from field: producerflow.producer.v1.GetProducerRequest.ExternalIDLookup external_id_lookup = 4;
+         */
+        value: GetProducerRequest_ExternalIDLookup;
+        case: "externalIdLookup";
     } | {
         case: undefined;
         value?: undefined;
@@ -1058,6 +1158,27 @@ export type GetProducerRequest_EmailLookup = Message<"producerflow.producer.v1.G
  * Use `create(GetProducerRequest_EmailLookupSchema)` to create a new message.
  */
 export declare const GetProducerRequest_EmailLookupSchema: GenMessage<GetProducerRequest_EmailLookup>;
+/**
+ * ExternalIDLookup allows looking up a producer by the external identifier
+ * previously set via the SetExternalID RPC.
+ *
+ * @generated from message producerflow.producer.v1.GetProducerRequest.ExternalIDLookup
+ */
+export type GetProducerRequest_ExternalIDLookup = Message<"producerflow.producer.v1.GetProducerRequest.ExternalIDLookup"> & {
+    /**
+     * The external identifier associated with the producer in the tenant's system.
+     * This corresponds to the value set via the SetExternalID RPC.
+     * Must be a non-empty string with maximum 255 characters.
+     *
+     * @generated from field: string external_id = 1;
+     */
+    externalId: string;
+};
+/**
+ * Describes the message producerflow.producer.v1.GetProducerRequest.ExternalIDLookup.
+ * Use `create(GetProducerRequest_ExternalIDLookupSchema)` to create a new message.
+ */
+export declare const GetProducerRequest_ExternalIDLookupSchema: GenMessage<GetProducerRequest_ExternalIDLookup>;
 /**
  * GetProducerResponse contains the producer information retrieved by the GetProducer RPC.
  *
@@ -1173,15 +1294,13 @@ export type GetAgencyResponse = Message<"producerflow.producer.v1.GetAgencyRespo
  */
 export declare const GetAgencyResponseSchema: GenMessage<GetAgencyResponse>;
 /**
- * GetAgencyAndProducersRequest requests information about an agency and all associated producers.
+ * Deprecated: Use GetAgencyRequest/GetAgencyProducersRequest instead.
  *
  * @generated from message producerflow.producer.v1.GetAgencyAndProducersRequest
+ * @deprecated
  */
 export type GetAgencyAndProducersRequest = Message<"producerflow.producer.v1.GetAgencyAndProducersRequest"> & {
     /**
-     * The UUID of the agency to retrieve information for.
-     * Must be a valid UUID format.
-     *
      * @generated from field: string agency_id = 1;
      */
     agencyId: string;
@@ -1189,23 +1308,21 @@ export type GetAgencyAndProducersRequest = Message<"producerflow.producer.v1.Get
 /**
  * Describes the message producerflow.producer.v1.GetAgencyAndProducersRequest.
  * Use `create(GetAgencyAndProducersRequestSchema)` to create a new message.
+ * @deprecated
  */
 export declare const GetAgencyAndProducersRequestSchema: GenMessage<GetAgencyAndProducersRequest>;
 /**
- * GetAgencyAndProducersResponse contains the agency information and all associated producers.
+ * Deprecated: Use GetAgencyResponse/GetAgencyProducersResponse instead.
  *
  * @generated from message producerflow.producer.v1.GetAgencyAndProducersResponse
+ * @deprecated
  */
 export type GetAgencyAndProducersResponse = Message<"producerflow.producer.v1.GetAgencyAndProducersResponse"> & {
     /**
-     * Complete agency information including contact details, principal, and bank account.
-     *
      * @generated from field: producerflow.producer.v1.Agency agency = 1;
      */
     agency?: Agency;
     /**
-     * List of all producers associated with the specified agency.
-     *
      * @generated from field: repeated producerflow.producer.v1.Producer producers = 2;
      */
     producers: Producer[];
@@ -1213,8 +1330,60 @@ export type GetAgencyAndProducersResponse = Message<"producerflow.producer.v1.Ge
 /**
  * Describes the message producerflow.producer.v1.GetAgencyAndProducersResponse.
  * Use `create(GetAgencyAndProducersResponseSchema)` to create a new message.
+ * @deprecated
  */
 export declare const GetAgencyAndProducersResponseSchema: GenMessage<GetAgencyAndProducersResponse>;
+/**
+ * GetAgencyProducersRequest requests all producers associated with an agency.
+ *
+ * @generated from message producerflow.producer.v1.GetAgencyProducersRequest
+ */
+export type GetAgencyProducersRequest = Message<"producerflow.producer.v1.GetAgencyProducersRequest"> & {
+    /**
+     * The UUID of the agency to retrieve producers for.
+     * Must be a valid UUID format.
+     *
+     * @generated from field: string agency_id = 1;
+     */
+    agencyId: string;
+    /**
+     * Optional. Pagination parameters for controlling result set size and navigation.
+     * If not provided, defaults to page_size=50. Maximum page_size is 200.
+     *
+     * @generated from field: producerflow.producer.v1.Pagination pagination = 2;
+     */
+    pagination?: Pagination;
+};
+/**
+ * Describes the message producerflow.producer.v1.GetAgencyProducersRequest.
+ * Use `create(GetAgencyProducersRequestSchema)` to create a new message.
+ */
+export declare const GetAgencyProducersRequestSchema: GenMessage<GetAgencyProducersRequest>;
+/**
+ * GetAgencyProducersResponse contains producers associated with the specified agency.
+ *
+ * @generated from message producerflow.producer.v1.GetAgencyProducersResponse
+ */
+export type GetAgencyProducersResponse = Message<"producerflow.producer.v1.GetAgencyProducersResponse"> & {
+    /**
+     * List of producers for the current page.
+     *
+     * @generated from field: repeated producerflow.producer.v1.Producer producers = 1;
+     */
+    producers: Producer[];
+    /**
+     * Token for retrieving the next page of results.
+     * Empty when there are no more results.
+     *
+     * @generated from field: string next_page_token = 2;
+     */
+    nextPageToken: string;
+};
+/**
+ * Describes the message producerflow.producer.v1.GetAgencyProducersResponse.
+ * Use `create(GetAgencyProducersResponseSchema)` to create a new message.
+ */
+export declare const GetAgencyProducersResponseSchema: GenMessage<GetAgencyProducersResponse>;
 /**
  * GetAgencyFilesRequest requests URLs for files associated with an agency.
  *
@@ -1427,6 +1596,15 @@ export type UpdateProducerRequest_Producer = Message<"producerflow.producer.v1.U
     externalMetadata: {
         [key: string]: string;
     };
+    /**
+     * The onboarding status of the producer.
+     * If provided, updates the producer's onboarding status.
+     * If not provided, the onboarding status remains unchanged.
+     * When set, the onboarding_status_updated_at timestamp is automatically updated.
+     *
+     * @generated from field: optional producerflow.producer.v1.OnboardingStatus onboarding_status = 15;
+     */
+    onboardingStatus?: OnboardingStatus;
 };
 /**
  * Describes the message producerflow.producer.v1.UpdateProducerRequest.Producer.
@@ -1542,6 +1720,18 @@ export type UpdateAgencyRequest_Agency = Message<"producerflow.producer.v1.Updat
     externalMetadata: {
         [key: string]: string;
     };
+    /**
+     * IVANS account information for electronic carrier communication.
+     * This is optional and only used if the agency uses IVANS.
+     *
+     * Update behavior:
+     * - If not provided (null): existing IVANS account is preserved unchanged
+     * - If provided with all fields: IVANS account is created or completely replaced
+     * - Partial updates are supported: only specified fields will be updated
+     *
+     * @generated from field: producerflow.producer.v1.UpdateAgencyRequest.Agency.IvansAccount ivans_account = 9;
+     */
+    ivansAccount?: UpdateAgencyRequest_Agency_IvansAccount;
 };
 /**
  * Describes the message producerflow.producer.v1.UpdateAgencyRequest.Agency.
@@ -1604,6 +1794,48 @@ export type UpdateAgencyRequest_Agency_Address = Message<"producerflow.producer.
  * Use `create(UpdateAgencyRequest_Agency_AddressSchema)` to create a new message.
  */
 export declare const UpdateAgencyRequest_Agency_AddressSchema: GenMessage<UpdateAgencyRequest_Agency_Address>;
+/**
+ * IvansAccount contains IVANS (Insurance Value Added Network Services) account information.
+ * IVANS is used for electronic communication between insurance agencies and carriers.
+ *
+ * @generated from message producerflow.producer.v1.UpdateAgencyRequest.Agency.IvansAccount
+ */
+export type UpdateAgencyRequest_Agency_IvansAccount = Message<"producerflow.producer.v1.UpdateAgencyRequest.Agency.IvansAccount"> & {
+    /**
+     * Account number for the IVANS service.
+     * If provided, must be non-empty.
+     *
+     * @generated from field: optional string account_number = 1;
+     */
+    accountNumber?: string;
+    /**
+     * Software used for IVANS communication (AMS - Agency Management System).
+     * If provided, must be non-empty.
+     *
+     * @generated from field: optional string ams_software = 2;
+     */
+    amsSoftware?: string;
+    /**
+     * Version of the AMS software.
+     * If provided, must be non-empty.
+     *
+     * @generated from field: optional string ams_version = 3;
+     */
+    amsVersion?: string;
+    /**
+     * Mailbox number for the IVANS service.
+     * Used for routing electronic messages.
+     * If provided, must be non-empty.
+     *
+     * @generated from field: optional string mailbox_number = 4;
+     */
+    mailboxNumber?: string;
+};
+/**
+ * Describes the message producerflow.producer.v1.UpdateAgencyRequest.Agency.IvansAccount.
+ * Use `create(UpdateAgencyRequest_Agency_IvansAccountSchema)` to create a new message.
+ */
+export declare const UpdateAgencyRequest_Agency_IvansAccountSchema: GenMessage<UpdateAgencyRequest_Agency_IvansAccount>;
 /**
  * UpdateAgencyResponse is the empty response returned after successfully updating an agency.
  *
@@ -1771,6 +2003,23 @@ export type Agency = Message<"producerflow.producer.v1.Agency"> & {
      * @generated from field: bool is_sole_proprietor = 15;
      */
     isSoleProprietor: boolean;
+    /**
+     * The relationship of this agency with its organization.
+     *
+     * Indicates whether the agency is the main agency or a related agency within
+     * an organization.
+     * - MAIN: The primary agency that owns or manages the organization
+     * - RELATED: An agency that is part of the organization but not the primary owner
+     * - UNSPECIFIED: Agency does not belong to any organization
+     *
+     * This field is always populated based on the agency's actual organization
+     * membership, regardless of how the agency was queried. If the agency belongs
+     * to an organization, this will be MAIN or RELATED. If the agency is standalone
+     * (not part of any organization), this will be UNSPECIFIED.
+     *
+     * @generated from field: optional producerflow.producer.v1.AgencyOrganizationRelationship organization_relationship = 16;
+     */
+    organizationRelationship?: AgencyOrganizationRelationship;
 };
 /**
  * Describes the message producerflow.producer.v1.Agency.
@@ -1791,12 +2040,11 @@ export type Agency_AgencyInfo = Message<"producerflow.producer.v1.Agency.AgencyI
      */
     onboardingId: string;
     /**
-     * The organization ID represents the ID of the root organization that the agency belongs to.
-     * An example of a root organization is an Aggregator (Like AgencyHero) or an Agency Network.
-     * We currently don't support multiple levels of organizations or agencies.
-     * Agencies are not always part of an organization, so this field is optional.
+     * Deprecated: Use the top-level `organization` field instead, which provides the full
+     * organization object including id, name, external_id, and email.
      *
-     * @generated from field: string root_organization_id = 2;
+     * @generated from field: string root_organization_id = 2 [deprecated = true];
+     * @deprecated
      */
     rootOrganizationId: string;
     /**
@@ -1841,7 +2089,13 @@ export type Agency_AgencyInfo = Message<"producerflow.producer.v1.Agency.AgencyI
     website: string;
     /**
      * National Producer Number (NPN) of the agency.
-     * This is a unique identifier assigned by the National Association of Insurance Commissioners (NAIC).
+     * A unique NAIC identifier assigned to business entities during the
+     * licensing application process and stored in the NIPR Producer Database
+     * (PDB).
+     * Format: 1-10 digit numeric string.
+     * Example: "1234567890"
+     * Only present for standard agencies (not sole proprietors).
+     * Reference: https://nipr.com
      *
      * @generated from field: string npn = 9;
      */
@@ -2104,9 +2358,13 @@ export type Agency_Principal = Message<"producerflow.producer.v1.Agency.Principa
      */
     email: string;
     /**
-     * The NPN of the principal. This is used to
-     * retrieve the license information
-     * of the principal from the NIPR API.
+     * National Producer Number (NPN) of the principal.
+     * A unique NAIC identifier assigned to individuals during the licensing
+     * application process and stored in the NIPR Producer Database (PDB).
+     * Format: 1-10 digit numeric string.
+     * Example: "1234567890"
+     * Used to retrieve license information from the NIPR API.
+     * Reference: https://nipr.com
      *
      * @generated from field: string npn = 5;
      */
@@ -2125,6 +2383,16 @@ export type Agency_Principal = Message<"producerflow.producer.v1.Agency.Principa
      * @generated from field: producerflow.producer.v1.Agency.Address address = 8;
      */
     address?: Agency_Address;
+    /**
+     * tenant_additional_questions contains tenant-specific custom questions configured by
+     * Producerflow and their corresponding responses. Keys are question identifiers or text,
+     * values are the answers provided.
+     *
+     * @generated from field: map<string, string> tenant_additional_questions = 10;
+     */
+    tenantAdditionalQuestions: {
+        [key: string]: string;
+    };
 };
 /**
  * Describes the message producerflow.producer.v1.Agency.Principal.
@@ -2248,14 +2516,24 @@ export type Agency_NIPR = Message<"producerflow.producer.v1.Agency.NIPR"> & {
      */
     licenses: Agency_NIPR_License[];
     /**
-     * Regulatory information from NIPR
+     * Regulatory information from NIPR.
      *
      * @generated from field: producerflow.producer.v1.Agency.NIPR.RegulatoryInfo regulatory_info = 4;
      */
     regulatoryInfo?: Agency_NIPR_RegulatoryInfo;
     /**
-     * List of carrier appointments held in NIPR.
-     * These represent relationships with insurance carriers.
+     * List of carrier appointments held by the agency in NIPR.
+     *
+     * Each appointment represents authorization to sell a specific carrier's
+     * products for a specific Line of Authority. An agency typically has
+     * multiple appointments across different carriers and LOAs.
+     *
+     * Before allowing an agency to quote or sell a product:
+     * 1. Verify they have an active appointment with that carrier
+     * 2. Verify the appointment's LOA matches the product type
+     * 3. Check the appointment renewal date hasn't passed
+     *
+     * This data is synchronized from NIPR and is read-only.
      *
      * @generated from field: repeated producerflow.producer.v1.Agency.NIPR.Appointment appointments = 5;
      */
@@ -2285,7 +2563,13 @@ export type Agency_NIPR_Biographic = Message<"producerflow.producer.v1.Agency.NI
      */
     fein: string;
     /**
-     * National Producer Number.
+     * National Producer Number (NPN) of the agency.
+     * A unique NAIC identifier assigned to business entities during the
+     * licensing application process and stored in the NIPR Producer Database
+     * (PDB).
+     * Format: 1-10 digit numeric string.
+     * Example: "1234567890"
+     * Reference: https://nipr.com
      *
      * @generated from field: string npn = 3;
      */
@@ -2394,19 +2678,28 @@ export declare const Agency_NIPR_AddressSchema: GenMessage<Agency_NIPR_Address>;
  */
 export type Agency_NIPR_License = Message<"producerflow.producer.v1.Agency.NIPR.License"> & {
     /**
-     * The license number assigned by the state regulatory authority.
+     * The license number assigned by the state Department of Insurance (DOI).
+     * Format varies by state (e.g., numeric, alphanumeric, or with prefixes).
+     * Examples: "0A12345" (CA), "BR-1234567" (TX), "100012345" (FL)
+     * This is a state-specific identifier, not globally unique across states.
+     * Reference: Each state's DOI maintains its own licensing database.
      *
      * @generated from field: string license_number = 1;
      */
     licenseNumber: string;
     /**
-     * The state that issued the license.
+     * The two-letter US state or territory code that issued the license.
+     * Format: ISO 3166-2 subdivision code (e.g., "CA", "TX", "NY").
      *
      * @generated from field: string license_state = 2;
      */
     licenseState: string;
     /**
      * Indicates whether this is a resident or non-resident license.
+     * Values: "Resident" (license in the producer's home/domicile state) or
+     * "Non-Resident" (license in a state other than the home state).
+     * A producer typically has one resident license and may hold multiple
+     * non-resident licenses in other states where they conduct business.
      *
      * @generated from field: string residency_status = 3;
      */
@@ -2431,13 +2724,24 @@ export type Agency_NIPR_License = Message<"producerflow.producer.v1.Agency.NIPR.
      */
     expirationDate?: Timestamp;
     /**
-     * License class description.
+     * License class description as defined by the state DOI.
+     * Describes the broad category of insurance the license covers.
+     * Common classes include:
+     * - "Insurance Producer": General license to sell insurance
+     * - "Limited Lines Producer": Restricted to specific product types
+     * - "Surplus Lines Broker": Authorized for non-admitted carriers
+     * - "Managing General Agent": Underwriting authority on behalf of insurers
+     * - "Consultant": Licensed to provide insurance advice for a fee
+     * Values vary by state as each DOI defines its own license classes.
      *
      * @generated from field: string license_class = 7;
      */
     licenseClass: string;
     /**
-     * License class code.
+     * Numeric code corresponding to the license class.
+     * This is the NIPR-standardized numeric identifier for the license class
+     * description in the license_class field.
+     * Used for programmatic comparisons rather than string matching.
      *
      * @generated from field: int32 license_class_code = 8;
      */
@@ -2481,7 +2785,12 @@ export type Agency_NIPR_License = Message<"producerflow.producer.v1.Agency.NIPR.
      */
     lastUpdatedOn?: Date;
     /**
-     * Lines of Authority associated with this license.
+     * Lines of Authority (LOAs) associated with this license.
+     *
+     * These define what types of insurance the agency is authorized to
+     * transact in this state. A single license typically has multiple LOAs.
+     * Always check that the agency has an active LOA matching the product
+     * type before allowing transactions.
      *
      * @generated from field: repeated producerflow.producer.v1.Agency.NIPR.License.LineOfAuthority lines_of_authority = 12;
      */
@@ -2492,6 +2801,12 @@ export type Agency_NIPR_License = Message<"producerflow.producer.v1.Agency.NIPR.
      * @generated from field: string license_id = 13;
      */
     licenseId: string;
+    /**
+     * The designated home state for adjuster licenses (ADHS).
+     *
+     * @generated from field: string designated_home_state = 17;
+     */
+    designatedHomeState: string;
 };
 /**
  * Describes the message producerflow.producer.v1.Agency.NIPR.License.
@@ -2499,21 +2814,51 @@ export type Agency_NIPR_License = Message<"producerflow.producer.v1.Agency.NIPR.
  */
 export declare const Agency_NIPR_LicenseSchema: GenMessage<Agency_NIPR_License>;
 /**
- * LineOfAuthority represents a specific type of insurance coverage
- * that is authorized under this license.
+ * LineOfAuthority (LOA) represents a specific type of insurance that an
+ * agency is authorized to transact under this license.
+ *
+ * Each license can have multiple LOAs. For example, a license might
+ * include:
+ * - LIFE
+ * - HEALTH
+ * - ACCIDENT AND HEALTH
+ * - PROPERTY AND CASUALTY
+ * - VARIABLE LIFE AND VARIABLE ANNUITY
+ *
+ * LOA Compliance:
+ * Before allowing an agency to sell a product, verify they have an
+ * active LOA that matches the product type. For example, an agency with
+ * only a LIFE LOA cannot sell Property & Casualty insurance.
+ *
+ * LOA names are standardized by NIPR but may vary slightly between states.
  *
  * @generated from message producerflow.producer.v1.Agency.NIPR.License.LineOfAuthority
  */
 export type Agency_NIPR_License_LineOfAuthority = Message<"producerflow.producer.v1.Agency.NIPR.License.LineOfAuthority"> & {
     /**
-     * The Line of Authority description (e.g., "Life", "Property and Casualty", "Health").
-     * This is typically an uppercase string that describes the insurance type.
+     * The Line of Authority name (e.g., "LIFE", "PROPERTY AND CASUALTY",
+     * "HEALTH").
+     *
+     * Common LOA types:
+     * - LIFE: Life insurance products
+     * - HEALTH: Health insurance products
+     * - ACCIDENT AND HEALTH: Combined accident and health coverage
+     * - PROPERTY: Property insurance
+     * - CASUALTY: Casualty insurance
+     * - PROPERTY AND CASUALTY: Combined property and casualty
+     * - VARIABLE LIFE AND VARIABLE ANNUITY: Variable products requiring
+     *   securities license
+     * - PERSONAL LINES: Homeowners, auto, and personal umbrella policies
+     * - COMMERCIAL LINES: Business insurance policies
+     *
+     * This is typically an uppercase string standardized by NIPR.
      *
      * @generated from field: string loa = 1;
      */
     loa: string;
     /**
      * Whether this Line of Authority is currently active.
+     * Inactive LOAs cannot be used to transact that type of insurance.
      *
      * @generated from field: bool active = 2;
      */
@@ -2526,7 +2871,9 @@ export type Agency_NIPR_License_LineOfAuthority = Message<"producerflow.producer
      */
     issueDate?: Timestamp;
     /**
-     * The date when this Line of Authority was issued.
+     * The date when this Line of Authority was first issued.
+     * This helps track how long the agency has been authorized for this
+     * insurance type.
      *
      * @generated from field: google.type.Date issued_on = 4;
      */
@@ -2574,8 +2921,13 @@ export declare enum Agency_NIPR_License_LicenseStatus {
  */
 export declare const Agency_NIPR_License_LicenseStatusSchema: GenEnum<Agency_NIPR_License_LicenseStatus>;
 /**
- * RegulatoryInfo contains regulatory information,
- * including any regulatory actions.
+ * RegulatoryInfo contains regulatory information from NIPR, including any
+ * formal regulatory actions taken against the agency by state Departments
+ * of Insurance (DOIs) or other regulatory authorities.
+ *
+ * Regulatory actions are significant events that may affect an agency's
+ * ability to conduct business. They should be reviewed during due diligence
+ * and compliance checks.
  *
  * @generated from message producerflow.producer.v1.Agency.NIPR.RegulatoryInfo
  */
@@ -2583,6 +2935,7 @@ export type Agency_NIPR_RegulatoryInfo = Message<"producerflow.producer.v1.Agenc
     /**
      * List of regulatory actions across different states.
      * Each regulatory action includes the state code where it applies.
+     * An empty list indicates no regulatory actions on record in NIPR.
      *
      * @generated from field: repeated producerflow.producer.v1.Agency.NIPR.RegulatoryInfo.RegulatoryAction regulatory_actions = 1;
      */
@@ -2594,25 +2947,42 @@ export type Agency_NIPR_RegulatoryInfo = Message<"producerflow.producer.v1.Agenc
  */
 export declare const Agency_NIPR_RegulatoryInfoSchema: GenMessage<Agency_NIPR_RegulatoryInfo>;
 /**
- * RegulatoryAction represents a regulatory action.
+ * RegulatoryAction represents a formal regulatory action taken against
+ * an agency by a state Department of Insurance or other regulatory body.
+ *
+ * Common types of regulatory actions include:
+ * - License revocation or suspension
+ * - Cease and desist orders
+ * - Consent agreements
+ * - Fines and monetary penalties
+ * - Probationary periods
+ * - Administrative actions for non-compliance
+ *
+ * These records are sourced from NIPR's PDB (Producer Database) and
+ * reflect official regulatory proceedings.
  *
  * @generated from message producerflow.producer.v1.Agency.NIPR.RegulatoryInfo.RegulatoryAction
  */
 export type Agency_NIPR_RegulatoryInfo_RegulatoryAction = Message<"producerflow.producer.v1.Agency.NIPR.RegulatoryInfo.RegulatoryAction"> & {
     /**
-     * Unique identifier for the regulatory action.
+     * Unique identifier for the regulatory action in NIPR's system.
      *
      * @generated from field: string action_id = 1;
      */
     actionId: string;
     /**
-     * The state code where this regulatory action applies.
+     * The two-letter state code of the regulatory authority that took
+     * the action.
+     * Format: US state code (e.g., "CA", "TX", "NY").
      *
      * @generated from field: string state_code = 2;
      */
     stateCode: string;
     /**
-     * The reason why the regulatory action was taken.
+     * The reason or cause for the regulatory action.
+     * Examples: "Misrepresentation", "Failure to Remit Premiums",
+     * "Unfair Trade Practices", "Fraud", "Non-Compliance".
+     * This is a free-text field as reasons are defined by each state DOI.
      *
      * @generated from field: string reason_for_action = 3;
      */
@@ -2624,37 +2994,46 @@ export type Agency_NIPR_RegulatoryInfo_RegulatoryAction = Message<"producerflow.
      */
     disposition: string;
     /**
-     * The date when the regulatory action was taken.
+     * The date when the regulatory action was formally initiated or filed.
      *
      * @generated from field: google.protobuf.Timestamp date_of_action = 5;
      */
     dateOfAction?: Timestamp;
     /**
-     * The date when the regulatory action became effective.
+     * The date when the regulatory action took effect.
+     * This may differ from date_of_action if there was a delayed
+     * effective date or appeal period.
      *
      * @generated from field: google.protobuf.Timestamp effective_date = 6;
      */
     effectiveDate?: Timestamp;
     /**
-     * The date when the entity entered into the regulatory action.
+     * The date when the agency entered into or acknowledged the
+     * regulatory action (e.g., signed a consent agreement).
      *
      * @generated from field: google.protobuf.Timestamp enter_date = 7;
      */
     enterDate?: Timestamp;
     /**
-     * Reference number for the regulatory action file.
+     * Reference number for the regulatory action file maintained by the
+     * state DOI. Can be used to look up additional details from the
+     * state's records.
      *
      * @generated from field: string file_ref = 8;
      */
     fileRef: string;
     /**
-     * Any financial penalties associated with the regulatory action.
+     * Any financial penalties, fines, or forfeitures associated with
+     * the regulatory action.
+     * Format: Free-text, typically a dollar amount (e.g., "$5,000.00").
      *
      * @generated from field: string penalty_fine_forfeiture = 9;
      */
     penaltyFineForfeiture: string;
     /**
      * Duration of any orders associated with the regulatory action.
+     * Format: Free-text describing the time period (e.g., "12 months",
+     * "Indefinite", "Until compliance").
      *
      * @generated from field: string length_of_order = 10;
      */
@@ -2666,48 +3045,92 @@ export type Agency_NIPR_RegulatoryInfo_RegulatoryAction = Message<"producerflow.
  */
 export declare const Agency_NIPR_RegulatoryInfo_RegulatoryActionSchema: GenMessage<Agency_NIPR_RegulatoryInfo_RegulatoryAction>;
 /**
- * Appointment represents a relationship with an insurance carrier.
+ * Appointment represents a formal relationship between an agency and an
+ * insurance carrier, granting the agency authority to sell that carrier's
+ * products. This data is sourced from NIPR's PDB (Producer Database).
+ *
+ * Appointment Lifecycle (status field values):
+ * 1. APPOINTED: Agency is authorized to sell this carrier's products for
+ *    the specified Line of Authority
+ * 2. TERMINATED: Appointment has ended (see termination_reason for details)
+ *
+ * Use Cases:
+ * - Verify agency is appointed before allowing them to sell a carrier's
+ *   products
+ * - Track which carriers an agency represents
+ * - Monitor appointment renewal dates for compliance
  *
  * @generated from message producerflow.producer.v1.Agency.NIPR.Appointment
  */
 export type Agency_NIPR_Appointment = Message<"producerflow.producer.v1.Agency.NIPR.Appointment"> & {
     /**
+     * Branch identifier for multi-branch agencies.
+     * Links the appointment to a specific agency branch, if applicable.
+     *
      * @generated from field: string branch_id = 1;
      */
     branchId: string;
     /**
      * Name of the insurance company for this appointment.
+     * Examples: "State Farm", "Allstate", "Blue Cross Blue Shield"
      *
      * @generated from field: string company_name = 2;
      */
     companyName: string;
     /**
-     * Federal Employer Identification Number of the carrier.
+     * Federal Employer Identification Number (FEIN) of the carrier.
+     * Format: 9-digit number assigned by the IRS.
+     * This uniquely identifies the carrier company for tax purposes.
      *
      * @generated from field: string fein = 3;
      */
     fein: string;
     /**
-     * Company code for the insurance carrier.
+     * NAIC Company Code (CoCode) for the insurance carrier.
+     * A unique identifier assigned by the National Association of Insurance
+     * Commissioners (NAIC) for regulatory reporting.
+     * Format: Typically a 5-digit numeric string.
+     * Reference: https://naic.org
      *
      * @generated from field: string co_code = 4;
      */
     coCode: string;
     /**
-     * Line of authority for this appointment (e.g., Life, Property, Casualty).
-     * Indicates what types of insurance can be sold.
+     * Line of Authority (LOA) for this appointment.
+     * Indicates what type of insurance the agency can sell for this carrier.
+     * A single carrier may have separate appointments for different LOAs.
+     *
+     * Common LOA values:
+     * - "LIFE": Life insurance products
+     * - "HEALTH": Health insurance products
+     * - "PROPERTY": Property insurance
+     * - "CASUALTY": Casualty insurance
+     * - "PROPERTY AND CASUALTY": Combined P&C
+     * - "VARIABLE LIFE AND VARIABLE ANNUITY": Variable products
+     *
+     * LOA names are standardized by NIPR but may vary slightly between states.
      *
      * @generated from field: string line_of_authority = 5;
      */
     lineOfAuthority: string;
     /**
-     * Code for the line of authority for this appointment.
+     * Standardized code for the Line of Authority.
+     * Used for programmatic matching rather than string comparison on the
+     * line_of_authority description field.
      *
      * @generated from field: string loa_code = 6;
      */
     loaCode: string;
     /**
-     * Current status of the appointment (e.g., Active, Terminated).
+     * Current status of the appointment as reported by NIPR.
+     *
+     * Values:
+     * - "APPOINTED": Appointment is active; the agency can sell this
+     *   carrier's products for the specified Line of Authority
+     * - "TERMINATED": Appointment has ended (see termination_reason for
+     *   details)
+     *
+     * Always check status is "APPOINTED" before allowing sales.
      *
      * @generated from field: string status = 7;
      */
@@ -2715,23 +3138,40 @@ export type Agency_NIPR_Appointment = Message<"producerflow.producer.v1.Agency.N
     /**
      * Reason for termination if the appointment has been terminated.
      *
+     * Common termination reasons include:
+     * - Voluntary termination by the agency
+     * - Carrier-initiated termination
+     * - Inadequate production
+     * - Company merger or liquidation
+     * - Regulatory or compliance issues
+     *
+     * This field is empty if the appointment is still active.
+     * Reference: https://pdb.nipr.com/Gateway/ValidTerms
+     *
      * @generated from field: string termination_reason = 8;
      */
     terminationReason: string;
     /**
-     * Date associated with the current status or reason.
+     * Date when the status or termination reason became effective.
+     * For terminated appointments, this is when the termination occurred.
+     * For active appointments, this may indicate when the current status
+     * was last confirmed.
      *
      * @generated from field: google.protobuf.Timestamp status_reason_date = 9;
      */
     statusReasonDate?: Timestamp;
     /**
      * Date when the appointment will renew.
+     * Appointments typically renew annually. Monitor this date for upcoming
+     * renewals to ensure continuous authorization.
      *
      * @generated from field: google.protobuf.Timestamp appointment_renewal_date = 10;
      */
     appointmentRenewalDate?: Timestamp;
     /**
-     * Additional affiliations or roles with the agency.
+     * Additional affiliations or roles the agency has with the carrier.
+     * This may include special designations, sub-agency relationships,
+     * or other relationship details.
      *
      * @generated from field: string agency_affiliations = 11;
      */
@@ -2803,9 +3243,13 @@ export type Producer = Message<"producerflow.producer.v1.Producer"> & {
      */
     email: string;
     /**
-     * The National Producer Number (NPN) of the producer.
-     * This is used to retrieve license information from the NIPR API.
-     * Must be non-empty.
+     * National Producer Number (NPN) of the producer.
+     * A unique NAIC identifier assigned to individuals during the licensing
+     * application process and stored in the NIPR Producer Database (PDB).
+     * Format: 1-10 digit numeric string.
+     * Example: "1234567890"
+     * Used to retrieve license, appointment, and regulatory data from NIPR.
+     * Reference: https://nipr.com
      *
      * @generated from field: string npn = 4;
      */
@@ -3042,14 +3486,18 @@ export declare const Producer_NIPRSchema: GenMessage<Producer_NIPR>;
  */
 export type Producer_NIPR_License = Message<"producerflow.producer.v1.Producer.NIPR.License"> & {
     /**
-     * The license number assigned by the state regulatory authority.
+     * The license number assigned by the state Department of Insurance (DOI).
+     * Format varies by state (e.g., numeric, alphanumeric, or with prefixes).
+     * Examples: "0A12345" (CA), "BR-1234567" (TX), "100012345" (FL)
+     * This is a state-specific identifier, not globally unique across states.
+     * Reference: Each state's DOI maintains its own licensing database.
      *
      * @generated from field: string license_number = 1;
      */
     licenseNumber: string;
     /**
-     * The state that issued the license.
-     * Typically a two-letter state code.
+     * The two-letter US state or territory code that issued the license.
+     * Format: ISO 3166-2 subdivision code (e.g., "CA", "TX", "NY").
      *
      * @generated from field: string license_state = 2;
      */
@@ -3109,6 +3557,12 @@ export type Producer_NIPR_License = Message<"producerflow.producer.v1.Producer.N
      * @generated from field: string license_id = 9;
      */
     licenseId: string;
+    /**
+     * The designated home state for adjuster licenses (ADHS).
+     *
+     * @generated from field: string designated_home_state = 11;
+     */
+    designatedHomeState: string;
 };
 /**
  * Describes the message producerflow.producer.v1.Producer.NIPR.License.
@@ -3260,22 +3714,27 @@ export type Producer_NIPR_Biographic = Message<"producerflow.producer.v1.Produce
      */
     dateOfBirth?: Timestamp;
     /**
-     * Federal Employer Identification Number if the producer is a business entity.
+     * Deprecated: producers in ProducerFlow are always individuals. NIPR does not
+     * return FEIN for individual agents; this field will always be empty.
      *
-     * @generated from field: string fein = 7;
+     * @generated from field: string fein = 7 [deprecated = true];
+     * @deprecated
      */
     fein: string;
     /**
-     * Company name if the producer is a business entity.
+     * Deprecated: producers in ProducerFlow are always individuals. NIPR does not
+     * return a company name for individual agents; this field will always be empty.
      *
-     * @generated from field: string company_name = 8;
+     * @generated from field: string company_name = 8 [deprecated = true];
+     * @deprecated
      */
     companyName: string;
     /**
-     * State of domicile (resident state) for the producer.
-     * This is the state where the producer is primarily located.
+     * Deprecated: producers in ProducerFlow are always individuals. NIPR does not
+     * return state of domicile for individual agents; this field will always be empty.
      *
-     * @generated from field: string state_domicile = 9;
+     * @generated from field: string state_domicile = 9 [deprecated = true];
+     * @deprecated
      */
     stateDomicile: string;
 };
@@ -3285,15 +3744,24 @@ export type Producer_NIPR_Biographic = Message<"producerflow.producer.v1.Produce
  */
 export declare const Producer_NIPR_BiographicSchema: GenMessage<Producer_NIPR_Biographic>;
 /**
- * ProducerRegulatoryInfo contains regulatory information about a producer,
- * including any regulatory actions taken against them.
+ * ProducerRegulatoryInfo contains regulatory information about a producer
+ * from NIPR, including any formal regulatory actions taken against them by
+ * state Departments of Insurance (DOIs) or other regulatory authorities
+ * (e.g., FINRA for securities-related licenses).
+ *
+ * Regulatory actions are significant events that may affect a producer's
+ * ability to sell insurance. They should be reviewed during hiring,
+ * contracting, and ongoing compliance monitoring.
  *
  * @generated from message producerflow.producer.v1.Producer.NIPR.ProducerRegulatoryInfo
  */
 export type Producer_NIPR_ProducerRegulatoryInfo = Message<"producerflow.producer.v1.Producer.NIPR.ProducerRegulatoryInfo"> & {
     /**
-     * Map of regulatory actions by state.
-     * The key is the state code, and the value is the regulatory action.
+     * Map of regulatory actions keyed by two-letter state code.
+     * The key is the state code (e.g., "CA", "TX"), and the value is the
+     * regulatory action for that state. A producer may have regulatory
+     * actions in multiple states.
+     * An empty map indicates no regulatory actions on record in NIPR.
      *
      * @generated from field: map<string, producerflow.producer.v1.Producer.NIPR.ProducerRegulatoryInfo.RegulatoryAction> regulatory_actions_by_state = 1;
      */
@@ -3302,12 +3770,19 @@ export type Producer_NIPR_ProducerRegulatoryInfo = Message<"producerflow.produce
     };
     /**
      * Clearance certification information for the producer.
+     * Indicates whether the producer has obtained clearance from NIPR's
+     * Clearance Certification process, which verifies the producer has no
+     * outstanding regulatory issues across all states.
      *
      * @generated from field: string clearance_certification_info = 2;
      */
     clearanceCertificationInfo: string;
     /**
      * Details about NASD/FINRA examinations taken by the producer.
+     * This includes securities-related examinations (e.g., Series 6,
+     * Series 7, Series 63, Series 66) that may be required for selling
+     * variable insurance products.
+     * Reference: https://www.finra.org
      *
      * @generated from field: string nasd_exam_details = 3;
      */
@@ -3319,68 +3794,104 @@ export type Producer_NIPR_ProducerRegulatoryInfo = Message<"producerflow.produce
  */
 export declare const Producer_NIPR_ProducerRegulatoryInfoSchema: GenMessage<Producer_NIPR_ProducerRegulatoryInfo>;
 /**
- * RegulatoryAction represents a regulatory action taken against a producer.
+ * RegulatoryAction represents a formal regulatory action taken against
+ * a producer by a state Department of Insurance, FINRA, or other
+ * regulatory body.
+ *
+ * Common types of regulatory actions include:
+ * - License revocation or suspension
+ * - Cease and desist orders
+ * - Consent agreements
+ * - Fines and monetary penalties
+ * - Probationary periods
+ * - Administrative actions for non-compliance
+ *
+ * These records are sourced from NIPR's PDB (Producer Database) and
+ * reflect official regulatory proceedings.
  *
  * @generated from message producerflow.producer.v1.Producer.NIPR.ProducerRegulatoryInfo.RegulatoryAction
  */
 export type Producer_NIPR_ProducerRegulatoryInfo_RegulatoryAction = Message<"producerflow.producer.v1.Producer.NIPR.ProducerRegulatoryInfo.RegulatoryAction"> & {
     /**
-     * Unique identifier for the regulatory action.
+     * Unique identifier for the regulatory action in NIPR's system.
      *
      * @generated from field: string action_id = 1;
      */
     actionId: string;
     /**
      * The regulatory body that originated the action.
-     * Typically a state insurance department or FINRA.
+     * Examples: "California Department of Insurance", "FINRA",
+     * "Texas Department of Insurance".
+     * This identifies which authority initiated the regulatory proceeding.
      *
      * @generated from field: string origin_of_action = 2;
      */
     originOfAction: string;
     /**
-     * The reason why the regulatory action was taken.
+     * The reason or cause for the regulatory action.
+     * Examples: "Misrepresentation", "Failure to Remit Premiums",
+     * "Unfair Trade Practices", "Fraud", "Non-Compliance".
+     * This is a free-text field as reasons are defined by each regulatory
+     * authority.
      *
      * @generated from field: string reason_for_action = 3;
      */
     reasonForAction: string;
     /**
      * The outcome or resolution of the regulatory action.
+     * Common dispositions include:
+     * - "Revoked": License permanently removed
+     * - "Suspended": License temporarily inactive
+     * - "Consent Agreement": Negotiated settlement
+     * - "Probation": Conditional continued operation
+     * - "Fine/Penalty": Monetary penalty imposed
+     * - "Dismissed": Action was dropped or resolved favorably
+     * - "Pending": Action is still being adjudicated
      *
      * @generated from field: string disposition = 4;
      */
     disposition: string;
     /**
-     * The date when the regulatory action was taken.
+     * The date when the regulatory action was formally initiated or filed.
      *
      * @generated from field: google.protobuf.Timestamp date_of_action = 5;
      */
     dateOfAction?: Timestamp;
     /**
-     * The date when the regulatory action became effective.
+     * The date when the regulatory action took effect.
+     * This may differ from date_of_action if there was a delayed
+     * effective date or appeal period.
      *
      * @generated from field: google.protobuf.Timestamp effective_date = 6;
      */
     effectiveDate?: Timestamp;
     /**
-     * The date when the producer entered into the regulatory action.
+     * The date when the producer entered into or acknowledged the
+     * regulatory action (e.g., signed a consent agreement).
      *
      * @generated from field: google.protobuf.Timestamp enter_date = 7;
      */
     enterDate?: Timestamp;
     /**
-     * Reference number for the regulatory action file.
+     * Reference number for the regulatory action file maintained by the
+     * regulatory authority. Can be used to look up additional details
+     * from the authority's records.
      *
      * @generated from field: string file_ref = 8;
      */
     fileRef: string;
     /**
-     * Any financial penalties associated with the regulatory action.
+     * Any financial penalties, fines, or forfeitures associated with
+     * the regulatory action.
+     * Format: Free-text, typically a dollar amount (e.g., "$5,000.00").
      *
      * @generated from field: string penalty_fine_forfeiture = 9;
      */
     penaltyFineForfeiture: string;
     /**
      * Duration of any orders associated with the regulatory action.
+     * Format: Free-text describing the time period (e.g., "12 months",
+     * "Indefinite", "Until compliance").
      *
      * @generated from field: string length_of_order = 10;
      */
@@ -3402,10 +3913,10 @@ export declare const Producer_NIPR_ProducerRegulatoryInfo_RegulatoryActionSchema
  * producer must also be appointed by each carrier whose products they want
  * to sell.
  *
- * Appointment Lifecycle:
- * 1. Active: Producer can sell this carrier's products
- * 2. Terminated: Appointment ended (various reasons: producer left, carrier
- *    terminated, etc.)
+ * Appointment Lifecycle (status field values):
+ * 1. APPOINTED: Producer can sell this carrier's products
+ * 2. TERMINATED: Appointment has ended (various reasons: producer left,
+ *    carrier terminated, etc.)
  *
  * Use Cases:
  * - Verify producer is appointed before allowing them to quote/sell a
@@ -3466,14 +3977,15 @@ export type Producer_NIPR_Appointment = Message<"producerflow.producer.v1.Produc
      */
     loaCode: string;
     /**
-     * Current status of the appointment.
+     * Current status of the appointment as reported by NIPR.
      *
-     * Common values:
-     * - "Active": Producer can sell this carrier's products
-     * - "Terminated": Appointment has ended
-     * - "Pending": Appointment is being processed
+     * Values:
+     * - "APPOINTED": Appointment is active; the producer can sell this
+     *   carrier's products for the specified Line of Authority
+     * - "TERMINATED": Appointment has ended (see termination_reason for
+     *   details)
      *
-     * Always check status is "Active" before allowing sales.
+     * Always check status is "APPOINTED" before allowing sales.
      *
      * @generated from field: string status = 7;
      */
@@ -3627,12 +4139,16 @@ export type NewProducer = Message<"producerflow.producer.v1.NewProducer"> & {
     email: string;
     /**
      * National Producer Number (NPN) of the producer.
-     * Optional but strongly recommended for licensed producers.
-     * This unique identifier from NAIC enables:
+     * A unique NAIC identifier assigned to individuals during the licensing
+     * application process and stored in the NIPR Producer Database (PDB).
+     * Format: 1-10 digit numeric string.
+     * Example: "1234567890"
+     * Optional but strongly recommended for licensed producers. Enables:
      * - NIPR data synchronization (licenses, appointments, regulatory actions)
      * - Carrier appointment verification
      * - Compliance tracking across states
      * If provided, must be valid in NIPR's database or creation will fail.
+     * Reference: https://nipr.com
      *
      * @generated from field: string npn = 4;
      */
@@ -4029,7 +4545,13 @@ export type NewContact = Message<"producerflow.producer.v1.NewContact"> & {
      */
     tenantId: string;
     /**
-     * National Producer Number (NPN) of the contact.
+     * National Producer Number (NPN) of the contact, if applicable.
+     * A unique NAIC identifier assigned during the licensing application process
+     * and stored in the NIPR Producer Database (PDB).
+     * Format: 1-10 digit numeric string.
+     * Example: "1234567890"
+     * Only applicable for contacts who are licensed insurance professionals.
+     * Reference: https://nipr.com
      *
      * @generated from field: optional string npn = 9;
      */
@@ -4190,6 +4712,12 @@ export type Contact = Message<"producerflow.producer.v1.Contact"> & {
     address?: Address;
     /**
      * National Producer Number (NPN) of the contact, if applicable.
+     * A unique NAIC identifier assigned during the licensing application process
+     * and stored in the NIPR Producer Database (PDB).
+     * Format: 1-10 digit numeric string.
+     * Example: "1234567890"
+     * Only present for contacts who are licensed insurance professionals.
+     * Reference: https://nipr.com
      *
      * @generated from field: string npn = 9;
      */
@@ -4456,21 +4984,27 @@ export type SetExternalIDResponse = Message<"producerflow.producer.v1.SetExterna
  */
 export declare const SetExternalIDResponseSchema: GenMessage<SetExternalIDResponse>;
 /**
- * ValidateProducerNPNRequest is used to validate a producer's National Producer Number.
+ * ValidateProducerNPNRequest is used to validate a producer's National Producer
+ * Number (NPN) against the NIPR database.
+ * This is a FREE operation using the NIPR NPN Lookup service.
  *
  * @generated from message producerflow.producer.v1.ValidateProducerNPNRequest
  */
 export type ValidateProducerNPNRequest = Message<"producerflow.producer.v1.ValidateProducerNPNRequest"> & {
     /**
      * The National Producer Number (NPN) to validate.
+     * Format: 1-10 digit numeric string.
+     * Example: "1234567890"
      * Required and must be non-empty.
+     * Reference: https://nipr.com
      *
      * @generated from field: string npn = 1;
      */
     npn: string;
     /**
-     * Optional name of the producer to validate.
-     * If provided, the NPN will be validated against this name.
+     * Optional name of the producer to validate against NIPR records.
+     * If provided, both NPN existence and name match are verified.
+     * If omitted, only NPN existence is verified.
      *
      * @generated from field: optional string name = 2;
      */
@@ -4489,7 +5023,8 @@ export declare const ValidateProducerNPNRequestSchema: GenMessage<ValidateProduc
 export type ValidateProducerNPNResponse = Message<"producerflow.producer.v1.ValidateProducerNPNResponse"> & {
     /**
      * Indicates whether the NPN is valid.
-     * True if the NPN exists and is valid, false otherwise.
+     * True if the NPN exists in NIPR (and name matches, if provided).
+     * False if the NPN does not exist or the name does not match.
      *
      * @generated from field: bool valid = 1;
      */
@@ -4501,14 +5036,19 @@ export type ValidateProducerNPNResponse = Message<"producerflow.producer.v1.Vali
  */
 export declare const ValidateProducerNPNResponseSchema: GenMessage<ValidateProducerNPNResponse>;
 /**
- * ValidateAgencyNPNRequest is used to validate an agency's National Producer Number.
+ * ValidateAgencyNPNRequest is used to validate an agency's National Producer
+ * Number (NPN) against the NIPR database.
+ * This is a FREE operation using the NIPR NPN Lookup service.
  *
  * @generated from message producerflow.producer.v1.ValidateAgencyNPNRequest
  */
 export type ValidateAgencyNPNRequest = Message<"producerflow.producer.v1.ValidateAgencyNPNRequest"> & {
     /**
      * The National Producer Number (NPN) to validate.
+     * Format: 1-10 digit numeric string.
+     * Example: "1234567890"
      * Required and must be non-empty.
+     * Reference: https://nipr.com
      *
      * @generated from field: string npn = 1;
      */
@@ -4527,7 +5067,8 @@ export declare const ValidateAgencyNPNRequestSchema: GenMessage<ValidateAgencyNP
 export type ValidateAgencyNPNResponse = Message<"producerflow.producer.v1.ValidateAgencyNPNResponse"> & {
     /**
      * Indicates whether the NPN is valid.
-     * True if the NPN exists and is valid, false otherwise.
+     * True if the NPN exists in NIPR's agency records.
+     * False if the NPN does not exist.
      *
      * @generated from field: bool valid = 1;
      */
@@ -4539,14 +5080,18 @@ export type ValidateAgencyNPNResponse = Message<"producerflow.producer.v1.Valida
  */
 export declare const ValidateAgencyNPNResponseSchema: GenMessage<ValidateAgencyNPNResponse>;
 /**
- * LookupNPNByFEINRequest is used to look up a producer's National Producer Number by their Federal Employer Identification Number (FEIN).
+ * LookupNPNByFEINRequest is used to look up an agency's National Producer
+ * Number (NPN) by their Federal Employer Identification Number (FEIN).
+ * This is a FREE operation using the NIPR NPN Lookup service.
  *
  * @generated from message producerflow.producer.v1.LookupNPNByFEINRequest
  */
 export type LookupNPNByFEINRequest = Message<"producerflow.producer.v1.LookupNPNByFEINRequest"> & {
     /**
      * The Federal Employer Identification Number (FEIN) to look up.
-     * Required and must be exactly 9 characters.
+     * Format: Exactly 9 digits, no dashes or spaces.
+     * Example: "123456789"
+     * This is the tax identification number assigned by the IRS.
      *
      * @generated from field: string fein = 1;
      */
@@ -4558,13 +5103,17 @@ export type LookupNPNByFEINRequest = Message<"producerflow.producer.v1.LookupNPN
  */
 export declare const LookupNPNByFEINRequestSchema: GenMessage<LookupNPNByFEINRequest>;
 /**
- * LookupNPNByFEINResponse contains the National Producer Number (NPN) for the producer associated with the given FEIN.
+ * LookupNPNByFEINResponse contains the National Producer Number (NPN)
+ * for the agency associated with the given FEIN.
  *
  * @generated from message producerflow.producer.v1.LookupNPNByFEINResponse
  */
 export type LookupNPNByFEINResponse = Message<"producerflow.producer.v1.LookupNPNByFEINResponse"> & {
     /**
-     * The National Producer Number (NPN) for the producer.
+     * The National Producer Number (NPN) found in NIPR for the given FEIN.
+     * Format: 1-10 digit numeric string.
+     * Example: "1234567890"
+     * Empty string if no matching NPN was found.
      *
      * @generated from field: string npn = 1;
      */
@@ -4814,7 +5363,11 @@ export type AgencySummary = Message<"producerflow.producer.v1.AgencySummary"> &
      */
     phone: string;
     /**
-     * National Producer Number (NPN) assigned by NIPR.
+     * National Producer Number (NPN) of the agency.
+     * A unique NAIC identifier assigned to business entities during the
+     * licensing application process and stored in the NIPR Producer Database
+     * (PDB).
+     * Format: 1-10 digit numeric string.
      * Only present for standard agencies (not sole proprietors).
      * Empty string if the agency doesn't have an NPN.
      *
@@ -4869,6 +5422,21 @@ export type AgencySummary = Message<"producerflow.producer.v1.AgencySummary"> &
      * @generated from field: string external_id = 11;
      */
     externalId: string;
+    /**
+     * The relationship of this agency with its organization.
+     *
+     * Indicates whether the agency is the main agency (primary owner) or a related
+     * agency within an organization. This field reflects the agency's actual
+     * organization membership, not the query context.
+     *
+     * Values:
+     * - MAIN: The primary agency that owns or manages the organization
+     * - RELATED: An agency that is part of the organization but not the primary owner
+     * - UNSPECIFIED: Agency does not belong to any organization
+     *
+     * @generated from field: optional producerflow.producer.v1.AgencyOrganizationRelationship organization_relationship = 12;
+     */
+    organizationRelationship?: AgencyOrganizationRelationship;
 };
 /**
  * Describes the message producerflow.producer.v1.AgencySummary.
@@ -4947,6 +5515,22 @@ export type ListAgenciesRequest = Message<"producerflow.producer.v1.ListAgencies
      * @generated from field: repeated producerflow.producer.v1.NIPRSyncState nipr_sync_statuses = 6;
      */
     niprSyncStatuses: NIPRSyncState[];
+    /**
+     * Optional. Filter by resident license state.
+     * Returns agencies whose resident license is in the selected state(s).
+     * Multiple states can be specified (OR logic within this filter).
+     *
+     * @generated from field: repeated string resident_states = 7;
+     */
+    residentStates: string[];
+    /**
+     * Optional. Filter by any active license state.
+     * Returns agencies that hold any active license (resident or non-resident) in the selected state(s).
+     * Multiple states can be specified (OR logic within this filter).
+     *
+     * @generated from field: repeated string licensed_states = 8;
+     */
+    licensedStates: string[];
 };
 /**
  * Describes the message producerflow.producer.v1.ListAgenciesRequest.
@@ -5845,6 +6429,41 @@ export declare enum AgencyType {
  * Describes the enum producerflow.producer.v1.AgencyType.
  */
 export declare const AgencyTypeSchema: GenEnum<AgencyType>;
+/**
+ * AgencyOrganizationRelationship defines the relationship an agency has with an organization.
+ *
+ * If an agency belongs to an organization, this field indicates the type of relationship.
+ * If an agency does not belong to any organization, this field will be UNSPECIFIED.
+ *
+ * @generated from enum producerflow.producer.v1.AgencyOrganizationRelationship
+ */
+export declare enum AgencyOrganizationRelationship {
+    /**
+     * Default unspecified value.
+     * Used when the agency does not belong to any organization.
+     *
+     * @generated from enum value: AGENCY_ORGANIZATION_RELATIONSHIP_UNSPECIFIED = 0;
+     */
+    UNSPECIFIED = 0,
+    /**
+     * The agency is the main/primary agency for the organization.
+     * The main agency typically owns or manages the organization.
+     *
+     * @generated from enum value: AGENCY_ORGANIZATION_RELATIONSHIP_MAIN = 1;
+     */
+    MAIN = 1,
+    /**
+     * The agency is a related agency in the organization's network.
+     * Related agencies are part of the organization but not the primary owner.
+     *
+     * @generated from enum value: AGENCY_ORGANIZATION_RELATIONSHIP_RELATED = 2;
+     */
+    RELATED = 2
+}
+/**
+ * Describes the enum producerflow.producer.v1.AgencyOrganizationRelationship.
+ */
+export declare const AgencyOrganizationRelationshipSchema: GenEnum<AgencyOrganizationRelationship>;
 /**
  * NIPRSyncState defines the synchronization state with the NIPR system.
  *
@@ -5880,7 +6499,19 @@ export declare enum NIPRSyncState {
      *
      * @generated from enum value: NIPR_SYNC_STATE_DISABLED = 4;
      */
-    NIPR_SYNC_STATE_DISABLED = 4
+    NIPR_SYNC_STATE_DISABLED = 4,
+    /**
+     * Synchronization is in progress.
+     *
+     * @generated from enum value: NIPR_SYNC_STATE_IN_PROGRESS = 5;
+     */
+    NIPR_SYNC_STATE_IN_PROGRESS = 5,
+    /**
+     * Synchronization is being stopped.
+     *
+     * @generated from enum value: NIPR_SYNC_STATE_STOPPING = 6;
+     */
+    NIPR_SYNC_STATE_STOPPING = 6
 }
 /**
  * Describes the enum producerflow.producer.v1.NIPRSyncState.
@@ -6410,36 +7041,55 @@ export declare const ProducerService: GenService<{
         output: typeof NewProducersResponseSchema;
     };
     /**
+     * Deprecated: Use GetAgency and GetAgencyProducers instead.
+     *
      * GetAgencyAndProducers retrieves complete information for an agency and all
-     * its producers.
-     *
-     * This endpoint returns comprehensive agency details including:
-     * - Agency contact information and business details
-     * - Principal producer information
-     * - Bank account for commission payments
-     * - Errors & Omissions insurance details
-     * - Business hours and contact points
-     * - NIPR synchronized data (licenses, appointments, regulatory actions, addresses)
-     * - All associated producers with their NIPR data
-     * - Agency locations
+     * its producers. This endpoint is deprecated because it returns too much data
+     * in a single call. Use GetAgency to retrieve agency details and
+     * GetAgencyProducers to retrieve the list of producers separately.
+     *
+     * Common Error Codes:
+     * - NOT_FOUND: Agency doesn't exist or doesn't belong to tenant
+     *
+     *
+     * @generated from rpc producerflow.producer.v1.ProducerService.GetAgencyAndProducers
+     * @deprecated
+     */
+    getAgencyAndProducers: {
+        methodKind: "unary";
+        input: typeof GetAgencyAndProducersRequestSchema;
+        output: typeof GetAgencyAndProducersResponseSchema;
+    };
+    /**
+     * GetAgencyProducers retrieves all producers associated with a specific agency.
+     *
+     * This is a lighter-weight alternative to GetAgencyAndProducers that returns
+     * only the producer data without the full agency details. Use this when you
+     * only need producer information.
+     *
+     * Each producer includes:
+     * - Basic information (name, email, phone, NPN)
+     * - NIPR data (licenses with LOAs, appointments, biographic data) if synced
+     * - Location assignments
+     * - Onboarding status (if enabled for the tenant)
      *
      * Validation Rules:
      * Proto validation (format checks):
      * - agency_id: Required, must be a valid UUID format
      *
      * Returns:
-     * Agency object with complete NIPR data and list of all associated producers.
+     * List of all producers associated with the specified agency.
      *
      * Common Error Codes:
      * - NOT_FOUND: Agency doesn't exist or doesn't belong to tenant
      *
      *
-     * @generated from rpc producerflow.producer.v1.ProducerService.GetAgencyAndProducers
+     * @generated from rpc producerflow.producer.v1.ProducerService.GetAgencyProducers
      */
-    getAgencyAndProducers: {
+    getAgencyProducers: {
         methodKind: "unary";
-        input: typeof GetAgencyAndProducersRequestSchema;
-        output: typeof GetAgencyAndProducersResponseSchema;
+        input: typeof GetAgencyProducersRequestSchema;
+        output: typeof GetAgencyProducersResponseSchema;
     };
     /**
      * GetAgency retrieves detailed information about a specific agency.
@@ -6478,10 +7128,11 @@ export declare const ProducerService: GenService<{
     /**
      * GetProducer retrieves detailed information about a specific producer.
      *
-     * Supports three lookup methods:
+     * Supports four lookup methods:
      * - By producer ID (UUID)
      * - By NPN (National Producer Number)
      * - By email address
+     * - By external ID (tenant-defined identifier set via SetExternalID)
      *
      * The response includes:
      * - Producer contact information (name, email, phone, address)
@@ -6499,6 +7150,7 @@ export declare const ProducerService: GenService<{
      * - producer_id_lookup.producer_id: Must be a valid UUID format
      * - npn_lookup.producer_npn: Must be non-empty string
      * - email_lookup.email: Must be a valid email format
+     * - external_id_lookup.external_id: Must be a non-empty string, max 255 characters
      *
      * Returns:
      * Complete producer information including all NIPR data.
@@ -6506,8 +7158,6 @@ export declare const ProducerService: GenService<{
      * Common Error Codes:
      * - NOT_FOUND: Producer doesn't exist or doesn't belong to tenant, or
      *   associated agency not found
-     * - UNIMPLEMENTED: Lookup method not supported (only producer_id, npn, and email
-     *   lookups are implemented)
      *
      *
      * @generated from rpc producerflow.producer.v1.ProducerService.GetProducer
@@ -7078,6 +7728,12 @@ export declare const ProducerService: GenService<{
      * - Biographic information (name, DOB, state of domicile)
      * - Address by state
      *
+     * Billing:
+     * This operation makes external NIPR API calls that may result in charges:
+     * - NPN validation lookup
+     * - Producer license data sync (if producer is not already synced)
+     * - PDB alerts subscription (if enabled for tenant)
+     *
      * Preconditions:
      * - Producer must exist and belong to the authenticated tenant
      * - Producer must have a valid NPN registered in NIPR
@@ -7100,10 +7756,13 @@ export declare const ProducerService: GenService<{
      * Empty response on success.
      *
      * Common Error Codes:
-     * - NOT_FOUND: Producer doesn't exist or doesn't belong to tenant
-     * - INVALID_ARGUMENT: Producer has no NPN or NPN is not registered in NIPR
+     * - NOT_FOUND: Producer doesn't exist, doesn't belong to tenant, or NPN could
+     *   not be found in NIPR. If the NPN cannot be found, the error message will
+     *   be "producer NPN could not be found in NIPR".
+     * - INVALID_ARGUMENT: Producer has no NPN.
      * - FAILED_PRECONDITION: Producer is already synced with NIPR (ACTIVE sync state)
      * - DEADLINE_EXCEEDED: NIPR sync took longer than 30 seconds
+     * - INTERNAL: Unexpected error during NIPR lookup or sync process
      *
      *
      * @generated from rpc producerflow.producer.v1.ProducerService.SyncProducerWithNIPR
@@ -7127,6 +7786,13 @@ export declare const ProducerService: GenService<{
      * - Regulatory actions and disciplinary history
      * - Address history by state
      *
+     * Billing:
+     * This operation makes external NIPR API calls that may result in charges:
+     * - NPN validation lookup
+     * - Agency license data sync (if agency is not already synced)
+     * - PDB alerts subscription (if enabled for tenant)
+     * - When sync_all_producers is true: additional calls per producer (license sync + PDB alerts)
+     *
      * Bulk Producer Sync:
      * When sync_all_producers is set to true, the system will also sync all
      * producers associated with the agency. This extends the timeout to 10
@@ -7354,8 +8020,9 @@ export declare const ProducerService: GenService<{
      * This ordering guarantee allows you to map request entries to their created IDs.
      *
      * Common Error Codes:
-     * - INVALID_ARGUMENT: Missing agency_id, no locations provided, duplicate
-     *   location names, or location with name already exists in agency
+     * - INVALID_ARGUMENT: Missing agency_id, no locations provided, or duplicate
+     *   location names within the request
+     * - ALREADY_EXISTS: A location with the same name already exists in the agency
      * - NOT_FOUND: Agency doesn't exist or doesn't belong to tenant
      *
      *