Apply filing session event

Applies one event to a filing session and returns the resulting form. Events set a field, invoke an action such as advancing to the next step, or search the values of a field. This operation authenticates with the session token returned by create filing session, not an API key. See session tokens.

Request

integer

required

The state version of the session that this event applies to. Use the state_version from your most recent response.

object

required

The event to process. It has a kind that selects one of the shapes below.

Show set_field

Sets the value of a field. This does not advance to the next step.

string

required

set_field.

string

required

The key of the field to set.

any

required

The new value, in the representation given by the field’s ty. For a field with options, use the value of one of the options exactly as given. A document is set with an object; see files.

Show action

Invokes one of the actions on the form, such as submitting the current step and advancing.

string

required

action.

string

required

The action_id of the action to invoke.

Show search

Searches the values of a field that has search. This does not set the field’s value. See search.

string

required

search.

string

required

The key of the field to search.

string

required

The text to search for. If empty, the response contains a default selection of results.

Response

object

The form to render after the event was applied. See the form reference.

integer

The new state version of the session. Use it for your next request.

Concurrency

A session handles one event at a time, and every event names the state version it was based on. This keeps two clients, or a client and a retry, from overwriting each other. If a request fails after you sent it and you cannot tell whether it was applied, send it again with the same state_version: if it was applied the session has moved on, and you get stale_state with the current form instead of a second application.

Errors

The session no longer exists.

Another request for this session is in progress. Wait briefly and retry the same event.

The state_version did not match the session’s current version. The error includes the current form and state_version. Use those rather than retrying blindly, since the field or action you intended may no longer apply.

The session has expired. This is terminal.

Example

Request

curl -X POST https://api.rhetoric.law/apply-filing-session-event \
  --header "Authorization: Bearer $SESSION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "state_version": 1,
    "event": {
      "kind": "set_field",
      "field": "court_system",
      "value": "illinois"
    }
  }'

Response

{
  "result": "ok",
  "form": {
    "title": "Select a court system",
    "blocks": [
      {
        "id": "field_group:court_system",
        "items": [
          {
            "kind": "field",
            "key": "court_system",
            "label": "Court system",
            "description": "The court system where your case will be filed.",
            "required": true,
            "disabled": false,
            "sensitive": false,
            "ty": "string",
            "options": [
              { "value": "california", "label": "California" },
              { "value": "illinois", "label": "Illinois" }
            ],
            "validations": [],
            "value": "illinois",
            "errors": []
          }
        ],
        "actions": []
      }
    ],
    "actions": [{ "action_id": "next", "label": "Next", "primary": true }],
    "breadcrumbs": ["Start filing", "Select a court system"],
    "errors": []
  },
  "state_version": 2
}

Stale state

{
  "result": "err",
  "code": "stale_state",
  "form": { "title": "Select a court system", "...": "..." },
  "state_version": 3
}

Guides

Element

API Reference

CLI Reference

Apply filing session event

Request

Response

Concurrency

Errors

Example

​Request

​Response

​Concurrency

​Errors

​Example

Request

Response

Concurrency

Errors

Example