Skip to content

API Reference

Jump to bottom
github-actions[bot] edited this page Aug 18, 2026 · 112 revisions

Producerflow API Documentation

Welcome to the Producerflow Public API reference.

This page is automatically generated from the Protocol Buffers definitions that power the API, ensuring that the information you see here is always up-to-date and consistent with the actual service implementation.

The Producerflow API provides programmatic access to the core onboarding, licensing, appointment, and compliance capabilities of the Producerflow platform. It allows carriers, MGAs, agencies, and technology partners to automate:

  • Producer onboarding and data ingestion
  • Agency creation and updates
  • License synchronization and real-time compliance checks
  • Appointment submission, tracking, and termination
  • Management of locations, bank accounts, E&O data, and other agency-level information

This document serves as the definitive schema reference for:

  • All API services and their RPC methods
  • Request and response message structures
  • Shared types reused across the API
  • Enumerations and field-level definitions (including deprecations)

The goal of this reference is to help developers understand the exact shape of the API and how to interact with it at the type level. It does not cover integration patterns, end-to-end flows, webhooks, or domain explanations.

For those topics, including onboarding guides, webhook behavior, examples, and architecture, please visit the main pages of the Producerflow Wiki.

Table of Contents

ProducerService

ProducerService provides a comprehensive API for managing insurance producers and agencies. This service simplifies producer and agency onboarding, data synchronization, and integration with the National Insurance Producer Registry (NIPR).

Key capabilities:

  • Producer and agency onboarding with self-service URLs
  • Automatic synchronization of license, appointment, and regulatory data from NIPR
  • NPN (National Producer Number) validation and lookup
  • Multi-location management for agencies
  • Integration with NIPR PDB Gateway, PDB Alerts, and NPN Lookup services

NIPR Integration: This service automatically fetches and maintains up-to-date licensing information, carrier appointments, and regulatory actions from NIPR. Most NIPR sync operations are billable and count against your monthly unique NPN quota. Enable PDB Alerts synchronization to receive automatic daily updates and reduce manual sync costs.

Authentication: All endpoints require API key authentication provided via the Authorization header.

Onboarding Operations Generate self-service URLs and create agencies/producers with NIPR validation.

CreateAgencyOnboardingURL

CreateAgencyOnboardingURL generates a secure, pre-filled URL for agency self-onboarding.

Use this endpoint to create personalized onboarding links that can be shared with agencies. The URL encodes agency defaults, tenant context, and optional pre-filled information to streamline the onboarding experience.

All fields in the request are optional. Provide as much or as little information as available - any missing data will be collected through the onboarding flow.

Typical Workflow:

  1. Generate onboarding URL with optional pre-filled data (agency name, NPN, principal info)
  2. Share URL with agency contact via email or portal
  3. Agency completes onboarding form through the URL
  4. System validates NPN with NIPR and creates agency record
  5. Optionally sync with NIPR to fetch licenses and appointments

Validation Rules: All fields in the request are optional. The system generates valid URLs even with an empty request. When fields are provided:

  • entity_type: Must be ENTITY_TYPE_SOLE_PROPRIETOR (1), ENTITY_TYPE_AGENCY (2), or ENTITY_TYPE_ASK_DURING_ONBOARDING (3). This is the only endpoint where ENTITY_TYPE_ASK_DURING_ONBOARDING is valid.
  • email: Must be a valid email format if provided
  • npn: Must be a valid NPN format (2-10 digits) if provided. Note that NPN validation against NIPR occurs during onboarding, not during URL generation.
  • fein: Must be exactly 9 digits if provided
  • organization_id: Must be a valid organization ID belonging to your tenant if provided
  • principal.email: Must be a valid email format if provided
  • principal.npn: Must be a valid NPN format (2-10 digits) if provided
  • principal.tenant_id: Maximum 255 characters if provided

Returns: A time-limited URL string that can be shared with the agency for self-service onboarding.

Request: CreateAgencyOnboardingURLRequest

CreateAgencyOnboardingURLRequest contains information needed to generate an agency onboarding URL. This includes basic agency information and defaults.

All fields in this request are optional. You can provide as much or as little information as you have available. Any missing information will be collected from the user during the onboarding process through the generated URL.

Field Type Label Description
agency CreateAgencyOnboardingURLRequest.Agency

Response: CreateAgencyOnboardingURLResponse

CreateAgencyOnboardingURLResponse contains the generated URL for agency onboarding

Field Type Label Description
url string URL that can be shared with the agency for self-onboarding

CreateProducerOnboardingURL

CreateProducerOnboardingURL generates a secure, pre-filled URL for producer self-onboarding.

Use this endpoint to create personalized onboarding links for individual producers joining an existing agency. The URL can include optional pre-filled data like NPN, name, email, and address to reduce manual data entry.

The producer must be associated with an existing agency. Use CreateAgencyOnboardingURL if you need to onboard an agency and its principal together.

Typical Workflow:

  1. Generate producer onboarding URL with agency_id and optional pre-filled data
  2. Share URL with producer via email
  3. Producer completes onboarding form through the URL
  4. System validates NPN with NIPR and associates producer with agency
  5. Optionally sync with NIPR to fetch producer licenses and appointments

Validation Rules:

  • agency_id: Required. must be a valid UUID of an agency belonging to your tenant.
  • producer_data: All fields are optional. When provided:
    • npn: Must be a valid NPN format (1-10 characters). Note that NPN validation against NIPR occurs during onboarding, not during URL generation.
    • email: Must be a valid email format if provided
    • mailing_address.state: Must be exactly 2 characters (state code) if provided
    • mailing_address.zip: Must be 1-10 characters if provided

Returns: A time-limited URL string that can be shared with the producer for self-service onboarding.

Common Error Codes:

  • NOT_FOUND: Agency doesn't exist or doesn't belong to tenant
  • INVALID_ARGUMENT: Invalid NPN provided (not found in NIPR)

Request: CreateProducerOnboardingURLRequest

Field Type Label Description
agency_id string Agency ID for which the producer will be onboarded
producer_data ProducerData Optional producer data to pre-fill in the onboarding form

Response: CreateProducerOnboardingURLResponse

Field Type Label Description
onboarding_url string The secure onboarding URL that can be shared with the producer

NewAgency

NewAgency creates a new agency with principal and optional additional producers.

This is the programmatic alternative to CreateAgencyOnboardingURL - use this when you want to create agencies directly via API instead of through a self-service form.

Entity Type Rules:

  • ENTITY_TYPE_SOLE_PROPRIETOR: Individual producer operating as their own agency. Cannot have an agency NPN. Only the principal is created.
  • ENTITY_TYPE_AGENCY: Standard insurance agency with multiple producers. Must provide either an NPN or FEIN. Can have multiple producers beyond the principal.

NIPR Validation and Sync: The system performs free NIPR API lookups to validate NPNs before creation. If sync_with_nipr is true (or tenant default), the system performs paid NIPR EntityInfo lookups to fetch complete license, appointment, and regulatory data.

Validation Performed:

  • Required fields are present and valid
  • Email addresses are unique within tenant
  • Agency NPN exists in NIPR (if provided)
  • Principal NPN exists in NIPR
  • Entity type rules are followed
  • Principal and subsequent producers last names must match NIPR records for the given NPN

Validation Rules: Proto validation (format checks):

  • agency: Required field containing all agency information
  • agency.name: Required, must be non-empty
  • agency.email: Required, must be a valid email format
  • agency.phone: Optional, if provided must match E.164 pattern (e.g., +15551234567)
  • agency.entity_type: Required, must be ENTITY_TYPE_SOLE_PROPRIETOR (1) or ENTITY_TYPE_AGENCY (2). ENTITY_TYPE_ASK_DURING_ONBOARDING is NOT valid here.
  • agency.fein: Optional, if provided must be exactly 9 digits. Required for ENTITY_TYPE_AGENCY if NPN is not provided.
  • agency.principal: Required, contains principal producer information
    • principal.first_name: Required, must be non-empty
    • principal.last_name: Required, must be non-empty
    • principal.email: Required, must be a valid email format
    • principal.npn: Required, must be 1-10 characters
    • principal.phone: Optional, if provided must match E.164 pattern
    • principal.tenant_id: Optional, maximum 255 characters
  • agency.bank_account (optional, if provided all subfields are required):
    • account_number: 8-17 characters
    • routing_number: Exactly 9 characters
    • account_type: Required, must be CHECKING (1) or SAVINGS (2)
    • account_holder_name: Required, must be non-empty
  • agency.eo_info (optional, if provided):
    • carrier: Required, must be non-empty
    • expiration_date: Required, must be in the future
    • coverage_amount: Required, must be non-empty
    • effective_date: Required
    • per_occurrence: Required, must be non-empty
  • agency.business_hours (optional, if provided):
    • timezone: Required, must be non-empty
    • business_hours: Required, at least one entry
      • week_days: Required, 1-7 days
      • opening_time: Required
      • closing_time: Required
  • agency.producers: Optional list of additional producers (see NewProducer validation)
  • agency.points_of_contact (optional, for each contact):
    • email: Required, must be a valid email format
    • role: Required
  • agency.root_organization_id: Optional, if provided must be 1-36 characters
  • agency.locations: Optional, maximum 100 locations

Business logic validation:

  • agency.email: Must be unique within the tenant
  • agency.npn: If provided, must exist in NIPR (validated via free NIPR lookup)
  • principal.email: Must be unique within the tenant
  • principal.npn: Must exist in NIPR (validated via free NIPR lookup)
  • All producer emails must be unique within the tenant

Returns: IDs of the created agency, principal, optional producers, and locations (if provided).

Common Error Codes:

  • INVALID_ARGUMENT: Missing required fields, entity type rule violations, or NPN not found in NIPR
  • ALREADY_EXISTS: Email or NPN already registered in your tenant. The error includes an AgencyAlreadyExistsErrorDetail with the identifiers of the existing agency (for principal email conflicts, the agency of the existing producer), so you can link the existing record on your side without a follow-up lookup. See AgencyAlreadyExistsErrorDetail for details on each conflict and how to decode it.

Request: NewAgencyRequest

NewAgencyRequest contains complete information for creating a new agency

Field Type Label Description
agency NewAgencyRequest.Agency
sync_with_nipr bool optional Optional. Overrides the tenant's default NIPR sync setting during onboarding. Most tenants have this enabled by default, so it usually doesn't need to be set. If specified, this value takes precedence over the tenant's default behavior.

Response: NewAgencyResponse

NewAgencyResponse contains the IDs of created resources after a successful agency creation

Field Type Label Description
agency_id string Unique identifier for the created agency
producer_ids string repeated List of unique identifiers for any producers created with the agency
principal_id string Unique identifier for the principal producer
location_ids string repeated IDs of the locations created for the agency (if any were provided in the request)

ListAgencies

ListAgencies retrieves a paginated list of agencies associated with the tenant.

This endpoint provides comprehensive agency listing with powerful filtering capabilities to efficiently manage and search through large numbers of agencies. Each agency in the response includes summary information for quick overview without the full NIPR data.

Filtering Capabilities:

  • Organization: Filter agencies belonging to a specific organization
  • Search: Free-text search across agency name, NPN, and email
  • Agency Type: Filter by internal (tenant) vs external agencies
  • Entity Type: Filter by sole proprietor vs standard agency
  • NIPR Sync Status: Filter by synchronization state (active, failing, pending, disabled)

The response uses cursor-based pagination for efficient data retrieval:

  • Default page size is 50 if not specified
  • Maximum page size is 200
  • Results are ordered by creation date, most recent first
  • Use the next_page_token to retrieve subsequent pages

Validation Rules: All fields are optional filters:

  • organization_id: If provided, must be a valid UUID format
  • search_query: Optional free-text search string (case-insensitive, partial matching)
  • pagination.page_size: Must be <= 200. Default is 50 if not specified.
  • pagination.page_token: Opaque token from previous response for pagination
  • agency_type: If provided, must be AGENCY_TYPE_INTERNAL (1) or AGENCY_TYPE_EXTERNAL (2)
  • entity_type: If provided, must be ENTITY_TYPE_SOLE_PROPRIETOR (1) or ENTITY_TYPE_AGENCY (2)
  • nipr_sync_statuses: Array of sync states to filter by (ACTIVE, FAILING, PENDING, DISABLED)

Returns: A paginated list of AgencySummary objects containing essential agency information without full NIPR data. Use GetAgencyAndProducers for complete agency details including NIPR data.

Request: ListAgenciesRequest

ListAgenciesRequest enables flexible querying of agencies with multiple filter options and pagination support.

All filters are optional and can be combined for precise results. When multiple filters are specified, they are applied with AND logic (agencies must match all specified criteria).

Example Use Cases:

  • Get all agencies in an organization: set organization_id
  • Search for an agency by name: set search_query
  • Find failing NIPR syncs: set nipr_sync_statuses to [NIPR_SYNC_STATE_FAILING]
  • Get sole proprietors only: set entity_type to ENTITY_TYPE_SOLE_PROPRIETOR
  • Paginate through all agencies: use pagination with page_token
Field Type Label Description
organization_id string optional Optional. Filter agencies by organization ID. Only agencies belonging to this specific organization will be returned. Must be a valid UUID if provided. Use ListOrganizations to get valid organization IDs.
search_query string optional Optional. Free-text search across agency fields. Searches in: agency name, NPN, and email address. The search is case-insensitive and uses partial matching. Example: "smith" will match "Smith Insurance Agency" and "john.smith@agency.com"
pagination Pagination Optional. Pagination parameters for controlling result set size and navigation. If not provided, defaults to page_size=50 with no offset. Maximum allowed page_size is 200; values above this will be capped.
agency_type AgencyType optional Optional. Filter by agency classification (internal vs external). - AGENCY_TYPE_INTERNAL: Agencies owned/operated by the tenant - AGENCY_TYPE_EXTERNAL: Partner or third-party agencies If not specified, returns both internal and external agencies.
entity_type EntityType optional Optional. Filter by business entity structure. - ENTITY_TYPE_SOLE_PROPRIETOR: Individual producers as agencies - ENTITY_TYPE_AGENCY: Standard multi-producer agencies If not specified, returns both sole proprietors and standard agencies.
nipr_sync_statuses NIPRSyncState repeated Optional. Filter by NIPR synchronization status. Multiple statuses can be specified to match agencies in any of those states. Useful for monitoring sync health and identifying agencies needing attention. Valid values: ACTIVE, FAILING, PENDING, DISABLED If empty, returns agencies in all sync states.
resident_states string repeated 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).
licensed_states string repeated 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).

Response: ListAgenciesResponse

ListAgenciesResponse provides paginated agency results with metadata for navigation and total counts.

The response is optimized for UI display with summary data only. For complete agency information including NIPR data, use GetAgencyAndProducers with the agency_id from the summary.

Pagination Notes:

  • Results are always ordered by creation date (newest first)
  • Page tokens are opaque and should not be constructed by clients
  • Total count reflects all matching agencies, not just the current page
  • Empty agencies list with total_count > 0 indicates you've paginated past the end
Field Type Label Description
agencies AgencySummary repeated List of agency summaries matching the filter criteria. Ordered by creation date with the most recently created agencies first. Will be empty if no agencies match the filters or if paginating past the last page. Maximum of page_size agencies per response (default 50, max 200).
next_page_token string Pagination token for retrieving the next page of results. Pass this value as page_token in the next request to continue pagination. Empty string indicates this is the last page of results. Tokens are opaque and their format may change; treat as black box.
total_count int32 Total number of agencies matching the filter criteria across all pages. This count is independent of pagination and represents the full result set. Useful for displaying "Showing X-Y of Z agencies" in UIs. Will be 0 if no agencies match the specified filters.

ListOrganizations

ListOrganizations retrieves all organizations accessible to your tenant.

Organizations represent logical groupings or hierarchical structures for managing agencies. They enable better organization of agencies into business units, networks, or aggregator relationships. Each organization can contain multiple agencies, allowing for hierarchical management and reporting across your insurance distribution network.

Not all tenants use organizations - this list may be empty if your tenant doesn't have organizational hierarchies enabled.

Validation Rules: Proto validation (format checks): All fields are optional:

  • pagination.page_size: Must be <= 200. Default is 50 if not specified.
  • pagination.page_token: Opaque token from previous response for pagination

Returns: A list of all organizations accessible to your tenant, including their IDs, names and external identifiers. Organizations are returned in alphabetical order by name for consistent presentation.

Request: ListOrganizationsRequest

ListOrganizationsRequest requests a list of all organizations associated with the authenticated tenant.

Organizations provide a way to group agencies into logical business units, networks, or aggregator relationships. This endpoint returns all organizations accessible to your tenant, which can be used to:

  • Display organization hierarchies in user interfaces
  • Filter agencies by organization
  • Apply organization-specific business rules or workflows

The response supports pagination for tenants with large numbers of organizations.

Field Type Label Description
pagination Pagination Optional pagination parameters to control the result set. Pagination allows you to retrieve organizations in manageable chunks: - page_size: Number of organizations to return (default: 50, max: 200) - page_token: Token from previous response to get the next page Example usage: - First request: page_size=100 (returns first 100 organizations) - Subsequent requests: Use next_page_token from previous response If omitted, returns the first 50 organizations.

Response: ListOrganizationsResponse

ListOrganizationsResponse contains the paginated list of organizations for the tenant.

The response includes all organizations accessible to your authenticated tenant, ordered alphabetically by name for consistent display. Empty results indicate that your tenant either doesn't use organizational hierarchies or has no organizations configured yet.

Pagination is automatically applied to large result sets to ensure optimal performance and reasonable response sizes.

Field Type Label Description
organizations Organization repeated List of organizations associated with the tenant. Each organization in the list includes: - Unique identifier (id) for API operations - Display name for user interfaces - External ID for system integration - Contact email (if configured) The list may be empty ([]) if: - No organizations are configured for your tenant - Your tenant doesn't use organizational hierarchies
next_page_token string Pagination token for retrieving the next page of results. When present, indicates more organizations are available. Pass this token as the page_token in the next ListOrganizationsRequest to retrieve the subsequent page. Empty string or omitted field indicates this is the last page. Important: Tokens are opaque and may expire. Don't store tokens long-term; retrieve fresh data when needed.
total_count int32 Total count of organizations matching the filter criteria. This count represents the total number of organizations available to your tenant, regardless of pagination. Use this to: - Display result counts in user interfaces ("Showing 1-50 of 237") - Calculate the number of pages available - Determine if pagination is needed The count remains consistent across paginated requests unless organizations are added or removed between calls.

GetOrganization

GetOrganization retrieves comprehensive details about a specific organization.

This endpoint returns complete organization information including all agencies assigned to it. For each agency, it provides summary data including appointment overview statistics and NIPR synchronization status. This allows you to understand the full scope of an organization's agency network in a single API call.

Validation Rules: Proto validation (format checks):

  • organization_id: Required, must be a valid UUID format

Returns: Complete organization details including all assigned agencies with their appointment overviews and sync statuses.

Common Error Codes:

  • NOT_FOUND: Organization doesn't exist or doesn't belong to tenant

Request: GetOrganizationRequest

GetOrganizationRequest specifies which organization to retrieve detailed information for.

Use this request to fetch comprehensive details about a specific organization, including all agencies assigned to it and their current status.

Field Type Label Description
organization_id string Unique identifier of the organization to retrieve. This must be a valid UUID that was previously returned from: - ListOrganizations response - Agency creation response (when agency is assigned to an organization) - Other API calls that reference organizations The organization must belong to your authenticated tenant; attempting to access organizations from other tenants will result in a NOT_FOUND error. Format: Standard UUID v4 (e.g., "123e4567-e89b-12d3-a456-426614174000")

Response: GetOrganizationResponse

GetOrganizationResponse contains details about the requested organization.

Field Type Label Description
organization Organization The requested organization with all available details.

CreateOrganization

CreateOrganization creates a new organization for the authenticated tenant.

Organizations are top-level groupings used to organize agencies within your tenant. They can represent business units, regions, or any logical grouping that makes sense for your operations.

Validation Rules: Proto validation (format checks):

  • name: Required, must be non-empty
  • external_id: Optional, your system's identifier for the organization
  • email: Optional, contact email for the organization

Business logic validation:

  • name: Must be unique within the tenant (case-insensitive)

Returns: The UUID of the newly created organization, which can be used to assign agencies to this organization.

Common Error Codes:

  • ALREADY_EXISTS: Organization with the same name already exists in tenant

Request: CreateOrganizationRequest

CreateOrganizationRequest contains the information needed to create a new organization.

Field Type Label Description
name string Required. The display name of the organization. Must be unique within the tenant.
external_id string Optional. The external identifier for the organization. This is the identifier used by the tenant's system to identify the organization.
email string Optional. The contact email address for the organization.

Response: CreateOrganizationResponse

CreateOrganizationResponse contains the result of creating a new organization.

Field Type Label Description
organization_id string The unique identifier of the newly created organization.

NewProducer

NewProducer adds a single producer to an existing agency.

Use this endpoint to programmatically add producers to agencies. This is the programmatic alternative to CreateProducerOnboardingURL.

NIPR Validation and Sync: The system validates the provided NPN exists in NIPR using a free API lookup. If sync_with_nipr is enabled, the system performs a paid NIPR EntityInfo lookup to fetch complete license, appointment, and regulatory data.

Validation Performed:

  • Email is unique within tenant
  • Agency exists and belongs to tenant
  • NPN exists in NIPR
  • Location IDs exist and belong to the agency (if provided)

Validation Rules: Proto validation (format checks):

  • agency_id: Required, must be a valid UUID format
  • producer: Required, contains producer information
    • first_name: Required, must be non-empty
    • last_name: Required, must be non-empty
    • email: Required, must be a valid email format
    • npn: Required, used for NIPR validation
    • phone: Optional, if provided must match E.164 pattern (e.g., +15551234567)
    • mailing_address (optional, if provided):
      • street: Required, must be non-empty
      • city: Required, must be non-empty
      • state: Required, must be exactly 2 characters (state code)
      • zip: Required, must be 1-10 characters
    • tenant_id: Optional, maximum 255 characters (external identifier)
    • location_ids: Optional, maximum 100 items, each must be a valid UUID
  • sync_with_nipr: Optional, overrides tenant default NIPR sync setting

Business logic validation:

  • agency_id: Agency must exist and belong to the authenticated tenant
  • email: Must be unique within the tenant (not already used by another producer or contact)
  • npn: Must exist in NIPR and the provided last name must match the NIPR records
  • npn: Must be unique within the tenant (not already assigned to another producer)
  • location_ids: All locations must exist and belong to the specified agency

Returns: The UUID of the created producer.

Common Error Codes:

  • NOT_FOUND: Agency doesn't exist or producer NPN not found in NIPR
  • ALREADY_EXISTS: Producer with email or NPN already exists in tenant
  • INVALID_ARGUMENT: Producer NPN is required (when NPN validation is enabled)
  • FAILED_PRECONDITION: Producer name does not match NIPR records for the provided NPN

Request: NewProducerRequest

NewProducerRequest is used to create a new producer and associate it with an agency. This will trigger a call to the NIPR API to retrieve license information of the producer.

Field Type Label Description
agency_id string The UUID of the agency to associate the producer with. Must be a valid UUID format.
producer NewProducer Information about the producer to create. This field is required.
sync_with_nipr bool optional Optional. Overrides the tenant's default NIPR sync setting during onboarding. Most tenants have this enabled by default, so it usually doesn't need to be set. If specified, this value takes precedence over the tenant's default behavior.

Response: NewProducerResponse

NewProducerResponse contains the ID of the created producer.

Field Type Label Description
producer_id string The UUID of the created producer. Must be a valid UUID format.

NewProducers

NewProducers creates multiple producers in bulk and associates them with a single agency.

This endpoint provides an efficient way to onboard multiple producers to the same agency in a single API call.

Bulk Operation Behavior: Producers are created sequentially. If a producer fails validation, the request returns an error, but any producers created before the failure will remain in the system. Each producer in the request undergoes the same validation as individual NewProducer calls.

NIPR Validation and Sync: For each producer:

  • The system performs a free NIPR API lookup to validate the NPN exists
  • If sync_with_nipr is true (or tenant default), performs paid NIPR EntityInfo lookups
  • All NIPR validations must succeed for the bulk operation to proceed

Validation Performed (for each producer):

  • Required fields are present and valid (name, email, NPN)
  • Email addresses are unique within the tenant
  • Agency exists and belongs to the authenticated tenant
  • NPNs exist in NIPR
  • Location IDs exist and belong to the agency (if provided)
  • Phone numbers match valid patterns (if provided)

