Skip to main content
POST
Request an appointment
Requests the appointment of one agent or one agency with the carrier of productId, in stateCode. The answer is the one the Turris dashboard would give: 201 with the new request, or the reason it was refused. Needs the Appointment product feature.

Request Body

Send exactly one of agentId and downstreamEntityAssociationId. Neither or both returns 400. For an agent:
For an agency, name it by its association with you:

What You Get Back

Every request starts as pending with processingMethod manual: Turris operations files it with the state, and its status moves from there. Follow it with Get an Appointment Request, which returns the same fields. See List Appointment Requests for the statuses.

Authorization in the Same Request

The licence is checked on every request: the agent or agency must be licensed in the state for the product. If it is licensed but not yet authorized there, the request authorizes it. A refused request authorizes nothing, with two exceptions, described under Calling It Again.
  • An agency is authorized through the association you named.
  • An agent on exactly one of your agencies is authorized through that agency.
  • An agent on several of your agencies can be requested only in a state it is already authorized in, through any of them. Any other state is refused with NOT_AUTHORIZED, and the message asks you to authorize the state in Turris first.

One Request per Call

A request for an agent does not also request the agency’s appointment. If the carrier needs both, make a second call with the agency’s downstreamEntityAssociationId.

Calling It Again

Only one request can be open for the same NPN, state and carrier. NIPR appoints the NPN, so when two of your agencies have the same NPN, a request made for one of them is the open request for both. A second call answers 409, and the two 409 codes mean different things:
  • OPEN_REQUEST_EXISTS: a request is already open, for this agent or agency, for another of your agencies with the same NPN, or under another of your products with the same carrier. details.existingAppointmentRequestId is its id.
  • ALREADY_APPOINTED: the agent or agency already holds the appointment. No request was made, and there is no id.
Both codes carry details.isStateAuthorized: whether the state is authorized for the product you sent, after this call. Both can still authorize it. If the agent or agency is licensed in the state but not yet authorized there for the product, the call authorizes the state, as a created request would, when an open request covers it, or when the appointment it already holds with the carrier covers every line of authority the product needs there. The field is then true, and a repeat call answers the same. ALREADY_APPOINTED with isStateAuthorized: false means the appointment lacks a line of authority the product needs, so the call authorized nothing. So OPEN_REQUEST_EXISTS with isStateAuthorized: true means the request exists and the state is authorized, and you can call this endpoint on every bind. A request counts as open while it is pending, submitting or submitted. Once it reaches any other status, a new call creates a new request. Send an idempotency-key header to make a network retry safe. A successful create is replayed with 201 and the same body for one hour. A refusal or a 503 is not stored, so a retry with the same key runs again. See Idempotency.

Refusals

Every 409 and 422 carries details.refusalCode. Branch on the code; show errorMessage to a person. When several refusals apply, which one you get follows the order Turris checks them in. That order is not part of the contract: branch on the code, not on the order. A 409 for an open request:
A 422 has the same shape, with errorType unprocessable_entity and neither existingAppointmentRequestId nor isStateAuthorized.

License Data Not Synced Yet

The license check reads the agent’s or agency’s NIPR data in Turris. Until its compliance data subscription has synced, Turris has no license on record, so the request is refused with LICENSE_DATA_NOT_SYNCED rather than NOT_LICENSED. A newly added agent or agency can get this while its first sync runs, and a first sync requested after about 8:45 PM Central waits for NIPR’s next overnight update. details.syncStatus says where the sync is and what to do: You can also follow the sync with Get Subscription Status, using details.niprDataSubscriptionId. If no webhook has arrived by the end of the next business day, contact Turris support. Once the sync has finished, an agent or agency that is not licensed in the state is refused with NOT_LICENSED.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

idempotency-key
string

UUID to ensure idempotent request processing

Example:

"550e8400-e29b-41d4-a716-446655440000"

x-idempotency-key
string

Alternative UUID header for idempotent request processing

Example:

"550e8400-e29b-41d4-a716-446655440000"

Body

application/json
stateCode
enum<string>
required

The state or territory to be appointed in

Available options:
AL,
AK,
AZ,
AR,
CA,
CO,
CT,
DE,
FL,
GA,
HI,
ID,
IL,
IN,
IA,
KS,
KY,
LA,
ME,
MD,
MA,
MI,
MN,
MS,
MO,
MT,
NE,
NV,
NH,
NJ,
NM,
NY,
NC,
ND,
OH,
OK,
OR,
PA,
RI,
SC,
SD,
TN,
TX,
UT,
VT,
VA,
WA,
WV,
WI,
WY,
GU,
PR,
VI,
DC
Example:

"TX"

productId
string
required

One of your products. Its carrier is the one the appointment is requested with.

Example:

"6600a1b2c3d4e5f6a7b8c9d0"

agentId
string

The producer to request the appointment for. Send this or downstreamEntityAssociationId, not both. If the agent is on exactly one of your agencies, a licensed state it is not yet authorized in is authorized through that agency in the same request.

Example:

"6650a1b2c3d4e5f6a7b8c9d0"

downstreamEntityAssociationId
string

The agency to request the appointment for, as one of your associations. Send this or agentId, not both.

Example:

"6651a1b2c3d4e5f6a7b8c9d0"

Response

The appointment request

data
object
required
requestId
string
required

Unique request identifier

Example:

"dev-2c5e7cf2-9acf-4c8c-ab2f-b81f39d775a8"

timestamp
string
required

Response timestamp

Example:

"2025-11-12T20:49:03.293Z"