Queue

The queue puts visitors in a live line at a location. A visitor joins a line, gets a ticket number (for example DL-004), and waits until staff at a station call the ticket. Staff work the line in the eCourtDate app. Visitors join on the agency's portal, on an eCourtDate kiosk, or through this API.

Each visit is a checkin with a queue state. This page covers the endpoints that another system, such as a kiosk vendor's software or a lobby check-in system, uses to add visitors and follow them. For a full kiosk setup, see Kiosks and Lobby Displays.

This page assumes the shared API Conventions for authentication, pagination, and lifecycle actions. All endpoints use the region's base URL and a Bearer token.

Endpoints

Method	Path	Description
GET	/v1/queue_lines	List the agency's lines
GET	/v1/queue_lines/{uuid}	Get a line
GET	/v1/queue_services	List the agency's services
GET	/v1/queue_services/{uuid}	Get a service
GET	/v1/queue/lines/{uuid}/status	Get a line's live status
POST	/v1/queue/visits	Add a visitor to a line
GET	/v1/queue/visits/{uuid}	Get a visit
GET	/v1/queue/visits/{uuid}/events	Get a visit's history
POST	/v1/queue/visits/{uuid}/arrive	Mark that a visitor arrived
POST	/v1/queue/visits/{uuid}/cancel	Cancel a visit

The eCourtDate app uses more queue endpoints: station sign-in, Call Next, the staff actions on a visit, line pause and close, and device pairing. They need a staff user at a station, so this page lists them only in Staff Endpoints.

Concepts

Term	Meaning
Line	What visitors join and stations serve, at one location. A line has a ticket prefix, a ranking strategy, and timers.
Service	What a visitor comes for, for example "Pay a fine". A service belongs to a line.
Station	A counter or desk that serves one or more lines. Staff sign in to a station and call the next visitor.
Visit	One visitor's place in a line, from joining to completion. A visit is a checkin row with a queue_state.
Ticket	The number a visitor sees and hears called, for example DL-004.

Find the Line and Service UUIDs

Staff create lines and services in the eCourtDate app. To add a visitor, an integration needs the UUID of the line, and the UUID of the service when the line has more than one.

curl "$BASE_URL/v1/queue_lines?location={location_uuid}" \
  -H "Authorization: Bearer $TOKEN"

curl "$BASE_URL/v1/queue_services?line={line_uuid}" \
  -H "Authorization: Bearer $TOKEN"

List filters:

Endpoint	Filters
GET /v1/queue_lines	search, location, reference, strategy
GET /v1/queue_services	search, line, reference, availability_template

Pagination (limit up to 100, skip, sort, sortDirection, fields) follows the shared conventions. Store the UUIDs in the integration's configuration. Look them up again when staff change the lines.

The Line Object

Field	Type	Description
uuid	string	Unique identifier.
location	string	UUID of the location the line is at.
name	string	Name of the line.
reference	string	The agency's own identifier for the line.
ticket_prefix	string	Letters and digits put before each ticket number, for example DL. Blank gives tickets such as 004.
strategy	string	How visitors are ranked: fifo (first in, first out, the default), appointment, or priority.
early_minutes	integer	On an appointment line, how early a visitor with an appointment can join. Default 30.
grace_minutes	integer	On an appointment line, how late a visitor can be and keep the appointment's place. Default 15.
very_late_action	string	On an appointment line, what happens after the grace period: walkin (join as a walk-in, the default) or reject.
call_timeout	integer	Minutes a called visitor has to come to the station before the visit becomes a no-show. Default 5.
max_active	integer	The most visitors that can wait at one time. null means no limit.
requires_arrival	integer	1 (the default) when a visitor who joins from away must be marked as arrived before staff can call them.
show_position	integer	1 when the visitor's status page shows the place in line. Default 0.

The Service Object

Field	Type	Description
uuid	string	Unique identifier.
line	string	UUID of the line the service belongs to.
name	string	Name of the service. A visit stores this name in its service field.
reference	string	The agency's own identifier for the service.
default_duration	integer	Expected minutes per visitor, used for wait estimates until the line has completed visits that day.

Add a Visitor to a Line

POST /v1/queue/visits

Request:

curl -X POST "$BASE_URL/v1/queue/visits" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0f8b2d4e-6a1c-4b3e-9d7f-2c5a8e1b4f60" \
  -d '{
    "line": "{line_uuid}",
    "service": "{service_uuid}",
    "source": "kiosk",
    "name": "Jane Doe",
    "phone": "+15551234567",
    "language": "en"
  }'