Validation Rules: Proto validation (format checks):

  • agency_id: Required, must be a valid UUID format
  • producers: Required, must contain at least 1 producer. Each producer:
    • first_name: Required, must be non-empty
    • last_name: Required, must be non-empty
    • email: Required, must be a valid email format
    • npn: Required, used for NIPR validation
    • phone: Optional, if provided must match E.164 pattern (e.g., +15551234567)
    • mailing_address (optional, if provided):
      • street: Required, must be non-empty
      • city: Required, must be non-empty
      • state: Required, must be exactly 2 characters (state code)
      • zip: Required, must be 1-10 characters
    • tenant_id: Optional, maximum 255 characters (external identifier)
    • location_ids: Optional, maximum 100 items per producer, each must be a valid UUID
  • sync_with_nipr: Optional, overrides tenant default NIPR sync setting for all producers

Business logic validation:

  • agency_id: Agency must exist and belong to the authenticated tenant
  • All producer emails must be unique within the tenant
  • All producer NPNs must exist in NIPR, match the provided last name, and be unique within the tenant
  • All location_ids must exist and belong to the specified agency
  • This is an all-or-nothing operation: if any producer fails validation, no producers are created

Returns: List of UUIDs for all created producers in the same order as the request. This ordering guarantee allows you to map request entries to their created IDs.

Common Error Codes:

  • NOT_FOUND: Agency doesn't exist or producer NPN not found in NIPR
  • ALREADY_EXISTS: Producer with email or NPN already exists in tenant
  • INVALID_ARGUMENT: Producer NPN is required (when NPN validation is enabled)
  • FAILED_PRECONDITION: Producer name does not match NIPR records for the provided NPN
  • PERMISSION_DENIED: Agency doesn't belong to the authenticated tenant

Request: NewProducersRequest

NewProducersRequest creates multiple producers and associates them with a single agency.

This request supports bulk creation of producers, which is more efficient than making multiple individual NewProducer calls. All producers in the request will be associated with the same agency, making this ideal for onboarding producer teams.

Operation Behavior: Producers are created sequentially. If a producer fails validation, the request returns an error, but any producers created before the failure will remain in the system.

Request Limits:

  • Minimum producers: 1 (enforced by validation)
  • All producers must be for the same agency

Each producer in the list can specify:

  • Basic information (name, email, phone)
  • NPN for NIPR validation and sync
  • Mailing address
  • Location assignments within the agency
  • External ID for tenant system integration
  • Custom metadata questions

Common Use Cases:

  • Bulk importing producers from spreadsheets or CSV files
  • Migrating producer data from legacy systems
  • Setting up new agencies with their initial producer roster
  • Adding multiple producers during mergers or acquisitions
Field Type Label Description
agency_id string The UUID of the agency to associate all producers with. This agency must exist and belong to the authenticated tenant. All producers in the request will be assigned to this single agency.
producers NewProducer repeated List of producers to create in this bulk operation. Required field that must contain at least one producer. Each producer undergoes full validation including NPN verification if provided.
sync_with_nipr bool optional Optional. Overrides the tenant's default NIPR sync setting for all producers in this request. NPN validation is always performed regardless of this setting. When true: Fetches full NIPR EntityInfo data after validation (paid lookup) When false: Skips NIPR EntityInfo fetch, only performs NPN validation When omitted: Uses the tenant's default configuration Cost Implications: Setting this to true will trigger billable NIPR EntityInfo lookups for each producer with an NPN, counting against your monthly quota. Consider using false for test data or when you plan to sync later via SyncProducerWithNIPR.

Response: NewProducersResponse

NewProducersResponse contains the IDs of all successfully created producers.

The response provides a list of producer IDs that directly corresponds to the order of producers in the request, allowing you to map each request entry to its created resource.

Order Guarantee: The producer_ids array maintains the exact same order as the producers array in the request. For example:

  • Request producers[0] → Response producer_ids[0]
  • Request producers[1] → Response producer_ids[1] This ordering guarantee simplifies client-side processing and record keeping.

Post-Creation Actions: After receiving this response, you can:

  • Use the IDs to fetch full producer details via GetProducer
  • Assign producers to locations via AssignProducerToLocations
  • Trigger NIPR sync if it was skipped during creation
  • Set external IDs via SetExternalID if not provided during creation
Field Type Label Description
producer_ids string repeated List of UUIDs for the newly created producers. These IDs are immediately available for use in subsequent API calls. The array length will always match the number of producers in the request. Order is guaranteed to match the request's producer array order.

GetAgencyAndProducers

Deprecated: Use GetAgency and GetAgencyProducers instead.

GetAgencyAndProducers retrieves complete information for an agency and all 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

Request: GetAgencyAndProducersRequest

Deprecated: Use GetAgencyRequest/GetAgencyProducersRequest instead.

Field Type Label Description
agency_id string

Response: GetAgencyAndProducersResponse

Deprecated: Use GetAgencyResponse/GetAgencyProducersResponse instead.

Field Type Label Description
agency Agency
producers Producer repeated

GetAgencyProducers

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: List of all producers associated with the specified agency.

Common Error Codes:

  • NOT_FOUND: Agency doesn't exist or doesn't belong to tenant

Request: GetAgencyProducersRequest

GetAgencyProducersRequest requests all producers associated with an agency.

Field Type Label Description
agency_id string The UUID of the agency to retrieve producers for. Must be a valid UUID format.
pagination Pagination Optional. Pagination parameters for controlling result set size and navigation. If not provided, defaults to page_size=50. Maximum page_size is 200.

Response: GetAgencyProducersResponse

GetAgencyProducersResponse contains producers associated with the specified agency.

Field Type Label Description
producers Producer repeated List of producers for the current page.
next_page_token string Token for retrieving the next page of results. Empty when there are no more results.

GetAgency

GetAgency retrieves detailed information about a specific agency.

Supports two lookup methods:

  • By agency ID (UUID)
  • By tenant agency ID (external identifier)

This endpoint returns complete agency details including contact information, addresses, bank account, E&O coverage, principal information, NIPR data, and locations.

Use this when you need full agency information without the list of associated producers. For agencies with their producers, use GetAgencyAndProducers instead.

Validation Rules: Proto validation (format checks): Exactly one lookup method must be provided (oneof required):

  • agency_id_lookup.agency_id: Must be a valid UUID format
  • tenant_agency_id_lookup.tenant_agency_id: Must be non-empty string

Returns: Complete agency information including all NIPR data and locations.

Common Error Codes:

  • NOT_FOUND: Agency doesn't exist or doesn't belong to tenant
  • PERMISSION_DENIED: Tenant doesn't have access to the agency

Request: GetAgencyRequest

GetAgencyRequest requests information about a specific agency.

Field Type Label Description
agency_id_lookup GetAgencyRequest.AgencyIDLookup Look up agency by ID.
tenant_agency_id_lookup GetAgencyRequest.AgencyTenantAgencyIDLookup Look up agency by tenant agency ID.

Response: GetAgencyResponse

GetAgencyResponse contains the complete agency information.

Field Type Label Description
agency Agency Complete agency information including contact details, addresses, principal, bank account, E&O coverage, NIPR data, and locations.

GetProducer

GetProducer retrieves detailed information about a specific producer.

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)
  • Associated agency information
  • NIPR synchronized data:
    • State licenses with expiration dates and Lines of Authority (LOAs)
    • Biographic information (name, DOB, state of domicile)
    • Regulatory actions by state
    • Carrier appointments with status and renewal dates
  • Location assignments

Validation Rules: Proto validation (format checks): Exactly one lookup method must be provided (oneof required):

  • 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.

Common Error Codes:

  • NOT_FOUND: Producer doesn't exist or doesn't belong to tenant, or associated agency not found

Request: GetProducerRequest

GetProducerRequest allows retrieving producer information through one of four possible lookup methods: by ID, by NPN, by email address, or by external ID.

Field Type Label Description
producer_id_lookup GetProducerRequest.ProducerIDLookup Look up producer by ID.
npn_lookup GetProducerRequest.ProducerNPNLookup Look up producer by NPN.
email_lookup GetProducerRequest.EmailLookup Look up producer by email.
external_id_lookup GetProducerRequest.ExternalIDLookup Look up producer by external ID set via SetExternalID.

Response: GetProducerResponse

GetProducerResponse contains the producer information retrieved by the GetProducer RPC.

Field Type Label Description
producer Producer The complete producer information including personal details, agency association, and NIPR data.

ListProducerRoles

ListProducerRoles returns the producer role labels configured for the authenticated tenant.

These role labels are the valid values for the role field on NewProducer / UpdateProducer requests, and the values that may appear in the role field of a Producer response. The list is configured per-tenant and may be empty if the tenant has not enabled the producer-role feature — callers should treat an empty list as "no role should be sent".

Use this endpoint to populate role pickers, validate role inputs client-side, or discover whether the feature is enabled for the tenant.

Returns: The list of role labels available for the authenticated tenant, in the order they were configured. Empty when the tenant has not configured any roles.

Request: ListProducerRolesRequest

ListProducerRolesRequest is the empty request for the ListProducerRoles RPC. The tenant is determined from the authenticated API key.

This message has no fields.

Response: ListProducerRolesResponse

ListProducerRolesResponse contains the producer role labels configured for the authenticated tenant.

Field Type Label Description
roles string repeated The list of producer role labels available for the authenticated tenant, in the order they were configured. Empty when the tenant has not configured any roles.

GetAgencyFiles

GetAgencyFiles retrieves signed URLs for accessing agency documents.

Returns pre-signed URLs for the following document types:

  • Errors & Omissions (E&O) insurance certificate
  • Voided check for ACH commission payments
  • W9 tax form
  • License documents
  • Broker bond documents

The URLs are time-limited and grant temporary read access to the documents. Empty strings are returned for documents that haven't been uploaded.

Validation Rules: Proto validation (format checks):

  • agency_id: Required, must be a valid UUID format

Returns: A set of pre-signed URLs for accessing agency documents.

Common Error Codes:

  • NOT_FOUND: Agency doesn't exist or doesn't belong to tenant

Request: GetAgencyFilesRequest

GetAgencyFilesRequest requests URLs for files associated with an agency.

Field Type Label Description
agency_id string The UUID of the agency to retrieve files for. Must be a valid UUID format.

Response: GetAgencyFilesResponse

GetAgencyFilesResponse contains URLs for various documents associated with an agency.

Field Type Label Description
eo_doc_url string URL of the Errors & Omissions (E&O) insurance document.
voided_check_doc_url string URL of the bank voided check document. It's used to safely share bank account information for electronic transfers.
w9_doc_url string URL of the W9 form document. It's a U.S. internal revenue service form, an identification document used in the onboarding process for tax reporting purposes.
license_doc_url string URL of the license document. An identification document that shows that the agency is licensed to carry out its operations in the relevant jurisdictions.
broker_bond_doc_url string URL of the broker bond document. It's a surety bond that a broker needs to operate legally, providing financial security for clients.

UpdateProducer

UpdateProducer updates editable fields for an existing producer.

Only information collected during onboarding can be updated via this endpoint. NIPR-sourced data (licenses, appointments, regulatory actions) is read-only and can only be updated by triggering a NIPR sync via SyncProducerWithNIPR.

Updatable Fields:

  • Contact information (first_name, last_name, middle_name, email, phone)
  • Mailing address (street, city, state, zip)
  • External metadata (for tenant-specific data)

Note: NPN cannot be updated after creation. The NPN field is deprecated in UpdateProducerRequest.Producer and will be ignored.

Validation:

  • Email must be unique within tenant if changed
  • All field format validations apply (e.g., valid email format, phone pattern)

Validation Rules: Proto validation (format checks):

  • producer_id: Required, must be a valid UUID format
  • producer: Required, contains fields to update (all fields optional):
    • first_name: If provided, must be non-empty
    • last_name: If provided, must be non-empty
    • middle_name: If provided, must be non-empty
    • email: If provided, must be a valid email format
    • npn: Deprecated and ignored - NPN cannot be updated after creation
    • phone: If provided, must match E.164 pattern (e.g., +15551234567)
    • street: If provided, must be non-empty
    • city: If provided, must be non-empty
    • state: If provided, must be at most 2 characters
    • zip: If provided, must be at least 5 characters
    • external_metadata: Map of key-value pairs for tenant-specific data

Returns: Empty response on success.

Common Error Codes:

  • NOT_FOUND: Producer doesn't exist or doesn't belong to tenant
  • INVALID_ARGUMENT: Producer field is missing in request

Request: UpdateProducerRequest

UpdateProducerRequest contains the fields that can be updated in a producer record. Only information collected during the onboarding process can be updated. Information from NIPR and other third-party sources cannot be updated directly.

Field Type Label Description
producer_id string The ID of the producer to update. Must be a valid UUID format.
producer UpdateProducerRequest.Producer The producer information to update. The field is required.

Response: UpdateProducerResponse

UpdateProducerResponse is the empty response returned after successfully updating a producer.

This message has no fields.

UpdateAgency

UpdateAgency updates editable fields for an existing agency.

Only information collected during onboarding can be updated via this endpoint. NIPR-sourced data (licenses, appointments, regulatory actions) is read-only and can only be updated by triggering a NIPR sync via SyncAgencyWithNIPR.

Updatable Fields:

  • Contact details (email, phone, fax)
  • Website URL
  • Physical address components
  • Requested appointments (state codes)
  • Notes
  • External metadata (for tenant-specific data)
  • IVANS account
  • Organization membership (organization_id) and the relationship the agency has with it (organization_relationship)

All fields are optional - only provide the fields you want to update. Unchanged fields retain their current values.

Validation:

  • Email must be unique within tenant if changed
  • All field format validations apply

Validation Rules: Proto validation (format checks):

  • agency_id: Required, must be a valid UUID format
  • agency: Required, contains fields to update (all fields optional):
    • email: If provided, must be a valid email format
    • phone: If provided, must match E.164 pattern (e.g., +15551234567)
    • fax: If provided, must match E.164 pattern
    • website: If provided, must be a valid URI format
    • requested_appointments: Array of unique 2-letter state codes (e.g., ["CA", "NY"])
    • notes: If provided, maximum 500 characters
    • physical_address (optional, if provided):
      • street: If provided, must be non-empty
      • city: If provided, must be non-empty
      • state: If provided, must be exactly 2 characters
      • zip: If provided, must be 1-10 characters
    • external_metadata: Map of key-value pairs for tenant-specific data
    • organization_id: If provided, maximum 36 characters; an empty string detaches the agency from its organization
    • organization_relationship: If provided, must be MAIN or RELATED

Business logic validation:

  • agency_id: Agency must exist and belong to the authenticated tenant
  • email: If changed, must be unique within the tenant (case-insensitive comparison)
  • phone: If provided, must be a valid phone number format
  • organization_id: The organization must exist within the tenant. The agency must belong to at most one organization, otherwise the organization it is moved from is ambiguous
  • organization_relationship: Cannot be combined with an empty organization_id. Turning a main agency into a related one requires the agency to have a principal

Returns: Empty response on success.

Common Error Codes:

  • NOT_FOUND: Agency doesn't exist or doesn't belong to tenant, or the requested organization doesn't exist
  • ALREADY_EXISTS: Email already exists within tenant
  • INVALID_ARGUMENT: Invalid phone number format, all address fields required when creating new address, or organization_relationship combined with an empty organization_id
  • FAILED_PRECONDITION: The agency belongs to more than one organization, a relationship change was requested for an agency without an organization, or a main agency without a principal was turned into a related agency

Request: UpdateAgencyRequest

UpdateAgencyRequest contains the fields that can be updated in an agency record. Only information collected during the onboarding process can be updated. Information from NIPR and other third-party sources cannot be updated directly. All fields are optional, allowing partial updates.

Field Type Label Description
agency_id string The ID of the agency to update. Must be a valid UUID format.
agency UpdateAgencyRequest.Agency The agency information to update.

Response: UpdateAgencyResponse

UpdateAgencyResponse is the empty response returned after successfully updating an agency.

This message has no fields.

NewContact

NewContact creates a new contact associated with an agency.

Use this endpoint to programmatically add non-producer individuals to agencies. Contacts represent staff members, administrators, or other personnel who are not licensed insurance producers but need to be associated with the agency for communication or administrative purposes.

Validation Performed:

  • Agency exists and belongs to the authenticated tenant
  • Email is unique within the tenant (across both producers and contacts)
  • Required fields are present and valid (first name, last name, email, role)
  • Phone number matches valid pattern (if provided)

Validation Rules: Proto validation (format checks):

  • agency_id: Required, must be a valid UUID format
  • contact: Required, contains contact information:
    • first_name: Required, must be non-empty
    • last_name: Required, must be non-empty
    • email: Required, must be a valid email format
    • role: Required, must be non-empty
    • phone: Optional, if provided must match E.164 pattern (e.g., +15551234567)
    • middle_name: Optional
    • address (optional, if provided):
      • street: Required, must be non-empty
      • city: Required, must be non-empty
      • state: Required, must be exactly 2 characters (state code)
      • zip: Required, must be 1-10 characters
    • tenant_id: Optional, maximum 255 characters (external identifier)
    • npn: Optional

Business logic validation:

  • agency_id: Agency must exist and belong to the authenticated tenant
  • email: Must be unique within the tenant (not already used by another producer or contact)
  • role: If CONTACT_ROLE_PRINCIPAL, the agency must not already have a principal

Returns: The UUID of the created contact.

Common Error Codes:

  • INVALID_ARGUMENT: Missing required fields or invalid field format
  • ALREADY_EXISTS: Email already registered in your tenant, or agency already has a principal
  • NOT_FOUND: Agency doesn't exist or doesn't belong to tenant

Request: NewContactRequest

NewContactRequest is used to create a new contact and associate it with an agency.

Field Type Label Description
agency_id string The UUID of the agency to associate the contact with. Must be a valid UUID format.
contact NewContact Information about the contact to create.

Response: NewContactResponse

NewContactResponse contains the ID of the created contact.

Field Type Label Description
contact_id string The UUID of the created contact. Must be a valid UUID format.

NewContacts

NewContacts creates multiple contacts in bulk and associates them with a single agency.

This endpoint provides an efficient way to add multiple non-producer contacts to the same agency in a single API call. Contacts represent staff members, administrators, or other personnel who are not licensed insurance producers.

Partial Success Behavior: Unlike bulk producer operations, this endpoint uses partial success semantics. Contacts that pass validation are created even if other contacts in the request fail. The response contains only the IDs of successfully created contacts.

Validation Performed (for each contact):

  • Agency exists and belongs to the authenticated tenant
  • Email is unique within the tenant (across both producers and contacts)
  • Required fields are present and valid (first name, last name, email, role)
  • Phone number matches valid pattern (if provided)

Validation Rules: Proto validation (format checks):

  • agency_id: Required, must be a valid UUID format
  • contacts: Required, must contain at least 1 contact. Each contact:
    • first_name: Required, must be non-empty
    • last_name: Required, must be non-empty
    • email: Required, must be a valid email format
    • role: Required, must be non-empty
    • phone: Optional, if provided must match E.164 pattern (e.g., +15551234567)
    • middle_name: Optional
    • address (optional, if provided):
      • street: Required, must be non-empty
      • city: Required, must be non-empty
      • state: Required, must be exactly 2 characters (state code)
      • zip: Required, must be 1-10 characters
    • tenant_id: Optional, maximum 255 characters (external identifier)
    • npn: Optional

Business logic validation:

  • agency_id: Agency must exist and belong to the authenticated tenant
  • Each contact email: Must be unique within the tenant. Contacts with duplicate emails are skipped (partial success - other valid contacts are still created)

Returns: List of UUIDs for successfully created contacts. If some contacts failed validation, only the IDs of successfully created contacts are returned. Failed contacts are logged but not included in the response. The order of returned IDs corresponds to the order of successful contacts, not the original request order.

Common Error Codes:

  • NOT_FOUND: Agency doesn't exist or doesn't belong to tenant

Request: NewContactsRequest

NewContactsRequest is used to create multiple contacts in a single request. All contacts will be associated with the specified agency.

Field Type Label Description
agency_id string The UUID of the agency to associate the contacts with. Must be a valid UUID format.
contacts NewContact repeated List of contacts to create. This field is required and must contain at least one contact.

Response: NewContactsResponse

NewContactsResponse contains the IDs of all created contacts.

Field Type Label Description
contact_ids string repeated List of UUIDs for the newly created contacts. The order matches the order of contacts in the request.

ListAgencyContacts

ListAgencyContacts retrieves all contacts associated with an agency.

Use this endpoint to fetch all non-producer contacts linked to a specific agency. Contacts represent staff members, administrators, or other personnel who are not licensed insurance producers but are associated with the agency.

The response includes complete contact information:

  • Personal details (name, email, phone)
  • Role within the agency
  • Mailing address
  • NPN (if applicable)
  • Creation timestamp
  • The agency the contact belongs to, including its external_id
  • The organization that agency belongs to, when it belongs to one

Validation Rules: Proto validation (format checks):

  • agency_id: Required, must be a valid UUID format

Returns: A list of all contacts associated with the specified agency. Returns an empty list if the agency has no contacts.

Common Error Codes:

  • NOT_FOUND: Agency doesn't exist or doesn't belong to tenant

Request: ListAgencyContactsRequest

ListAgencyContactsRequest requests all contacts associated with an agency.

Field Type Label Description
agency_id string The UUID of the agency to retrieve contacts for. Must be a valid UUID format.

Response: ListAgencyContactsResponse

ListAgencyContactsResponse contains all contacts associated with an agency.

Field Type Label Description
contacts Contact repeated List of all contacts associated with the specified agency.

GetContact

GetContact retrieves a single contact.

Unlike ListAgencyContacts, this does not require knowing the agency, which makes it usable in flows where only the contact is known.

Supports two lookup methods:

  • By contact ID (UUID)
  • By external ID (tenant-defined identifier set via SetExternalID)

The response includes the contact's external_id and external_metadata, the agency it belongs to (with the agency's external_id), and the organization that agency belongs to when it belongs to one. This resolves a contact to its partner/source organization in a single call.

Validation Rules: Proto validation (format checks): Exactly one lookup method must be provided (oneof required):

  • contact_id_lookup.contact_id: Must be a valid UUID format
  • external_id_lookup.external_id: Must be a non-empty string, max 255 characters

Returns: The single matched contact.

Common Error Codes:

  • NOT_FOUND: Contact doesn't exist or doesn't belong to tenant

Request: GetContactRequest

GetContactRequest looks up a single contact, without requiring the agency to be known in advance. Exactly one lookup method must be provided.

Field Type Label Description
contact_id_lookup GetContactRequest.ContactIDLookup
external_id_lookup GetContactRequest.ExternalIDLookup

Response: GetContactResponse

GetContactResponse contains the single matched contact.

Field Type Label Description
contact Contact The matched contact, including its external_id and external_metadata.

UpdateContact

UpdateContact updates editable fields for an existing contact.

This endpoint allows updating contact information for non-producer personnel associated with an agency. All fields are optional, enabling partial updates where only specified fields are modified.

Updatable Fields:

  • Name fields (first name, middle name, last name)
  • Email address (must remain unique within tenant)
  • Phone number
  • Mailing address components
  • Role within the agency
  • External metadata (for tenant-specific data)

Validation Rules: Proto validation (format checks):

  • contact_id: Required, must be a valid UUID format
  • contact: Required, contains the fields to update
    • first_name: If provided, must be non-empty
    • last_name: If provided, must be non-empty
    • middle_name: If provided, must be non-empty
    • email: If provided, must be a valid email format
    • phone: If provided, must match E.164 pattern (e.g., +15551234567)
    • role: If provided, must be non-empty
    • address (if provided, uses address_line_1 and address_line_2):
      • address_line_1: If provided, must be non-empty
      • address_line_2: If provided, must be non-empty
      • city: If provided, must be non-empty
      • state: If provided, must be exactly 2 characters (state code)
      • zip: If provided, must be 1-10 characters
    • external_metadata: Map of key-value pairs for tenant-specific data

Business logic validation:

  • contact_id: Contact must exist and belong to the authenticated tenant
  • email: If provided, must be unique within the tenant (across both producers and contacts)

Update Behavior:

  • Only fields explicitly provided in the request are updated
  • Omitted optional fields remain unchanged
  • Empty strings are treated as clearing the field value
  • Address updates are all-or-nothing (provide complete address or omit entirely)

Returns: Empty response on success. The contact is updated atomically.

Common Error Codes:

  • NOT_FOUND: Contact doesn't exist or doesn't belong to tenant
  • ALREADY_EXISTS: Email is already in use by another producer or contact within the tenant
  • INVALID_ARGUMENT: Validation failed for one or more fields

Request: UpdateContactRequest

UpdateContactRequest is used to update an existing contact's information.

