# Data model

This page is for developers who need to know how the main VBASoftware records fit together before they write an integration. It covers group setup, membership and enrollment, claims, authorizations, and premium billing, with the key fields that join them and the paths that address each record.

Field names are the ones in request and response bodies. For how composite keys appear in paths, see [IDs, keys, and field names](/developer-portal/concepts/ids-and-conventions).

## Overview

A group (an employer) is split into divisions, and each division has contracts that set its coverage periods and offer plans. Subscribers (a family unit) and their members enroll in a group contract. Claims are entered into claim batches and become claims when they are processed. Authorizations and premium billing refer back to the same groups, subscribers, and members.

```mermaid
flowchart LR
    subgraph setup["Group setup"]
        G["Group"] -->|group_ID| D["Division"]
        D -->|division_ID| GC["Group contract"]
        P["Plan"] -->|plan_ID| GC
    end
    subgraph membership["Membership and enrollment"]
        S["Subscriber"] -->|subscriber_ID| M["Member"]
        S --> E["Subscriber enrollment"]
    end
    GC -->|coverage_Start| E
    subgraph claims["Claims"]
        CB["Claim batch"] -->|batch_Number| CE["Claim batch entry"]
        CE -->|process| C["Claim"]
    end
    M -->|"subscriber_ID + member_Seq"| CE
    M --> A["Authorization"]
    subgraph billing["Premium billing"]
        PP["Premium payment"] --> I["Premium invoice"]
    end
    S --> I
```

Each section below has a detailed diagram with every key field.

## Group setup

Group setup is configuration that must exist before anyone can enroll. Plan types and plans are shared across groups; a group contract offers plans by listing them as group contract plans.

```mermaid
erDiagram
    BillingCycle ||--o{ Group : "billing_Cycle_ID"
    Group ||--o{ Division : "group_ID"
    Division ||--o{ GroupContract : "group_ID, division_ID"
    GroupContract ||--o{ GroupContractPlan : "group_ID, division_ID, coverage_Start"
    Plan ||--o{ GroupContractPlan : "plan_ID"
    PlanType ||--o{ Plan : "plan_Type"
    BillingCycle {
        string billing_Cycle_ID PK
    }
    Group {
        string group_ID PK
        string billing_Cycle_ID FK
    }
    Division {
        string group_ID PK
        string division_ID PK
    }
    GroupContract {
        string group_ID PK
        string division_ID PK
        datetime coverage_Start PK
    }
    GroupContractPlan {
        string group_ID PK
        string division_ID PK
        datetime coverage_Start PK
        string plan_ID PK
    }
    Plan {
        string plan_ID PK
        string plan_Type FK
    }
    PlanType {
        string plan_Type PK
    }
```