Field	Required	Description
line	Yes	UUID of the line to join.
service	No	UUID of a service on the line.
service_name	No	A service name to store in place of the service's own name. Up to 100 characters.
source	No	Where the visit came from: portal, appointment, walkin, kiosk, concierge, qr, sms, api, or staff. Kiosk software sends kiosk. Other systems send api. When omitted, the source is appointment if appointment_at is set, otherwise staff.
name	No	The visitor's name. Up to 100 characters. HTML is removed.
phone	No	A phone number that can receive texts. Up to 36 characters. It must be a valid phone number (US numbers do not need the country code).
email	No	An email address. Up to 255 characters. It must be a valid email address.
language	No	Language code for the visitor's messages. Up to 4 characters. Defaults to en. See Language codes.
notes	No	Notes for staff. Up to 100 characters. HTML is removed.
client	No	UUID of a known client.
event	No	UUID of the event (the appointment or court date) the visitor came for.
portal	No	UUID of the portal the visit came through.
priority	No	Priority class, 0 to 9. Used on priority lines.
appointment_at	No	The appointment time, in UTC. On an appointment line it ranks the visitor by the appointment.
arrived	No	true (the default) when the visitor is at the location now. Send false for a visitor who joins from away. On a line that requires arrival, staff cannot call that visitor until the visit is marked as arrived.
data	No	An object of extra details to keep on the visit.

Send the Idempotency-Key header (or an idempotency_key body field) with a UUID generated once per visitor. A retry with the same key returns the visit that the first request created, with 201, and does not add a second visit. Keys are unique per agency, up to 36 characters. Without a key, every request adds a new visit.

Response (201): the visit.

{
  "uuid": "6b1f0c2e-3d4a-4e5f-8a9b-0c1d2e3f4a5b",
  "line": "{line_uuid}",
  "queue_service": "{service_uuid}",
  "service": "Pay a fine",
  "location": "{location_uuid}",
  "name": "Jane Doe",
  "phone": "+15551234567",
  "language": "en",
  "source": "kiosk",
  "ticket": "DL-004",
  "queue_state": "queued",
  "status": "waiting",
  "priority": 0,
  "callable": true,
  "rank_reason": "Walk-in, ranked from arrival",
  "recalls": 0,
  "version": 1,
  "arrived_at": "2026-11-03T14:41:07Z",
  "estimated_at": "2026-11-03T15:02:00Z",
  "url": "aB3dE5fG7hJ9",
  "created_at": "2026-11-03 14:41:07"
}

Create Behavior

• Ticket numbers count up per line, per day in the agency's time zone, and start again each day. The number has at least three digits, after the line's ticket_prefix and a hyphen (DL-001, DL-002), or without a prefix (001).
• queue_state starts as queued. status is the agency's label for that state, waiting by default.
• callable is true when staff can call the visitor. It is false for a visitor who has not arrived on a line that requires arrival.
• estimated_at is the expected time the visitor is called. It comes from the visitors ahead, the median service time of the line's visits that day (or the service's default_duration, or 10 minutes), and the number of open stations.
• url is the token of the visitor's own status page, https://{portal domain}/v/{url}. The page shows the ticket and the call, and the place in line when the line's show_position is on. Give the token only to that visitor, for example as a link or QR code on the ticket. Anyone with the token can see and change the visit.
• data is a JSON-encoded string in this response. GET /v1/queue/visits/{uuid} returns it as an object.
• Messages. When the visit has a phone, an email, or a client, eCourtDate sends the agency's auto message for the queue_joined trigger, if the agency has one. Later auto messages use the triggers queue_approaching, queue_called, queue_recalled, and queue_delayed. Without a matching auto message, no message is sent.
• Timestamps. created_at is YYYY-MM-DD HH:MM:SS in UTC. arrived_at and estimated_at are ISO 8601 in UTC.

Errors

Status	Message	Cause
400	line {error} (and other field names)	A field failed validation, for example a missing line or a source that is not in the list.
400	phone is not a valid phone number	phone is set but is not a valid phone number.
400	email is not a valid email address	email is set but is not a valid email address.
404	Line not found	No active line of the agency has this UUID.
404	Service not found	No active service of the agency has this UUID.
423	This line is paused	Staff paused the line.
423	This line is closed	Staff closed the line.
423	This line is not taking new visitors	Staff stopped new joins. Visitors already waiting are still served.
423	This line is full	The line has max_active visitors waiting.
422	Too early to check in; come back at {time}	On an appointment line, the visitor is more than early_minutes before the appointment.
422	More than {n} minutes past the appointment; please reschedule	On an appointment line with very_late_action set to reject, the visitor is past the grace period.
503	The queue store failed during {operation}	eCourtDate could not record the visit. Retry with the same Idempotency-Key.

Show the visitor a plain message for a 423 or 422, for example "This line is not open. Please see the front desk." Do not retry these automatically.

Get a Visit

GET /v1/queue/visits/{uuid}

Returns the visit with its data decoded. While the visit is active, the response has its live queue_state, callable, rank_reason, estimated_at, and, once called, the station and served_by. Returns 404 with Visit {uuid} not found when no visit matches.

Visit States

queue_state	Active	Default status label	Meaning
queued	Yes	waiting	Waiting in line.
called	Yes	ready	Staff called the ticket to a station.
serving	Yes	in_progress	Staff are serving the visitor.
held	Yes	waiting	Staff put the visit on hold.
completed	No	checked_out	Service is complete.
cancelled	No	cancelled	The visit was cancelled.
no_show	No	no_show	The visitor did not come when called.
abandoned	No	left	The visit was still waiting from an earlier service day.