Field Type Label Description
contact_id string The UUID of the contact to update. Must be a valid UUID format.
contact UpdateContactRequest.Contact The contact information to update. The field is required.

Response: UpdateContactResponse

UpdateContactResponse is the empty response returned after successfully updating a contact.

This message has no fields.

SetExternalID

SetExternalID sets an external identifier for a producer, agency, contact, or organization.

Use this endpoint to link ProducerFlow entities to corresponding records in your external systems (CRM, AMS, legacy databases). This enables bi-directional synchronization and lookups across systems.

Supported Entity Types:

  • Producer: Links a producer to an external system record
  • Agency: Links an agency to an external system record
  • Contact: Links a contact to an external system record
  • Organization: Links an organization to an external system record

Exactly one entity type must be specified per request.

Validation Performed:

  • Exactly one entity ID is provided (producer_id, agency_id, contact_id, or organization_id)
  • The external ID (tenant_id) is non-empty and at most 255 characters
  • The external ID is unique within the tenant (not already assigned to another entity)
  • The specified entity exists and belongs to the authenticated tenant

Validation Rules: Proto validation (format checks): Exactly one entity ID must be provided (oneof required):

  • producer_id: Must be a valid UUID format
  • agency_id: Must be a valid UUID format
  • contact_id: Must be a valid UUID format
  • organization_id: Must be a valid UUID format

Required field:

  • tenant_id: Required, must be 1-255 characters (the external identifier to assign)

Business logic validation:

  • tenant_id: Must be unique within the tenant (not already assigned to any other entity)
  • Entity must exist and belong to the authenticated tenant:
    • Producer: Verified via tenant-scoped lookup
    • Contact: Verified via tenant-scoped lookup
    • Agency: Verified via tenant-scoped lookup and tenant ownership check
    • Organization: Verified via tenant-scoped lookup and tenant ownership check

Returns: Empty response on success.

Common Error Codes:

  • INVALID_ARGUMENT: No entity ID provided or external ID validation failed
  • NOT_FOUND: The specified entity doesn't exist or doesn't belong to tenant
  • ALREADY_EXISTS: The external ID is already assigned to another entity in the tenant
  • PERMISSION_DENIED: The entity doesn't belong to the authenticated tenant

Request: SetExternalIDRequest

SetExternalIDRequest is used to associate an external identifier with a producer, agency, or contact. This allows integration with external systems that use different ID schemes.

Only one entity type can be specified.

Field Type Label Description
producer_id string The UUID of the producer to set an external ID for.
agency_id string The UUID of the agency to set an external ID for.
contact_id string The UUID of the contact to set an external ID for.
organization_id string The UUID of the organization to set an external ID for.
tenant_id string External identifier to associate with the entity in the tenant's system. This field allows tenants to maintain a reference to their own internal ID for the specified entity (producer, agency, contact, or organization), enabling bi-directional synchronization between ProducerFlow and the tenant's system. Purpose: Links ProducerFlow entities to corresponding entities in external systems. Enables lookups and synchronization across systems. Maintains referential integrity with tenant's internal databases. Usage: Call this RPC after creating an entity if you need to add or update the external reference. This can also be provided during entity creation for producers and contacts. This is independent of ProducerFlow's internal IDs and the authentication tenant context. Relationship to authentication: The tenant context is determined by the API key used for authentication. This tenant_id field is purely for storing the tenant's own external identifier. Multiple tenants cannot share the same entity; each tenant has their own isolated data. Common use cases: Syncing with CRM systems (e.g., Salesforce IDs, HubSpot IDs). Integrating with AMS platforms (e.g., Applied Epic, Vertafore). Maintaining references to legacy system identifiers. Format: Any string identifier that is meaningful in your system (e.g., "SF-001234", "LEGACY-9876"). Validation: Must be non-empty, maximum length of 255 characters

Response: SetExternalIDResponse

SetExternalIDResponse is the empty response returned after successfully setting an external ID.

This message has no fields.

ValidateProducerNPN

ValidateProducerNPN checks whether a producer's National Producer Number (NPN) exists in NIPR.

Use this endpoint to verify an NPN is valid before creating a producer. This is a free NIPR API lookup that does not count against your monthly billing quota.

Validation Modes:

  • NPN only: Validates that the NPN exists in NIPR
  • NPN with name: Validates that the NPN exists AND the name matches the NIPR record (recommended for additional verification)

NIPR Billing: This is a FREE operation. It uses the NIPR NPN Lookup service which does not incur charges, unlike the other NIPR entity lookups used during sync operations.

Validation Rules: Proto validation (format checks):

  • npn: Required, must be non-empty string
  • name: Optional, if provided validates NPN matches this producer name in NIPR

Business logic validation:

  • NPN is validated against NIPR database via free NIPR NPN Lookup API
  • If name is provided, both NPN and name must match a producer record in NIPR
  • If name is not provided, only NPN existence is verified

Returns: A boolean indicating whether the NPN is valid. Returns true if the NPN exists in NIPR (and name matches, if provided), false otherwise.

Request: ValidateProducerNPNRequest

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.

Field Type Label Description
npn string 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
name string optional 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.

Response: ValidateProducerNPNResponse

ValidateProducerNPNResponse contains the result of validating a producer's NPN.

Field Type Label Description
valid bool optional Indicates whether the NPN is valid. 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. Marked optional so the field is always emitted in JSON, even when false.

ValidateAgencyNPN

ValidateAgencyNPN checks whether an agency's National Producer Number (NPN) exists in NIPR.

Use this endpoint to verify an agency NPN is valid before creating an agency. This is a free NIPR API lookup that does not count against your monthly billing quota.

NIPR Billing: This is a FREE operation. It uses the NIPR NPN Lookup service which does not incur charges, unlike the NIPR entity lookups used during sync operations.

Validation Rules: Proto validation (format checks):

  • npn: Required, must be non-empty string

Business logic validation:

  • NPN is validated against NIPR database via free NIPR NPN Lookup API
  • Agency NPN must exist in NIPR's agency records

Returns: A boolean indicating whether the agency NPN is valid. Returns true if the NPN exists in NIPR, false otherwise.

Request: ValidateAgencyNPNRequest

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.

Field Type Label Description
npn string 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

Response: ValidateAgencyNPNResponse

ValidateAgencyNPNResponse contains the result of validating an agency's NPN.

Field Type Label Description
valid bool optional Indicates whether the NPN is valid. True if the NPN exists in NIPR's agency records. False if the NPN does not exist. Marked optional so the field is always emitted in JSON, even when false.
agency_name string The agency name as registered in NIPR. Populated only when the NPN is valid; empty otherwise.

LookupNPNByFEIN

LookupNPNByFEIN finds an agency's NPN using their Federal Employer Identification Number (FEIN).

Use this endpoint to help agencies discover their NPN when they only know their FEIN. This is common during onboarding when agencies may not have their NPN readily available but know their tax identification number.

NIPR Billing: This is a FREE operation. It uses the NIPR NPN Lookup service which does not incur charges, unlike the EntityInfo lookups used during sync operations.

Validation Rules: Proto validation (format checks):

  • fein: Required, must be exactly 9 characters

Business logic validation:

  • FEIN is looked up against NIPR database via free NIPR NPN Lookup API
  • Agency with the given FEIN must exist in NIPR's records

Returns: The agency's NPN if found in NIPR.

Common Error Codes:

  • NOT_FOUND: No agency found in NIPR with the given FEIN

Request: LookupNPNByFEINRequest

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.

Field Type Label Description
fein string The Federal Employer Identification Number (FEIN) to look up. Format: Exactly 9 digits, no dashes or spaces. Example: "123456789" This is the tax identification number assigned by the IRS.

Response: LookupNPNByFEINResponse

LookupNPNByFEINResponse contains the National Producer Number (NPN) for the agency associated with the given FEIN.

Field Type Label Description
npn string 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.

ResyncProducer

ResyncProducer triggers a manual resynchronization of a producer's data. This can be used to refresh data after external change

Common Error Codes:

  • NOT_FOUND: Producer doesn't exist or doesn't belong to tenant
  • INVALID_ARGUMENT: Producer ID is empty

Request: ResyncProducerRequest

ResyncProducerRequest is used to trigger a manual resynchronization of producer data.

Field Type Label Description
producer_id string The UUID of the producer to resynchronize. Must be a valid UUID format.

Response: ResyncProducerResponse

ResyncProducerResponse is the empty response returned after successfully triggering a resynchronization.

This message has no fields.

ResyncAgency

ResyncAgency triggers a manual resynchronization of an agency's data. Similar to ResyncProducer, this can be used to refresh data after external changes. Common Error Codes:

  • NOT_FOUND: Agency doesn't exist or doesn't belong to tenant
  • INVALID_ARGUMENT: Agency ID is empty or request is empty

Request: ResyncAgencyRequest

ResyncAgencyRequest is used to trigger a manual resynchronization of agency data. This will re-fetch all data from the NIPR API for the agency and all associated producers.

Field Type Label Description
agency_id string The UUID of the agency to resynchronize. Must be a valid UUID format.

Response: ResyncAgencyResponse

ResyncAgencyResponse is the empty response returned after successfully triggering a resynchronization.

This message has no fields.

SyncProducerWithNIPR

SyncProducerWithNIPR synchronizes a producer's data with NIPR.

Use this endpoint to manually trigger an immediate refresh of producer data from NIPR. The operation validates the producer NPN exists in NIPR before syncing.

What Gets Synchronized:

  • State licenses with expiration dates and Lines of Authority
  • Carrier appointments with status and renewal dates
  • Regulatory actions and disciplinary history
  • 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
  • Producer must not already be in active sync state

Validation Rules: Proto validation (format checks):

  • producer_id: Required, must be a valid UUID format

Business logic validation:

  • producer_id: Producer must exist and belong to the authenticated tenant
  • Producer must have an NPN assigned (cannot sync a producer without NPN)
  • Producer's NPN must exist in NIPR (validated via NIPR NPN Lookup API)
  • Producer must not already be in ACTIVE sync state (prevents redundant syncs)

Timeout: 30 seconds. If NIPR takes longer, you'll receive a DEADLINE_EXCEEDED error.

Returns: Empty response on success.

Common Error Codes:

  • 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

Request: SyncProducerWithNIPRRequest

SyncProducerWithNIPRRequest is used to synchronize a producer's data with the NIPR API.

Field Type Label Description
producer_id string The UUID of the producer to synchronize. Must be a valid UUID format.

Response: SyncProducerWithNIPRResponse

SyncProducerWithNIPRResponse is the empty response returned after successfully synchronizing a producer's data with the NIPR API.

This message has no fields.

SyncAgencyWithNIPR

SyncAgencyWithNIPR synchronizes an agency's data with NIPR.

Use this endpoint to manually trigger an immediate refresh of agency data from NIPR. The operation validates the agency NPN exists in NIPR before syncing.

What Gets Synchronized:

  • Agency biographic information (company name, FEIN, contact details)
  • State licenses with expiration dates and Lines of Authority
  • Carrier appointments with status and renewal dates
  • 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 minutes to accommodate the additional operations. Each producer sync is a separate billable NIPR lookup.

Preconditions:

  • Agency must exist and belong to the authenticated tenant
  • Agency must have a valid NPN registered in NIPR
  • Agency must not already be in active sync state
  • Agency must not be a sole proprietor (sync the underlying producer instead)

Validation Rules: Proto validation (format checks):

  • agency_id: Required, must be a valid UUID format
  • sync_all_producers: Optional boolean, defaults to false

Business logic validation:

  • agency_id: Agency must exist and belong to the authenticated tenant
  • Agency's NPN must exist in NIPR (validated via NIPR NPN Lookup API)
  • Agency must not already be in ACTIVE sync state (prevents redundant syncs)

Timeout:

  • 30 seconds when syncing agency only
  • 10 minutes when sync_all_producers is true

Returns: Empty response on success.

Common Error Codes:

  • NOT_FOUND: Agency doesn't exist or doesn't belong to tenant
  • INVALID_ARGUMENT: Agency NPN is not valid (not found in NIPR)
  • FAILED_PRECONDITION: Agency is already synced with NIPR (ACTIVE sync state), or the agency is a sole proprietor (sync the underlying producer instead)
  • DEADLINE_EXCEEDED: NIPR sync operation timed out (30s for agency only, 10m with sync_all_producers)

Request: SyncAgencyWithNIPRRequest

SyncAgencyWithNIPRRequest is used to synchronize an agency's data with the NIPR API.

Field Type Label Description
agency_id string The UUID of the agency to synchronize. Must be a valid UUID format.
sync_all_producers bool If true, all producers associated with the agency will be synchronized. If false, only the agency will be synchronized.

Response: SyncAgencyWithNIPRResponse

SyncAgencyWithNIPRResponse is the empty response returned after successfully synchronizing an agency's data with the NIPR API.

This message has no fields.

StopSyncProducerWithNIPR

StopSyncProducerWithNIPR disables automatic NIPR synchronization for a producer.

Use this endpoint to stop receiving automatic updates from NIPR for a specific producer. Once stopped, the producer's NIPR data will no longer be refreshed via PDB Alerts or other automatic sync mechanisms.

This does not delete existing NIPR data - it only prevents future updates. To re-enable synchronization, use the SyncProducerWithNIPR endpoint.

Preconditions:

  • Producer must exist and belong to the authenticated tenant
  • Producer must be in active or failing sync state (not already disabled/pending)

Validation Rules: Proto validation (format checks):

  • producer_id: Required, must be a valid UUID format

Business logic validation:

  • producer_id: Producer must exist and belong to the authenticated tenant
  • Producer must be in ACTIVE or FAILING sync state (cannot stop if already DISABLED or PENDING)

Returns: Empty response on success.

Common Error Codes:

  • NOT_FOUND: Producer doesn't exist or doesn't belong to tenant
  • FAILED_PRECONDITION: Producer is already unsynced (DISABLED or PENDING sync state)

Request: StopSyncProducerWithNIPRRequest

StopSyncProducerWithNIPRRequest is used to stop synchronizing a producer's data with the NIPR API.

Field Type Label Description
producer_id string The UUID of the producer to stop synchronizing. Must be a valid UUID format.

Response: StopSyncProducerWithNIPRResponse

StopSyncProducerWithNIPRResponse is the empty response returned after successfully stopping the synchronization of a producer's data with the NIPR API.

This message has no fields.

StopSyncAgencyWithNIPR

StopSyncAgencyWithNIPR disables automatic NIPR synchronization for an agency.

Use this endpoint to stop receiving automatic updates from NIPR for a specific agency. Once stopped, the agency's NIPR data will no longer be refreshed via PDB Alerts or other automatic sync mechanisms.

This does not delete existing NIPR data - it only prevents future updates. To re-enable synchronization, use the SyncAgencyWithNIPR endpoint.

Bulk Producer Stop: When stop_all_producers is set to true, the system will also stop sync for all producers associated with the agency. This is useful when offboarding an entire agency from NIPR synchronization. When this flag is set, the precondition check for agency sync state is bypassed.

Preconditions:

  • Agency must exist and belong to the authenticated tenant
  • Agency must be in active or failing sync state (unless stop_all_producers is true)

Validation Rules: Proto validation (format checks):

  • agency_id: Required, must be a valid UUID format
  • stop_all_producers: Optional boolean, defaults to false

Business logic validation:

  • agency_id: Agency must exist and belong to the authenticated tenant
  • Unless stop_all_producers is true, agency must be in ACTIVE or FAILING sync state (cannot stop if already DISABLED or PENDING)

Returns: Empty response on success.

Common Error Codes:

  • NOT_FOUND: Agency doesn't exist or doesn't belong to tenant
  • FAILED_PRECONDITION: Agency is already unsynced (DISABLED or PENDING sync state, unless stop_all_producers is true)

Request: StopSyncAgencyWithNIPRRequest

StopSyncAgencyWithNIPRRequest is used to stop synchronizing an agency's data with the NIPR API.

Field Type Label Description
agency_id string The UUID of the agency to stop synchronizing. Must be a valid UUID format.
stop_all_producers bool If true, all producers associated with the agency will be stopped from synchronizing. If false, only the agency will be stopped from synchronizing.

Response: StopSyncAgencyWithNIPRResponse

StopSyncAgencyWithNIPRResponse is the empty response returned after successfully stopping the synchronization of an agency's data with the NIPR API.

This message has no fields.

CreateProducerUploadURL

CreateProducerUploadURL generates a secure URL for bulk producer uploads to an existing agency.

Use this endpoint to create a shareable link that allows agencies to upload multiple producers at once. The URL includes security tokens and tenant context to ensure secure, authenticated access.

Unlike CreateProducerOnboardingURL which creates a self-service form for a single producer, this endpoint generates a URL for bulk uploading producer data (typically via CSV or spreadsheet format).

The agency is identified by its National Producer Number (NPN), which must already exist in your tenant. Use ListAgencies or GetAgencyAndProducers to look up agency NPNs if needed.

Typical Workflow:

  1. Generate producer upload URL using the agency's NPN
  2. Share URL with agency contact via email or portal
  3. Agency uploads producer data through the URL
  4. System processes uploads, validates NPNs with NIPR, and creates producer records
  5. Producers are associated with the agency and optionally synced with NIPR

URL Expiration: The generated URL has a default expiration of 7 days. After expiration, a new URL must be generated.

Validation Performed:

  • Agency NPN format is valid (numeric string, 2-10 digits)
  • Agency with the given NPN exists in your tenant
  • Agency belongs to the authenticated tenant

Validation Rules: Proto validation (format checks):

  • agency_npn: Required, must be 2-10 digits (numeric characters only)

Business logic validation:

  • Agency with the given NPN must exist in the authenticated tenant
  • Agency must belong to the authenticated tenant (ownership verification)
  • Only one agency should match the NPN (multiple matches indicate data issue)

Returns: A time-limited URL string that can be shared with the agency for bulk producer uploads.

Common Error Codes:

  • NOT_FOUND: No agency found with the given NPN in your tenant

Request: CreateProducerUploadURLRequest

CreateProducerUploadURLRequest contains information needed to generate a producer upload URL. This includes the agency NPN.

Field Type Label Description
agency_npn string The National Producer Number (NPN) of the agency. Required and must be a valid NPN format (numeric string between 2-10 digits).

Response: CreateProducerUploadURLResponse

CreateProducerUploadURLResponse contains the generated URL for producer uploads

Field Type Label Description
url string URL that can be shared with the agency for producer uploads. The URL is time-limited and includes necessary security tokens.

AddAgencyLocations

AddAgencyLocations adds one or more locations to an existing agency.

Use this endpoint to programmatically add physical locations (offices, branches, etc.) to an agency. Locations enable organizing producers by their work sites and tracking agency presence across different addresses.

Bulk Operation Behavior: This is an all-or-nothing operation - if any location fails validation, the entire request will fail and no locations will be added. You can add up to 100 locations in a single request.

Validation Performed:

  • Agency exists and belongs to the authenticated tenant
  • At least one location is provided
  • Location names are unique within the agency (case-insensitive)
  • Location names are not duplicated within the request
  • Valid address information is provided for each location

Validation Rules: Proto validation (format checks):

  • agency_id: Required, must be a valid UUID format
  • locations: Required, 1-100 locations. Each location:
    • name: Required, must be non-empty (unique within agency)
    • address: Required
      • street: Required, must be non-empty
      • city: Required, must be non-empty
      • state: Required, must be exactly 2 characters (state code)
      • zip: Required, must be 1-10 characters
    • phone: Required, must match E.164 pattern (e.g., +15551234567)
    • email: Required, must be a valid email format
    • is_primary: Optional boolean, marks location as primary

Business logic validation:

  • agency_id: Agency must exist and belong to the authenticated tenant
  • Location names must be unique within the agency (case-insensitive)
  • Location names must not duplicate any existing location names in the agency
  • Location names must not duplicate other location names within the same request

Returns: List of UUIDs for all created locations in the same order as the request. This ordering guarantee allows you to map request entries to their created IDs.

Common Error Codes:

  • 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

Request: AddAgencyLocationsRequest

AddAgencyLocationsRequest adds new locations to an agency.

Field Type Label Description
agency_id string Required. Agency ID to add locations to.
locations LocationInput repeated Required. List of locations to add.

Response: AddAgencyLocationsResponse

AddAgencyLocationsResponse contains the results of adding locations.

Field Type Label Description
location_ids string repeated IDs of successfully created locations, in the same order as the input.

RemoveAgencyLocations

RemoveAgencyLocations removes one or more locations from an agency.

Use this endpoint to delete locations that are no longer needed. This is useful when closing branch offices or consolidating agency locations.

Producer Unassignment: When a location is removed, all producers assigned to that location are automatically unassigned. The producers themselves are not deleted - they remain associated with the agency but without a location assignment.

Partial Success Behavior: Locations that don't exist are silently ignored. The response contains only the IDs of locations that were actually removed.

Validation Performed:

  • At least one location ID is provided

Validation Rules: Proto validation (format checks):

  • agency_id: Required, must be a valid UUID format
  • location_ids: Required, 1-100 items, each must be a valid UUID format

Business logic validation:

  • agency_id: Agency must exist and belong to the authenticated tenant
  • Location IDs that don't exist are silently ignored (partial success)

Returns: List of UUIDs for locations that were successfully removed.

Common Error Codes:

  • INVALID_ARGUMENT: Missing agency_id or no location_ids provided
  • NOT_FOUND: Agency doesn't exist or doesn't belong to tenant

Request: RemoveAgencyLocationsRequest

RemoveAgencyLocationsRequest removes locations from an agency.

Field Type Label Description
agency_id string Required. Agency ID to remove locations from.
location_ids string repeated Required. IDs of locations to remove.

Response: RemoveAgencyLocationsResponse

RemoveAgencyLocationsResponse contains the results of removing locations.

Field Type Label Description
removed_location_ids string repeated IDs of successfully removed locations.

ListAgencyLocations

ListAgencyLocations retrieves all locations associated with an agency.

Use this endpoint to fetch the complete list of physical locations belonging to an agency. Each location includes its address, contact information, and primary status.

The response includes complete location information:

  • Location ID and name
  • Physical address (street, city, state, zip)
  • Contact information (phone, email)
  • Primary location indicator

Validation Rules: Proto validation (format checks):

  • agency_id: Required, must be a valid UUID format

Returns: A list of all locations associated with the specified agency. Returns an empty list if the agency has no locations.

Common Error Codes:

  • INVALID_ARGUMENT: Invalid request
  • NOT_FOUND: Agency doesn't exist or doesn't belong to tenant

Request: ListAgencyLocationsRequest

ListAgencyLocationsRequest retrieves all locations for an agency.

Field Type Label Description
agency_id string Required. Agency ID to list locations for.

Response: ListAgencyLocationsResponse

ListAgencyLocationsResponse contains the list of agency locations.

Field Type Label Description
locations Location repeated List of all locations associated with the agency.

AssignProducerToLocations

AssignProducerToLocations assigns one or more locations to a producer.

Use this endpoint to associate a producer with specific agency locations (branch offices, work sites, etc.). A producer can be assigned to multiple locations within their agency.

Location Ownership: All specified locations must belong to the same agency as the producer. Cross-agency location assignments are not permitted.

Idempotent Behavior: If a producer is already assigned to a location, the assignment is preserved without error. The response includes all successfully assigned location IDs.

Validation Performed:

  • Producer exists and belongs to the authenticated tenant
  • All location IDs exist and belong to the producer's agency
  • At least one location ID is provided

Validation Rules: Proto validation (format checks):

  • producer_id: Required, must be a valid UUID format
  • location_ids: Required, 1-100 items, each must be a valid UUID format

Business logic validation:

  • producer_id: Producer must exist and belong to the authenticated tenant
  • Producer's agency must exist and belong to the authenticated tenant
  • All location_ids must exist and belong to the producer's agency

Returns: List of location IDs that were successfully assigned to the producer.

Common Error Codes:

  • INVALID_ARGUMENT: Request is missing
  • NOT_FOUND: Producer doesn't exist, agency doesn't exist, or specified locations don't exist
  • PERMISSION_DENIED: Agency doesn't belong to the authenticated tenant

Request: AssignProducerToLocationsRequest

AssignProducerToLocationsRequest assigns locations to a producer.

Field Type Label Description
producer_id string Required. Producer ID to assign locations to.
location_ids string repeated Required. Location IDs to assign (1-100 items). These locations must belong to the same agency as the producer.

Response: AssignProducerToLocationsResponse

AssignProducerToLocationsResponse contains the assigned location IDs.

Field Type Label Description
assigned_location_ids string repeated IDs of successfully assigned locations.

UnassignProducerFromLocations

UnassignProducerFromLocations removes one or more location assignments from a producer.

Use this endpoint to disassociate a producer from specific agency locations. This is useful when producers change work sites or when consolidating location assignments.