| Record | Key fields | What it is | Paths |
|  --- | --- | --- | --- |
| [Billing cycle](/openapi/vbasoftware/vbasoftware.api/billing-cycles) | `billing_Cycle_ID` | A billing schedule. A group's `billing_Cycle_ID` sets the cycle used when invoices are created. | [`/billing-cycles`](/openapi/vbasoftware/vbasoftware.api/billing-cycles/listbillingcycle), [`/billing-cycles/{billingCycleID}`](/openapi/vbasoftware/vbasoftware.api/billing-cycles/getbillingcycle) |
| [Group](/openapi/vbasoftware/vbasoftware.api/groups) | `group_ID` | The employer group. | [`/groups`](/openapi/vbasoftware/vbasoftware.api/groups/listgroups), [`/groups/{groupID}`](/openapi/vbasoftware/vbasoftware.api/groups/getgroups) |
| [Division](/openapi/vbasoftware/vbasoftware.api/group-divisions) | `group_ID`, `division_ID` | A part of a group with its own contracts and plans. `division_ID` is unique within its group. | [`/groups/{groupID}/divisions`](/openapi/vbasoftware/vbasoftware.api/group-divisions/listgroupdivision), [`/groups/{groupID}/divisions/{divisionID}`](/openapi/vbasoftware/vbasoftware.api/group-divisions/getgroupdivision) |
| [Group contract](/openapi/vbasoftware/vbasoftware.api/group-contracts) | `group_ID`, `division_ID`, `coverage_Start` | A coverage period for a division, starting on `coverage_Start`. | [`/groups/{groupID}/divisions/{divisionID}/contracts`](/openapi/vbasoftware/vbasoftware.api/group-contracts/listgroupcontract), [`/groups/{groupID}/divisions/{divisionID}/contracts/{coverageStart}`](/openapi/vbasoftware/vbasoftware.api/group-contracts/getgroupcontract) |
| [Group contract plan](/openapi/vbasoftware/vbasoftware.api/group-contract-plans) | the contract's keys plus `plan_ID` | A plan offered under a group contract. | [`/groups/{groupID}/divisions/{divisionID}/contracts/{coverageStart}/plans`](/openapi/vbasoftware/vbasoftware.api/group-contract-plans/listgroupcontractplan), [`/groups/{groupID}/divisions/{divisionID}/contracts/{coverageStart}/plans/{planID}`](/openapi/vbasoftware/vbasoftware.api/group-contract-plans/getgroupcontractplan) |
| [Plan type](/openapi/vbasoftware/vbasoftware.api/plan-types) | `plan_Type` | The kind of plan, for example medical or dental. Accumulators are tied to the plan type, not the plan. | [`/plan-types`](/openapi/vbasoftware/vbasoftware.api/plan-types/listplantype), [`/plan-types/{planType}`](/openapi/vbasoftware/vbasoftware.api/plan-types/getplantype) |
| [Plan](/openapi/vbasoftware/vbasoftware.api/plans) | `plan_ID` | A benefit plan of one plan type (`plan_Type`). | [`/plans`](/openapi/vbasoftware/vbasoftware.api/plans/listplans), [`/plans/{planID}`](/openapi/vbasoftware/vbasoftware.api/plans/getplans) |


## Membership and enrollment

A subscriber is a family unit, identified by `subscriber_ID`. Each person in the family is a member, identified by `subscriber_ID` plus `member_Seq`. A subscriber enrollment ties the subscriber to one group contract from a start date, and enrollment plans record which of that contract's plans the subscriber has.

```mermaid
erDiagram
    Subscriber ||--|{ Member : "subscriber_ID"
    Subscriber ||--o{ SubEnrollment : "subscriber_ID"
    GroupContract ||--o{ SubEnrollment : "group_ID, division_ID, coverage_Start = group_Coverage_Start"
    SubEnrollment ||--o{ SubEnrollmentPlan : "all five enrollment keys"
    GroupContractPlan ||--o{ SubEnrollmentPlan : "plan_ID"
    Subscriber {
        string subscriber_ID PK
    }
    Member {
        string subscriber_ID PK
        string member_Seq PK
    }
    GroupContract {
        string group_ID PK
        string division_ID PK
        datetime coverage_Start PK
    }
    SubEnrollment {
        string subscriber_ID PK
        string group_ID PK
        string division_ID PK
        datetime group_Coverage_Start PK
        datetime start_Date PK
    }
    SubEnrollmentPlan {
        string subscriber_ID PK
        string group_ID PK
        string division_ID PK
        datetime group_Coverage_Start PK
        datetime start_Date PK
        string plan_ID PK
        datetime plan_Start
    }
    GroupContractPlan {
        string plan_ID PK
    }
```

