Skip to main content
POST
Request a termination
Requests the termination of an agent’s or agency’s appointment 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. An agency you have archived in Turris, and an agent you have removed from your agencies, can still be terminated. For an agent:
For an agency, name it by its association with you:
terminationReasonCode is the NIPR termination reason code, as a string. Whether it is required, and which codes are accepted, depends on the state. See Termination Reason Codes.

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 a Termination Request, which returns the same fields. While it is pending you can withdraw it with Cancel a Termination Request.

What Gets Terminated

The request covers the lines of authority the agent or agency holds with the carrier in the state that the product uses. Lines that another of your products with the same carrier still needs, for an agent or agency authorized for that product in the state, are kept. The state stays authorized for the product. A termination does not change authorization; unauthorize the state in the Turris dashboard if that is also what you want. NIPR appoints per NPN, carrier and state, not per product or per organization. A termination ends the appointment with that carrier for every organization that relies on it.

Shared Lines of Authority

Two of your products with the same carrier can need the same lines in a state. Say both Commercial Auto and General Liability need Property and Casualty in Texas, and the agency is authorized for both there. A termination through either product is refused with LINES_OF_AUTHORITY_PRESERVED, because the other product still needs every line. The refusal names the products in details.preservingProducts. To end the appointment anyway, unauthorize the state for one of those products in the Turris dashboard, then request the termination again through the other.

Termination Reason Codes

A state that requires a code refuses a request without one with TERMINATION_REASON_CODE_REQUIRED. A code the state does not accept is refused with TERMINATION_REASON_CODE_NOT_ACCEPTED. Both refusals list the codes the state accepts in details.acceptedCodes. Where a state has no list of its own, the code is optional and any code above is accepted.

One Request per Call

A request for an agent does not also terminate 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, so a termination is refused with 409 while another request for them is open. A request counts as open while it is pending, submitting or submitted.
  • TERMINATION_REQUEST_EXISTS: a termination is already open, made for this agent or agency, for another of your agencies with the same NPN, under another of your products with the same carrier, or in the Turris dashboard. details.existingTerminationRequestId is its id and details.status its status.
  • OPEN_CHANGE_REQUEST_EXISTS: another kind of request is open, such as an appointment request. details.existingRequestId, details.category and details.status say which. A pending appointment request can be withdrawn with Cancel an Appointment Request; once a request is submitting or submitted, Turris operations is filing it, so wait for it to finish. Other kinds of requests are cancelled in the Turris dashboard.
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 over an open appointment request:
A 422 for shared lines:

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 of the appointment

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. The appointment with its carrier is terminated, on the lines of authority this product uses.

Example:

"6600a1b2c3d4e5f6a7b8c9d0"

agentId
string

The producer whose appointment to terminate. Send this or downstreamEntityAssociationId, not both. An agent removed from your agencies is accepted.

Example:

"6650a1b2c3d4e5f6a7b8c9d0"

downstreamEntityAssociationId
string

The agency whose appointment to terminate, as one of your associations, archived ones included. Send this or agentId, not both.

Example:

"6651a1b2c3d4e5f6a7b8c9d0"

terminationReasonCode
string

The NIPR termination reason code, as a string ("1" is Voluntary Termination). Required in states that require one; the Request a Termination page lists the codes each state accepts.

Example:

"1"

Response

The termination 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"