Skip to main content

Reviewing and signing

Once an application is SUBMITTED it waits for a judge. This guide covers the review side of the workflow.

The review queue​

curl -s "$BASE/warrants?status=SUBMITTED&limit=50" -H "x-api-key: $API_KEY"

Order the result by priority and submitted_at in your client: URGENT applications are the reason this workflow exists at all, and a queue that buries one is worse than no queue.

To show one judge their own routed work:

curl -s "$BASE/warrants?status=SUBMITTED&assigned_to_me=true" \
  -H "x-api-key: $API_KEY" \
  -H "X-On-Behalf-Of: judge.alvarez@example.gov"

Routing​

Assignment is a routing hint, not a lock. It says who is expected to act, and it directs the notification. Any judge in the agency can still sign, which is what keeps an urgent application from stalling behind one person's day. The audit trail then shows who was asked and who signed.

List the judges who can take work, with how much they already hold:

curl -s "$BASE/warrants/assignable-judges" -H "x-api-key: $API_KEY"
[
  {
    "id": "a83f5c07-2d19-4b6e-9f42-5c7a1e3d8b90",
    "full_name": "Hon. Maria Alvarez",
    "email": "judge.alvarez@example.gov",
    "on_dnd": false,
    "open_warrants": 2
  }
]

on_dnd means the judge has muted notifications. They can still be assigned; they just will not be paged.

Route or reroute:

curl -s -X PATCH "$BASE/warrants/$WARRANT_ID/assign" \
  -H "x-api-key: $API_KEY" \
  -H "X-On-Behalf-Of: clerk.hayes@example.gov" \
  -H "Content-Type: application/json" \
  -d '{"judge_id": "a83f5c07-2d19-4b6e-9f42-5c7a1e3d8b90", "reason": "On call for the overnight bench rotation."}'

Clear it with DELETE /v1/warrants/{id}/assign, which returns the application to the unassigned queue.

Routing at submission time, and the agency-wide default, are covered in agency settings.

Escalation​

An assigned application that nobody acts on escalates to the whole bench after a configurable interval, separately for URGENT and STANDARD priority. The escalation is recorded in the audit trail as its own action, so "nobody was told" and "everybody was told and nobody acted" are distinguishable after the fact. Configure the intervals in agency settings.

Signing​

curl -s -X PATCH "$BASE/warrants/$WARRANT_ID/sign" \
  -H "x-api-key: $API_KEY" \
  -H "X-On-Behalf-Of: judge.alvarez@example.gov"

Signing requires the warrants:sign scope and an X-On-Behalf-Of naming a person who may sign in that agency. The signature applied to the document is that person's stored signature, and the warrant records them as the signer. An integration cannot sign as itself.

The response carries judge_name, signed_at, and a short-lived pdf_url for the rendered document.

Rejecting​

curl -s -X PATCH "$BASE/warrants/$WARRANT_ID/reject" \
  -H "x-api-key: $API_KEY" \
  -H "X-On-Behalf-Of: judge.alvarez@example.gov" \
  -H "Content-Type: application/json" \
  -d '{"reason": "The examination time predates the reported incident. Correct the timeline and resubmit."}'

Write the reason for the applicant, not for the file. It is added to the comment thread and it is the only thing they have to work from, so name the field that is wrong and what would make it right. The applicant can then reopen the application, correct it, and submit again.

What reviewers may change​

Reviewers do not edit an application's form_data in the normal case: an application signed after a reviewer quietly changed it is not the application the applicant swore to. Correction runs through rejection and reopening, which leaves the change in the applicant's hands and in the audit trail.

Agencies that permit reviewer edits grant that through a custom role; the edit is audited like any other.