| Record | Key fields | What it is | Paths |
|  --- | --- | --- | --- |
| [Subscriber](/openapi/vbasoftware/vbasoftware.api/subscribers) | `subscriber_ID` | The family unit and policy holder. A subscriber has no group field of its own; it belongs to a group through its enrollments. | [`/subscribers`](/openapi/vbasoftware/vbasoftware.api/subscribers/listsubscribers), [`/subscribers/{subscriberID}`](/openapi/vbasoftware/vbasoftware.api/subscribers/getsubscribers) |
| [Member](/openapi/vbasoftware/vbasoftware.api/members) | `subscriber_ID`, `member_Seq` | A person in the family: the subscriber and each dependent. `relationship` records how the member relates to the subscriber. | [`/subscribers/{subscriberID}/members`](/openapi/vbasoftware/vbasoftware.api/members/listmembers), [`/subscribers/{subscriberID}/members/{memberSeq}`](/openapi/vbasoftware/vbasoftware.api/members/getmembers) |
| [Subscriber enrollment](/openapi/vbasoftware/vbasoftware.api/subscriber-enrollments) | `subscriber_ID`, `group_ID`, `division_ID`, `group_Coverage_Start`, `start_Date` | The subscriber's enrollment in a group contract. `group_Coverage_Start` is the contract's `coverage_Start`; `start_Date` and `end_Date` bound this subscriber's coverage. | [`/subscribers/{subscriberID}/enrollments`](/openapi/vbasoftware/vbasoftware.api/subscriber-enrollments/listsubenrollment), [`/subscribers/{subscriberID}/enrollments/{groupID}/{divisionID}/{groupCoverageStart}/{startDate}`](/openapi/vbasoftware/vbasoftware.api/subscriber-enrollments/getsubenrollment) |
| [Enrollment plan](/openapi/vbasoftware/vbasoftware.api/subscriber-enrollment-plans) | the enrollment's five keys plus `plan_ID` | A plan the subscriber is enrolled in under that enrollment, from `plan_Start`. `plan_ID` must be one of the contract's plans. | [`/subscribers/{subscriberID}/enrollments/{groupID}/{divisionID}/{groupCoverageStart}/{startDate}/plans`](/openapi/vbasoftware/vbasoftware.api/subscriber-enrollment-plans/listsubenrollmentplan) |


[`POST /subscribers/{subscriberID}/add-enrollment`](/openapi/vbasoftware/vbasoftware.api/adv.-enrollment/subscriberaddenrollment) is an advanced operation that adds an enrollment for the subscriber and, with `addMembers`, for its members too. It runs in the background and returns `202`.

## Claims

A claim starts as an entry in a claim batch. It stays there, with its service lines, while it is entered and adjudicated. Processing moves it out of the batch into the claim table, where it gets a `claim_Number`.

```mermaid
flowchart TD
    CB["Claim batch<br/>POST /claim-batches<br/>key: batch_Number"] --> CE["Claim batch entry<br/>POST /claim-batches/{batchNumber}/claims<br/>key: batch_Number + batch_Claim"]
    CE --> SL["Service lines<br/>POST .../claims/{batchClaim}/details<br/>key: + claim_Seq + adjustment_Seq"]
    SL --> ADJ{"Adjudicate or process"}
    ADJ -->|".../adjudicate"| IN["Adjudicated, still in the claim batch"]
    ADJ -->|".../process, claim pends or is stopped"| IN
    ADJ -->|".../process, succeeds"| CL["Claim<br/>GET /claims/{claimNumber}<br/>key: claim_Number<br/>keeps batch_Number + batch_Claim"]
    CL --> CD["Claim service lines<br/>GET /claims/{claimNumber}/details<br/>key: claim_Number + claim_Seq + adjustment_Seq"]
```

