Skip to main content
GET
List appointment requests
Returns the appointment requests for your agents and agencies, newest first. Requests made anywhere are included, the Turris dashboard too, so this list shows everything Turris operations is working on for you. Each row carries an appointmentRequestId. Use it with Get an Appointment Request to follow one request until it completes.
The appointments themselves, once granted, are on the agent and downstream entity association appointment endpoints. This list is the requests on their way there.

Query Parameters

Every filter is optional, and filters combine. An agentId or downstreamEntityAssociationId that is not in your organization returns 404, not an empty list. Both together return 400.

Statuses

pending, submitting and submitted are in progress. Every other status is final, so stop polling a request once it reaches one of them. The Appointment Request Status Change webhook tells you about each change without polling. A cancelled request stays in the list with status canceled, whether it was cancelled in the Turris dashboard, with Cancel an Appointment Request, or because a product was unassigned. To leave cancelled requests out, filter by the statuses you want. Turris operations moves requests between statuses today. When filing is automated, requests move through the same statuses on their own; no new value is added.

What the list leaves out

  • Renewal and line-of-authority change requests.

Response Shape

All successful responses are wrapped in the standard response envelope. See Request/Response Conventions.
At most one of agentId and downstreamEntityAssociationId is set on each row: a request for an agency that has no association with you left at all carries neither. Fields with no value are left out. submittedAt is the time of the request’s most recent move to submitted. It is kept when the request moves on, and removed if the request goes back to pending or submitting. A request that never reached submitted, and requests submitted before Turris started recording it, lack it, so status is the signal that a request has been filed. completedAt is set on completion, but some older completed requests lack it, so status is the completion signal. canceledAt and canceledBy are set only on a canceled request. canceledAt is when it was cancelled. canceledBy.type says who cancelled it: api_client when it was cancelled through this API, member for a person signed in to the Turris dashboard, admin for Turris operations, and system when Turris cancelled it on its own. Member ids and emails are not included. Requests cancelled before Turris started recording this lack both fields, so status is the signal that a request is cancelled.

Authorizations

Authorization
string
header
required

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

Query Parameters

page
integer
default:1

1-based page number

Required range: x >= 1
Example:

1

limit
integer
default:50

Page size (max 100)

Required range: 1 <= x <= 100
Example:

50

agentId
string

Only requests for this agent. Cannot be combined with downstreamEntityAssociationId. Returns 404 when the agent is not in your organization.

Example:

"6650a1b2c3d4e5f6a7b8c9d0"

downstreamEntityAssociationId
string

Only the requests of the agency behind this downstream entity association and of your other agencies with the same NPN, closed ones included: one open request covers every agency with that NPN, so the filter returns it whichever of them it was made for. Each row carries the current association id of the agency it was made for, which can differ from the one you sent. An archived association works too. Requests for the agency's producers are not included, because an agent request does not record the agency it was made through. Cannot be combined with agentId. Returns 404 when the association is not in your organization.

Example:

"6651a1b2c3d4e5f6a7b8c9d0"

stateCode
enum<string>

Only requests in this state or territory

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

Only requests made under this product

Example:

"6600a1b2c3d4e5f6a7b8c9d0"

status
enum<string>[]

Only requests in any of these statuses. Repeat the parameter (status=pending&status=submitted) or separate values with commas.

Available options:
pending,
submitting,
submitted,
completed,
failed,
submission failed,
rejected,
canceled,
archived
Example:

Response

A page of appointment requests

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"