# IDs, keys, and field names

This page is for developers building request bodies and paths for VBAPI. It explains how fields are named, how records are identified (often by more than one key field), which flags a create call must send, how to send dates, and what the `x-advanced` marker means.

## Field names

Request and response bodies use the VBASoftware database column names, with the first letter lower-cased: the `Subscriber_ID` column is `subscriber_ID`, `First_Name` is `first_Name`, and `Birth_Date` is `birth_Date`. The same names appear in every request and response body.

A few names look unusual because the column starts with an abbreviation, for example `coB_Type`, `acH_Account_Key`, and `tPlan_Printed`. Copy field names from the schema in the [API reference](/openapi/vbasoftware/vbasoftware.api) rather than deriving them, and send them exactly as the schema writes them.

Some places use the database column names unchanged:

- Search requests name tables and columns as they are in the database, for example `Groups` and `Group_ID`. See [Search API](/developer-portal/concepts/search).
- The `id` of each item in a batch (`207`) response uses the column name, for example `County_Code`. See [Requests and responses](/developer-portal/concepts/requests-and-responses#batch-create-or-update-207-multi-status).
- `sortBy` matches field names without regard to case, so `group_ID:asc` and `Group_ID:asc` both work.


## Keys you choose and keys VBA assigns

Most core records have a text key that you choose when you create them. The spec gives each one a maximum length:

| Record | Key field | Maximum length |
|  --- | --- | --- |
| Group | `group_ID` | 20 |
| Division | `division_ID` (unique within its group) | 20 |
| Plan | `plan_ID` | 20 |
| Plan type | `plan_Type` | 6 |
| Billing cycle | `billing_Cycle_ID` | 2 |
| Subscriber | `subscriber_ID` | 9 |
| Member | `member_Seq` (within its subscriber) | 2 |
| Authorization | `auth_Number` | 20 |


A value longer than the maximum is rejected with `400` and a message such as "Value cannot exceed 9 characters." `subscriber_ID` can also be assigned by the system when the subscriber is created.

Other keys are integers that VBA assigns, for example `invoice_Key` on premium invoices, `premPayment_Key` on premium payments, `criteria_Key` on search criteria, and `claim_Number` on adjudicated claims. Leave these out of create bodies (or send `0`), because the API refuses a create that sets them, and read the assigned value from the response.

`claim_Number` is assigned each time a claim is processed out of its claim batch, and it can change if the claim is returned to the batch and processed again. Use `batch_Number` plus `batch_Claim` to follow a claim from entry to payment; see [Data model](/developer-portal/concepts/data-model#claims).

## Composite keys

Many records are identified by several fields together. A get, update, or delete needs every part, in the order the path gives them, and the key fields in a `PUT` body must match the path.

| Record | Key fields | Path |
|  --- | --- | --- |
| Member | `subscriber_ID`, `member_Seq` | [`/subscribers/{subscriberID}/members/{memberSeq}`](/openapi/vbasoftware/vbasoftware.api/members/getmembers) |
| Group contract | `group_ID`, `division_ID`, `coverage_Start` | [`/groups/{groupID}/divisions/{divisionID}/contracts/{coverageStart}`](/openapi/vbasoftware/vbasoftware.api/group-contracts/getgroupcontract) |
| Group contract plan | `group_ID`, `division_ID`, `coverage_Start`, `plan_ID` | [`/groups/{groupID}/divisions/{divisionID}/contracts/{coverageStart}/plans/{planID}`](/openapi/vbasoftware/vbasoftware.api/group-contract-plans/getgroupcontractplan) |
| Subscriber enrollment | `subscriber_ID`, `group_ID`, `division_ID`, `group_Coverage_Start`, `start_Date` | [`/subscribers/{subscriberID}/enrollments/{groupID}/{divisionID}/{groupCoverageStart}/{startDate}`](/openapi/vbasoftware/vbasoftware.api/subscriber-enrollments/getsubenrollment) |
| Claim batch entry (a claim not yet processed) | `batch_Number`, `batch_Claim` | [`/claim-batches/{batchNumber}/claims/{batchClaim}`](/openapi/vbasoftware/vbasoftware.api/claim-batch/getclaimbatch) |
| Claim batch service line | `batch_Number`, `batch_Claim`, `claim_Seq`, `adjustment_Seq` | [`/claim-batches/{batchNumber}/claims/{batchClaim}/details/{claimSeq}/{adjustmentSeq}`](/openapi/vbasoftware/vbasoftware.api/claim-batch-details/getclaimbatchdetail) |
| Adjudicated claim service line | `claim_Number`, `claim_Seq`, `adjustment_Seq` | [`/claims/{claimNumber}/details/{claimSeq}/{adjustmentSeq}`](/openapi/vbasoftware/vbasoftware.api/claim-details/getclaimdetail) |


Things to watch:

- **Sequence fields are strings.** `member_Seq` (up to 2 characters), `claim_Seq` (2), and `adjustment_Seq` (3) are text, not numbers. Send them exactly as stored, for example `"01"`, and compare them as strings.
- **There is no top-level members path.** Members are always under their subscriber: `/subscribers/{subscriberID}/members`.
- **An enrollment's `group_Coverage_Start` is the group contract's `coverage_Start`.** It ties the enrollment to one contract of the division, and `start_Date` is when this subscriber's coverage starts.


## Path parameter names are not uniform

The same key can have differently written parameter names on different paths. For example, the claim queue key is `{claimQueue_Key}` in [`/claim-queues/{claimQueue_Key}`](/openapi/vbasoftware/vbasoftware.api/claim-queues/getclaimqueue) but `{claimQueueKey}` in [`/claim-queues/{claimQueueKey}/details`](/openapi/vbasoftware/vbasoftware.api/claim-queue-details/listclaimqueuedetail). The group ID is `{Group_ID}` in [`/groups/{Group_ID}/ach-pulls`](/openapi/vbasoftware/vbasoftware.api/group-ach-pulls/listgroupachpull) and `{groupID}` almost everywhere else, and [`/subscribers/{Subscriber_ID}/members/{Member_Seq}/address-history`](/openapi/vbasoftware/vbasoftware.api/member-address-history/listmemberaddresshistory) uses `{Subscriber_ID}` and `{Member_Seq}`.

The values are the same; only the names differ. If you [generate an SDK](/developer-portal/reference/generate-sdk) from the spec, its method parameters inherit these names, so expect `claimQueue_Key` on one method and `claimQueueKey` on another.

## Required flags on create calls

Many schemas have required boolean flags, because the matching database columns cannot be empty. For example, `Members` requires `subscriber_ID` and six flags: `adult_Dependent`, `continue_Coverage`, `initial_Volume_Salary_Pct`, `other_Insurance`, `smoker`, and `use_Member_Plan_Year`. Eighteen of the 19 required fields on `Groups` are flags, and `ClaimBatch` has 32 required flags.

Send every required flag on a create, with the value you mean. Do not rely on the API to reject a body that leaves one out. Check each schema's required fields in the API reference before you build a payload.

Example body for [`POST /subscribers/{subscriberID}/members`](/openapi/vbasoftware/vbasoftware.api/members/createmembers) (illustrative; field values are fake). It has the required fields plus a name and birth date:

```json
{
  "subscriber_ID": "DOCS00001",
  "member_Seq": "01",
  "first_Name": "Sample",
  "last_Name": "Member",
  "birth_Date": "2030-01-01T00:00:00",
  "adult_Dependent": false,
  "continue_Coverage": false,
  "initial_Volume_Salary_Pct": false,
  "other_Insurance": false,
  "smoker": false,
  "use_Member_Plan_Year": false
}
```

`DOCS00001` is used because `subscriber_ID` allows only 9 characters.

## Dates

Date fields in the spec are date-times (`format: date-time`), including dates such as `birth_Date` that have no meaningful time. Send them in ISO 8601 form, for example `2030-01-01T00:00:00`. Path segments that are dates, such as `{coverageStart}`, `{groupCoverageStart}`, and `{startDate}`, are date-times too; use the value stored on the record.

## Advanced operations (`x-advanced`)

Operations that run VBASoftware business logic, rather than reading or writing one table, carry `x-advanced: true` in the OpenAPI file. Their reference tags usually start with "Adv.", for example Adv. Claim, Adv. Enrollment, and Adv. Billing, and the claim adjudication operations are also advanced. Examples:

- [`POST /subscribers/{subscriberID}/add-enrollment`](/openapi/vbasoftware/vbasoftware.api/adv.-enrollment/subscriberaddenrollment) adds an enrollment for a subscriber and, optionally, all of its members.
- [`POST /claim-batches/{batchNumber}/claims/{batchClaim}/process`](/openapi/vbasoftware/vbasoftware.api/claim-adjudication/processclaim) adjudicates a claim and moves it out of its batch.
- [`POST /claim-queues/{claimQueueKey}/details-mass-insert`](/openapi/vbasoftware/vbasoftware.api/adv.-claim/massinsertclaimqueuedetail) adds many claims to a claim queue.


An advanced operation can change many records in one call, and many run in the background and return `202`; see [Queued work](/developer-portal/concepts/requests-and-responses#queued-work). Read its reference description before you call it, and try it with clearly fake data first.

## Related

- [Data model](/developer-portal/concepts/data-model): how the records relate.
- [Requests and responses](/developer-portal/concepts/requests-and-responses): methods, status codes, and batch results.
- [Glossary](/developer-portal/reference/glossary): VBA terms.