# Build with AI

This page is for developers who use the portal's AI assistant or an MCP-connected AI tool to write VBAPI integration code. It gives a prompt for each playbook and a checklist for checking the result before you run it against production.

Use the prompts in the portal's AI assistant, or in an AI tool connected as described in [Connect your AI tools](/developer-portal/ai/connect-your-tools). In an MCP client, start the prompt with "Using the VBASoftware MCP server," so the tool looks the answer up instead of guessing.

## Write prompts that get grounded answers

Specific prompts get answers built from the documentation. Vague ones get generic code.

| Specific | Vague |
|  --- | --- |
| "Using the Enroll employees and dependents playbook, show Python code that loads subscribers with `PUT /subscribers-batch` and reports each failed row." | "How do I use the API?" |
| "Which fields does the `POST /search` request require?" | "Fix my code", with no code or error message |
| "How should my client retry a `429` response?" | "What can you do?" |


To get better answers:

- **Name the playbook** for any multi-step task. The playbooks list the calls in order and the minimum payload for each.
- **Name the language.** The documentation's samples are in C#, Python, and TypeScript with axios.
- **Ask for the operations by name.** Ask the AI to write each call as `METHOD /path` so you can check it in the reference.
- **Give the error, not your data.** When something fails, paste the HTTP status, the `error` object, and the `debug.activityID`, with any personal data removed.
- **Ask it to admit gaps.** Add "If the documentation does not cover a step, say so instead of guessing."


## Prompt recipes

Each recipe names a playbook and the operations it uses. Copy the prompt, change the language or the details, and keep the last two sentences: they make the AI cite operations and say when the documentation does not cover something.

### First call

Playbook: [Quick start](/developer-portal/get-started/quick-start)

```text
Using the VBAPI Quick start, write a TypeScript script with axios that logs in with POST /user-authentication and then lists five groups with GET /groups. Read the credentials from environment variables, send every required header, and stop with a clear message if the login returns a challenge instead of tokens. Cite every operation as METHOD /path. If the documentation does not cover a step, say so instead of guessing.
```

### Onboard a new employer group

Playbook: [Onboard a new employer group](/developer-portal/playbooks/onboard-employer-group)

```text
Using the "Onboard a new employer group" playbook, write a C# method that creates a group with POST /groups and then copies a template division with POST /groups/{groupID}/divisions/{divisionID}/copy. Use only the required fields from the schema, and sample IDs that start with DOCS-. Cite every operation as METHOD /path. If the documentation does not cover a step, say so instead of guessing.
```

### Enroll employees and dependents

Playbook: [Enroll employees and dependents](/developer-portal/playbooks/enroll-employees)

```text
Using the "Enroll employees and dependents" playbook, write a C# function that loads a CSV census with PUT /subscribers-batch and reports every row that failed in the 207 response. Then request ID cards with POST /id-card-requests. Cite every operation as METHOD /path. If the documentation does not cover a step, say so instead of guessing.
```

### Enter claims and adjudicate them overnight

Playbook: [Enter claims and adjudicate them overnight](/developer-portal/playbooks/claims-intake-and-adjudication)

```text
Using the "Enter claims and adjudicate them overnight" playbook, write Python that creates a claim batch with POST /claim-batches, adds a claim with POST /claim-batches/{batchNumber}/claims, and then processes a claim queue with POST /claim-queues/{claimQueueKey}/process. Explain what the 202 response means and how to check the result later. Cite every operation as METHOD /path. If the documentation does not cover a step, say so instead of guessing.
```

### Bill premiums and apply payments

Playbook: [Bill premiums and apply payments](/developer-portal/playbooks/premium-billing-and-payments)

```text
Using the "Bill premiums and apply payments" playbook, write TypeScript with axios that generates a group invoice with POST /generate-group-invoice and then processes a payment file with POST /process-payment-file. Explain what each call returns. Cite every operation as METHOD /path. If the documentation does not cover a step, say so instead of guessing.
```

### Member self-service

Playbook: [Member self-service](/developer-portal/playbooks/member-self-service)

```text
Using the "Member self-service" playbook, write Python that shows one member's claims with GET /subscribers/{subscriberID}/members/{memberSeq}/list-member-claim and their accumulators with GET /subscribers/{subscriberID}/members/{memberSeq}/list-accum-benefit-detail. Page through the results using the X-Pagination header. Cite every operation as METHOD /path. If the documentation does not cover a step, say so instead of guessing.
```

### Create an authorization

Playbook: [Create an authorization](/developer-portal/playbooks/create-authorization)

```text
Using the "Create an authorization" playbook, write C# that creates an authorization with POST /auths and adds a diagnosis code to it with POST /auths/{authNumber}/diagnostic-codes. Use only the required fields from the schema. Cite every operation as METHOD /path. If the documentation does not cover a step, say so instead of guessing.
```

### Disenroll a member or group

Playbook: [Disenroll a member or group](/developer-portal/playbooks/disenroll-member)

```text
Using the "Disenroll a member or group" playbook, write TypeScript with axios that first lists the premium adjustments with GET /subscribers/{subscriberID}/as-of-date/{asOfDate}/disenroll-adjustments, asks me to confirm, and only then disenrolls the member with POST /subscribers/{subscriberID}/members/{memberSeq}/disenroll. Cite every operation as METHOD /path. If the documentation does not cover a step, say so instead of guessing.
```

### Extract data with the Search API

Playbook: [Extract data with the Search API](/developer-portal/playbooks/search-extract)

```text
Using the "Extract data with the Search API" playbook and the Search concept page, write Python that creates criteria with POST /criterias and then pages through POST /search results. Respect the documented page size limit and say which request settings make the X-Pagination totals accurate. Cite every operation as METHOD /path. If the documentation does not cover a step, say so instead of guessing.
```

## Verify before you ship

AI-written code is a draft. Before you run it against your database:

- [ ] Every operation exists in the [API reference](/openapi/vbasoftware/vbasoftware.api) with the same method and path.
- [ ] Field names match the schema exactly, including their casing (for example `first_Name`), and every required field is sent, including required booleans.
- [ ] Every call sends `x-api-key`, `Authorization: Bearer <idToken>`, and `vbasoftware-database`, plus a descriptive `User-Agent` (recommended). A call without `x-api-key` returns `403`. See [Authentication and tokens](/developer-portal/concepts/authentication).
- [ ] The code retries `429` with backoff and stays within the [rate limits](/developer-portal/concepts/rate-limits-and-performance).
- [ ] Error handling logs `debug.activityID`, which VBA support needs. See [Errors and troubleshooting](/developer-portal/concepts/errors).
- [ ] Write calls are tried in a non-production database first if VBA has given you one. Clients only have access to the production API, so every write changes real records in the database you name.
- [ ] No real credentials or PHI appear in your prompts, your code, or your logs.