Producer Preservation: This operation only removes the location assignments - the producer remains active and associated with the agency. To fully remove a producer, use the appropriate producer deletion endpoint.

Validation Performed:

  • Producer exists and belongs to the authenticated tenant
  • All location IDs exist and belong to the producer's agency
  • At least one location ID is provided

Validation Rules: Proto validation (format checks):

  • producer_id: Required, must be a valid UUID format
  • location_ids: Required, 1-100 items, each must be a valid UUID format

Business logic validation:

  • producer_id: Producer must exist and belong to the authenticated tenant
  • All location_ids must exist and belong to the producer's agency

Returns: List of location IDs that were successfully unassigned from the producer.

Common Error Codes:

  • INVALID_ARGUMENT: Request is missing, producer_id is empty, or no location_ids provided
  • NOT_FOUND: Producer doesn't exist or specified locations don't exist

Request: UnassignProducerFromLocationsRequest

UnassignProducerFromLocationsRequest removes location assignments from a producer.

Field Type Label Description
producer_id string Required. Producer ID to unassign locations from.
location_ids string repeated Required. Location IDs to unassign (1-100 items).

Response: UnassignProducerFromLocationsResponse

UnassignProducerFromLocationsResponse contains the unassigned location IDs.

Field Type Label Description
unassigned_location_ids string repeated IDs of successfully unassigned locations.

UpdateAgencyLocation

UpdateAgencyLocation updates an existing agency location.

Use this endpoint to modify location details such as address, contact information, or primary status. This is useful when locations move, change phone numbers, or when designating a new primary location.

Updatable Fields:

  • Name (must remain unique within the agency)
  • Address (street, city, state, zip)
  • Contact information (phone, email)
  • Primary location status

All fields are optional - only provide the fields you want to update. Unchanged fields retain their current values.

Name Uniqueness: If updating the location name, the new name must not already exist for another location within the same agency (case-insensitive comparison).

Validation Rules: Proto validation (format checks):

  • agency_id: Required, must be a valid UUID format
  • location_id: Required, must be a valid UUID format
  • name: If provided, must be non-empty (unique within agency)
  • address: If provided (all fields optional within):
    • street: If provided, must be non-empty
    • city: If provided, must be non-empty
    • state: If provided, must be exactly 2 characters (state code)
    • zip: If provided, must be 1-10 characters
  • phone: If provided, must match E.164 pattern (e.g., +15551234567)
  • email: If provided, must be a valid email format
  • is_primary: Optional boolean

Business logic validation:

  • agency_id: Agency must exist and belong to the authenticated tenant
  • location_id: Location must exist and belong to the specified agency
  • name: If provided, must be unique within the agency (case-insensitive, excluding the location being updated)

Returns: The complete updated location object with all current field values.

Common Error Codes:

  • INVALID_ARGUMENT: Missing agency_id or location_id, or invalid request
  • NOT_FOUND: Agency or location doesn't exist or doesn't belong to tenant
  • ALREADY_EXISTS: New location name already exists within the agency

Request: UpdateAgencyLocationRequest

UpdateAgencyLocationRequest updates an existing agency location.

Field Type Label Description
agency_id string Required. Agency ID that owns the location.
location_id string Required. Location ID to update.
name string optional Optional. New name for the location. Must be unique within the agency.
address Address optional Optional. New address for the location.
phone string optional Optional. New phone number. Must be in E.164 format.
email string optional Optional. New email address.
is_primary bool optional Optional. Whether this should be the primary location.
external_id string optional Optional. Carrier-specific external ID for this location. Must be unique within the tenant when set. Pass an empty string to clear it.

Response: UpdateAgencyLocationResponse

UpdateAgencyLocationResponse contains the updated location details.

Field Type Label Description
location Location The updated location with all current values.

AppointmentService

AppointmentService manages license appointments through NIPR.

The appointment flow in NIPR is as follows:

  1. A new appointment (or termination) is requested for a license number.
  2. Some time later, NIPR processes the request and returns the final result.

Since NIPR does not return results immediately, RequestAppointment and TerminateAppointment RPCs will return a processing status of IN_PROGRESS if the request is accepted by NIPR. When the appointment is finally processed by NIPR, ProducerFlow will notify via a webhook of the final result. Also, any call from this point on to ListAppointments or GetAppointment will also return the final result.

IMPORTANT: Appointments in registry states or with capacity carriers (carriers that do not have NIPR integration) are processed automatically without going through NIPR. In these cases:

  • RequestAppointment will immediately return APPOINTED status.
  • TerminateAppointment will immediately return TERMINATED status.

Any call to this service must be authenticated using an API key in the request headers. The API key can be found in the ProducerFlow API key section of the ProducerFlow UI and it identifies the tenant that is making the request.

GetAppointment

Retrieves the details of an appointment by its ID.

Request: GetAppointmentRequest

Request to retrieve an appointment by ID.

Field Type Label Description
appointment_id string Required. The ID of the appointment to retrieve.

Response: GetAppointmentResponse

Field Type Label Description
appointment Appointment The appointment details.

GetAppointmentFees

Retrieves the total fees associated with requesting an appointment for the given license. Fee amounts are represented as integer values in cents. E.g. $10.34 is sent as 1034.

Request: GetAppointmentFeesRequest

Request to get appointment fees.

Field Type Label Description
license_id string Required. The ID of the license to get the appointment fee for.

Response: GetAppointmentFeesResponse

Field Type Label Description
fee_in_cents int64 Total fee for the appointment in cents.

GetAppointableCarriers

Retrieves the carriers that are available to appoint licenses for the tenant.

Request: GetAppointableCarriersRequest

Request to retrieve carriers that are available to be appointed.

This message has no fields.

Response: GetAppointableCarriersResponse

Response containing carriers that are available to be appointed.

Field Type Label Description
carriers Carrier repeated The list of carriers that are available to be appointed.

GetTerminationFees

Retrieves the total fees associated with terminating an appointment for the given license. Fee amounts are represented as integer values in cents. E.g. $10.34 is sent as 1034.

Request: GetTerminationFeesRequest

Request to get termination fees.

Field Type Label Description
license_id string Required. The ID of the license to get the termination fee for.

Response: GetTerminationFeesResponse

Field Type Label Description
fee_in_cents int64 Total fee for the termination in cents.

ListAppointments

Lists appointments for the tenant, optionally filtered by processing status.

Request: ListAppointmentsRequest

Request to list appointments, optionally filtered by processing status.

Field Type Label Description
processing_status ProcessingStatus repeated Optional. Filter results by processing status.
producer_id string
agency_id string
operational_status OperationalStatus repeated Optional. Filter results by operational status.
pagination producerflow.producer.v1.Pagination Optional. Pagination parameters. If not provided, defaults to page_size=50. Maximum page_size is 200.

Response: ListAppointmentsResponse

Field Type Label Description
appointments Appointment repeated List of appointments.
next_page_token string Token for fetching the next page of results. Empty when there are no more results.

ListEligibleLicenses

Returns a list of licenses that are eligible to be appointed.

Request: ListEligibleLicensesRequest

Request to retrieve a list of licenses that are eligible to be appointed.

Field Type Label Description
producer_id string
agency_id string

Response: ListEligibleLicensesResponse

Field Type Label Description
licenses License repeated List of licenses that are eligible to be appointed.

RequestAppointment

Requests a new appointment for a license that is eligible to be appointed.

The simpler way to do this is to call ListEligibleLicenses to get a list of licenses that are eligible to be appointed. Then, call RequestAppointment for the licenses in the list that you want to appoint.

Processing behavior varies based on the license state and carrier NIPR integration:

For NIPR-integrated carriers in non-registry states:

  • If the request is accepted by NIPR, the appointment will have IN_PROGRESS processing status.
  • If rejected, it will have REJECTED status and reasons will be provided in not_eligible_reasons.
  • Final result will be delivered via webhook when NIPR completes processing.

For registry states or capacity carriers (carriers without NIPR integration):

  • The appointment is processed automatically and immediately.
  • Returns APPOINTED status immediately upon successful processing.

Requesting an appointment that already exists for the same license and carrier is refused with ALREADY_EXISTS, unless that appointment is TERMINATED or REJECTED. Both of those are sent to the state again, reusing the existing appointment's ID and moving it back to IN_PROGRESS, so the result reads the same as a first request.

Before re-sending a REJECTED appointment, fix whatever caused the rejection: an unchanged appointment gets the same answer from the state and is charged again.

Either re-send is refused when the underlying license is inactive or expired, since the state would reject it anyway, and when a NIPR transaction is already in flight for the appointment.

Request: RequestAppointmentRequest

Request to create a new appointment.

Field Type Label Description
license_id string Required. The ID of the license to appoint.
carrier_id string Required. The ID of the carrier to appoint the license with.

Response: RequestAppointmentResponse

Field Type Label Description
appointment_id string The ID of the created appointment.
processing_status ProcessingStatus Processing status of the appointment request. For NIPR-integrated carriers: IN_PROGRESS if accepted, REJECTED if rejected. For registry states or non-NIPR carriers: APPOINTED if successful.
not_eligible_reasons string repeated If the appointment was rejected or ineligible, these reasons explain why. Only populated when processing_status is REJECTED.

TerminateAppointment

Terminates an existing appointment, permanently ending the relationship between the license holder and the carrier.

Before calling this method, you must:

  1. Ensure the appointment exists and is in APPOINTED status.
  2. Call ListTerminationReasons to get valid termination reasons for the license's state.
  3. Select an appropriate termination reason from the state-specific list.

Processing behavior varies based on the license state and carrier NIPR integration:

For NIPR-integrated carriers in non-registry states:

  • The request is submitted to NIPR for processing.
  • Once NIPR completes processing, the status becomes TERMINATED.
  • If rejected by NIPR, the appointment remains in its current status.
  • You will receive webhook notifications when the termination is processed by NIPR.

For registry states, capacity carriers (carriers without NIPR integration), or synthetic appointments:

  • The termination is processed automatically and immediately.
  • Returns TERMINATED status immediately upon successful processing.

Important considerations:

  • Termination is permanent and cannot be undone.
  • Termination reasons must be valid for the specific state where the license is issued.
  • Some terminations may incur fees (check GetTerminationFees first).
  • The response indicates whether the termination request was successfully submitted, not whether the actual termination was completed (since NIPR processes asynchronously).

Request: TerminateAppointmentRequest

Request to terminate an appointment.

Field Type Label Description
appointment_id string ID of the appointment to terminate.
reason TerminationReason Reason for termination. This must be a valid termination reason for the state where the license is issued. Call ListTerminationReasons first to get the list of valid reasons for the specific state.

Response: TerminateAppointmentResponse

Field Type Label Description
success bool Indicates whether the termination request was successfully processed. For NIPR-integrated carriers: - Indicates whether the termination request was successfully submitted to NIPR. - This does not indicate that the appointment has been terminated, only that the request has been accepted for processing. - The actual termination will be processed asynchronously by NIPR, and you will be notified via webhook when the process completes. For registry states or non-NIPR carriers: - Indicates whether the termination was successfully completed immediately.

ListTerminationReasons

Lists the valid termination reasons for appointments in a specific state.

When terminating an appointment, you must provide a valid termination reason that is accepted by NIPR for the state where the license is issued. Termination reasons vary by state, so you should call this method first to retrieve the list of valid reasons before calling TerminateAppointment.

The termination reasons returned are based on NIPR's valid termination codes for the specified state. Each reason corresponds to a specific business scenario for why an appointment might be terminated (e.g., voluntary termination, inadequate production, company merger, etc.).

Request: ListTerminationReasonsRequest

Field Type Label Description
state string Required. The two-letter state code of the license for which you want to retrieve valid termination reasons. Different states may have different sets of valid termination reasons accepted by NIPR.

Response: ListTerminationReasonsResponse

Field Type Label Description
termination_reasons TerminationReason repeated The list of valid termination reasons for the specified state. These reasons can be used when calling TerminateAppointment for licenses issued in this state.

TestingService

============================================================================ DEV AND UAT ONLY — NOT AVAILABLE IN PRODUCTION. Every method on this service is enabled exclusively in the dev and UAT test environments. In production, every call is rejected with PERMISSION_DENIED, regardless of the API key or arguments.

TestingService provides cleanup utilities that let tenants reset their test environments between automated runs. For example, deleting an agency frees the licenses it used so the same test setup can be reused across test cases instead of provisioning new agencies each time. These operations are intended solely for preparing and cleaning up automated test scenarios and have no production use.

Any call to this service must be authenticated using an API key in the request headers. The API key can be found in the ProducerFlow API key section of the ProducerFlow UI and it identifies the tenant that is making the request.

DeleteAgency

DeleteAgency permanently removes an agency and every producer, appointment, and NIPR record scoped to it, freeing the underlying licenses to be appointed again. It lets tenants reset the same agency between automated test runs instead of provisioning a new one each time.

DEV AND UAT ONLY: this method is not available in production. Calls made in production are always rejected with PERMISSION_DENIED.

The agency must belong to the tenant resolved from the request's API key. Tenant (internal) agencies cannot be deleted — they hold per-tenant configuration. The operation is irreversible and emits no events.

Errors:

  • NOT_FOUND: no agency with the given ID exists for the tenant.
  • FAILED_PRECONDITION: the agency is a tenant (internal) agency.
  • INVALID_ARGUMENT: agency_id is missing or is not a valid UUID.
  • PERMISSION_DENIED: the call was made outside dev/UAT (e.g. production).

Request: DeleteAgencyRequest

Field Type Label Description
agency_id string UUID of the Agencies row to delete. Must belong to the tenant resolved from the API key; a cross-tenant or unknown agency_id returns NOT_FOUND.

Response: DeleteAgencyResponse

Empty response

This message has no fields.

DeleteAppointment

DeleteAppointment permanently removes a single appointment, freeing the underlying license to be appointed again. Unlike terminating an appointment — which leaves a TERMINATED record that still blocks the license from being re-appointed — deleting it removes the row entirely so the same license can be reused across automated test runs.

DEV AND UAT ONLY: this method is not available in production. Calls made in production are always rejected with PERMISSION_DENIED.

The appointment must belong to the tenant resolved from the request's API key. Its interleaved history is removed with it. The operation is irreversible, emits no events, and sends nothing to NIPR.

Errors:

  • NOT_FOUND: no appointment with the given ID exists for the tenant.
  • INVALID_ARGUMENT: appointment_id is missing or is not a valid UUID.
  • PERMISSION_DENIED: the call was made outside dev/UAT (e.g. production).

Request: DeleteAppointmentRequest

Field Type Label Description
appointment_id string UUID of the Appointments row to delete. Must belong to the tenant resolved from the API key; a cross-tenant or unknown appointment_id returns NOT_FOUND.

Response: DeleteAppointmentResponse

Field Type Label Description
state string State of the deleted appointment, echoed back for confirmation.
agency_id string Agency the deleted appointment belonged to, echoed back for confirmation.

Shared Types

These types are used across multiple API methods.

producerflow/producer/v1/producer.proto

AddAgencyLocationsRequest

AddAgencyLocationsRequest adds new locations to an agency.

Field Type Label Description
agency_id string Required. Agency ID to add locations to.
locations LocationInput repeated Required. List of locations to add.

AddAgencyLocationsResponse

AddAgencyLocationsResponse contains the results of adding locations.

Field Type Label Description
location_ids string repeated IDs of successfully created locations, in the same order as the input.

Address

Address represents a physical location with standard address components. Used for mailing, physical, and invoicing addresses throughout the API.

Field Type Label Description
street string Deprecated. Deprecated: Use address_line_1 instead.
address_line_1 string Primary address line including house/building number and street name. For backward compatibility, either street or address_line_1 can be used.
city string City of the address
state string State of the address
zip string Zip code of the address
county string County of the address
address_line_2 string optional Optional second line of address (apt, suite, unit, etc.)

Agency

Agency represents a complete insurance agency with all associated data.

This message contains comprehensive agency information including:

  • Basic contact and identification details
  • Principal producer information
  • Banking details for commission payments
  • Business operating information
  • NIPR-synchronized licensing and regulatory data
  • Physical locations

The NIPR data is automatically synchronized from the National Insurance Producer Registry and includes licenses, appointments, regulatory actions, and addresses. This data is read-only and can only be updated by triggering NIPR sync operations.

Field Type Label Description
agency_id string Unique identifier for the agency (UUID format). This ID is used in all API operations that reference this agency.
agency_info Agency.AgencyInfo AgencyInfo type field named agency_info
physical_address Agency.Address Physical address of the agency.
mailing_address Agency.Address Mailing address of the agency.
invoicing_address Agency.Address Invoicing address of the agency.
bank_account Agency.BankAccount Banking information for commission payments. Used for electronic transfers of commissions and other payments.
eo_info Agency.EOInfo
principal Agency.Principal Information about the agency's principal. This is a required field as each agency must have a principal.
ivans_account Agency.IvansAccount IVANS account information for electronic carrier communication. This is optional and only used if the agency uses IVANS.
requested_appointments string repeated The list of requested appointments for the agency.
business_hours Agency.BusinessHours Operating hours of the agency.
nipr Agency.NIPR Data synchronized from the NIPR service. Contains basic information, addresses, licenses, regulatory actions, and carrier appointments.
locations Location repeated Locations associated with the agency.
organization Organization Organization that the agency belongs to. This field contains the full organization details including id, name, and contact information. Agencies may optionally belong to an organization (such as an aggregator or agency network).
is_sole_proprietor bool Indicates whether this agency is a sole proprietor. True: Individual producer operating as their own agency (ENTITY_TYPE_SOLE_PROPRIETOR). False: Standard agency with multiple producers (ENTITY_TYPE_AGENCY).
organization_relationship AgencyOrganizationRelationship optional 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.

Agency.Address

Address is a data structure that represents a physical or mailing location.

Field Type Label Description
street string Deprecated. Deprecated: Use address_line_1 instead.
city string City where the location resides.
state string State/Province where the location resides.
zip string ZIP/Postal code of the location.
address_line_1 string Primary address line including street name and number of the location.
address_line_2 string optional Optional second line of address (apt, suite, unit, etc.)

Agency.AgencyInfo

AgencyInfo contains contact and identification information for an agency.

Field Type Label Description
onboarding_id string The unique identifier for the onboarding process. Used to track the agency through the onboarding flow.
root_organization_id string Deprecated. Deprecated: Use the top-level organization field instead, which provides the full organization object including id, name, external_id, and email.
agency_name string The official name of the agency. This is typically the legal name of the entity.
agency_fein string Federal Employer Identification Number (FEIN) of the agency. This is a unique nine-digit number assigned by the Internal Revenue Service (IRS) to businesses operating in the United States.
email string Primary email address for the agency. Used for communication and must be unique.
phone string Phone number for the agency.
fax string Fax number for the agency.
website string Website URL for the agency, if available.
npn string 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" Only present for standard agencies (not sole proprietors). Reference: https://nipr.com
pdb_alerts_sync_enabled bool Indicates whether the agency is enabled to be synchronized with NIPR API. When true, the system will regularly check for updates from NIPR.
metadata_questions Agency.AgencyInfo.MetadataQuestionsEntry repeated Deprecated. MetadataQuestions contains custom metadata questions and answers for the agency. This field stores tenant-specific questions that were collected during agency onboarding. The map key is the question identifier/text, and the value is the answer provided. This field is deprecated and will be removed in a future release.
external_metadata Agency.AgencyInfo.ExternalMetadataEntry repeated ExternalMetadata contains additional custom information that the tenant stores in ProducerFlow's data model. This field allows tenants to attach arbitrary key-value pairs to agencies for their own business logic, reporting, or integration needs. This field is populated programmatically via API calls by the tenant's systems. Common use cases include: - Storing references to external system states or categories - Adding custom tags or classifications - Maintaining tenant-specific business attributes - Storing computed values or derived data The map key is the metadata field name, and the value is the associated data.
tenant_additional_questions Agency.AgencyInfo.TenantAdditionalQuestionsEntry repeated 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.
external_id string Tenant-provided external identifier for this agency. This ID allows tenants to map Producerflow agencies back to their own system's identifiers. Set during agency creation/onboarding via the public API.

Agency.AgencyInfo.ExternalMetadataEntry

Field Type Label Description
key string
value string

Agency.AgencyInfo.MetadataQuestionsEntry

Field Type Label Description
key string
value string

Agency.AgencyInfo.TenantAdditionalQuestionsEntry

Field Type Label Description
key string
value string

Agency.BankAccount

BankAccount contains information about a bank account for commission payments.

Field Type Label Description
account_number string Account number for the bank account.
routing_number string Routing number for the bank. This is a nine-digit code identifying the financial institution.
account_type Agency.BankAccount.AccountType Type of account (checking or savings). Indicates how the account should be treated for electronic transfers.
account_holder_name string Name of the account holder as it appears on bank records.

Agency.BusinessHours

BusinessHours contains the operating hours of the agency.

Field Type Label Description
timezone string Timezone of the agency.
business_hours Agency.BusinessHours.BusinessHour repeated List of business hour entries.

Agency.BusinessHours.BusinessHour

BusinessHour represents operating hours for specific days.

Field Type Label Description
week_days google.type.DayOfWeek repeated Days of the week when the agency is open.
opening_time google.type.TimeOfDay Time when the agency opens.
closing_time google.type.TimeOfDay Time when the agency closes.

Agency.EOInfo

EOInfo contains Errors & Omissions insurance information

Field Type Label Description
carrier string Insurance carrier providing the E&O coverage
expiration_date google.protobuf.Timestamp Date when the E&O coverage will expire
coverage_amount string Amount of coverage provided by the E&O policy (aggregate limit)
per_occurrence string Per occurrence limit for the E&O policy
effective_date google.protobuf.Timestamp Effective date of the E&O policy

Agency.IvansAccount

IvansAccount contains information for IVANS integration. IVANS is a system for electronic communication between insurance agencies and carriers.

Field Type Label Description
account_number string Account number for the IVANS service.
ams_software string Software used for IVANS communication.
ams_version string Version of the IVANS software.
mailbox_number string Mailbox number for the IVANS service. Used for routing electronic messages.

Agency.NIPR

NIPR contains data synchronized from the National Insurance Producer Registry.

Field Type Label Description
biographic Agency.NIPR.Biographic Biographic information from NIPR
addresses Agency.NIPR.Address repeated List of addresses from NIPR.
licenses Agency.NIPR.License repeated List of all licenses held across different states.
regulatory_info Agency.NIPR.RegulatoryInfo Regulatory information from NIPR.
appointments Agency.NIPR.Appointment repeated 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.

Agency.NIPR.Address

Address represents address information from NIPR.

Field Type Label Description
address_type string Type of address (Residence, Business, Mailing).
state string License state: state of the license for which the address is registered in NIPR.
address_state string Address state: state of the actual address registered in NIPR.
street string Deprecated. Deprecated: Use address_line_1 instead.
zip_code string ZIP code of the address.
city string City of the address.
country string Country of the address.
date_updated google.protobuf.Timestamp The date NIPR last updated the address in their system.
updated_at google.protobuf.Timestamp The time when this address information was last fetched from NIPR.
address_line_1 string Primary address line.

Agency.NIPR.Appointment

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
Field Type Label Description
branch_id string Branch identifier for multi-branch agencies. Links the appointment to a specific agency branch, if applicable.
company_name string Name of the insurance company for this appointment. Examples: "State Farm", "Allstate", "Blue Cross Blue Shield"
fein string 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.
co_code string 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
line_of_authority string 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.
loa_code string Standardized code for the Line of Authority. Used for programmatic matching rather than string comparison on the line_of_authority description field.
status string 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.
termination_reason string 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
status_reason_date google.protobuf.Timestamp 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.
appointment_renewal_date google.protobuf.Timestamp Date when the appointment will renew. Appointments typically renew annually. Monitor this date for upcoming renewals to ensure continuous authorization.
agency_affiliations string Additional affiliations or roles the agency has with the carrier. This may include special designations, sub-agency relationships, or other relationship details.

Agency.NIPR.Biographic

Biographic contains basic information from NIPR.

Field Type Label Description
company_name string Company name as recorded in NIPR.
fein string Federal Employer Identification Number.
npn string 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
business_email string Business email address.
business_phone string Business phone number.
updated_at google.protobuf.Timestamp The time when this biographic information was last fetched from NIPR.

Agency.NIPR.License

License contains information about an insurance license.

