Appointments

Appointments authorize producers to conduct business in relation to a limited set of products and jurisdictions, even if a producer is licensed to conduct business in relation to additional products and jurisdictions. Each appointment is associated with one producer. Products can be configured to require producers associated with a quote or policy transaction to have a valid appointment when an underwriting request is processed.

Appointments can contain extension data. Extension data for appointments supports media data.

Note

Appointments do not require producers to be licensed, though this is typically the case.

Lifecycle

The following diagram illustrates the lifecycle for appointments:

Appointments begin in the draft state after creation and will move to the validated state following a successful validation request.

Appointments in the draft or validated states will move to the discarded state following a successful discard request. Once appointments are moved to the discarded state, they cannot be moved back to the validated state and cannot be used again.

Configuration

Before appointments can be created, they must be defined within the producerAppointments object in the producerManagement configuration object.

For example:

{
    "producerManagement": {
        "producerAppointments": {
            "ExampleProducerAppointment": {
                "abstract": true,
                "extend": "AnotherProducerAppointment",
                "data": {},
                "defaultSearchable": false
            }
        }
    }
}

Appointments can be defined as abstract, meaning they cannot be created directly. Appointments can inherit data from the appointment specified in the extend field.

Extension data can be defined in the data field.

The defaultSearchable field can be used to modify search behavior.

Create an Appointment

Once your configuration changes have been deployed, create an appointment through the Create Producer Appointment API endpoint.

Here’s an example request:

{
    "type": "ExampleProducerAppointment",
    "appointmentNumber": "34677263",
    "producerCodes": ["43668", "84634"], // An empty list means all producer codes associated with a producer
    "jurisdictions": ["CA", "FL"], // An empty list means all jurisdictions
    "products": ["CommercialAuto", "CommercialProperty"], // An empty list means all products
    "licenses": ["01HSZ77AA61B87613", "01J37GAVZ732AB176"], // Optionally associate the appointment with one or more license locators
    "effectiveTime": "2026-06-15T00:00:00Z",
    "expirationTime": "2027-06-15T00:00:00Z",
    "data": {}
}

The request object contains the following fields:

type - The name of an appointment listed in the producerAppointments configuration object
appointmentNumber - An appointment number associated with the appointment
producerCodes - The producer codes covered by the appointment
jurisdictions - The jurisdictions covered by the appointment
products - The products covered by the appointment
licenses - License locators associated with the appointment
effectiveTime - When the appointment becomes active
expirationTime - When the appointment expires
data - Extension data

An empty list for producerCodes, jurisdictions, or products means the appointment applies to all possible values for the given field.

The producerCodes field can include producer codes associated with the producer and producer codes associated with producers contained within the producer hierarchy.

Appointment details can be updated through the Update Producer Appointment API endpoint. Expired licenses can be renewed by updating the effectiveTime and expirationTime values.

Use the Validate Producer Appointment API endpoint to validate an appointment.

Refer to the Producer Management API index for additional API endpoints.

Underwriting Criteria for Appointments

Products can be configured to require producers associated with a quote or policy transaction to meet the following underwriting criteria:

Producers must have a non-expired appointment currently in effect and in the validated state for the product.
Producers must have an appointment associated with the jurisdiction that matches the jurisdiction associated with the product. See the Jurisdictions feature guide for more information.

These requirements can be enabled by setting the producerQualification field at the top level of the ProductRef configuration to appointment. The default value is none.

If the producerQualification field is set to appointment, and a quote or policy transaction associated with a producer fails to meet the above underwriting criteria, underwriting requests will fail, and the system will automatically add an underwriting flag to the quote or policy transaction. See the Producers feature guide for more information.

Underwriting criteria for appointments are evaluated based on the producerCode associated with a quote or policy transaction. The producerCodeOfRecord associated with a quote or policy transaction has no effect on underwriting criteria for appointments.

Note

These requirements are only enforced if a quote or policy transaction is associated with a producer. If a product is not associated with a jurisdiction, producers associated with the product are not required to have an association with any specific jurisdiction.

Here’s an example product configuration:

{
    "products": {
        "CommercialAuto": {
            "producerQualification": "appointment" // none | license | appointment - The default value is none
        }
    }
}