| Record | Key fields | What it is | Paths |
|  --- | --- | --- | --- |
| [Claim batch](/openapi/vbasoftware/vbasoftware.api/claim-batches) | `batch_Number` | A batch that claims are entered into. | [`/claim-batches`](/openapi/vbasoftware/vbasoftware.api/claim-batches/listclaimbatches), [`/claim-batches/{batchNumber}`](/openapi/vbasoftware/vbasoftware.api/claim-batches/getclaimbatches) |
| [Claim batch entry](/openapi/vbasoftware/vbasoftware.api/claim-batch) | `batch_Number`, `batch_Claim` | A claim that has not been processed yet: the claim header. The patient is `subscriber_ID` plus `member_Seq`, and `group_ID`, `division_ID`, and `coverage_Start` point at the enrollment. `provider_ID` is the servicing provider. | [`/claim-batches/{batchNumber}/claims`](/openapi/vbasoftware/vbasoftware.api/claim-batch/listclaimbatch), [`/claim-batches/{batchNumber}/claims/{batchClaim}`](/openapi/vbasoftware/vbasoftware.api/claim-batch/getclaimbatch), and the combined view [`/claim-batches/{batchNumber}/claims/{batchClaim}/full-claimbatch`](/openapi/vbasoftware/vbasoftware.api/adv.-claim/getfullclaimbatch) |
| [Claim batch service line](/openapi/vbasoftware/vbasoftware.api/claim-batch-details) | `batch_Number`, `batch_Claim`, `claim_Seq`, `adjustment_Seq` | One service on the claim, with `procedure_Code`, the billed price, and, after adjudication, the paid amounts. `auth_Number` links it to an authorization. | [`/claim-batches/{batchNumber}/claims/{batchClaim}/details`](/openapi/vbasoftware/vbasoftware.api/claim-batch-details/listclaimbatchdetail), [`/claim-batches/{batchNumber}/claims/{batchClaim}/details/{claimSeq}/{adjustmentSeq}`](/openapi/vbasoftware/vbasoftware.api/claim-batch-details/getclaimbatchdetail) |
| [Claim](/openapi/vbasoftware/vbasoftware.api/claims) | `claim_Number` | A processed claim. It keeps the `batch_Number` and `batch_Claim` it came from. | [`/claims/{claimNumber}`](/openapi/vbasoftware/vbasoftware.api/claims/getclaim) |
| [Claim service line](/openapi/vbasoftware/vbasoftware.api/claim-details) | `claim_Number`, `claim_Seq`, `adjustment_Seq` | A service line of a processed claim. | [`/claims/{claimNumber}/details`](/openapi/vbasoftware/vbasoftware.api/claim-details/listclaimdetail), [`/claims/{claimNumber}/details/{claimSeq}/{adjustmentSeq}`](/openapi/vbasoftware/vbasoftware.api/claim-details/getclaimdetail) |


### Batch entry and claim number

`batch_Number` plus `batch_Claim` identifies a claim from the moment it is entered, both while it is in the batch and after it is processed. `claim_Number` is assigned each time the claim is processed out of the batch, and it can change if the claim is returned to the batch and processed again. So:

- Store `batch_Number` and `batch_Claim` as your reference for a claim you submitted.
- Use the claim batch operations for claims that are not processed yet, and `/claims/{claimNumber}` only for processed claims.
- Read `claim_Number` from the processed claim when you need it, and expect it to change after a reprocess.


The three ways to run adjudication:

- [`POST /claim-batches/{batchNumber}/claims/{batchClaim}/adjudicate`](/openapi/vbasoftware/vbasoftware.api/claim-adjudication/adjudicateclaim) adjudicates the claim and returns the result. The claim stays in the batch.
- [`POST /claim-batches/{batchNumber}/claims/{batchClaim}/process`](/openapi/vbasoftware/vbasoftware.api/claim-adjudication/processclaim) adjudicates the claim and, unless a business rule stops it (for example a pend), moves it into the claim table.
- [`POST /claim-queues/{claimQueueKey}/adjudicate`](/openapi/vbasoftware/vbasoftware.api/claim-adjudication/adjudicateclaimqueue) and [`POST /claim-queues/{claimQueueKey}/process`](/openapi/vbasoftware/vbasoftware.api/claim-adjudication/processclaimqueue) do the same for every claim in a [claim queue](/openapi/vbasoftware/vbasoftware.api/claim-queues), in the background. A queue lists claims by `batch_Number` and `batch_Claim`.