Field Type Label Description
license_number string 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.
license_state string The two-letter US state or territory code that issued the license. Format: ISO 3166-2 subdivision code (e.g., "CA", "TX", "NY").
residency_status 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.
active bool Indicates whether the license is currently active.
status Agency.NIPR.License.LicenseStatus The current status of the license (valid, expired, etc.).
expiration_date google.protobuf.Timestamp Deprecated. Deprecated: Use expires_on instead.
license_class string 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.
license_class_code int32 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.
issue_date google.protobuf.Timestamp Deprecated. Deprecated: Use issued_on instead.
update_date google.protobuf.Timestamp Deprecated. Deprecated: Use last_updated_on instead.
updated_at google.protobuf.Timestamp The time when this license information was last fetched from NIPR.
expires_on google.type.Date The date when the license will expire if not renewed.
issued_on google.type.Date The date when the license was originally issued.
last_updated_on google.type.Date The date NIPR last updated the license in their system.
lines_of_authority Agency.NIPR.License.LineOfAuthority repeated 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.
license_id string The unique identifier for this license.
designated_home_state string The designated home state for adjuster licenses (ADHS).

Agency.NIPR.License.LineOfAuthority

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.

Field Type Label Description
loa string 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.
active bool Whether this Line of Authority is currently active. Inactive LOAs cannot be used to transact that type of insurance.
issue_date google.protobuf.Timestamp Deprecated. Deprecated: Use issued_on instead.
issued_on google.type.Date The date when this Line of Authority was first issued. This helps track how long the agency has been authorized for this insurance type.

Agency.NIPR.RegulatoryInfo

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.

Field Type Label Description
regulatory_actions Agency.NIPR.RegulatoryInfo.RegulatoryAction repeated 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.

Agency.NIPR.RegulatoryInfo.RegulatoryAction

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.

Field Type Label Description
action_id string Unique identifier for the regulatory action in NIPR's system.
state_code string The two-letter state code of the regulatory authority that took the action. Format: US state code (e.g., "CA", "TX", "NY").
reason_for_action string 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.
disposition string The outcome or resolution of the regulatory action.
date_of_action google.protobuf.Timestamp The date when the regulatory action was formally initiated or filed.
effective_date google.protobuf.Timestamp 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.
enter_date google.protobuf.Timestamp The date when the agency entered into or acknowledged the regulatory action (e.g., signed a consent agreement).
file_ref string 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.
penalty_fine_forfeiture string Any financial penalties, fines, or forfeitures associated with the regulatory action. Format: Free-text, typically a dollar amount (e.g., "$5,000.00").
length_of_order string Duration of any orders associated with the regulatory action. Format: Free-text describing the time period (e.g., "12 months", "Indefinite", "Until compliance").

Agency.Principal

Principal is a data structure that represents the principal of a agency. A principal is the person or entity that is responsible for the day-to-day operations of the agency. The principal is usually the CEO or CFO of the agency.nThe principal is also known as the "owner" of the agency.

Field Type Label Description
id string Unique identifier for the principal (as a producer).
first_name string First name of the principal.
last_name string Last name of the principal.
middle_name string Middle name of the principal.
email string Email address of the principal. Must be unique and is used for communication.
npn string 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
phone string Phone number of the principal. Used for communication.
address Agency.Address Address of the principal. This may differ from the agency address.
tenant_additional_questions Agency.Principal.TenantAdditionalQuestionsEntry repeated 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.

Agency.Principal.TenantAdditionalQuestionsEntry

Field Type Label Description
key string
value string

AgencyAlreadyExistsErrorDetail

AgencyAlreadyExistsErrorDetail identifies the agency that already exists when a NewAgency call fails with ALREADY_EXISTS, so you can link the existing record on your side — store its agency ID, assign your own external ID with SetExternalID, or check which organization it belongs to — without searching for it in a follow-up call.

Which agency it identifies:

  • Agency email or agency NPN conflict: the existing agency that holds the email or NPN (for sole-proprietor requests, the email checked is the principal's).
  • Principal email conflict: the agency of the existing producer that already uses the email.
  • Sole-proprietor NPN conflict: the existing sole-proprietor agency registered under the principal's NPN.

How to decode it: The detail travels in the error's details list as a google.protobuf.Any with the message type producerflow.producer.v1.AgencyAlreadyExistsErrorDetail. Connect and gRPC clients expose it through their standard error-details APIs. The detail is provided on a best-effort basis, so handle its absence gracefully.

Field Type Label Description
agency_id string Unique identifier (UUID format) of the existing agency. Use it with GetAgency, or any other API operation that references an agency, to retrieve the full record.
external_id string Your system's identifier for the existing agency, as provided at creation (tenant_agency_id) or assigned later with SetExternalID. Empty when no external ID has been assigned yet.
npn string National Producer Number (NPN) of the existing agency. Empty for sole-proprietor agencies, whose NPN lives on the principal.
organization_id string Unique identifier of the organization the existing agency belongs to, usable with GetOrganization. Empty when the agency is not part of any organization.

AgencySummary

AgencySummary provides essential agency information for list views and quick reference.

This message is optimized for displaying agencies in lists, tables, and search results without the overhead of full NIPR data. It contains only the most commonly needed fields for agency identification and basic contact information.

For complete agency information including NIPR data, licenses, appointments, and associated producers, use the GetAgencyAndProducers RPC.

Field Type Label Description
agency_id string Unique identifier for the agency (UUID format). Use this ID to retrieve full agency details via GetAgencyAndProducers.
name string The official name of the agency. This is typically the legal business name.
email string Primary email address for the agency. Used for general communication and must be unique within the tenant.
phone string Main phone number for the agency. Format may vary but typically includes country code for international numbers.
npn string 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.
fein string Federal Employer Identification Number (FEIN). Nine-digit number assigned by the IRS for tax purposes. May be empty for sole proprietors or agencies without FEIN.
organization_id string optional Organization ID that the agency belongs to. References organizations like aggregators or agency networks. Optional field - null if the agency isn't part of an organization.
is_tenant_agency bool Indicates whether this is an internal tenant agency. True for agencies owned/operated by the tenant. False for external/partner agencies.
is_sole_proprietor bool Indicates whether this agency is a sole proprietor. True: Individual producer operating as their own agency (ENTITY_TYPE_SOLE_PROPRIETOR). False: Standard agency with multiple producers (ENTITY_TYPE_AGENCY).
created_at google.protobuf.Timestamp Timestamp when the agency was created in the system. Used for sorting agencies by creation date in list views. Always in UTC timezone.
external_id string Tenant-provided external identifier for this agency. This ID allows tenants to map Producerflow agencies back to their own system's identifiers. Set during agency creation/onboarding via the public API.
organization_relationship AgencyOrganizationRelationship optional 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

AssignProducerToLocationsRequest

AssignProducerToLocationsRequest assigns locations to a producer.

Field Type Label Description
producer_id string Required. Producer ID to assign locations to.
location_ids string repeated Required. Location IDs to assign (1-100 items). These locations must belong to the same agency as the producer.

AssignProducerToLocationsResponse

AssignProducerToLocationsResponse contains the assigned location IDs.

Field Type Label Description
assigned_location_ids string repeated IDs of successfully assigned locations.

Contact

Contact represents a contact associated with an agency. Contacts are non-producer individuals linked to the agency.

Field Type Label Description
id string Unique identifier for the contact.
first_name string First name of the contact.
middle_name string Middle name of the contact.
last_name string Last name of the contact.
email string Email address of the contact. Must be unique within the tenant.
phone string Phone number of the contact.
role string Deprecated. Role or position of the contact within the agency. Deprecated: Use role_type instead. This field will be removed in a future version.
address Address Mailing address of the contact.
npn string 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
created_at google.protobuf.Timestamp When the contact was created.
role_type ContactRole The role type of the contact as an enum. This field replaces the deprecated string-based 'role' field.
external_metadata Contact.ExternalMetadataEntry repeated ExternalMetadata contains additional custom information that the tenant stores in ProducerFlow's data model. This field allows tenants to attach arbitrary key-value pairs to contacts for their own business logic, reporting, or integration needs. The map key is the metadata field name, and the value is the associated data.
external_id string Tenant-provided external identifier for this contact. This ID allows tenants to map Producerflow contacts back to their own system's identifiers. Set via SetExternalID. Empty string if the tenant has not assigned one.
agency Contact.Agency Basic information about the agency this contact is associated with.
organization Organization Organization that the contact's agency belongs to. This field contains the full organization details including id, name, and contact information. Unset when the contact's agency does not belong to any organization.

Contact.Agency

Agency contains basic information about the agency this contact is associated with. Use GetAgency to read the rest of the agency's details.

Field Type Label Description
agency_id string Unique identifier for the associated agency.
name string Name of the associated agency.
external_id string Tenant-provided external identifier for the associated agency. This ID allows tenants to map Producerflow agencies back to their own system's identifiers without an extra GetAgency call. Set during agency creation/onboarding via the public API.

Contact.ExternalMetadataEntry

Field Type Label Description
key string
value string

CreateAgencyOnboardingURLRequest

CreateAgencyOnboardingURLRequest contains information needed to generate an agency onboarding URL. This includes basic agency information and defaults.

All fields in this request are optional. You can provide as much or as little information as you have available. Any missing information will be collected from the user during the onboarding process through the generated URL.

Field Type Label Description
agency CreateAgencyOnboardingURLRequest.Agency

CreateAgencyOnboardingURLRequest.Agency

Agency contains the information about the agency to be onboarded. All fields within the Agency message are also optional.

Field Type Label Description
name string Name of the agency
entity_type EntityType Entity type of the agency: Sole Proprietor, Agency or Ask during onboarding
tenant_agency_id string Tenant agency id is a unique identifier for the agency used by the tenant this is used to identify the agency in the tenant system not in the producerflow system
docusign_template_id string Deprecated. 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.
fein string FEIN (Federal Employer Identification Number) of the agency
email string Email of the agency Important: For Sole Proprietor entities (entity_type = ENTITY_TYPE_SOLE_PROPRIETOR) or when entity_type = ENTITY_TYPE_ASK_DURING_ONBOARDING and the user later selects Sole Proprietor during onboarding, the principal.email will be used as the agency email, and this field will be ignored.
phone string Phone of the agency
fax string Fax of the agency
website string Website of the agency
npn string 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
mailing_address Address Mailing address of the agency
physical_address Address Physical address of the agency
invoicing_address Address Invoicing address of the agency
organization_id string Organization ID of the agency. To get valid organization IDs, use the ListOrganizations RPC.
signature_template_id string optional 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.
organization_relationship AgencyOrganizationRelationship optional Relationship the agency will have with the organization once onboarded: - MAIN: The agency owns or manages the organization. - RELATED: The agency is part of the organization but not the primary owner. Only allowed when organization_id is set. If not provided, the agency is attached to the organization as RELATED.
principal CreateAgencyOnboardingURLRequest.Agency.Principal

CreateAgencyOnboardingURLRequest.Agency.Principal

Principal is the person responsible for the agency. All fields within the Principal message are also optional.

Field Type Label Description
tenant_id string Optional. External identifier for the principal in the tenant's system. This field allows tenants to maintain a reference to their own internal ID for this principal, enabling bi-directional synchronization between ProducerFlow and the tenant's system. Usage: Provide this when you have an existing identifier for the principal in your system. Omit if you don't need to track a reference to your internal system. This is independent of ProducerFlow's internal IDs and the authentication tenant context. Format: Any string identifier that is meaningful in your system (e.g., "USR-12345", "uuid"). Validation: Maximum length of 255 characters.
first_name string First name of the principal
last_name string Last name of the principal
middle_name string Middle name of the principal
email string Email of the principal
phone string Phone of the principal
npn string 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
address Address Address of the principal

CreateAgencyOnboardingURLResponse

CreateAgencyOnboardingURLResponse contains the generated URL for agency onboarding

Field Type Label Description
url string URL that can be shared with the agency for self-onboarding

CreateOrganizationRequest

CreateOrganizationRequest contains the information needed to create a new organization.

Field Type Label Description
name string Required. The display name of the organization. Must be unique within the tenant.
external_id string Optional. The external identifier for the organization. This is the identifier used by the tenant's system to identify the organization.
email string Optional. The contact email address for the organization.

CreateOrganizationResponse

CreateOrganizationResponse contains the result of creating a new organization.

Field Type Label Description
organization_id string The unique identifier of the newly created organization.

CreateProducerOnboardingURLRequest

Field Type Label Description
agency_id string Agency ID for which the producer will be onboarded
producer_data ProducerData Optional producer data to pre-fill in the onboarding form

CreateProducerOnboardingURLResponse

Field Type Label Description
onboarding_url string The secure onboarding URL that can be shared with the producer

CreateProducerUploadURLRequest

CreateProducerUploadURLRequest contains information needed to generate a producer upload URL. This includes the agency NPN.

Field Type Label Description
agency_npn string The National Producer Number (NPN) of the agency. Required and must be a valid NPN format (numeric string between 2-10 digits).

CreateProducerUploadURLResponse

CreateProducerUploadURLResponse contains the generated URL for producer uploads

Field Type Label Description
url string URL that can be shared with the agency for producer uploads. The URL is time-limited and includes necessary security tokens.

GetAgencyAndProducersRequest

Deprecated: Use GetAgencyRequest/GetAgencyProducersRequest instead.

Field Type Label Description
agency_id string

GetAgencyAndProducersResponse

Deprecated: Use GetAgencyResponse/GetAgencyProducersResponse instead.

Field Type Label Description
agency Agency
producers Producer repeated

GetAgencyFilesRequest

GetAgencyFilesRequest requests URLs for files associated with an agency.

Field Type Label Description
agency_id string The UUID of the agency to retrieve files for. Must be a valid UUID format.

GetAgencyFilesResponse

GetAgencyFilesResponse contains URLs for various documents associated with an agency.

Field Type Label Description
eo_doc_url string URL of the Errors & Omissions (E&O) insurance document.
voided_check_doc_url string URL of the bank voided check document. It's used to safely share bank account information for electronic transfers.
w9_doc_url string URL of the W9 form document. It's a U.S. internal revenue service form, an identification document used in the onboarding process for tax reporting purposes.
license_doc_url string URL of the license document. An identification document that shows that the agency is licensed to carry out its operations in the relevant jurisdictions.
broker_bond_doc_url string URL of the broker bond document. It's a surety bond that a broker needs to operate legally, providing financial security for clients.

GetAgencyProducersRequest

GetAgencyProducersRequest requests all producers associated with an agency.

Field Type Label Description
agency_id string The UUID of the agency to retrieve producers for. Must be a valid UUID format.
pagination Pagination Optional. Pagination parameters for controlling result set size and navigation. If not provided, defaults to page_size=50. Maximum page_size is 200.

GetAgencyProducersResponse

GetAgencyProducersResponse contains producers associated with the specified agency.

Field Type Label Description
producers Producer repeated List of producers for the current page.
next_page_token string Token for retrieving the next page of results. Empty when there are no more results.

GetAgencyRequest

GetAgencyRequest requests information about a specific agency.

Field Type Label Description
agency_id_lookup GetAgencyRequest.AgencyIDLookup Look up agency by ID.
tenant_agency_id_lookup GetAgencyRequest.AgencyTenantAgencyIDLookup Look up agency by tenant agency ID.

GetAgencyRequest.AgencyIDLookup

AgencyIDLookup allows looking up an agency by its unique identifier.

Field Type Label Description
agency_id string The UUID of the agency to retrieve. Must be a valid UUID format.

GetAgencyRequest.AgencyTenantAgencyIDLookup

AgencyTenantAgencyIDLookup allows looking up an agency by its tenant-specific agency ID.

Field Type Label Description
tenant_agency_id string The tenant-specific agency ID to retrieve. Must be a non-empty string.

GetAgencyResponse

GetAgencyResponse contains the complete agency information.

Field Type Label Description
agency Agency Complete agency information including contact details, addresses, principal, bank account, E&O coverage, NIPR data, and locations.

GetContactRequest

GetContactRequest looks up a single contact, without requiring the agency to be known in advance. Exactly one lookup method must be provided.

Field Type Label Description
contact_id_lookup GetContactRequest.ContactIDLookup
external_id_lookup GetContactRequest.ExternalIDLookup

GetContactRequest.ContactIDLookup

ContactIDLookup looks up a contact by its internal UUID.

Field Type Label Description
contact_id string The UUID of the contact to retrieve.

GetContactRequest.ExternalIDLookup

ExternalIDLookup looks up a contact by its tenant-defined external ID.

Field Type Label Description
external_id string The tenant-defined external identifier of the contact to retrieve.

GetContactResponse

GetContactResponse contains the single matched contact.

Field Type Label Description
contact Contact The matched contact, including its external_id and external_metadata.

GetOrganizationRequest

GetOrganizationRequest specifies which organization to retrieve detailed information for.

Use this request to fetch comprehensive details about a specific organization, including all agencies assigned to it and their current status.

Field Type Label Description
organization_id string Unique identifier of the organization to retrieve. This must be a valid UUID that was previously returned from: - ListOrganizations response - Agency creation response (when agency is assigned to an organization) - Other API calls that reference organizations The organization must belong to your authenticated tenant; attempting to access organizations from other tenants will result in a NOT_FOUND error. Format: Standard UUID v4 (e.g., "123e4567-e89b-12d3-a456-426614174000")

GetOrganizationResponse

GetOrganizationResponse contains details about the requested organization.

Field Type Label Description
organization Organization The requested organization with all available details.

GetProducerRequest

GetProducerRequest allows retrieving producer information through one of four possible lookup methods: by ID, by NPN, by email address, or by external ID.

Field Type Label Description
producer_id_lookup GetProducerRequest.ProducerIDLookup Look up producer by ID.
npn_lookup GetProducerRequest.ProducerNPNLookup Look up producer by NPN.
email_lookup GetProducerRequest.EmailLookup Look up producer by email.
external_id_lookup GetProducerRequest.ExternalIDLookup Look up producer by external ID set via SetExternalID.

GetProducerRequest.EmailLookup

EmailLookup allows looking up a producer by their email address.

Field Type Label Description
email string The email address of the producer to retrieve. Must be a valid email format.

GetProducerRequest.ExternalIDLookup

ExternalIDLookup allows looking up a producer by the external identifier previously set via the SetExternalID RPC.

Field Type Label Description
external_id string 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.

GetProducerRequest.ProducerIDLookup

ProducerIDLookup allows looking up a producer by their unique identifier.

Field Type Label Description
producer_id string The UUID of the producer to retrieve. Must be a valid UUID format.

GetProducerRequest.ProducerNPNLookup

ProducerNPNLookup allows looking up a producer by their National Producer Number (NPN).

Field Type Label Description
producer_npn string The National Producer Number (NPN) of the producer to retrieve. Must be a non-empty string.

GetProducerResponse

GetProducerResponse contains the producer information retrieved by the GetProducer RPC.

Field Type Label Description
producer Producer The complete producer information including personal details, agency association, and NIPR data.

ListAgenciesRequest

ListAgenciesRequest enables flexible querying of agencies with multiple filter options and pagination support.

All filters are optional and can be combined for precise results. When multiple filters are specified, they are applied with AND logic (agencies must match all specified criteria).

Example Use Cases:

  • Get all agencies in an organization: set organization_id
  • Search for an agency by name: set search_query
  • Find failing NIPR syncs: set nipr_sync_statuses to [NIPR_SYNC_STATE_FAILING]
  • Get sole proprietors only: set entity_type to ENTITY_TYPE_SOLE_PROPRIETOR
  • Paginate through all agencies: use pagination with page_token
Field Type Label Description
organization_id string optional Optional. Filter agencies by organization ID. Only agencies belonging to this specific organization will be returned. Must be a valid UUID if provided. Use ListOrganizations to get valid organization IDs.
search_query string optional Optional. Free-text search across agency fields. Searches in: agency name, NPN, and email address. The search is case-insensitive and uses partial matching. Example: "smith" will match "Smith Insurance Agency" and "john.smith@agency.com"
pagination Pagination Optional. Pagination parameters for controlling result set size and navigation. If not provided, defaults to page_size=50 with no offset. Maximum allowed page_size is 200; values above this will be capped.
agency_type AgencyType optional Optional. Filter by agency classification (internal vs external). - AGENCY_TYPE_INTERNAL: Agencies owned/operated by the tenant - AGENCY_TYPE_EXTERNAL: Partner or third-party agencies If not specified, returns both internal and external agencies.
entity_type EntityType optional Optional. Filter by business entity structure. - ENTITY_TYPE_SOLE_PROPRIETOR: Individual producers as agencies - ENTITY_TYPE_AGENCY: Standard multi-producer agencies If not specified, returns both sole proprietors and standard agencies.
nipr_sync_statuses NIPRSyncState repeated Optional. Filter by NIPR synchronization status. Multiple statuses can be specified to match agencies in any of those states. Useful for monitoring sync health and identifying agencies needing attention. Valid values: ACTIVE, FAILING, PENDING, DISABLED If empty, returns agencies in all sync states.
resident_states string repeated 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).
licensed_states string repeated 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).

ListAgenciesResponse

ListAgenciesResponse provides paginated agency results with metadata for navigation and total counts.

The response is optimized for UI display with summary data only. For complete agency information including NIPR data, use GetAgencyAndProducers with the agency_id from the summary.

Pagination Notes:

  • Results are always ordered by creation date (newest first)
  • Page tokens are opaque and should not be constructed by clients
  • Total count reflects all matching agencies, not just the current page
  • Empty agencies list with total_count > 0 indicates you've paginated past the end
Field Type Label Description
agencies AgencySummary repeated List of agency summaries matching the filter criteria. Ordered by creation date with the most recently created agencies first. Will be empty if no agencies match the filters or if paginating past the last page. Maximum of page_size agencies per response (default 50, max 200).
next_page_token string Pagination token for retrieving the next page of results. Pass this value as page_token in the next request to continue pagination. Empty string indicates this is the last page of results. Tokens are opaque and their format may change; treat as black box.
total_count int32 Total number of agencies matching the filter criteria across all pages. This count is independent of pagination and represents the full result set. Useful for displaying "Showing X-Y of Z agencies" in UIs. Will be 0 if no agencies match the specified filters.

ListAgencyContactsRequest

ListAgencyContactsRequest requests all contacts associated with an agency.

Field Type Label Description
agency_id string The UUID of the agency to retrieve contacts for. Must be a valid UUID format.

ListAgencyContactsResponse

ListAgencyContactsResponse contains all contacts associated with an agency.

Field Type Label Description
contacts Contact repeated List of all contacts associated with the specified agency.

ListAgencyLocationsRequest

ListAgencyLocationsRequest retrieves all locations for an agency.

Field Type Label Description
agency_id string Required. Agency ID to list locations for.

ListAgencyLocationsResponse

ListAgencyLocationsResponse contains the list of agency locations.

Field Type Label Description
locations Location repeated List of all locations associated with the agency.

ListNewProducersRequest

ListNewProducersRequest requests a list of new producers, optionally filtered by agency.

Field Type Label Description
agency_id string optional Optional agency ID to filter producers by. If provided, only producers belonging to this agency will be returned. If not provided, producers from all agencies will be returned.

ListNewProducersResponse

ListNewProducersResponse contains a list of new producers that match the filter criteria.

Field Type Label Description
new_producers Producer repeated List of new producers matching the filter criteria. These are producers typically in the NEW or pending onboarding state.

ListOrganizationsRequest

ListOrganizationsRequest requests a list of all organizations associated with the authenticated tenant.

Organizations provide a way to group agencies into logical business units, networks, or aggregator relationships. This endpoint returns all organizations accessible to your tenant, which can be used to:

  • Display organization hierarchies in user interfaces
  • Filter agencies by organization
  • Apply organization-specific business rules or workflows

The response supports pagination for tenants with large numbers of organizations.

Field Type Label Description
pagination Pagination Optional pagination parameters to control the result set. Pagination allows you to retrieve organizations in manageable chunks: - page_size: Number of organizations to return (default: 50, max: 200) - page_token: Token from previous response to get the next page Example usage: - First request: page_size=100 (returns first 100 organizations) - Subsequent requests: Use next_page_token from previous response If omitted, returns the first 50 organizations.

ListOrganizationsResponse

ListOrganizationsResponse contains the paginated list of organizations for the tenant.

The response includes all organizations accessible to your authenticated tenant, ordered alphabetically by name for consistent display. Empty results indicate that your tenant either doesn't use organizational hierarchies or has no organizations configured yet.

Pagination is automatically applied to large result sets to ensure optimal performance and reasonable response sizes.

