# Playbooks

Playbooks are for developers and implementation teams who want to automate a complete business workflow with VBAPI, not just make single calls. Each one lists the calls in order, the smallest request body each call accepts, what to carry from one step to the next, and how to check the result, with runnable samples in C#, Python, and TypeScript.

Most playbooks change production data
VBAPI clients connect to production. Playbooks marked "Writes data: Yes" create or change real records in the database you name in `vbasoftware-database`. Try them in a non-production database first if VBA has given you one, and use obviously fake values while you test.

## Choose a playbook

P1. Onboard a new employer group
**Outcome:** a new group with a division copied from a template, including contracts, plans, and premiums.

**For:** implementation teams. **Time:** about 20 minutes. **Writes data:** Yes.

P2. Enroll employees and dependents
**Outcome:** subscribers and dependents enrolled in a group plan, with ID card requests; one family or a whole census.

**For:** HR and benefits integrators. **Time:** about 20 minutes. **Writes data:** Yes.

P3. Enter claims and adjudicate them
**Outcome:** claims keyed in, queued, and adjudicated in bulk, with examiners notified.

**For:** claims integrators. **Time:** about 30 minutes. **Writes data:** Yes.

P4. Bill premiums and apply payments
**Outcome:** group invoices generated and a bank payment file applied.

**For:** finance and billing teams. **Time:** about 30 minutes. **Writes data:** Yes.

P5. Member self-service
**Outcome:** the backend calls for a member app: plan, deductible and out-of-pocket progress, claims, EOBs, and ID card requests.

**For:** portal and app developers. **Time:** about 15 minutes. **Writes data:** Yes, one step (ID card request).

P6. Create an authorization (coming soon)
**Outcome:** a prior authorization recorded for a member and provider.

**For:** care management integrators. **Writes data:** Yes.

P7. Disenroll a member or group (coming soon)
**Outcome:** a member, family, or group ended correctly, with the effect on claims and premiums checked.

**For:** enrollment teams. **Writes data:** Yes.

P8. Extract data with the Search API (coming soon)
**Outcome:** a repeatable extract of members, claims, or other records using saved search configurations.

**For:** reporting and data teams. **Writes data:** No.

## Suggested order

P1 to P5 build on each other: the group from P1 is where P2 enrolls a family, P3 enters claims for that family, P4 bills the group, and P5 reads it all back for the member. Each playbook also works on its own with your existing groups and members.

## How every playbook is laid out

- A summary table: who it is for, time to run, whether it writes data, and the operations used.
- **Before you start:** what must already exist and which rights the API user needs.
- **Steps:** each step names its operation as `METHOD /path` with a link to the API reference, shows the minimal JSON body, and shows the code in C#, Python, and TypeScript tabs.
- **Save from the response:** the values the next step needs.
- **Verify the result**, **Safe to re-run?**, **Undo**, **Common errors**, and **Variations**.


## Running the samples

Every playbook's code comes from a runnable sample in the docs repository under `_samples/playbooks/<playbook>/`. The samples share a small client per language that logs in, sends the required headers, retries rate-limited requests, and reads paging headers, so the playbook code shows only the workflow. Set your credentials as environment variables first:

The samples read your credentials from environment variables, so nothing secret is written into code. Set them in the terminal you run the samples from:

PowerShell
```powershell
$env:VBAPI_BASE_URL    = "https://vbapi.vbasoftware.com/vbasoftware"
$env:VBAPI_API_KEY     = "your-api-key"
$env:VBAPI_CLIENT_ID   = "your-client-id"
$env:VBAPI_CLIENT_CODE = "your-client-code"
$env:VBAPI_DATABASE    = "YOUR_DATABASE"
$env:VBAPI_USERNAME    = "your-api-username"
$env:VBAPI_PASSWORD    = "your-api-password"
$env:VBAPI_USER_AGENT  = "YourCompany-Integration/1.0"
```

bash
```bash
export VBAPI_BASE_URL="https://vbapi.vbasoftware.com/vbasoftware"
export VBAPI_API_KEY="your-api-key"
export VBAPI_CLIENT_ID="your-client-id"
export VBAPI_CLIENT_CODE="your-client-code"
export VBAPI_DATABASE="YOUR_DATABASE"
export VBAPI_USERNAME="your-api-username"
export VBAPI_PASSWORD="your-api-password"
export VBAPI_USER_AGENT="YourCompany-Integration/1.0"
```

In production code, load these from your secrets manager instead.

New to VBAPI? Start with the [quick start](/developer-portal/get-started/quick-start) and the [data model](/developer-portal/concepts/data-model).

Contacting support
Send VBA support:

- the `debug.activityID` from the response
- the date and time of the call, with time zone
- the method and path, for example `POST /claim-batches`
- the full `error` object from the response
- the request body, with passwords, tokens, and personal data removed


Never send your password, API key, or tokens. See [Support and escalation](/developer-portal/help/support).