[Requests and responses](/developer-portal/concepts/requests-and-responses#queued-work) explains their responses and how to tell when queued work is done.

## Authorizations

An authorization approves services for a member ahead of a claim.

| Record | Key fields | What it is | Paths |
|  --- | --- | --- | --- |
| [Authorization](/openapi/vbasoftware/vbasoftware.api/auth) | `auth_Number` | The authorization. The member is `subscriber_ID` plus `member_Seq`, using VBA's own IDs (not an alternate member ID), and `provider_ID` is VBA's provider ID (not an NPI). It also carries `plan_ID`, `auth_Type`, and `status`. | [`/auths`](/openapi/vbasoftware/vbasoftware.api/auth/createauth), [`/auths/{authNumber}`](/openapi/vbasoftware/vbasoftware.api/auth/getauth) |
| [Authorization procedure code](/openapi/vbasoftware/vbasoftware.api/auth-procedure-codes) | `auth_Number`, `authProcCodes_Key` | A procedure the authorization covers (`procedure_Code`). | [`/auths/{authNumber}/procedure-codes`](/openapi/vbasoftware/vbasoftware.api/auth-procedure-codes/listauthproccodebyauth) |
| [Authorization diagnostic code](/openapi/vbasoftware/vbasoftware.api/auth-diagnostic-codes) | `auth_Number`, `diagnostic_Code`, `diagnostic_Code_Type` | A diagnosis on the authorization, with its ICD version. | [`/auths/{authNumber}/diagnostic-codes`](/openapi/vbasoftware/vbasoftware.api/auth-diagnostic-codes/getauthdiagcodelist) |


A claim service line refers to an authorization through its `auth_Number`.

## Premium billing

Premium invoices bill groups, divisions, or subscribers for coverage, and premium payments record money received. The invoice and payment keys are integers that VBA assigns.

| Record | Key fields | What it is | Paths |
|  --- | --- | --- | --- |
| [Premium invoice](/openapi/vbasoftware/vbasoftware.api/premium-invoices) | `invoice_Key` | An invoice for a billing period (`billing_From` to `billing_Thru`) and billing cycle (`billing_Cycle_ID`). `invoice_Level` says whether it is for a group, division, or subscriber. | [`/premium-invoices`](/openapi/vbasoftware/vbasoftware.api/premium-invoices/listpreminvoice), [`/premium-invoices/{invoiceKey}`](/openapi/vbasoftware/vbasoftware.api/premium-invoices/getpreminvoice) |
| [Invoice subscriber](/openapi/vbasoftware/vbasoftware.api/premium-invoice-subscribers) | `invoice_Key`, `group_ID`, `division_ID`, `subscriber_ID` | A subscriber billed on the invoice. | [`/premium-invoices/{invoiceKey}/subscribers`](/openapi/vbasoftware/vbasoftware.api/premium-invoice-subscribers/listpreminvoicesubscriber), [`/premium-invoices/{invoiceKey}/subscribers/{groupID}/{divisionID}/{subscriberID}`](/openapi/vbasoftware/vbasoftware.api/premium-invoice-subscribers/getpreminvoicesubscriber) |
| [Premium payment](/openapi/vbasoftware/vbasoftware.api/premium-payments) | `premPayment_Key` | A payment received, with `group_ID`, `division_ID`, or `subscriber_ID` for who paid. | [`/premium-payments`](/openapi/vbasoftware/vbasoftware.api/premium-payments/listprempayment), [`/premium-payments/{premPaymentKey}`](/openapi/vbasoftware/vbasoftware.api/premium-payments/getprempayment) |
| [Invoice payment](/openapi/vbasoftware/vbasoftware.api/premium-invoice-payments) | `invoice_Key`, `premPayment_Key` | Links a payment to an invoice. | [`/premium-invoice-payments`](/openapi/vbasoftware/vbasoftware.api/premium-invoice-payments/listpreminvoicepayment), [`/premium-invoice-payments/{invoiceKey}/{premPaymentKey}`](/openapi/vbasoftware/vbasoftware.api/premium-invoice-payments/getpreminvoicepayment) |


Applying payments to invoices is done with advanced operations, for example [`POST /premium-invoices/{invoiceKey}/auto-apply`](/openapi/vbasoftware/vbasoftware.api/adv.-billing/preminvoiceautoapply), which applies all payments to the selected invoice.

## Related

- [IDs, keys, and field names](/developer-portal/concepts/ids-and-conventions): composite keys in paths, required flags, and dates.
- [Search API](/developer-portal/concepts/search): read joined data across these records in one call.
- [Onboard a new employer group](/developer-portal/playbooks/onboard-employer-group), [Enroll employees and dependents](/developer-portal/playbooks/enroll-employees), and [Enter claims and adjudicate them overnight](/developer-portal/playbooks/claims-intake-and-adjudication): these records in use.
- [Glossary](/developer-portal/reference/glossary): VBA terms.