Field Type Label Description
organizations Organization repeated List of organizations associated with the tenant. Each organization in the list includes: - Unique identifier (id) for API operations - Display name for user interfaces - External ID for system integration - Contact email (if configured) The list may be empty ([]) if: - No organizations are configured for your tenant - Your tenant doesn't use organizational hierarchies
next_page_token string Pagination token for retrieving the next page of results. When present, indicates more organizations are available. Pass this token as the page_token in the next ListOrganizationsRequest to retrieve the subsequent page. Empty string or omitted field indicates this is the last page. Important: Tokens are opaque and may expire. Don't store tokens long-term; retrieve fresh data when needed.
total_count int32 Total count of organizations matching the filter criteria. This count represents the total number of organizations available to your tenant, regardless of pagination. Use this to: - Display result counts in user interfaces ("Showing 1-50 of 237") - Calculate the number of pages available - Determine if pagination is needed The count remains consistent across paginated requests unless organizations are added or removed between calls.

ListProducerRolesRequest

ListProducerRolesRequest is the empty request for the ListProducerRoles RPC. The tenant is determined from the authenticated API key.

ListProducerRolesResponse

ListProducerRolesResponse contains the producer role labels configured for the authenticated tenant.

Field Type Label Description
roles string repeated The list of producer role labels available for the authenticated tenant, in the order they were configured. Empty when the tenant has not configured any roles.

Location

Location represents a physical or virtual location where an agency operates. Each location includes address information and optional contact details.

Field Type Label Description
id string Unique identifier for the location.
name string Required. Name of the location. Must be unique within the agency.
address Address Required. Physical address of the location.
phone string Required. Phone number for the location.
email string Required. Email address for the location.
is_primary bool Whether this is the primary location for the agency.
external_id string Tenant-specific external ID for this location.

LocationInput

LocationInput represents the input data for creating a new location.

Field Type Label Description
name string Required. Name of the location. Must be unique within the agency.
address Address Required. Physical address of the location.
phone string Required. Phone number for the location.
email string Required. Email address for the location.
is_primary bool Whether this should be marked as the primary location.

LookupNPNByFEINRequest

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.

Field Type Label Description
fein string The Federal Employer Identification Number (FEIN) to look up. Format: Exactly 9 digits, no dashes or spaces. Example: "123456789" This is the tax identification number assigned by the IRS.

LookupNPNByFEINResponse

LookupNPNByFEINResponse contains the National Producer Number (NPN) for the agency associated with the given FEIN.

Field Type Label Description
npn string 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.

NewAgencyRequest

NewAgencyRequest contains complete information for creating a new agency

Field Type Label Description
agency NewAgencyRequest.Agency
sync_with_nipr bool optional Optional. Overrides the tenant's default NIPR sync setting during onboarding. Most tenants have this enabled by default, so it usually doesn't need to be set. If specified, this value takes precedence over the tenant's default behavior.

NewAgencyRequest.Agency

Agency contains all information about the agency to be created

Field Type Label Description
name string The name of the agency.
email string The email address of the agency.
npn string 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
phone string optional The phone number of the agency.
website string The website of the agency.
principal NewAgencyRequest.Agency.Principal Information about the agency's principal. This is a required field as each agency must have a principal.
bank_account NewAgencyRequest.Agency.BankAccount
eo_info NewAgencyRequest.Agency.EOInfo
business_hours NewAgencyRequest.Agency.BusinessHours
producers NewProducer repeated List of producers associated with the agency
points_of_contact NewAgencyRequest.Agency.PointOfContact repeated
root_organization_id string optional RootOrganizationID 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. To get valid organization IDs, use the ListOrganizations RPC.
organization_relationship AgencyOrganizationRelationship optional Relationship the agency will have with the organization referenced by root_organization_id: - MAIN: The agency owns or manages the organization. - RELATED: The agency is part of the organization but not the primary owner. Only allowed when root_organization_id is set. If not provided, the agency is attached to the organization as RELATED. Supported for both entity types, including ENTITY_TYPE_SOLE_PROPRIETOR.
entity_type EntityType EntityType represents the type of business entity for an agency.
fein string optional FEIN represents the Federal Employer Identification Number of the agency. Required for ENTITY_TYPE_AGENCY Not allowed for ENTITY_TYPE_SOLE_PROPRIETOR
mailing_address Address MailingAddress represents the mailing address of the agency.
physical_address Address PhysicalAddress represents the physical address of the agency.
invoicing_address Address InvoicingAddress represents the invoicing address of the agency.
tenant_agency_id string TenantAgencyID represents the ID of the agency in the tenant. This is used to link the agency to the tenant.
locations LocationInput repeated Optional field that allows specifying multiple locations during agency creation.
metadata_questions NewAgencyRequest.Agency.MetadataQuestionsEntry repeated Deprecated. MetadataQuestions contains custom metadata questions and answers for the agency. The map key is the question identifier/text, and the value is the answer provided. This field is deprecated and will be removed in a future release.
tenant_additional_questions NewAgencyRequest.Agency.TenantAdditionalQuestionsEntry repeated 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.
ivans_account NewAgencyRequest.Agency.IvansAccount IVANS account information for electronic carrier communication. This is optional and only used if the agency uses IVANS.
external_metadata NewAgencyRequest.Agency.ExternalMetadataEntry repeated ExternalMetadata is custom key-value metadata the tenant stores in Producerflow's data model, populated programmatically via API. Keys are trimmed before storage. At creation an absent or empty map leaves the metadata unset (unlike UpdateAgency, where an empty map clears it). Distinct from tenant_additional_questions and from tenant_agency_id/tenant_id.

NewAgencyRequest.Agency.BankAccount

BankAccount contains banking information for commission payments This is used to store the bank account information for the agency

Field Type Label Description
account_number string
routing_number string Routing number for the bank account
account_type NewAgencyRequest.Agency.BankAccount.AccountType Type of account (checking or savings)
account_holder_name string Name of the account holder

NewAgencyRequest.Agency.BusinessHours

BusinessHours contains the business hours of the agency

Field Type Label Description
timezone string Timezone of the agency
business_hours NewAgencyRequest.Agency.BusinessHours.BusinessHour repeated

NewAgencyRequest.Agency.BusinessHours.BusinessHour

Field Type Label Description
week_days google.type.DayOfWeek repeated Days of the week when the agency is open
opening_time google.type.TimeOfDay Time when the agency opens
closing_time google.type.TimeOfDay Time when the agency closes

NewAgencyRequest.Agency.EOInfo

EOInfo contains Errors & Omissions insurance information

Field Type Label Description
carrier string Insurance carrier providing the E&O coverage
expiration_date google.protobuf.Timestamp Date when the E&O coverage will expire
coverage_amount string Amount of coverage provided by the E&O policy (aggregate limit)
effective_date google.protobuf.Timestamp Date when the E&O coverage will become effective
per_occurrence string Per occurrence limit for the E&O policy

NewAgencyRequest.Agency.ExternalMetadataEntry

Field Type Label Description
key string
value string

NewAgencyRequest.Agency.IvansAccount

IvansAccount contains IVANS (Insurance Value Added Network Services) account information. IVANS is used for electronic communication between insurance agencies and carriers.

Field Type Label Description
account_number string Account number for the IVANS service.
ams_software string Software used for IVANS communication (AMS - Agency Management System).
ams_version string Version of the AMS software.
mailbox_number string Mailbox number for the IVANS service. Used for routing electronic messages.

NewAgencyRequest.Agency.MetadataQuestionsEntry

Field Type Label Description
key string
value string

NewAgencyRequest.Agency.PointOfContact

PointOfContact contains contact information for the agency. Each point of contact consists of an email address with an associated role. Carriers will send specific information to these email addresses based on their roles. For example, if an email is assigned the COMMUNICATION_ROLE_ACCOUNTING role, all accounting information from the carrier will be sent to that email address.

Field Type Label Description
email string Email address of the point of contact
role NewAgencyRequest.Agency.PointOfContact.CommunicationRole Role of the point of contact

NewAgencyRequest.Agency.Principal

Principal is a data structure that represents the principal of a agency. A principal is the person or entity that is responsible for the day-to-day operations of the agency. The principal is usually the CEO or CFO of the agency.nThe principal is also known as the "owner" of the agency.

Field Type Label Description
first_name string The first name of the principal.
last_name string The last name of the principal.
middle_name string The middle name of the principal.
email string The email address of the principal.
phone string optional The phone number of the principal.
npn string 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
tenant_id string Optional. External identifier for the principal in the tenant's system. This field allows tenants to maintain a reference to their own internal ID for this principal, enabling bi-directional synchronization between ProducerFlow and the tenant's system. Usage: Provide this when you have an existing identifier for the principal in your system. Omit if you don't need to track a reference to your internal system. This is independent of ProducerFlow's internal IDs and the authentication tenant context. Format: Any string identifier that is meaningful in your system (e.g., "USR-12345", "uuid"). Validation: Maximum length of 255 characters.
sync_with_nipr bool optional Optional. Controls whether the principal should be validated and synced with NIPR. If set to false, the principal's NPN will not be validated against NIPR and the principal will not be synced with NIPR. Defaults to true if not specified.
tenant_additional_questions NewAgencyRequest.Agency.Principal.TenantAdditionalQuestionsEntry repeated 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.
mailing_address Address The mailing address of the principal. This is where correspondence for the principal will be sent.
external_metadata NewAgencyRequest.Agency.Principal.ExternalMetadataEntry repeated ExternalMetadata is custom key-value metadata the tenant stores in Producerflow's data model, populated programmatically via API. Keys are trimmed before storage. At creation an absent or empty map leaves the metadata unset (unlike UpdateProducer, where an empty map clears it). Distinct from tenant_additional_questions and from tenant_id/tenant_agency_id. When the principal is unlicensed (no NPN), the metadata is stored on the principal Contact.

NewAgencyRequest.Agency.Principal.ExternalMetadataEntry

Field Type Label Description
key string
value string

NewAgencyRequest.Agency.Principal.TenantAdditionalQuestionsEntry

Field Type Label Description
key string
value string

NewAgencyRequest.Agency.TenantAdditionalQuestionsEntry

Field Type Label Description
key string
value string

NewAgencyResponse

NewAgencyResponse contains the IDs of created resources after a successful agency creation

Field Type Label Description
agency_id string Unique identifier for the created agency
producer_ids string repeated List of unique identifiers for any producers created with the agency
principal_id string Unique identifier for the principal producer
location_ids string repeated IDs of the locations created for the agency (if any were provided in the request)

NewContact

NewContact represents the data needed to create a new contact in the system. Contacts represent non-producer individuals associated with an agency.

Field Type Label Description
first_name string First name of the contact. Required and must be non-empty.
last_name string Last name of the contact. Required and must be non-empty.
middle_name string Middle name of the contact. Optional.
email string Email address of the contact. Required and must be a valid email format. Must be unique within the tenant.
phone string optional Phone number of the contact. Optional if default value, but if provided must match the pattern of a valid phone number.
address Address Mailing address of the contact.
role ContactRole Role or position of the contact within the agency. Required and must be a valid ContactRole enum value (not UNSPECIFIED). See ContactRole enum for available options.
tenant_id string Optional. External identifier for the contact in the tenant's system. This field allows tenants to maintain a reference to their own internal ID for this contact, enabling bi-directional synchronization between ProducerFlow and the tenant's system. Usage: Provide this when you have an existing identifier for the contact in your system. Omit if you don't need to track a reference to your internal system. This is independent of ProducerFlow's internal IDs and the authentication tenant context. Can be used with SetExternalID RPC to update this value after creation. Common use cases: Linking to an existing CRM or AMS system contact ID. Maintaining synchronization with legacy systems. Enabling lookups from external systems back to ProducerFlow. Format: Any string identifier that is meaningful in your system (e.g., "CONT-12345", "uuid"). Validation: Maximum length of 255 characters
npn string optional 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

NewContactRequest

NewContactRequest is used to create a new contact and associate it with an agency.

Field Type Label Description
agency_id string The UUID of the agency to associate the contact with. Must be a valid UUID format.
contact NewContact Information about the contact to create.

NewContactResponse

NewContactResponse contains the ID of the created contact.

Field Type Label Description
contact_id string The UUID of the created contact. Must be a valid UUID format.

NewContactsRequest

NewContactsRequest is used to create multiple contacts in a single request. All contacts will be associated with the specified agency.

Field Type Label Description
agency_id string The UUID of the agency to associate the contacts with. Must be a valid UUID format.
contacts NewContact repeated List of contacts to create. This field is required and must contain at least one contact.

NewContactsResponse

NewContactsResponse contains the IDs of all created contacts.

Field Type Label Description
contact_ids string repeated List of UUIDs for the newly created contacts. The order matches the order of contacts in the request.

NewProducer

NewProducer represents the data needed to create a new producer in the system.

This message is used by both NewProducer (single) and NewProducers (bulk) RPCs to define producer information during creation. Producers are licensed insurance professionals who can sell insurance products on behalf of carriers.

Required vs Optional Fields:

  • Required: first_name, last_name, email
  • Strongly recommended: npn (for NIPR sync and validation)
  • Optional: All other fields

NIPR Integration: If an NPN is provided, the system will validate it against NIPR's database. Depending on the sync_with_nipr setting, it may also fetch complete license, appointment, and regulatory information from NIPR.

Field Type Label Description
first_name string First name of the producer. Required field that must be non-empty. Used for identification and correspondence.
last_name string Last name of the producer. Required field that must be non-empty. Used for identification and formal communications.
middle_name string Middle name of the producer. Optional field for complete name identification. Important for NIPR matching when multiple producers have similar names.
email string Email address of the producer. Required field with email format validation. Must be unique across all producers in the tenant. Used for: - Account notifications and communications - Password resets and authentication - Unique identifier within the system
npn string 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" 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
phone string optional Phone number of the producer. Optional field for contact purposes. If provided, must match international phone number pattern. Format: Can include country code (e.g., +1 for US)
mailing_address NewProducer.Address Mailing address of the producer. Optional but recommended for complete producer profiles. This address is used for physical mail delivery and may differ from the agency's address.
tenant_id string External identifier for the producer in the tenant's system. Optional field that enables bi-directional synchronization between ProducerFlow and your internal systems. This allows you to maintain your existing producer identifiers while leveraging ProducerFlow's capabilities. Usage Guidelines: - Provide this when you have an existing identifier for the producer - Omit if you don't need to track a reference to your internal system - Can be updated later using the SetExternalID RPC - Must be unique within your tenant for meaningful lookups Common Use Cases: - Linking to an existing CRM or AMS system producer ID - Maintaining synchronization with legacy systems - Enabling lookups from external systems back to ProducerFlow - Supporting data migration and system transitions Format: Any string identifier meaningful in your system (e.g., "PROD-12345", UUID) Maximum length: 255 characters
location_ids string repeated Location IDs to assign to the producer during creation. Optional field for associating the producer with specific agency locations. This is useful for multi-location agencies where producers work from or service specific offices. Validation: - All location IDs must be valid UUIDs - All locations must exist and belong to the specified agency - Maximum of 100 locations per producer - Invalid location IDs will cause the entire creation to fail Post-Creation Management: - Use AssignProducerToLocations to add more locations later - Use UnassignProducerFromLocations to remove locations - Use ListAgencyLocations to see available locations for an agency
metadata_questions NewProducer.MetadataQuestionsEntry repeated Deprecated. Custom metadata questions and answers for the producer. Optional field for storing tenant-specific information collected during producer onboarding. This allows tenants to capture additional data points that are important for their business processes but not part of the standard producer fields. Structure: - Key: Question identifier or the question text itself - Value: The producer's answer or response Common Use Cases: - Compliance questionnaires (e.g., "Have you ever had a license revoked?") - Business preferences (e.g., "Preferred carrier partners") - Specializations (e.g., "Areas of expertise") - Internal classifications (e.g., "Producer tier", "Region") Note: This data is stored but not validated by ProducerFlow. Ensure your application handles any necessary validation of the responses. Deprecated: Use tenant_additional_questions instead. This field will be removed in a future release.
tenant_additional_questions NewProducer.TenantAdditionalQuestionsEntry repeated 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.
role string optional Tenant-defined role label for the producer (e.g. "Licensed Producer", "CSR", "Agency Principal"). Optional. When set, the value must match one of the role labels configured for the tenant; otherwise the request is rejected with INVALID_ARGUMENT. Tenants that have not configured any roles should leave this empty.
external_metadata NewProducer.ExternalMetadataEntry repeated ExternalMetadata is custom key-value metadata the tenant stores in Producerflow's data model, populated programmatically via API. Keys are trimmed before storage. At creation an absent or empty map leaves the metadata unset (unlike UpdateProducer, where an empty map clears it). Distinct from tenant_additional_questions and from tenant_id/tenant_agency_id.

NewProducer.Address

Address represents a mailing address for the producer. All fields are required when an address is provided. This address is used for:

  • Official correspondence
  • Licensing documentation
  • Commission statements
Field Type Label Description
street string Deprecated. Deprecated: Use address_line_1 instead.
city string City of the producer's mailing address.
state string State of the producer's mailing address. Must be a valid 2-letter US state code (e.g., "CA", "NY").
zip string Zip code of the producer's mailing address. Supports both 5-digit (12345) and ZIP+4 (12345-6789) formats.
address_line_2 string optional Optional second line of address (apt, suite, unit, etc.)
address_line_1 string Primary address line of the producer. For backward compatibility, either street or address_line_1 can be used.

NewProducer.ExternalMetadataEntry

Field Type Label Description
key string
value string

NewProducer.MetadataQuestionsEntry

Field Type Label Description
key string
value string

NewProducer.TenantAdditionalQuestionsEntry

Field Type Label Description
key string
value string

NewProducerRequest

NewProducerRequest is used to create a new producer and associate it with an agency. This will trigger a call to the NIPR API to retrieve license information of the producer.

Field Type Label Description
agency_id string The UUID of the agency to associate the producer with. Must be a valid UUID format.
producer NewProducer Information about the producer to create. This field is required.
sync_with_nipr bool optional Optional. Overrides the tenant's default NIPR sync setting during onboarding. Most tenants have this enabled by default, so it usually doesn't need to be set. If specified, this value takes precedence over the tenant's default behavior.

NewProducerResponse

NewProducerResponse contains the ID of the created producer.

Field Type Label Description
producer_id string The UUID of the created producer. Must be a valid UUID format.

NewProducersRequest

NewProducersRequest creates multiple producers and associates them with a single agency.

This request supports bulk creation of producers, which is more efficient than making multiple individual NewProducer calls. All producers in the request will be associated with the same agency, making this ideal for onboarding producer teams.

Operation Behavior: Producers are created sequentially. If a producer fails validation, the request returns an error, but any producers created before the failure will remain in the system.

Request Limits:

  • Minimum producers: 1 (enforced by validation)
  • All producers must be for the same agency

Each producer in the list can specify:

  • Basic information (name, email, phone)
  • NPN for NIPR validation and sync
  • Mailing address
  • Location assignments within the agency
  • External ID for tenant system integration
  • Custom metadata questions

Common Use Cases:

  • Bulk importing producers from spreadsheets or CSV files
  • Migrating producer data from legacy systems
  • Setting up new agencies with their initial producer roster
  • Adding multiple producers during mergers or acquisitions
Field Type Label Description
agency_id string The UUID of the agency to associate all producers with. This agency must exist and belong to the authenticated tenant. All producers in the request will be assigned to this single agency.
producers NewProducer repeated List of producers to create in this bulk operation. Required field that must contain at least one producer. Each producer undergoes full validation including NPN verification if provided.
sync_with_nipr bool optional Optional. Overrides the tenant's default NIPR sync setting for all producers in this request. NPN validation is always performed regardless of this setting. When true: Fetches full NIPR EntityInfo data after validation (paid lookup) When false: Skips NIPR EntityInfo fetch, only performs NPN validation When omitted: Uses the tenant's default configuration Cost Implications: Setting this to true will trigger billable NIPR EntityInfo lookups for each producer with an NPN, counting against your monthly quota. Consider using false for test data or when you plan to sync later via SyncProducerWithNIPR.

NewProducersResponse

NewProducersResponse contains the IDs of all successfully created producers.

The response provides a list of producer IDs that directly corresponds to the order of producers in the request, allowing you to map each request entry to its created resource.

Order Guarantee: The producer_ids array maintains the exact same order as the producers array in the request. For example:

  • Request producers[0] → Response producer_ids[0]
  • Request producers[1] → Response producer_ids[1] This ordering guarantee simplifies client-side processing and record keeping.

Post-Creation Actions: After receiving this response, you can:

  • Use the IDs to fetch full producer details via GetProducer
  • Assign producers to locations via AssignProducerToLocations
  • Trigger NIPR sync if it was skipped during creation
  • Set external IDs via SetExternalID if not provided during creation
Field Type Label Description
producer_ids string repeated List of UUIDs for the newly created producers. These IDs are immediately available for use in subsequent API calls. The array length will always match the number of producers in the request. Order is guaranteed to match the request's producer array order.

Organization

Organization represents a logical grouping or hierarchical structure for managing agencies.

Organizations enable better management of insurance distribution networks by grouping agencies into meaningful business units. Common organization types include:

  • Agency networks or clusters
  • Aggregators
  • Geographic regions or territories
  • Franchise groups or corporate structures
  • Market segments or product lines
Field Type Label Description
id string Unique identifier for the organization (UUID format). This ID is system-generated and immutable. Use this ID to: - Reference the organization in API calls (GetOrganization, agency creation) - Establish relationships between organizations and agencies - Track organization-level metrics and reporting Format: Standard UUID v4 (e.g., "123e4567-e89b-12d3-a456-426614174000")
name string Display name of the organization. This is the human-readable name shown in user interfaces and reports. Names must be unique within your tenant (case-insensitive comparison). Best Practices: - Use clear, descriptive names that reflect the organization's purpose - Include geographic or business unit identifiers when relevant - Avoid special characters that may cause display issues Examples: "West Coast Network", "AgencyHero Aggregator", "Premium Partners Group"
external_id string External identifier for the organization. This field maps the ProducerFlow organization to your internal system's organization ID, enabling bi-directional synchronization and integration. Use Cases: - Maintain references to your CRM or ERP system - Enable data synchronization between systems - Support migration from legacy systems This field is optional and can be any string format meaningful to your system. Examples: "ORG-12345", "west-coast-001", UUID from your system
email string Primary contact email address for the organization. Optional field. If provided, must be a valid email format. Example: "admin@westcoastnetwork.com"

Pagination

Pagination provides page token and page size for paginating list results.

Field Type Label Description
page_size int32 The maximum number of items to return. The service may return fewer than this value. If unspecified, at most 50 items will be returned. The maximum value is 200; values above 200 will be rejected.
page_token string A page token, received from a previous list call. Provide this to retrieve the subsequent page. When paginating, all other parameters must match the call that provided the page token.

Producer

Producer represents an insurance producer (agent) with complete licensing information.

This message contains comprehensive producer information including:

  • Basic contact details (name, email, phone, address)
  • Agency association
  • NIPR-synchronized licensing data (licenses, appointments, regulatory actions)
  • Location assignments within the agency

NIPR Data Synchronization: The NIPR data is automatically fetched from the National Insurance Producer Registry when the producer is created (if sync_with_nipr is enabled) and can be refreshed by:

  • Calling SyncProducerWithNIPR manually
  • Automatic daily updates via PDB Alerts (if pdb_alerts_sync_enabled is true)

Use Cases:

  • Verify producer licenses before selling insurance products
  • Check Lines of Authority (LOAs) to ensure producers can sell specific product types
  • Monitor license expiration dates for compliance
  • Track carrier appointments to know which companies the producer can represent
  • Review regulatory history before hiring or contracting