An agency can change the status labels, so an integration reads queue_state to decide what to do.

Get a Visit's History

GET /v1/queue/visits/{uuid}/events

Returns a JSON array of the visit's events, oldest first. Each event has type, from_state, to_state, version, actor_type (api, user, or visitor), station, payload, and occurred_at.

Event types include VISIT_CREATED, ARRIVED, PRIORITY_CHANGED, DELAYED, CALLED, RECALLED, SERVICE_STARTED, HELD, RESUMED, NO_SHOW, REJOINED, ABANDONED, CANCELLED, and COMPLETED.

Mark That a Visitor Arrived

POST /v1/queue/visits/{uuid}/arrive

Use this for a visit created with "arrived": false, when the visitor reaches the location. On a line that requires arrival, the visit becomes callable. The visit must be queued.

Response (200): the visit.

Cancel a Visit

POST /v1/queue/visits/{uuid}/cancel

Cancels an active visit, for example when the visitor presses Leave the line on the integration's screen. An optional reason (up to 255 characters) is kept in the visit's history.

curl -X POST "$BASE_URL/v1/queue/visits/{visit_uuid}/cancel" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Visitor left from the kiosk"}'

Response (200): the visit, with queue_state set to cancelled.

Action Errors

Status	Message	Cause
404	Visit {uuid} not found	No visit of the agency has this UUID.
404	Active visit not found	The visit is no longer active. An active visit expires 48 hours after it was created.
409	A {state} visit cannot {action}	The visit is not in a state that allows the action. The response also has state and allowed, the actions the visit allows now.
409	Visit {uuid} changed underneath this request; reload and retry	Another change to the visit happened at the same time. Get the visit and try again.

Get a Line's Status

GET /v1/queue/lines/{uuid}/status

Response (200):

{
  "uuid": "{line_uuid}",
  "name": "Driver License",
  "location": "{location_uuid}",
  "open_stations": 3,
  "status": "open",
  "intake": "open",
  "waiting": 12,
  "serving": 2
}

Field	Description
status	open, paused, or closed.
intake	open, paused, or closed. When it is not open, the line takes no new visitors.
open_stations	The number of signed-in stations at the line's location that are not on a break.
waiting	About how many visitors are waiting.
serving	About how many visitors are being served.

Read the status before showing a line on a kiosk screen. A line can take new visitors only when both status and intake are open.

Staff Endpoints

The eCourtDate app uses these endpoints. They need a staff user signed in to a station, and an integration does not usually call them.

Method	Path	Description
POST	/v1/queue/visits/{uuid}/recall	Call a called visitor again.
POST	/v1/queue/visits/{uuid}/start	Start serving a called visitor.
POST	/v1/queue/visits/{uuid}/complete	Complete a visit.
POST	/v1/queue/visits/{uuid}/hold	Put a visit on hold.
POST	/v1/queue/visits/{uuid}/resume	Return a held visit to the line.
POST	/v1/queue/visits/{uuid}/no-show	Mark a called visitor as a no-show.
POST	/v1/queue/visits/{uuid}/rejoin	Return a no-show to the line.
POST	/v1/queue/visits/{uuid}/delay	Give a waiting visitor more time (minutes, 1 to 120).
POST	/v1/queue/visits/{uuid}/priority	Change a visit's priority. A reason is required.
GET	/v1/queue/stations/{uuid}	Get a station and its current visit.
POST, PATCH, DELETE	/v1/queue/stations/{uuid}/sessions	Sign in to, change the state of, or sign out of a station.
POST	/v1/queue/stations/{uuid}/next	Call the next visitor to the station.
POST	/v1/queue/lines/{uuid}/pause, /resume, /close, /pause-intake	Pause, open, close, or stop new joins on a line.

FAQs

How does a visitor know their ticket was called?

The visitor's status page (/v/{url}) and the lobby display show the call. When the visit has a phone or email, the agency's queue_called auto message is sent too, if the agency has one.

Can the integration print a ticket?

Yes. Print the ticket from the create response. Add a link or QR code to https://{portal domain}/v/{url} so the visitor can follow the line on a phone.

What happens when the network fails during a create?

Send the request again with the same Idempotency-Key. When the first request reached eCourtDate, the retry returns that visit and adds no second ticket.

How do I list the visitors in a line?

GET /v1/checkins?line={line_uuid}&queue_state=queued. The Checkins list also filters by ticket and source.

Can I change a visit with PATCH /v1/checkins/{uuid}?

Do not use it for queue visits. It changes the checkin row only, not the visit's place in the line. Use the queue endpoints on this page.

Related Documentation

• Kiosks and Lobby Displays: set up eCourtDate kiosks and displays, or connect other kiosk software
• Checkins: the record each visit is stored as
• API Conventions: shared listing, filtering, and lifecycle behavior
• Idempotency & Deduplication: safe retries
• Error Handling: status codes and error responses