Quickstart

This guide will help you set up a basic integration with Rhetoric. In broad strokes, this is the process:

Create an API key
Install the necessary SDKs
Initiate a filing session
Submit your first filing
Listen for filing events

Create an API key

You use API keys to authenticate requests to the Rhetoric API. Create one from the dashboard. Each key is scoped to an environment: live or test. Filings submitted using a test key do not get sent to a real court. Use a test key while you build out your integration. Treat API keys like passwords. Keep them on your backend, and do not commit them to source control or expose them to the browser.

Install the API client on your backend

The Rhetoric API client is a TypeScript package that exposes all of the operations provided by our API. It is meant to be used on your backend. You can install it using the following command:

npm install @rhetoriclabs/rhetoric

Once the package is installed, create a client like so:

import { RhetoricClient } from "@rhetoriclabs/rhetoric";

const client = new RhetoricClient({
  url: "https://api.rhetoric.law",
  token: process.env.RHETORIC_API_KEY,
});

Install the Element on your frontend

The Rhetoric Element is an embeddable React component that guides your users through filing. It supports React 18+ and is meant to be used on your frontend. You can install it using the following command:

npm install @rhetoriclabs/element-react

The Element needs a session token to function. We will create one in a subsequent section.

Create a filer

A filer represents an entity that files documents through Rhetoric, such as an individual or an organization. A filer typically corresponds one to one with a user of your platform. Call create filer on the backend the first time a user of your platform needs to file something, and associate the returned filer ID with your user (e.g., by storing Rhetoric filer ID as a field on your user record). On subsequent filings for the same user, reuse that ID rather than creating a new filer.

const { filer } = await client.createFiler({});

Create a filing session

A filing session holds the state of an in-progress filing. The Element guides the filer through that session. Call create filing session with the ID of the filer conducting the filing.

const { session, sessionToken } = await client.createFilingSession({
  filerId: filer.id,
});

This operation returns a sessionToken. The Element component uses this token to authenticate requests for the duration of the session, and it is only returned once at creation time. It cannot be recovered later, so capture it and pass it on to your frontend.

Pass the session token to your frontend

Unlike your API key, which should stay on your backend, a session token is scoped to a single filing session and is safe to hand to the browser. Send it to your frontend through whatever mechanism your application already uses to serve data to the client, such as your own backend API.

Render the Element

With the session token available in the browser, render the Element component and give it the token.

import { Element } from "@rhetoriclabs/element-react";

function FilingPanel({ sessionToken }: { sessionToken: string }) {
  return <Element sessionToken={sessionToken} />;
}

Submit a filing

From here, the Element takes over. It renders the current step of the filing, collects any information the court requires, and calls back to Rhetoric directly as the filer progresses, all the way through submission. You can try this out yourself before wiring up a real filer. Walk through the Element submission process end to end using a demo account and a test filing:

Select a court system

Choose California.

Select court

Choose Santa Cruz - Civil.

Log in using our test account. The username is mustafa+prose-demo@rhetoric.law and the password is Hellorhetoric1.

Choose a filing type

Choose New case.

Select case category

Choose Civil - Unlimited.

Select case type

Choose Breach of Contract/Warranty.

Add parties

This filing requires two parties. Add Mustafa Moiz as a plaintiff, and add Hamza Surti as a defendant. For each party, set the party kind to Individual. Mustafa Moiz should be designated as the filer.

Add a filing entry

Add a filing entry with the filing code Complaint. Add a document to the entry with the document type Public. Upload a document of your choosing, or you can use this sample complaint as a placeholder. It has one page.

Select a payment account

Use our test payment method, listed as Credit card.

Review fees

The fee review page shows you the total cost of filing as well as the line items that contribute to that cost.

Disclaimers

Check the box to agree to the eService Agreement.

Review and submit

The final review page shows a summary of the filing, including the routing info, parties, documents, and payment account. Confirm that the selections match the guidance above, then click Submit filing.

Listen for the submission webhook

When the filer completes the session, Rhetoric sends a filing submitted event to any webhook you have registered. Register a webhook endpoint from the dashboard to be notified, rather than polling the API for status changes. See the webhooks guide for details on registering endpoints, retries, and idempotency, and the webhooks reference for the events Rhetoric can send.

Next steps

If you want a deeper understanding of the domain, our filing primer provides a high level overview of the efiling system and the core concepts involved. For detailed information about the endpoints Rhetoric offers and the patterns we follow, see the API reference. For more on registering endpoints and handling delivery correctly, see the webhooks guide.

Guides

API Reference

CLI Reference

Create an API key

Install the API client on your backend

Install the Element on your frontend

Create a filer

Create a filing session

Pass the session token to your frontend

Render the Element

Submit a filing

Listen for the submission webhook

Next steps

​Create an API key

​Install the API client on your backend

​Install the Element on your frontend

​Create a filer

​Create a filing session

​Pass the session token to your frontend

​Render the Element

​Submit a filing

​Listen for the submission webhook

​Next steps

Create an API key

Install the API client on your backend

Install the Element on your frontend

Create a filer

Create a filing session

Pass the session token to your frontend

Render the Element

Submit a filing

Listen for the submission webhook

Next steps