Field Type Label Description
id string Unique identifier for the producer (UUID format). This ID is used in all API operations that reference this producer.
first_name string First name of the producer.
middle_name string Middle name of the producer.
last_name string Last name of the producer.
email string The email address of the producer. Used for communication and must be unique within the tenant. Must be a valid email format.
npn string 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
phone string Phone number of the producer.
pdb_alerts_sync_enabled bool Indicates whether the producer is enabled to be synchronized with NIPR API. When true, the system will regularly check for updates from NIPR using PDB Alerts, providing automatic daily updates at no extra cost.
agency Producer.Agency Basic information about the agency this producer is associated with.
nipr Producer.NIPR Data synchronized from the NIPR service. Contains license information, biographic data, regulatory actions, and carrier appointments.
is_principal bool Indicates whether this producer is the principal of an agency. A principal producer has additional responsibilities and permissions.
requested_appointments string repeated The list of requested appointments for the producer.
address Producer.Address Address of the producer.
locations Location repeated Locations assigned to this producer.
metadata_questions Producer.MetadataQuestionsEntry repeated Deprecated. MetadataQuestions contains custom metadata questions and answers for the producer. This field stores tenant-specific questions that need to be asked during producer onboarding. The map key is the question identifier/text, and the value is the answer provided. This field is deprecated and will be removed in a future release.
external_metadata Producer.ExternalMetadataEntry repeated ExternalMetadata contains additional custom information that the tenant stores in ProducerFlow's data model. This field allows tenants to attach arbitrary key-value pairs to producers for their own business logic, reporting, or integration needs. This field is populated programmatically via API calls by the tenant's systems. Common use cases include: - Storing references to external system states or categories - Adding custom tags or classifications - Maintaining tenant-specific business attributes - Storing computed values or derived data The map key is the metadata field name, and the value is the associated data.
tenant_additional_questions Producer.TenantAdditionalQuestionsEntry repeated 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.
external_id string Tenant-provided external identifier for this producer. This ID allows tenants to map Producerflow producers back to their own system's identifiers. Set during producer creation/onboarding via the public API.
onboarding_status OnboardingStatus Current onboarding status of the producer in the workflow. This field tracks the producer's progression through the onboarding process, from initial onboarding to being ready to quote. This field is only populated when the tenant has enabled the onboarding status feature. When the feature is disabled, this field will be ONBOARDING_STATUS_UNSPECIFIED.
onboarding_status_updated_at google.protobuf.Timestamp Timestamp when the onboarding status was last updated. This field is only populated when the tenant has enabled the onboarding status feature.
role string Tenant-defined role label for the producer (e.g. "Licensed Producer", "CSR", "Agency Principal"). Reflects the role assigned during NewProducer / onboarding or via UpdateProducer. Empty when the producer has no role assigned, or when the tenant has not configured any role labels.
organization Organization Organization that the producer's agency belongs to. This field contains the full organization details including id, name, and contact information. Unset when the producer's agency does not belong to any organization.

Producer.Address

Address represents a mailing address for the producer.

Field Type Label Description
street string Deprecated. Deprecated: Use address_line_1 instead.
city string City of the producer.
state string State of the producer.
zip string Zip code of the producer.
address_line_2 string optional Optional second line of address (apt, suite, unit, etc.)
address_line_1 string Primary address line of the producer.

Producer.Agency

Agency contains basic information about the agency this producer is associated with.

Field Type Label Description
agency_id string Unique identifier for the associated agency.
name string Name of the associated agency.
external_id string Tenant-provided external identifier for the associated agency. This ID allows tenants to map Producerflow agencies back to their own system's identifiers without an extra GetAgency call. Set during agency creation/onboarding via the public API.
external_metadata Producer.Agency.ExternalMetadataEntry repeated ExternalMetadata contains additional custom information that the tenant stores in ProducerFlow's data model for the associated agency. The map key is the metadata field name, and the value is the associated data. Exposed here so callers do not need an extra GetAgency call to read it.

Producer.Agency.ExternalMetadataEntry

Field Type Label Description
key string
value string

Producer.ExternalMetadataEntry

Field Type Label Description
key string
value string

Producer.MetadataQuestionsEntry

Field Type Label Description
key string
value string

Producer.NIPR

NIPR contains data synchronized from the National Insurance Producer Registry.

Field Type Label Description
licenses Producer.NIPR.License repeated List of all licenses held by the producer across different states.
biographic Producer.NIPR.Biographic Biographic information of the producer from NIPR
regulatory_info Producer.NIPR.ProducerRegulatoryInfo Producer's regulatory information from NIPR
appointments Producer.NIPR.Appointment repeated List of carrier appointments held by the producer. Each appointment represents authorization to sell a specific carrier's products for a specific line of authority. A producer typically has multiple appointments across different carriers and LOAs. Before allowing a producer 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.
nipr_sync_status NIPRSyncState Current synchronization status with NIPR. Indicates whether NIPR data sync is active, failing, pending, or disabled.
nipr_sync_status_updated_at google.protobuf.Timestamp Timestamp when the NIPR sync status was last updated.

Producer.NIPR.Appointment

Appointment represents a producer's authorization to sell products for a specific insurance carrier.

What is an Appointment? An appointment is a formal relationship between a producer and an insurance company that grants the producer authority to sell that company's insurance products. Having a license is not enough - the producer must also be appointed by each carrier whose products they want to sell.

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 carrier's products
  • Track which carriers each producer can represent
  • Monitor appointment renewal dates
  • Understand termination reasons for compliance and vetting
Field Type Label Description
branch_id string Branch identifier for multi-branch agencies. This links the appointment to a specific agency branch if applicable.
company_name string Name of the insurance company for this appointment. Examples: "State Farm", "Allstate", "Blue Cross Blue Shield"
fein string Federal Employer Identification Number (FEIN) of the insurance carrier. This uniquely identifies the carrier company.
co_code string Company code: A standardized code identifying the insurance carrier. This is used in industry systems for carrier identification.
line_of_authority string Line of authority for this appointment. This indicates what type of insurance the producer can sell for this carrier. A producer might have multiple appointments with the same carrier for different LOAs. Examples: "LIFE", "HEALTH", "PROPERTY AND CASUALTY", "VARIABLE LIFE AND VARIABLE ANNUITY"
loa_code string Code for the line of authority. A standardized code representing the LOA type.
status string Current status of the appointment as reported by NIPR. 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 "APPOINTED" before allowing sales.
termination_reason string Reason for termination if the appointment has been terminated. Common termination reasons: - Producer requested termination - Carrier terminated appointment - Producer left agency - Compliance or regulatory issues This field is empty if the appointment is still active.
status_reason_date google.protobuf.Timestamp Date when the status or termination reason became effective. For terminated appointments, this is when the termination occurred.
appointment_renewal_date google.protobuf.Timestamp Date when the appointment will renew. Appointments typically renew annually. Monitor this date for upcoming renewals.
agency_affiliations string Additional affiliations or roles the producer has with the agency. This may include special designations or relationship details.

Producer.NIPR.Biographic

Biographic contains personal and identifying information about the producer.

Field Type Label Description
last_name string Last name of the producer as recorded in NIPR.
first_name string First name of the producer as recorded in NIPR.
middle_name string Middle name of the producer as recorded in NIPR.
date_of_birth google.protobuf.Timestamp Date of birth of the producer.
fein string Deprecated. Deprecated: producers in ProducerFlow are always individuals. NIPR does not return FEIN for individual agents; this field will always be empty.
company_name string Deprecated. Deprecated: producers in ProducerFlow are always individuals. NIPR does not return a company name for individual agents; this field will always be empty.
state_domicile string Deprecated. Deprecated: producers in ProducerFlow are always individuals. NIPR does not return state of domicile for individual agents; this field will always be empty.

Producer.NIPR.License

License contains information about a producer's insurance license in a specific state.

Each producer can hold multiple licenses across different states. Each license includes a set of Lines of Authority (LOAs) that define what types of insurance the producer is authorized to sell.

Key Concepts:

  • Resident License: License in the producer's home state
  • Non-Resident License: License in states other than the producer's home state
  • Lines of Authority (LOAs): Specific insurance types the license permits (e.g., Life, Health, Property & Casualty, Variable Contracts)

Compliance Use Cases:

  • Verify producer is licensed in the state where they're selling
  • Check license hasn't expired before allowing sales
  • Ensure producer has the correct LOA for the product type
  • Monitor expiration dates to send renewal reminders
Field Type Label Description
license_number string 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.
license_state string The two-letter US state or territory code that issued the license. Format: ISO 3166-2 subdivision code (e.g., "CA", "TX", "NY").
residency_status string Indicates whether this is a resident or non-resident license. Values are typically "Resident" or "Non-Resident".
active bool Indicates whether the license is currently active.
status Producer.NIPR.License.LicenseStatus The current status of the license (valid, expired, etc.).
expiration_date google.protobuf.Timestamp Deprecated. Deprecated: Use expires_on instead.
expires_on google.type.Date The date when the license will expire if not renewed.
updated_at google.protobuf.Timestamp The time when this license information was last fetched from NIPR.
lines_of_authority Producer.NIPR.License.LineOfAuthority repeated Lines of Authority (LOAs) associated with this license. These define what types of insurance the producer is authorized to sell in this state. A single license typically has multiple LOAs. Always check that the producer has an active LOA matching the product type before allowing sales.
license_id string The unique identifier for this license.
designated_home_state string The designated home state for adjuster licenses (ADHS).
license_class string 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.
license_class_code int32 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.

Producer.NIPR.License.LineOfAuthority

LineOfAuthority (LOA) represents a specific type of insurance that a producer is authorized to sell 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 a producer to sell a product, verify they have an active LOA that matches the product type. For example, a producer with only a LIFE LOA cannot sell Property & Casualty insurance.

LOA names are standardized by NIPR but may vary slightly between states.

Field Type Label Description
loa string 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.
active bool Whether this Line of Authority is currently active. Inactive LOAs cannot be used to sell that type of insurance.
issue_date google.protobuf.Timestamp Deprecated. Deprecated: Use issued_on instead.
issued_on google.type.Date The date when this Line of Authority was first issued. This helps track how long the producer has been authorized for this insurance type.

Producer.NIPR.ProducerRegulatoryInfo

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.

Field Type Label Description
regulatory_actions_by_state Producer.NIPR.ProducerRegulatoryInfo.RegulatoryActionsByStateEntry repeated Deprecated. Deprecated: use regulatory_actions instead. Map of regulatory actions keyed by two-letter state code. A producer may have multiple regulatory actions in the same state, but this map can only carry one per state — additional actions are dropped. Populated for backwards compatibility only.
clearance_certification_info string 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.
nasd_exam_details 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
regulatory_actions Producer.NIPR.ProducerRegulatoryInfo.RegulatoryAction repeated All regulatory actions on record for this producer, including multiple actions in the same state. Each action carries its own state_code. An empty list indicates no regulatory actions on record in NIPR.

Producer.NIPR.ProducerRegulatoryInfo.RegulatoryAction

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.

Field Type Label Description
action_id string Unique identifier for the regulatory action in NIPR's system.
origin_of_action string The regulatory body that originated the action. Examples: "California Department of Insurance", "FINRA", "Texas Department of Insurance". This identifies which authority initiated the regulatory proceeding.
reason_for_action string 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.
disposition 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
date_of_action google.protobuf.Timestamp The date when the regulatory action was formally initiated or filed.
effective_date google.protobuf.Timestamp 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.
enter_date google.protobuf.Timestamp The date when the producer entered into or acknowledged the regulatory action (e.g., signed a consent agreement).
file_ref string 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.
penalty_fine_forfeiture string Any financial penalties, fines, or forfeitures associated with the regulatory action. Format: Free-text, typically a dollar amount (e.g., "$5,000.00").
length_of_order string Duration of any orders associated with the regulatory action. Format: Free-text describing the time period (e.g., "12 months", "Indefinite", "Until compliance").
state_code string The two-letter state code of the regulatory authority that took the action. Format: US state code (e.g., "CA", "TX", "NY").

Producer.NIPR.ProducerRegulatoryInfo.RegulatoryActionsByStateEntry

Field Type Label Description
key string
value Producer.NIPR.ProducerRegulatoryInfo.RegulatoryAction

Producer.TenantAdditionalQuestionsEntry

Field Type Label Description
key string
value string

ProducerData

Field Type Label Description
npn string optional 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
first_name string optional First name of the producer
last_name string optional Last name of the producer
middle_name string optional Middle name of the producer
email string optional Email address of the producer
phone string optional Phone number of the producer
mailing_address ProducerData.Address Mailing address of the producer

ProducerData.Address

Field Type Label Description
street string Deprecated. Deprecated: Use address_line_1 instead.
city string
state string
zip string
country string
address_line_2 string optional
address_line_1 string Primary address line including house/building number and street name

RemoveAgencyLocationsRequest

RemoveAgencyLocationsRequest removes locations from an agency.

Field Type Label Description
agency_id string Required. Agency ID to remove locations from.
location_ids string repeated Required. IDs of locations to remove.

RemoveAgencyLocationsResponse

RemoveAgencyLocationsResponse contains the results of removing locations.

Field Type Label Description
removed_location_ids string repeated IDs of successfully removed locations.

ResyncAgencyRequest

ResyncAgencyRequest is used to trigger a manual resynchronization of agency data. This will re-fetch all data from the NIPR API for the agency and all associated producers.

Field Type Label Description
agency_id string The UUID of the agency to resynchronize. Must be a valid UUID format.

ResyncAgencyResponse

ResyncAgencyResponse is the empty response returned after successfully triggering a resynchronization.

ResyncProducerRequest

ResyncProducerRequest is used to trigger a manual resynchronization of producer data.

Field Type Label Description
producer_id string The UUID of the producer to resynchronize. Must be a valid UUID format.

ResyncProducerResponse

ResyncProducerResponse is the empty response returned after successfully triggering a resynchronization.

SetExternalIDRequest

SetExternalIDRequest is used to associate an external identifier with a producer, agency, or contact. This allows integration with external systems that use different ID schemes.

Only one entity type can be specified.

Field Type Label Description
producer_id string The UUID of the producer to set an external ID for.
agency_id string The UUID of the agency to set an external ID for.
contact_id string The UUID of the contact to set an external ID for.
organization_id string The UUID of the organization to set an external ID for.
tenant_id string External identifier to associate with the entity in the tenant's system. This field allows tenants to maintain a reference to their own internal ID for the specified entity (producer, agency, contact, or organization), enabling bi-directional synchronization between ProducerFlow and the tenant's system. Purpose: Links ProducerFlow entities to corresponding entities in external systems. Enables lookups and synchronization across systems. Maintains referential integrity with tenant's internal databases. Usage: Call this RPC after creating an entity if you need to add or update the external reference. This can also be provided during entity creation for producers and contacts. This is independent of ProducerFlow's internal IDs and the authentication tenant context. Relationship to authentication: The tenant context is determined by the API key used for authentication. This tenant_id field is purely for storing the tenant's own external identifier. Multiple tenants cannot share the same entity; each tenant has their own isolated data. Common use cases: Syncing with CRM systems (e.g., Salesforce IDs, HubSpot IDs). Integrating with AMS platforms (e.g., Applied Epic, Vertafore). Maintaining references to legacy system identifiers. Format: Any string identifier that is meaningful in your system (e.g., "SF-001234", "LEGACY-9876"). Validation: Must be non-empty, maximum length of 255 characters

SetExternalIDResponse

SetExternalIDResponse is the empty response returned after successfully setting an external ID.

StopSyncAgencyWithNIPRRequest

StopSyncAgencyWithNIPRRequest is used to stop synchronizing an agency's data with the NIPR API.

Field Type Label Description
agency_id string The UUID of the agency to stop synchronizing. Must be a valid UUID format.
stop_all_producers bool If true, all producers associated with the agency will be stopped from synchronizing. If false, only the agency will be stopped from synchronizing.

StopSyncAgencyWithNIPRResponse

StopSyncAgencyWithNIPRResponse is the empty response returned after successfully stopping the synchronization of an agency's data with the NIPR API.

StopSyncProducerWithNIPRRequest

StopSyncProducerWithNIPRRequest is used to stop synchronizing a producer's data with the NIPR API.

Field Type Label Description
producer_id string The UUID of the producer to stop synchronizing. Must be a valid UUID format.

StopSyncProducerWithNIPRResponse

StopSyncProducerWithNIPRResponse is the empty response returned after successfully stopping the synchronization of a producer's data with the NIPR API.

SyncAgencyWithNIPRRequest

SyncAgencyWithNIPRRequest is used to synchronize an agency's data with the NIPR API.

Field Type Label Description
agency_id string The UUID of the agency to synchronize. Must be a valid UUID format.
sync_all_producers bool If true, all producers associated with the agency will be synchronized. If false, only the agency will be synchronized.

SyncAgencyWithNIPRResponse

SyncAgencyWithNIPRResponse is the empty response returned after successfully synchronizing an agency's data with the NIPR API.

SyncProducerWithNIPRRequest

SyncProducerWithNIPRRequest is used to synchronize a producer's data with the NIPR API.

Field Type Label Description
producer_id string The UUID of the producer to synchronize. Must be a valid UUID format.

SyncProducerWithNIPRResponse

SyncProducerWithNIPRResponse is the empty response returned after successfully synchronizing a producer's data with the NIPR API.

UnassignProducerFromLocationsRequest

UnassignProducerFromLocationsRequest removes location assignments from a producer.

Field Type Label Description
producer_id string Required. Producer ID to unassign locations from.
location_ids string repeated Required. Location IDs to unassign (1-100 items).

UnassignProducerFromLocationsResponse

UnassignProducerFromLocationsResponse contains the unassigned location IDs.

Field Type Label Description
unassigned_location_ids string repeated IDs of successfully unassigned locations.

UpdateAgencyLocationRequest

UpdateAgencyLocationRequest updates an existing agency location.

Field Type Label Description
agency_id string Required. Agency ID that owns the location.
location_id string Required. Location ID to update.
name string optional Optional. New name for the location. Must be unique within the agency.
address Address optional Optional. New address for the location.
phone string optional Optional. New phone number. Must be in E.164 format.
email string optional Optional. New email address.
is_primary bool optional Optional. Whether this should be the primary location.
external_id string optional Optional. Carrier-specific external ID for this location. Must be unique within the tenant when set. Pass an empty string to clear it.

UpdateAgencyLocationResponse

UpdateAgencyLocationResponse contains the updated location details.

Field Type Label Description
location Location The updated location with all current values.

UpdateAgencyRequest

UpdateAgencyRequest contains the fields that can be updated in an agency record. Only information collected during the onboarding process can be updated. Information from NIPR and other third-party sources cannot be updated directly. All fields are optional, allowing partial updates.

Field Type Label Description
agency_id string The ID of the agency to update. Must be a valid UUID format.
agency UpdateAgencyRequest.Agency The agency information to update.

UpdateAgencyRequest.Agency

Agency contains the fields that can be updated for an agency. All fields are optional, allowing partial updates.

Field Type Label Description
email string optional Email address of the agency.
phone string optional Phone number of the agency.
fax string optional Fax number of the agency.
website string optional Website URL of the agency.
requested_appointments string repeated List of requested appointments for the agency (state codes). The list contains a list of two-lettercd country codes where the appointments are requested. The only valid values are the U.S country codes.
notes string optional
physical_address UpdateAgencyRequest.Agency.Address optional Physical address of the agency.
external_metadata UpdateAgencyRequest.Agency.ExternalMetadataEntry repeated ExternalMetadata contains additional custom information that the tenant stores in ProducerFlow's data model. This field allows tenants to attach arbitrary key-value pairs to agencies for their own business logic, reporting, or integration needs. This field is populated programmatically via API calls by the tenant's systems. Common use cases include: - Storing references to external system states or categories - Adding custom tags or classifications - Maintaining tenant-specific business attributes - Storing computed values or derived data The map key is the metadata field name, and the value is the associated data. Update behavior: - If not provided (null): existing metadata is preserved unchanged - If provided as empty map {}: existing metadata is cleared - If provided with values: existing metadata is completely replaced with the new values
ivans_account UpdateAgencyRequest.Agency.IvansAccount 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
organization_relationship AgencyOrganizationRelationship optional Relationship the agency has with the organization it belongs to: - MAIN: The agency owns or manages the organization. - RELATED: The agency is part of the organization but not the primary owner. Update behavior: - If not provided (null): the current relationship is preserved unchanged - If provided together with organization_id: the agency is moved to that organization with the requested relationship - If provided on its own: the relationship with the agency's current organization is switched to the requested value (no-op if it already matches). The agency must already belong to an organization; otherwise the request fails with FAILED_PRECONDITION Turning a main agency into a related one requires the agency to have a principal, otherwise the request fails with FAILED_PRECONDITION. Cannot be combined with an empty organization_id, which detaches the agency and leaves it with no relationship at all.
organization_id string optional Organization the agency belongs to. Use the ListOrganizations RPC to get valid organization IDs. The producers under the agency follow it, since a producer's organization is derived from its agency. Update behavior: - If not provided (null): the current organization is preserved unchanged - If provided with an organization ID: the agency is moved to that organization (no-op if it already belongs to it), or attached to it if it had no organization. The relationship comes from organization_relationship when set, and is otherwise preserved from the organization the agency is moved from (RELATED when it had none) - If provided as an empty string: the agency is detached from its organization The agency must belong to at most one organization, otherwise the organization it is moved from is ambiguous and the request fails with FAILED_PRECONDITION. Detaching is exempt, as it removes every membership.

UpdateAgencyRequest.Agency.Address

Address represents a physical location with standard address components. All fields are optional, allowing partial updates of address fields. Address fields cannot be cleared - if provided, they must have valid values.

Field Type Label Description
street string optional Deprecated. Deprecated: Use address_line_1 instead.
city string optional City of the address. If provided, must be non-empty.
state string optional State of the address. If provided, must be exactly 2 characters (state code).
zip string optional Zip code of the address. If provided, must be between 1 and 10 characters.
address_line_2 string optional Additional address line (e.g., apartment, suite, floor number). If provided, must be non-empty.
address_line_1 string optional Primary address line including house/building number and street name. If provided, must be non-empty.

UpdateAgencyRequest.Agency.ExternalMetadataEntry

Field Type Label Description
key string
value string

UpdateAgencyRequest.Agency.IvansAccount

IvansAccount contains IVANS (Insurance Value Added Network Services) account information. IVANS is used for electronic communication between insurance agencies and carriers.

Field Type Label Description
account_number string optional Account number for the IVANS service. If provided, must be non-empty.
ams_software string optional Software used for IVANS communication (AMS - Agency Management System). If provided, must be non-empty.
ams_version string optional Version of the AMS software. If provided, must be non-empty.
mailbox_number string optional Mailbox number for the IVANS service. Used for routing electronic messages. If provided, must be non-empty.

UpdateAgencyResponse

UpdateAgencyResponse is the empty response returned after successfully updating an agency.

UpdateContactRequest

UpdateContactRequest is used to update an existing contact's information.

Field Type Label Description
contact_id string The UUID of the contact to update. Must be a valid UUID format.
contact UpdateContactRequest.Contact The contact information to update. The field is required.

UpdateContactRequest.Contact

Contact contains the fields that can be updated for a contact. All fields are optional, allowing partial updates.

Field Type Label Description
first_name string optional First name of the contact. If provided, must be non-empty.
last_name string optional Last name of the contact. If provided, must be non-empty.
middle_name string optional Middle name of the contact. If provided, must be non-empty.
email string optional Email address of the contact. If provided, must be a valid email format. Must be unique within the tenant.
phone string optional Phone number of the contact. If provided, must be a valid phone number format.
role ContactRole optional Role or position of the contact within the agency. If provided, must be a valid ContactRole enum value (not UNSPECIFIED). See ContactRole enum for available options.
address Address optional Mailing address of the contact. If provided, all address fields should be included. This replaces the entire address.
external_metadata UpdateContactRequest.Contact.ExternalMetadataEntry repeated ExternalMetadata contains additional custom information that the tenant stores in ProducerFlow's data model. This field allows tenants to attach arbitrary key-value pairs to contacts for their own business logic, reporting, or integration needs. This field is populated programmatically via API calls by the tenant's systems. Common use cases include: - Storing references to external system states or categories - Adding custom tags or classifications - Maintaining tenant-specific business attributes - Storing computed values or derived data The map key is the metadata field name, and the value is the associated data. Update behavior: - If not provided (null): existing metadata is preserved unchanged - If provided as empty map {}: existing metadata is cleared - If provided with values: existing metadata is completely replaced with the new values

UpdateContactRequest.Contact.ExternalMetadataEntry

Field Type Label Description
key string
value string

UpdateContactResponse

UpdateContactResponse is the empty response returned after successfully updating a contact.

UpdateProducerRequest

UpdateProducerRequest contains the fields that can be updated in a producer record. Only information collected during the onboarding process can be updated. Information from NIPR and other third-party sources cannot be updated directly.

Field Type Label Description
producer_id string The ID of the producer to update. Must be a valid UUID format.
producer UpdateProducerRequest.Producer The producer information to update. The field is required.

UpdateProducerRequest.Producer

Producer contains the fields that can be updated for a producer. All fields are optional, allowing partial updates.

