Build an insurance verification app in 30 minutes with Stedi and a coding agent

Coding agents, like Claude Code or Codex, are how many people develop applications now. You tell the agent what you want to build and point it at some related docs. Minutes later, you have a working app.

Try that with most healthcare clearinghouses, and you’re in for a world of pain.

Stedi gives agents everything they need, including AI-legible docs, test API keys, and test workflows that mirror production. You can access it all using a free account.

This guide shows how to build an insurance verification app in less than 30 minutes using Stedi's JSON Eligibility API and a coding agent. You'll get step-by-step instructions, with prompts for your agent at each step.

What you need

To get started, all you need is a terminal app with Claude Code, Codex, or your preferred coding agent installed.

Step 1. Create a Stedi account

Signing up takes less than two minutes:

1. Go to stedi.com/create-account.

2. Select Create a healthcare clearinghouse account.

3. Fill out the form. Select a free account.

Step 2. Create a test API key

We recommend you use a test API key during development. Test API keys use the same endpoint as production, but they only work with predefined mock requests.

Mock requests return realistic responses (active coverage, copays, deductibles) with no risk of sending real patient data to a payer. When you’re ready to go live, just swap the test key for a production one.

To create a test API key:

1. Log in to your Stedi account.

2. Click your account name at the top right of the screen and select API Keys.

3. Click Generate new API Key.

4. Enter a name for your API key. For example, eligibility-test.

5. Select Test mode.

6. Click Generate and copy the key.

Stedi only shows the key once. Paste it into a password manager or save it somewhere safe before closing the modal.

Step 3. Set up your project folder

In your terminal, create an empty folder for the app:

mkdir eligibility-tutorial
cd eligibility-tutorial

Step 4. Build the backend

Next, you’ll create a Next.js app that calls Stedi’s JSON Eligibility API.

Start your coding agent in the project folder and give it the following prompt:

Scaffold a Next.js app with a route handler at `/api/eligibility` that proxies POST requests to Stedi's real-time eligibility API. Read the key from `STEDI_API_KEY` in `.env.local` and pass it as the `Authorization` header.

Use this OpenAPI spec as the source of truth for the request and response shape: https://raw.githubusercontent.com/Stedi/openApi/main/healthcare.json.

Also create a `.env.local` file in the project root with a single line: `STEDI_API_KEY=your-key-here` as a placeholder.

After creating `.env.local`, open it in the system's default text editor so I can paste my API key.

When finished, just confirm in one line. No summary, file list, or run instructions. 

Step 5. Add your API key

Your agent will open .env.local in a text editor. In the file, replace your-key-here with the Stedi test API key you saved in Step 2, then save the file.

STEDI_API_KEY=your-key-here

Step 6. Build the UI

So far, your app can make API calls, but it doesn’t have a UI yet. To create it, give your coding agent this prompt:

Build a polished eligibility checker. Use shadcn/ui and react-hook-form.

Page title: "Eligibility checker"
No descriptive helper text or subtitles. The page is the title, the form, and the response Card – no prose between them.
Layout: form Card on the left, response Card on the right.

On submit, POST the form to `/api/eligibility` and render the response in the right Card. The response Card has two tabs: a Formatted view (coverage status, plan info, benefits, or an error view when AAA codes are present) and a JSON view (the raw response).

Group form fields under Provider, Subscriber, and Encounter sections, with human-friendly labels:
- Payer ID → `tradingPartnerServiceId`
- Service type → `encounter.serviceTypeCodes` (single value, wrapped in an array on submit; e.g. `30`)
- Provider organization → `provider.organizationName`
- Provider NPI → `provider.npi`
- Subscriber first name → `subscriber.firstName`
- Subscriber last name → `subscriber.lastName`
- Subscriber DOB → `subscriber.dateOfBirth` (`YYYYMMDD`)
- Member ID → `subscriber.memberId`

Above the form, render a "Select a request" dropdown that pre-fills the form with these three mock requests from Stedi's docs. Use the `.mdx` URL – the `.html` version hides the request bodies in collapsed accordions:

- Aetna active coverage: https://www.stedi.com/docs/healthcare/api-reference/mock-requests-eligibility-checks.mdx#aetna---mock-request-1-1
- UHC active coverage: https://www.stedi.com/docs/healthcare/api-reference/mock-requests-eligibility-checks.mdx#uhc---mock-request-1
- AAA-72 error: https://www.stedi.com/docs/healthcare/api-reference/mock-requests-eligibility-checks.mdx#72---aaa-error---mock-request

Copy the `--data` JSON from each accordion's "Request - JSON" tab verbatim. Don't substitute or drop fields. The mocks return errors when the data doesn't match exactly.

When finished, run `npm run dev` so I can preview the app at http://localhost:3000. Leave it running.

Step 7. Test out your app

Open http://localhost:3000 in your web browser to see the app. Select a mock request and run the eligibility check to see live results from Stedi’s API.

This is how our app looked. Your app may look slightly different.

Keep in mind that the test API key only works with the predefined mock requests. You can’t use it with other request values.

Next steps: Move to production

When you're ready to run real eligibility checks, you'll need to take a few extra steps:

• Decide which Eligibility API request fields you want to support, and have your coding agent remove the Select a request dropdown and mock requests.

• Swap the test API key in .env.local for a production API key. If you’re on a free account, you’ll need to upgrade to a production account first.

• Update the app to use Stedi's Payers API to find and use payer IDs that support eligibility checks.

• Refine the UI to suit your use case.

• Deploy to Vercel or your preferred hosting platform. For Vercel, add your production API key as the STEDI_API_KEY variable in your project's environment variables.

For more tips, see How to use Stedi with a coding agent.