Field Type Label Description
first_name string optional First name of the producer. If provided, must be non-empty.
last_name string optional Last name of the producer. If provided, must be non-empty.
middle_name string optional Middle name of the producer. If provided, must be non-empty.
email string optional Email address of the producer. If provided, must be a valid email format. Must be unique within the tenant.
npn string optional Deprecated. National Producer Number (NPN) of the producer. If provided, must be non-empty. Deprecated: NPN cannot be updated. This field is ignored and will be removed in a future version.
phone string optional Phone number of the producer. If provided, must be a valid phone number format.
street string optional Deprecated. Deprecated: Use address_line_1 instead.
address_line_1 string optional Primary address line of the producer. If provided, must be non-empty.
address_line_2 string optional Second line of the address (apartment, suite, unit, etc.). If provided, must be non-empty.
city string optional City of the producer. If provided, must be non-empty.
state string optional State of the producer. If provided, must be a valid 2-letter US state code.
zip string optional ZIP code of the producer's address. If provided, must be at least 5 characters.
external_metadata UpdateProducerRequest.Producer.ExternalMetadataEntry repeated ExternalMetadata contains additional custom information that the tenant stores in ProducerFlow's data model. This field allows tenants to attach arbitrary key-value pairs to agencies for their own business logic, reporting, or integration needs. This field is populated programmatically via API calls by the tenant's systems. Common use cases include: - Storing references to external system states or categories - Adding custom tags or classifications - Maintaining tenant-specific business attributes - Storing computed values or derived data The map key is the metadata field name, and the value is the associated data. Update behavior: - If not provided (null): existing metadata is preserved unchanged - If provided as empty map {}: existing metadata is cleared - If provided with values: existing metadata is completely replaced with the new values
onboarding_status OnboardingStatus optional 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.
role string optional Tenant-defined role label for the producer (e.g. "Licensed Producer", "CSR", "Agency Principal"). Update behavior: - If not provided (null): the existing role is preserved unchanged. - If provided as empty string: the role is cleared. - If provided with a value: the value must match one of the role labels configured in the tenant's settings; otherwise the request is rejected with INVALID_ARGUMENT.

UpdateProducerRequest.Producer.ExternalMetadataEntry

Field Type Label Description
key string
value string

UpdateProducerResponse

UpdateProducerResponse is the empty response returned after successfully updating a producer.

ValidateAgencyNPNRequest

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.

Field Type Label Description
npn string 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

ValidateAgencyNPNResponse

ValidateAgencyNPNResponse contains the result of validating an agency's NPN.

Field Type Label Description
valid bool optional Indicates whether the NPN is valid. True if the NPN exists in NIPR's agency records. False if the NPN does not exist. Marked optional so the field is always emitted in JSON, even when false.
agency_name string The agency name as registered in NIPR. Populated only when the NPN is valid; empty otherwise.

ValidateProducerNPNRequest

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.

Field Type Label Description
npn string 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
name string optional 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.

ValidateProducerNPNResponse

ValidateProducerNPNResponse contains the result of validating a producer's NPN.

Field Type Label Description
valid bool optional Indicates whether the NPN is valid. 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. Marked optional so the field is always emitted in JSON, even when false.

producerflow/appointment/v1/appointment.proto

Appointment

Represents a managed appointment for a license, tracked through the ProducerFlow appointment lifecycle. Unlike NIPR-sourced appointment data on the Producer/Agency messages, this represents appointments that are actively managed (requested, terminated) through the AppointmentService.

Field Type Label Description
appointment_id string Unique identifier for the appointment (UUID format).
license License Information about the license being appointed.
name string The license number of the license being appointed. This is a denormalized copy of license.license_number for convenience.
agency_id string The UUID of the agency that holds this appointment.
producer_id string optional Optional. The UUID of the producer that holds this appointment, if any. When empty, this is an agency-level appointment.
carrier string The name of the carrier to which the license is appointed. Examples: "State Farm", "Allstate", "Progressive"
appointment_type AppointmentType Type of appointment (registry, up-front, just-in-time, or synthetic). Determines how the appointment was established and processed.
processing_status ProcessingStatus Current processing status of the appointment in the NIPR pipeline. See ProcessingStatus for the complete lifecycle documentation.
comments string Optional. Comments or notes related to the appointment. May include NIPR processing notes or rejection details.
effective_date google.protobuf.Timestamp Timestamp of when the appointment became or becomes effective.
termination_date google.protobuf.Timestamp optional Optional. Timestamp of when the appointment was terminated. Only populated when processing_status is TERMINATED.
updated_at google.protobuf.Timestamp Timestamp of the last update to this appointment record.
operational_status AppointmentOperationalStatus Operational status information for the appointment. Provides insight into the current operational health and any risk factors (e.g., expired license, inactive E&O) that may affect the appointment's continued validity.
cocode string NAIC Company Code (CoCode) of the 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
parent_appointment_id string Optional. The UUID of the parent appointment, if this is a synthetic appointment (APPOINTMENT_TYPE_SYNTHETIC). Empty for non-synthetic appointments. Synthetic appointments inherit properties from and are terminated with their parent appointment.

AppointmentOperationalStatus

AppointmentOperationalStatus contains operational status information for an appointment. This message provides detailed information about the current operational state and any risk factors that may affect the appointment's continued validity.

Field Type Label Description
status OperationalStatus The current operational status of the appointment.
risk_reasons RiskReason repeated Specific reason(s) why the appointment is at risk, if applicable. This field is only populated when status is AT_RISK.
last_updated google.protobuf.Timestamp Timestamp when the operational status was last updated. This helps track when status changes occurred.

Carrier

Represents a carrier that is available to be appointed.

Field Type Label Description
carrier_id string The ID of the carrier.
name string The name of the carrier.
npn string National Producer Number (NPN) of the carrier. 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
fein string Federal Employer Identification Number (FEIN) of the carrier. Format: 9-digit number assigned by the IRS for tax identification. Example: "123456789"
cocode string NAIC Company Code (CoCode) of the carrier. A unique identifier assigned by the National Association of Insurance Commissioners (NAIC) to each insurance company for regulatory reporting. Format: Typically a 5-digit numeric string. Example: "12345" Reference: https://naic.org
has_nipr_integration bool Indicates whether this carrier has NIPR integration enabled. Capacity carriers (carriers without NIPR integration) process appointments and terminations automatically without going through NIPR.

GetAppointableCarriersRequest

Request to retrieve carriers that are available to be appointed.

GetAppointableCarriersResponse

Response containing carriers that are available to be appointed.

Field Type Label Description
carriers Carrier repeated The list of carriers that are available to be appointed.

GetAppointmentFeesRequest

Request to get appointment fees.

Field Type Label Description
license_id string Required. The ID of the license to get the appointment fee for.

GetAppointmentFeesResponse

Field Type Label Description
fee_in_cents int64 Total fee for the appointment in cents.

GetAppointmentRequest

Request to retrieve an appointment by ID.

Field Type Label Description
appointment_id string Required. The ID of the appointment to retrieve.

GetAppointmentResponse

Field Type Label Description
appointment Appointment The appointment details.

GetTerminationFeesRequest

Request to get termination fees.

Field Type Label Description
license_id string Required. The ID of the license to get the termination fee for.

GetTerminationFeesResponse

Field Type Label Description
fee_in_cents int64 Total fee for the termination in cents.

License

Field Type Label Description
license_id string The ID of the license.
license_number string 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.
producer_id string
agency_id string
state string The two-letter US state or territory code that issued the license. Format: ISO 3166-2 subdivision code (e.g., "CA", "TX", "NY").
license_class string 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 Values vary by state as each DOI defines its own license classes.
is_registry_state bool Indicates whether this license is in a registry state. Licenses in registry states and capacity carriers are processed automatically without going through NIPR.
carrier_id string The ID of the carrier associated with this license.
expiration_date google.type.Date The date the license expires.
issue_date google.type.Date The date the license was issued.

ListAppointmentsRequest

Request to list appointments, optionally filtered by processing status.

Field Type Label Description
processing_status ProcessingStatus repeated Optional. Filter results by processing status.
producer_id string
agency_id string
operational_status OperationalStatus repeated Optional. Filter results by operational status.
pagination producerflow.producer.v1.Pagination Optional. Pagination parameters. If not provided, defaults to page_size=50. Maximum page_size is 200.

ListAppointmentsResponse

Field Type Label Description
appointments Appointment repeated List of appointments.
next_page_token string Token for fetching the next page of results. Empty when there are no more results.

ListEligibleLicensesRequest

Request to retrieve a list of licenses that are eligible to be appointed.

Field Type Label Description
producer_id string
agency_id string

ListEligibleLicensesResponse

Field Type Label Description
licenses License repeated List of licenses that are eligible to be appointed.

ListTerminationReasonsRequest

Field Type Label Description
state string Required. The two-letter state code of the license for which you want to retrieve valid termination reasons. Different states may have different sets of valid termination reasons accepted by NIPR.

ListTerminationReasonsResponse

Field Type Label Description
termination_reasons TerminationReason repeated The list of valid termination reasons for the specified state. These reasons can be used when calling TerminateAppointment for licenses issued in this state.

RequestAppointmentRequest

Request to create a new appointment.

Field Type Label Description
license_id string Required. The ID of the license to appoint.
carrier_id string Required. The ID of the carrier to appoint the license with.

RequestAppointmentResponse

Field Type Label Description
appointment_id string The ID of the created appointment.
processing_status ProcessingStatus Processing status of the appointment request. For NIPR-integrated carriers: IN_PROGRESS if accepted, REJECTED if rejected. For registry states or non-NIPR carriers: APPOINTED if successful.
not_eligible_reasons string repeated If the appointment was rejected or ineligible, these reasons explain why. Only populated when processing_status is REJECTED.

TerminateAppointmentRequest

Request to terminate an appointment.

Field Type Label Description
appointment_id string ID of the appointment to terminate.
reason TerminationReason Reason for termination. This must be a valid termination reason for the state where the license is issued. Call ListTerminationReasons first to get the list of valid reasons for the specific state.

TerminateAppointmentResponse

Field Type Label Description
success bool Indicates whether the termination request was successfully processed. For NIPR-integrated carriers: - Indicates whether the termination request was successfully submitted to NIPR. - This does not indicate that the appointment has been terminated, only that the request has been accepted for processing. - The actual termination will be processed asynchronously by NIPR, and you will be notified via webhook when the process completes. For registry states or non-NIPR carriers: - Indicates whether the termination was successfully completed immediately.

producerflow/testing/v1/testing.proto

DeleteAgencyRequest

Field Type Label Description
agency_id string UUID of the Agencies row to delete. Must belong to the tenant resolved from the API key; a cross-tenant or unknown agency_id returns NOT_FOUND.

DeleteAgencyResponse

Empty response

DeleteAppointmentRequest

Field Type Label Description
appointment_id string UUID of the Appointments row to delete. Must belong to the tenant resolved from the API key; a cross-tenant or unknown appointment_id returns NOT_FOUND.

DeleteAppointmentResponse

Field Type Label Description
state string State of the deleted appointment, echoed back for confirmation.
agency_id string Agency the deleted appointment belonged to, echoed back for confirmation.

↑ Back to Table of Contents

Enums

producerflow/producer/v1/producer.proto

Agency.BankAccount.AccountType

The type of account.

Name Number Description
ACCOUNT_TYPE_UNSPECIFIED 0 Default unspecified value. Avoid using this.
ACCOUNT_TYPE_CHECKING 1 Standard checking account.
ACCOUNT_TYPE_SAVINGS 2 Savings account.

Agency.NIPR.License.LicenseStatus

LicenseStatus defines the possible statuses of an insurance license.

Name Number Description
LICENSE_STATUS_UNSPECIFIED 0 Default unspecified value. Avoid using this.
LICENSE_STATUS_EXPIRED 1 The license has expired and is no longer valid.
LICENSE_STATUS_VALID 2 License is currently active.
LICENSE_STATUS_NOT_ACTIVE 3 The license exists but is not in an active state. This could be due to suspension, revocation, or other reasons.

AgencyOrganizationRelationship

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.

Name Number Description
AGENCY_ORGANIZATION_RELATIONSHIP_UNSPECIFIED 0 Default unspecified value. Used when the agency does not belong to any organization.
AGENCY_ORGANIZATION_RELATIONSHIP_MAIN 1 The agency is the main/primary agency for the organization. The main agency typically owns or manages the organization.
AGENCY_ORGANIZATION_RELATIONSHIP_RELATED 2 The agency is a related agency in the organization's network. Related agencies are part of the organization but not the primary owner.

AgencyType

AgencyType defines whether an agency is internal (tenant agency) or external.

Name Number Description
AGENCY_TYPE_UNSPECIFIED 0 Default unspecified value. Do not use.
AGENCY_TYPE_INTERNAL 1 Internal agencies are the agencies that are tenant agencies.
AGENCY_TYPE_EXTERNAL 2 External agencies are the agencies that are not tenant agencies.

ContactRole

ContactRole defines the role or position of a contact within an agency.

Contacts represent non-producer personnel associated with an agency. These roles help categorize and organize contacts based on their responsibilities and access levels.

Name Number Description
CONTACT_ROLE_UNSPECIFIED 0 Default unspecified value. Do not use. This value is invalid and will be rejected by the API.
CONTACT_ROLE_AGENCY_ADMINISTRATOR 1 Agency Administrator: A contact with administrative responsibilities. Typically has elevated permissions and manages agency operations.
CONTACT_ROLE_OTHER 2 Other: A contact role that doesn't fit into predefined categories. Use this for flexible role assignment.
CONTACT_ROLE_CSR 3 Customer Service Representative (CSR): A contact who handles customer inquiries and support. Does not hold an insurance producer license.
CONTACT_ROLE_UNLICENSED_PRODUCER 4 Deprecated: Use CONTACT_ROLE_UNLICENSED_SERVICE instead. Requests carrying this value are accepted for backward compatibility and stored as CONTACT_ROLE_UNLICENSED_SERVICE.
CONTACT_ROLE_UNLICENSED_SERVICE 5 Unlicensed Service: A contact providing services to the agency without requiring an insurance license.
CONTACT_ROLE_PRINCIPAL 6 Principal: The principal owner of the agency who does not hold an active insurance producer license. This role is system-assigned during onboarding and cannot be set via API.

EntityType

EntityType defines the business structure of an agency.

This determines important business rules around NPNs, producers, and onboarding requirements.

Name Number Description
ENTITY_TYPE_UNSPECIFIED 0 Default unspecified value. Do not use. This value is invalid and will be rejected by the API.
ENTITY_TYPE_SOLE_PROPRIETOR 1 Sole proprietor: An individual insurance producer operating independently. Business Rules for Sole Proprietors: - Cannot have a separate agency NPN (only the principal's NPN is used) - Cannot have additional producers beyond the principal - The principal producer IS the agency - FEIN is optional Use this type for independent agents who operate alone.
ENTITY_TYPE_AGENCY 2 Standard insurance agency: A business entity with multiple producers. Business Rules for Agencies: - Must provide either an agency NPN or FEIN (or both) - Can have multiple producers in addition to the principal - The agency is a separate legal entity from its producers - Typically has business structure (LLC, Corporation, Partnership, etc.) Use this type for traditional insurance agencies with multiple agents.
ENTITY_TYPE_ASK_DURING_ONBOARDING 3 Dynamic determination: Let the user select during onboarding. Use this value only when generating onboarding URLs and you don't know the entity type in advance. The onboarding form will present both options and let the user choose. This value is ONLY valid for CreateAgencyOnboardingURL and will be rejected by NewAgency and other direct creation endpoints.

NIPRSyncState

NIPRSyncState defines the synchronization state with the NIPR system.

Name Number Description
NIPR_SYNC_STATE_UNSPECIFIED 0 Default unspecified value. Do not use.
NIPR_SYNC_STATE_ACTIVE 1 Synchronization is active and working properly.
NIPR_SYNC_STATE_FAILING 2 Synchronization is failing due to errors.
NIPR_SYNC_STATE_PENDING 3 Synchronization is pending and has not started yet.
NIPR_SYNC_STATE_DISABLED 4 Synchronization has been disabled.
NIPR_SYNC_STATE_IN_PROGRESS 5 Synchronization is in progress.
NIPR_SYNC_STATE_STOPPING 6 Synchronization is being stopped.
NIPR_SYNC_STATE_NO_LICENSE_FOUND 7 NIPR returned no license information for a valid NPN. This is not an error: the entity simply has no license data on file in NIPR, so the sync is not retried automatically (a manual re-sync remains available). Distinguished from NIPR_SYNC_STATE_FAILING so callers can tell an expected empty result apart from a genuine sync failure.

NewAgencyRequest.Agency.BankAccount.AccountType

Name Number Description
ACCOUNT_TYPE_UNSPECIFIED 0 Default unspecified value. Avoid using this.
ACCOUNT_TYPE_CHECKING 1 Standard checking account
ACCOUNT_TYPE_SAVINGS 2 Savings account

NewAgencyRequest.Agency.PointOfContact.CommunicationRole

Name Number Description
COMMUNICATION_ROLE_UNSPECIFIED 0 Default unspecified value. Avoid using this.
COMMUNICATION_ROLE_ACCOUNTING 1 Accounting role
COMMUNICATION_ROLE_LICENSING 2 Licensing role
COMMUNICATION_ROLE_REPORTING 3 Reporting role
COMMUNICATION_ROLE_SALES 4 Sales role
COMMUNICATION_ROLE_CUSTOMER_SERVICE 5 Customer service role
COMMUNICATION_ROLE_ALL 6 All roles

OnboardingStatus

OnboardingStatus represents the current stage of a producer in the onboarding workflow. This status is used to track producer progression from initial onboarding through to being fully ready to quote and sell insurance products.

This field is only populated when the tenant has enabled the onboarding status feature.

Name Number Description
ONBOARDING_STATUS_UNSPECIFIED 0 Default unspecified value. Do not use.
ONBOARDING_STATUS_ONBOARDED 1 Producer has completed the initial onboarding process.
ONBOARDING_STATUS_APPROVED 2 Producer has been approved and verified.
ONBOARDING_STATUS_READY_TO_QUOTE 3 Producer is fully ready to quote and sell insurance products.
ONBOARDING_STATUS_TERMINATED 4 Producer has been terminated and is no longer active.

Producer.NIPR.License.LicenseStatus

LicenseStatus defines the current state of an insurance license.

Name Number Description
LICENSE_STATUS_UNSPECIFIED 0 Default unspecified value. Avoid using this.
LICENSE_STATUS_EXPIRED 1 The license has expired and is no longer valid for selling insurance. The producer must renew the license before conducting business in this state.
LICENSE_STATUS_VALID 2 License is currently active and in good standing. The producer can sell insurance in this state according to their LOAs.
LICENSE_STATUS_NOT_ACTIVE 3 The license exists but is not currently active. Reasons include: suspension, revocation, lapsed (not renewed), or voluntarily inactive. The producer cannot sell insurance in this state until the license is reinstated.

producerflow/appointment/v1/appointment.proto

AppointmentType

AppointmentType categorizes how the appointment was established and processed.

The appointment type determines the processing behavior:

  • Registry and Synthetic appointments are processed automatically
  • Up-front appointments go through NIPR's standard processing pipeline
  • Just-in-time appointments are created on demand when needed
Name Number Description
APPOINTMENT_TYPE_UNSPECIFIED 0
APPOINTMENT_TYPE_REGISTRY 1 Registry appointment: Processed automatically for licenses in registry states. Registry states allow appointments without going through NIPR's standard appointment process.
APPOINTMENT_TYPE_UP_FRONT 2 Up-front appointment: Standard appointment processed through NIPR. These require NIPR approval and may take time to process. The carrier pays appointment fees to NIPR/state.
APPOINTMENT_TYPE_JUST_IN_TIME 3 Just-in-time appointment: Created on demand when a producer needs to sell a product but doesn't have a pre-existing appointment.
APPOINTMENT_TYPE_SYNTHETIC 4 Synthetic appointment: Programmatically created for individual producers in states where only agency-level appointments are permitted (CA, DC, HI, KY, LA, MA, MT, UT, WA). They are automatically created when an agency appointment is approved and inherit properties from the parent agency appointment. The parent_appointment_id field links to the parent agency appointment. Synthetic appointments do not require separate regulatory approval and are terminated when the parent appointment is terminated.

OperationalStatus

OperationalStatus represents the current operational status of an appointment. This indicates whether the appointment is actively functioning or at risk of termination.

Name Number Description
OPERATIONAL_STATUS_UNSPECIFIED 0
OPERATIONAL_STATUS_ACTIVE 1 Appointment is actively functioning and meeting all requirements.
OPERATIONAL_STATUS_AT_RISK 2 Appointment is at risk of termination due to various factors.

ProcessingStatus

ProcessingStatus represents the lifecycle state of an appointment as it moves through the NIPR processing pipeline.

Appointment Lifecycle:

RequestAppointment | v IN_PROGRESS -----> APPOINTED (active appointment) | | v v (TerminateAppointment) REJECTED TERMINATION_REQUESTED --> TERMINATED

For registry states or capacity carriers (no NIPR integration): RequestAppointment --> APPOINTED (immediate) TerminateAppointment --> TERMINATED (immediate)

Reference: https://pdb.nipr.com/Gateway

Name Number Description
PROCESSING_STATUS_UNSPECIFIED 0
PROCESSING_STATUS_IN_PROGRESS 1 Appointment request has been submitted to NIPR and is awaiting processing. This is a transient state; the final result will be delivered via webhook.
PROCESSING_STATUS_APPOINTED 2 Appointment has been approved and is active. The producer/agency can sell this carrier's products for the specified Line of Authority.
PROCESSING_STATUS_TERMINATED 3 Appointment has been terminated. The producer/agency can no longer sell this carrier's products. This is a terminal state.
PROCESSING_STATUS_REJECTED 4 Appointment request was rejected by NIPR. Check not_eligible_reasons for details. Common reasons include: missing resident license, unmet continuing education requirements, or outstanding regulatory actions.
PROCESSING_STATUS_MISSING_LICENSE 5 The license required for this appointment is missing or could not be found. The producer/agency needs to obtain the appropriate license before the appointment can be processed.
PROCESSING_STATUS_TERMINATION_REQUESTED 6 A termination request has been submitted to NIPR and is awaiting processing. This is a transient state; the final result (TERMINATED) will be delivered via webhook.

RiskReason

RiskReason represents the specific reason why an appointment is considered at risk. These reasons correspond to business rules and compliance requirements that may trigger operational status changes.

Name Number Description
RISK_REASON_UNSPECIFIED 0
RISK_REASON_LICENSE_INACTIVE 1 License is inactive (License Active = false).
RISK_REASON_LICENSE_EXPIRED 2 License has expired (License ExpirationDate < current date).
RISK_REASON_EO_NOT_FOUND 3 No E&O coverage exists for agency.
RISK_REASON_EO_INACTIVE 4 E&O Status is not "Active".
RISK_REASON_EO_EXPIRED 5 E&O coverage has expired (E&O ExpirationDate < current date).
RISK_REASON_STATE_APPOINTMENT_TERMINATED 6 A state has terminated the appointment (reported via NIPR) while producerflow still shows it as active.
RISK_REASON_REGULATORY_ACTION 7 An undismissed regulatory action exists (reported via NIPR) against the appointment's producer or agency in the appointment's state.

TerminationReason

TerminationReason represents the reason for the termination of an appointment.

These reasons correspond to NIPR's valid termination codes and vary by state. Not all reasons are valid in every state - use ListTerminationReasons to get the valid reasons for a specific state before calling TerminateAppointment.

Reference: https://pdb.nipr.com/Gateway/ValidTerms

Name Number Description
TERMINATION_REASON_UNSPECIFIED 0
TERMINATION_REASON_VOLUNTARY_TERMINATION 1 Producer or agency voluntarily chose to end the appointment.
TERMINATION_REASON_INADEQUATE_PRODUCTION 2 Carrier terminated due to insufficient premium production or sales volume.
TERMINATION_REASON_CANCELLED_BY_GENERAL_AGENT 3 Appointment was cancelled by the managing general agent (MGA).
TERMINATION_REASON_DEATH 4 Producer has passed away.
TERMINATION_REASON_COMPANY_DEFUNCT_OR_LIQUIDATION 5 Insurance company has ceased operations or entered liquidation.
TERMINATION_REASON_COMPANY_INDEBTEDNESS 6 Producer owes money to the insurance company (e.g., unremitted premiums).
TERMINATION_REASON_POOR_POLICYHOLDER_SERVICE 7 Carrier terminated due to poor service to policyholders.
TERMINATION_REASON_AGENT_MOVED 8 Producer relocated to a different jurisdiction.
TERMINATION_REASON_APPOINTED_IN_ERROR 9 Appointment was created in error and is being corrected.
TERMINATION_REASON_CANCELLED 10 General cancellation without a more specific reason.
TERMINATION_REASON_CANCELLED_FOR_CAUSE 11 Carrier terminated for cause (e.g., misconduct, policy violations).
TERMINATION_REASON_COMPANY_MERGER 12 Insurance company merged with another company.
TERMINATION_REASON_REVOKED 13 Producer's license has been revoked by a regulatory authority.
TERMINATION_REASON_SUSPENDED_FOR_COMPLIANCE 14 Producer's license has been suspended for compliance issues.
TERMINATION_REASON_REQUEST_REGULATORY_REVIEW 15 Termination is being submitted for regulatory review by the state DOI.

↑ Back to Table of Contents

Clone this wiki locally