{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["partial","admonition","tabs","tab","code-snippet"]},"type":"markdown"},"seo":{"title":"Enroll employees and dependents, and request ID cards"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"enroll-employees-and-dependents-and-request-id-cards","__idx":0},"children":["Enroll employees and dependents, and request ID cards"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This playbook is for HR and benefits integrators and enrollment teams who load new hires or a census into VBASoftware. At the end, each family is a subscriber with members, enrolled in a group contract and plan, with an ID card request on file."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Who this is for"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["HR and benefits integrators, enrollment and implementation teams"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Time to run"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["About 20 minutes for one family; the census variation takes longer for a large file"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Writes data"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes. Try it in a non-production database first if you have one."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Operations used"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["12 in the main flow, plus 2 batch operations for a census: ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/group-contracts/listgroupcontract"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /groups/{groupID}/divisions/{divisionID}/contracts"]}]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/group-contract-plans/listgroupcontractplan"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /groups/{groupID}/divisions/{divisionID}/contracts/{coverageStart}/plans"]}]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/relationships/listrelationships"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /relationships"]}]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/subscribers/createsubscribers"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /subscribers"]}]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/members/createmembers"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /subscribers/{subscriberID}/members"]}]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/adv.-enrollment/subscriberaddenrollment"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /subscribers/{subscriberID}/add-enrollment"]}]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/subscriber-enrollments/listsubenrollment"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /subscribers/{subscriberID}/enrollments"]}]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/subscriber-enrollment-plans/createsubenrollmentplan"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /subscribers/{subscriberID}/enrollments/{groupID}/{divisionID}/{groupCoverageStart}/{startDate}/plans"]}]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/subscriber-enrollment-plans/listsubenrollmentplan"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /subscribers/{subscriberID}/enrollments/{groupID}/{divisionID}/{groupCoverageStart}/{startDate}/plans"]}]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/member-id-card-request-types/listidcardrequesttype"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /id-card-request-types"]}]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/member-id-card-requests/createidcardrequest"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /id-card-requests"]}]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/member-id-card-requests/getidcardrequest"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /id-card-requests/{iDCardRequestKey}"]}]},"; census: ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/subscribers/updatebatchsubscribers"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT /subscribers-batch"]}]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/members/updatebatchmembers"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT /subscribers/{subscriberID}/members-batch"]}]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"This changes production data"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["VBAPI clients connect to production, so the write calls on this page create or change real records in the database you name in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["vbasoftware-database"]},". Try the steps in a non-production database first if VBA has given you one, use clearly fake values while you test, and keep the \"Check it worked\" calls, which only read data. \"Try it\" in the API reference also calls production."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Before you start"},"children":[{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You have finished the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/developer-portal/get-started/quick-start"},"children":["quick start"]}," and can get an ID token. The samples read your credentials from environment variables; see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#set-up-your-environment"},"children":["Set up your environment"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The employer's group and division exist, with at least one contract and a plan on it. The samples use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DOCS-GRP1"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DOCS-DIV1"]}," from ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/developer-portal/playbooks/onboard-employer-group"},"children":["Onboard a new employer group"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The API user can create subscribers, members, and enrollments, and create ID card requests."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You have read the subscribers, members, and enrollments part of the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/developer-portal/concepts/data-model"},"children":["data model"]},"."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-it-fits-together","__idx":1},"children":["How it fits together"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["subscriber"]}," is the family unit, identified by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subscriber_ID"]},". ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Members"]}," are the people in it, identified by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subscriber_ID"]}," plus a two-character ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["member_Seq"]},". One member is the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["insured"]}," (the employee). The family's ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["enrollment"]}," ties the subscriber to a group contract for a date range, and enrollment ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["plans"]}," say which plan they are covered by."]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","diagramType":"mermaid","diagramSource":"sequenceDiagram\n participant App as Your system\n participant API as VBAPI\n App->>API: GET contracts and plans, GET /relationships\n API-->>App: coverage dates, plan_ID, relationship codes\n App->>API: POST /subscribers\n API-->>App: 200 subscriber\n App->>API: POST /subscribers/{id}/members (insured, then dependents)\n API-->>App: 200 member with member_Seq\n App->>API: POST /subscribers/{id}/add-enrollment\n API-->>App: 202 Accepted, no body\n App->>API: GET /subscribers/{id}/enrollments\n API-->>App: the new enrollment\n App->>API: POST .../enrollments/.../plans\n API-->>App: 200 enrollment plan\n App->>API: POST /id-card-requests\n API-->>App: 200 with idCardRequest_Key\n","diagramHtml":"VBAPIYour systemVBAPIYour systemGET contracts and plans, GET /relationshipscoverage dates, plan_ID, relationship codesPOST /subscribers200 subscriberPOST /subscribers/{id}/members (insured, then dependents)200 member with member_SeqPOST /subscribers/{id}/add-enrollment202 Accepted, no bodyGET /subscribers/{id}/enrollmentsthe new enrollmentPOST .../enrollments/.../plans200 enrollment planPOST /id-card-requests200 with idCardRequest_Key","diagramHtmlDark":"VBAPIYour systemVBAPIYour systemGET contracts and plans, GET /relationshipscoverage dates, plan_ID, relationship codesPOST /subscribers200 subscriberPOST /subscribers/{id}/members (insured, then dependents)200 member with member_SeqPOST /subscribers/{id}/add-enrollment202 Accepted, no bodyGET /subscribers/{id}/enrollmentsthe new enrollmentPOST .../enrollments/.../plans200 enrollment planPOST /id-card-requests200 with idCardRequest_Key"},"children":["sequenceDiagram\n participant App as Your system\n participant API as VBAPI\n App->>API: GET contracts and plans, GET /relationships\n API-->>App: coverage dates, plan_ID, relationship codes\n App->>API: POST /subscribers\n API-->>App: 200 subscriber\n App->>API: POST /subscribers/{id}/members (insured, then dependents)\n API-->>App: 200 member with member_Seq\n App->>API: POST /subscribers/{id}/add-enrollment\n API-->>App: 202 Accepted, no body\n App->>API: GET /subscribers/{id}/enrollments\n API-->>App: the new enrollment\n App->>API: POST .../enrollments/.../plans\n API-->>App: 200 enrollment plan\n App->>API: POST /id-card-requests\n API-->>App: 200 with idCardRequest_Key\n"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The samples use the fake subscriber ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DOCS-0001"]},". ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subscriber_ID"]}," allows only 9 characters, so check the length of your own IDs."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"steps","__idx":2},"children":["Steps"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"1-pick-the-contract-and-plan","__idx":3},"children":["1. Pick the contract and plan"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/group-contracts/listgroupcontract"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /groups/{groupID}/divisions/{divisionID}/contracts"]}]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/group-contract-plans/listgroupcontractplan"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /groups/{groupID}/divisions/{divisionID}/contracts/{coverageStart}/plans"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Enrollment points at a specific group contract, identified by its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["coverage_Start"]},". Read the division's contracts, choose the one that covers the employee's start date (the sample takes the latest), and read the plans offered on it. Pass ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["coverageStart"]}," in the path as a date, for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2030-01-01"]},"."]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"C#","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"../../_samples/playbooks/enroll-employees/EnrollEmployeesPlaybook.cs","language":"csharp","header":{"controls":{"copy":{}}},"lang":"csharp","source":" var contracts = new List();\n await foreach (var c in api.GetAllAsync($\"/groups/{GroupId}/divisions/{DivisionId}/contracts\"))\n contracts.Add(c!);\n var contract = contracts.OrderBy(c => c[\"coverage_Start\"]!.GetValue(), StringComparer.Ordinal).Last(); // the latest contract\n var coverageStart = DatePart(contract[\"coverage_Start\"]);\n var coverageEnd = DatePart(contract[\"coverage_End\"]);\n if (coverageEnd.Length == 0)\n throw new InvalidOperationException(\"The contract has no coverage_End. add-enrollment needs an end_Date; set one for this sample.\");\n var groupPlans = (await api.GetAsync($\"/groups/{GroupId}/divisions/{DivisionId}/contracts/{coverageStart}/plans\")).Data!.AsArray();\n var planId = groupPlans[0]![\"plan_ID\"]!.GetValue();\n Console.WriteLine($\"Contract {coverageStart} to {coverageEnd} plan {planId}\");\n "},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Python","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"../../_samples/playbooks/enroll-employees/enroll_employees.py","language":"python","header":{"controls":{"copy":{}}},"lang":"python","source":" contracts = sorted(\n api.iter_pages(f\"/groups/{GROUP_ID}/divisions/{DIVISION_ID}/contracts\"),\n key=lambda c: c[\"coverage_Start\"],\n )\n contract = contracts[-1] # the latest contract\n coverage_start = contract[\"coverage_Start\"][:10]\n coverage_end = (contract.get(\"coverage_End\") or \"\")[:10]\n if not coverage_end:\n raise SystemExit(\"The contract has no coverage_End. add-enrollment needs an end_Date; set one for this sample.\")\n plans = api.get(f\"/groups/{GROUP_ID}/divisions/{DIVISION_ID}/contracts/{coverage_start}/plans\").data\n plan_id = plans[0][\"plan_ID\"]\n print(\"Contract\", coverage_start, \"to\", coverage_end, \"plan\", plan_id)\n "},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"TypeScript","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"../../_samples/playbooks/enroll-employees/enrollEmployees.ts","language":"typescript","header":{"controls":{"copy":{}}},"lang":"typescript","source":" const contracts: any[] = [];\n for await (const c of api.getAll(`/groups/${GROUP_ID}/divisions/${DIVISION_ID}/contracts`)) contracts.push(c);\n contracts.sort((a, b) => a.coverage_Start.localeCompare(b.coverage_Start));\n const contract = contracts[contracts.length - 1]; // the latest contract\n const coverageStart = datePart(contract.coverage_Start);\n const coverageEnd = datePart(contract.coverage_End);\n if (!coverageEnd) throw new Error(\"The contract has no coverage_End. add-enrollment needs an end_Date; set one for this sample.\");\n const groupPlans: any[] = (await api.get(`/groups/${GROUP_ID}/divisions/${DIVISION_ID}/contracts/${coverageStart}/plans`)).data;\n const planId: string = groupPlans[0].plan_ID;\n console.log(\"Contract\", coverageStart, \"to\", coverageEnd, \"plan\", planId);\n "},"children":[]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Save from the response:"]}," the contract's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["coverage_Start"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["coverage_End"]}," (steps 5 and 7), and a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plan_ID"]}," (step 7)."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"2-look-up-the-relationship-codes","__idx":4},"children":["2. Look up the relationship codes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/relationships/listrelationships"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /relationships"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Relationship codes are configured per database, so look them up rather than hardcoding them. The relationship whose ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subscriber"]}," flag is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"1\""]}," marks the insured; VBAPI uses it to decide which member is the employee. The one whose ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["spouse"]}," flag is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"1\""]}," is the spouse. Other dependents (children, for example) use the code whose ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["description"]}," matches."]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"C#","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"../../_samples/playbooks/enroll-employees/EnrollEmployeesPlaybook.cs","language":"csharp","header":{"controls":{"copy":{}}},"lang":"csharp","source":" var relationships = (await api.GetAsync(\"/relationships\")).Data!.AsArray();\n var insuredCode = relationships.First(r => r![\"subscriber\"]?.GetValue() == \"1\")![\"relate_Code\"]!.GetValue();\n var spouseCode = relationships.First(r => r![\"spouse\"]?.GetValue() == \"1\")![\"relate_Code\"]!.GetValue();\n Console.WriteLine($\"Insured relationship: {insuredCode} spouse relationship: {spouseCode}\");\n "},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Python","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"../../_samples/playbooks/enroll-employees/enroll_employees.py","language":"python","header":{"controls":{"copy":{}}},"lang":"python","source":" relationships = api.get(\"/relationships\").data\n insured_code = next(r[\"relate_Code\"] for r in relationships if r.get(\"subscriber\") == \"1\")\n spouse_code = next(r[\"relate_Code\"] for r in relationships if r.get(\"spouse\") == \"1\")\n print(\"Insured relationship:\", insured_code, \"spouse relationship:\", spouse_code)\n "},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"TypeScript","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"../../_samples/playbooks/enroll-employees/enrollEmployees.ts","language":"typescript","header":{"controls":{"copy":{}}},"lang":"typescript","source":" const relationships: any[] = (await api.get(\"/relationships\")).data;\n const insuredCode: string = relationships.find((r) => r.subscriber === \"1\").relate_Code;\n const spouseCode: string = relationships.find((r) => r.spouse === \"1\").relate_Code;\n console.log(\"Insured relationship:\", insuredCode, \"spouse relationship:\", spouseCode);\n "},"children":[]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Save from the response:"]}," the insured and spouse ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["relate_Code"]}," values (step 4)."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"3-create-the-subscriber","__idx":5},"children":["3. Create the subscriber"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/subscribers/createsubscribers"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /subscribers"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Subscribers"]}," schema has no required fields. Send the family's ID, name, and address:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"subscriber_ID\": \"DOCS-0001\",\n \"first_Name\": \"Sample\",\n \"last_Name\": \"Member\",\n \"address\": \"123 Example St\",\n \"city\": \"Exampleville\",\n \"state\": \"TX\",\n \"zip_Code\": \"00000\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you leave out ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subscriber_ID"]},", VBAPI generates a 9-character ID and returns it; ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/subscribers/generatesubscriberid"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /subscribers-generate-id"]}]}," also returns one. Creating a subscriber does not create any member, not even the employee, so step 4 is always needed."]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"C#","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"../../_samples/playbooks/enroll-employees/EnrollEmployeesPlaybook.cs","language":"csharp","header":{"controls":{"copy":{}}},"lang":"csharp","source":" if (await ExistsAsync(api, $\"/subscribers/{SubscriberId}\"))\n {\n Console.WriteLine($\"Subscriber {SubscriberId} already exists; skipping create\");\n }\n else\n {\n var subscriber = (await api.PostAsync(\"/subscribers\", new\n {\n subscriber_ID = SubscriberId,\n first_Name = \"Sample\",\n last_Name = \"Member\",\n address = \"123 Example St\",\n city = \"Exampleville\",\n state = \"TX\",\n zip_Code = \"00000\",\n })).Data!;\n Console.WriteLine($\"Created subscriber {subscriber[\"subscriber_ID\"]}\");\n }\n "},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Python","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"../../_samples/playbooks/enroll-employees/enroll_employees.py","language":"python","header":{"controls":{"copy":{}}},"lang":"python","source":" if exists(api, f\"/subscribers/{SUBSCRIBER_ID}\"):\n print(\"Subscriber\", SUBSCRIBER_ID, \"already exists; skipping create\")\n else:\n subscriber = api.post(\"/subscribers\", {\n \"subscriber_ID\": SUBSCRIBER_ID,\n \"first_Name\": \"Sample\",\n \"last_Name\": \"Member\",\n \"address\": \"123 Example St\",\n \"city\": \"Exampleville\",\n \"state\": \"TX\",\n \"zip_Code\": \"00000\",\n }).data\n print(\"Created subscriber\", subscriber[\"subscriber_ID\"])\n "},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"TypeScript","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"../../_samples/playbooks/enroll-employees/enrollEmployees.ts","language":"typescript","header":{"controls":{"copy":{}}},"lang":"typescript","source":" if (await exists(api, `/subscribers/${SUBSCRIBER_ID}`)) {\n console.log(`Subscriber ${SUBSCRIBER_ID} already exists; skipping create`);\n } else {\n const subscriber = (\n await api.post(\"/subscribers\", {\n subscriber_ID: SUBSCRIBER_ID,\n first_Name: \"Sample\",\n last_Name: \"Member\",\n address: \"123 Example St\",\n city: \"Exampleville\",\n state: \"TX\",\n zip_Code: \"00000\",\n })\n ).data;\n console.log(\"Created subscriber\", subscriber.subscriber_ID);\n }\n "},"children":[]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Save from the response:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subscriber_ID"]}," (every later step)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Check it worked:"]}," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/subscribers/getsubscribers"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /subscribers/{subscriberID}"]}]}," returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"4-add-the-employee-and-dependents","__idx":6},"children":["4. Add the employee and dependents"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/members/createmembers"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /subscribers/{subscriberID}/members"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create the employee first, with the insured relationship code, then each dependent. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subscriber_ID"]}," in the body must match the path. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Members"]}," has six required booleans; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]}," is the usual value for a new enrollee:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"subscriber_ID\": \"DOCS-0001\",\n \"first_Name\": \"Sample\",\n \"last_Name\": \"Member\",\n \"relationship\": \"INSURED_CODE_FROM_STEP_2\",\n \"adult_Dependent\": false,\n \"continue_Coverage\": false,\n \"initial_Volume_Salary_Pct\": false,\n \"other_Insurance\": false,\n \"smoker\": false,\n \"use_Member_Plan_Year\": false\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Leave out ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["member_Seq"]}," and VBAPI assigns the next number in the family: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["01"]}," for the first member, then ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["02"]},", and so on, up to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["99"]},". Creating the employee first gives them ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["01"]},". Add ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["birth_Date"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sex"]},", and the other fields your plans' eligibility rules use; the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/members/createmembers"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Members"]}," schema"]}," lists them."]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"C#","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"../../_samples/playbooks/enroll-employees/EnrollEmployeesPlaybook.cs","language":"csharp","header":{"controls":{"copy":{}}},"lang":"csharp","source":" var members = (await api.GetAsync($\"/subscribers/{SubscriberId}/members\")).Data?.AsArray()\n .Select(m => m!).ToList() ?? new List();\n var existing = members.Select(m => m[\"relationship\"]?.GetValue()).ToHashSet();\n var people = new[]\n {\n (FirstName: \"Sample\", Relationship: insuredCode), // the insured: create first\n (FirstName: \"Sample Spouse\", Relationship: spouseCode),\n };\n foreach (var person in people)\n {\n if (existing.Contains(person.Relationship))\n continue;\n var member = (await api.PostAsync($\"/subscribers/{SubscriberId}/members\", new\n {\n subscriber_ID = SubscriberId,\n first_Name = person.FirstName,\n last_Name = \"Member\",\n relationship = person.Relationship,\n // Required booleans.\n adult_Dependent = false,\n continue_Coverage = false,\n initial_Volume_Salary_Pct = false,\n other_Insurance = false,\n smoker = false,\n use_Member_Plan_Year = false,\n })).Data!;\n members.Add(member);\n Console.WriteLine($\"Created member {member[\"member_Seq\"]} {member[\"first_Name\"]}\");\n }\n var insuredSeq = members.First(m => m[\"relationship\"]?.GetValue() == insuredCode)[\"member_Seq\"]!.GetValue();\n "},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Python","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"../../_samples/playbooks/enroll-employees/enroll_employees.py","language":"python","header":{"controls":{"copy":{}}},"lang":"python","source":" members = api.get(f\"/subscribers/{SUBSCRIBER_ID}/members\").data or []\n existing = {m[\"relationship\"] for m in members}\n people = [\n {\"first_Name\": \"Sample\", \"relationship\": insured_code}, # the insured: create first\n {\"first_Name\": \"Sample Spouse\", \"relationship\": spouse_code},\n ]\n for person in people:\n if person[\"relationship\"] in existing:\n continue\n member = api.post(f\"/subscribers/{SUBSCRIBER_ID}/members\", {\n \"subscriber_ID\": SUBSCRIBER_ID,\n \"first_Name\": person[\"first_Name\"],\n \"last_Name\": \"Member\",\n \"relationship\": person[\"relationship\"],\n # Required booleans.\n \"adult_Dependent\": False,\n \"continue_Coverage\": False,\n \"initial_Volume_Salary_Pct\": False,\n \"other_Insurance\": False,\n \"smoker\": False,\n \"use_Member_Plan_Year\": False,\n }).data\n members.append(member)\n print(\"Created member\", member[\"member_Seq\"], member[\"first_Name\"])\n insured_seq = next(m[\"member_Seq\"] for m in members if m[\"relationship\"] == insured_code)\n "},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"TypeScript","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"../../_samples/playbooks/enroll-employees/enrollEmployees.ts","language":"typescript","header":{"controls":{"copy":{}}},"lang":"typescript","source":" const members: any[] = (await api.get(`/subscribers/${SUBSCRIBER_ID}/members`)).data ?? [];\n const existing = new Set(members.map((m) => m.relationship));\n const people = [\n { firstName: \"Sample\", relationship: insuredCode }, // the insured: create first\n { firstName: \"Sample Spouse\", relationship: spouseCode },\n ];\n for (const person of people) {\n if (existing.has(person.relationship)) continue;\n const member = (\n await api.post(`/subscribers/${SUBSCRIBER_ID}/members`, {\n subscriber_ID: SUBSCRIBER_ID,\n first_Name: person.firstName,\n last_Name: \"Member\",\n relationship: person.relationship,\n // Required booleans.\n adult_Dependent: false,\n continue_Coverage: false,\n initial_Volume_Salary_Pct: false,\n other_Insurance: false,\n smoker: false,\n use_Member_Plan_Year: false,\n })\n ).data;\n members.push(member);\n console.log(\"Created member\", member.member_Seq, member.first_Name);\n }\n const insuredSeq: string = members.find((m) => m.relationship === insuredCode).member_Seq;\n "},"children":[]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example response (illustrative; field values are fake):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"data\": {\n \"subscriber_ID\": \"DOCS-0001\",\n \"member_Seq\": \"01\",\n \"first_Name\": \"Sample\",\n \"last_Name\": \"Member\",\n \"relationship\": \"INSURED_CODE_FROM_STEP_2\",\n \"adult_Dependent\": false,\n \"continue_Coverage\": false,\n \"initial_Volume_Salary_Pct\": false,\n \"other_Insurance\": false,\n \"smoker\": false,\n \"use_Member_Plan_Year\": false\n },\n \"error\": null,\n \"debug\": { \"activityID\": \"00000000-0000-0000-0000-000000000000\" }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Save from the response:"]}," each member's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["member_Seq"]}," (the employee's is used in step 9)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Check it worked:"]}," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/members/listmembers"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /subscribers/{subscriberID}/members"]}]}," lists every member."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"5-enroll-the-family","__idx":7},"children":["5. Enroll the family"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/adv.-enrollment/subscriberaddenrollment"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /subscribers/{subscriberID}/add-enrollment"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This creates the family's enrollment in the group contract. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subEnrollment"]}," names the contract by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["group_ID"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["division_ID"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["group_Coverage_Start"]}," (the contract's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["coverage_Start"]},"), and the family's coverage dates by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["start_Date"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["end_Date"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"requesting_User_ID\": \"your-api-username\",\n \"addMembers\": true,\n \"subEnrollment\": {\n \"subscriber_ID\": \"DOCS-0001\",\n \"group_ID\": \"DOCS-GRP1\",\n \"division_ID\": \"DOCS-DIV1\",\n \"group_Coverage_Start\": \"2030-01-01T00:00:00\",\n \"start_Date\": \"2030-01-01T00:00:00\",\n \"end_Date\": \"2030-12-31T00:00:00\"\n }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["requesting_User_ID"]}," is required (up to 20 characters). The samples send the API user name."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["end_Date"]}," is not marked required in the schema, but VBAPI rejects the request without it. Use the contract's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["coverage_End"]}," unless the employee's coverage ends sooner."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["addMembers: true"]}," includes the dependents. With ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]},", only the insured member is made active on the enrollment."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["VBAPI checks that the subscriber exists, that at least one member exists, and that the group contract exists, and returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}," with a message if not."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The response is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["202 Accepted"]}," with no body."]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"C#","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"../../_samples/playbooks/enroll-employees/EnrollEmployeesPlaybook.cs","language":"csharp","header":{"controls":{"copy":{}}},"lang":"csharp","source":" if (await FindEnrollmentAsync(api, coverageStart) is not null)\n {\n Console.WriteLine($\"Already enrolled in {GroupId} {DivisionId} {coverageStart}\");\n }\n else\n {\n var response = await api.PostAsync($\"/subscribers/{SubscriberId}/add-enrollment\", new\n {\n requesting_User_ID = requestingUserId,\n addMembers = true,\n subEnrollment = new\n {\n subscriber_ID = SubscriberId,\n group_ID = GroupId,\n division_ID = DivisionId,\n group_Coverage_Start = $\"{coverageStart}T00:00:00\",\n start_Date = $\"{coverageStart}T00:00:00\",\n end_Date = $\"{coverageEnd}T00:00:00\",\n },\n });\n Console.WriteLine($\"add-enrollment returned {(int)response.Status}\"); // 202 Accepted, no body\n }\n "},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Python","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"../../_samples/playbooks/enroll-employees/enroll_employees.py","language":"python","header":{"controls":{"copy":{}}},"lang":"python","source":" if find_enrollment():\n print(\"Already enrolled in\", GROUP_ID, DIVISION_ID, coverage_start)\n else:\n response = api.post(f\"/subscribers/{SUBSCRIBER_ID}/add-enrollment\", {\n \"requesting_User_ID\": REQUESTING_USER_ID,\n \"addMembers\": True,\n \"subEnrollment\": {\n \"subscriber_ID\": SUBSCRIBER_ID,\n \"group_ID\": GROUP_ID,\n \"division_ID\": DIVISION_ID,\n \"group_Coverage_Start\": f\"{coverage_start}T00:00:00\",\n \"start_Date\": f\"{coverage_start}T00:00:00\",\n \"end_Date\": f\"{coverage_end}T00:00:00\",\n },\n })\n print(\"add-enrollment returned\", response.status) # 202 Accepted, no body\n "},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"TypeScript","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"../../_samples/playbooks/enroll-employees/enrollEmployees.ts","language":"typescript","header":{"controls":{"copy":{}}},"lang":"typescript","source":" if (await findEnrollment(api, coverageStart)) {\n console.log(\"Already enrolled in\", GROUP_ID, DIVISION_ID, coverageStart);\n } else {\n const response = await api.post(`/subscribers/${SUBSCRIBER_ID}/add-enrollment`, {\n requesting_User_ID: requestingUserId,\n addMembers: true,\n subEnrollment: {\n subscriber_ID: SUBSCRIBER_ID,\n group_ID: GROUP_ID,\n division_ID: DIVISION_ID,\n group_Coverage_Start: `${coverageStart}T00:00:00`,\n start_Date: `${coverageStart}T00:00:00`,\n end_Date: `${coverageEnd}T00:00:00`,\n },\n });\n console.log(\"add-enrollment returned\", response.status); // 202 Accepted, no body\n }\n "},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"6-confirm-the-enrollment","__idx":8},"children":["6. Confirm the enrollment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/subscriber-enrollments/listsubenrollment"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /subscribers/{subscriberID}/enrollments"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["202"]}," has no body, so read the enrollment back. The sample checks a few times, two seconds apart, before it gives up. Match on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["group_ID"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["division_ID"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["group_Coverage_Start"]},"."]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"C#","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"../../_samples/playbooks/enroll-employees/EnrollEmployeesPlaybook.cs","language":"csharp","header":{"controls":{"copy":{}}},"lang":"csharp","source":" JsonNode? enrollment = null;\n for (var attempt = 0; attempt < 5 && enrollment is null; attempt++)\n {\n enrollment = await FindEnrollmentAsync(api, coverageStart);\n if (enrollment is null)\n await Task.Delay(TimeSpan.FromSeconds(2));\n }\n if (enrollment is null)\n throw new InvalidOperationException(\"The enrollment did not appear. Check the subscriber in VBASoftware.\");\n var startDate = DatePart(enrollment[\"start_Date\"]);\n Console.WriteLine($\"Enrollment {enrollment[\"group_ID\"]} {enrollment[\"division_ID\"]} {startDate} to {DatePart(enrollment[\"end_Date\"])}\");\n "},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Python","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"../../_samples/playbooks/enroll-employees/enroll_employees.py","language":"python","header":{"controls":{"copy":{}}},"lang":"python","source":" enrollment = None\n for _ in range(5):\n enrollment = find_enrollment()\n if enrollment:\n break\n time.sleep(2)\n if not enrollment:\n raise SystemExit(\"The enrollment did not appear. Check the subscriber in VBASoftware.\")\n start_date = enrollment[\"start_Date\"][:10]\n print(\"Enrollment\", enrollment[\"group_ID\"], enrollment[\"division_ID\"], start_date, \"to\", (enrollment.get(\"end_Date\") or \"\")[:10])\n "},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"TypeScript","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"../../_samples/playbooks/enroll-employees/enrollEmployees.ts","language":"typescript","header":{"controls":{"copy":{}}},"lang":"typescript","source":" let enrollment: any;\n for (let attempt = 0; attempt < 5 && !enrollment; attempt++) {\n enrollment = await findEnrollment(api, coverageStart);\n if (!enrollment) await sleep(2000);\n }\n if (!enrollment) throw new Error(\"The enrollment did not appear. Check the subscriber in VBASoftware.\");\n const startDate = datePart(enrollment.start_Date);\n console.log(\"Enrollment\", enrollment.group_ID, enrollment.division_ID, startDate, \"to\", datePart(enrollment.end_Date));\n "},"children":[]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example response (illustrative; field values are fake):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"data\": [\n {\n \"subscriber_ID\": \"DOCS-0001\",\n \"group_ID\": \"DOCS-GRP1\",\n \"division_ID\": \"DOCS-DIV1\",\n \"group_Coverage_Start\": \"2030-01-01T00:00:00\",\n \"start_Date\": \"2030-01-01T00:00:00\",\n \"end_Date\": \"2030-12-31T00:00:00\"\n }\n ],\n \"error\": null,\n \"debug\": { \"activityID\": \"00000000-0000-0000-0000-000000000000\" }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Save from the response:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["start_Date"]}," (with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["group_Coverage_Start"]},", it identifies the enrollment in step 7)."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"7-add-the-plan-to-the-enrollment","__idx":9},"children":["7. Add the plan to the enrollment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/subscriber-enrollment-plans/createsubenrollmentplan"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /subscribers/{subscriberID}/enrollments/{groupID}/{divisionID}/{groupCoverageStart}/{startDate}/plans"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["add-enrollment"]}," does not choose a plan. Add one for each plan the family elected. The path identifies the enrollment from step 6; pass both dates as dates, for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2030-01-01"]},". ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plan_ID"]}," must be a plan on the group contract (step 1)."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"subscriber_ID\": \"DOCS-0001\",\n \"group_ID\": \"DOCS-GRP1\",\n \"division_ID\": \"DOCS-DIV1\",\n \"group_Coverage_Start\": \"2030-01-01T00:00:00\",\n \"start_Date\": \"2030-01-01T00:00:00\",\n \"plan_ID\": \"PLAN_ID_FROM_STEP_1\",\n \"plan_Start\": \"2030-01-01T00:00:00\",\n \"plan_End\": \"2030-12-31T00:00:00\",\n \"use_Volume_Scale\": false\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["use_Volume_Scale"]}," is the one required boolean; it matters for life and disability volume plans. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tier"]}," sets the family's coverage tier when the plan is tiered."]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"C#","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"../../_samples/playbooks/enroll-employees/EnrollEmployeesPlaybook.cs","language":"csharp","header":{"controls":{"copy":{}}},"lang":"csharp","source":" var enrolledPlans = (await api.GetAsync(plansPath)).Data?.AsArray() ?? new JsonArray();\n if (enrolledPlans.Any(p => p![\"plan_ID\"]!.GetValue() == planId))\n {\n Console.WriteLine($\"Plan {planId} already on the enrollment\");\n }\n else\n {\n await api.PostAsync(plansPath, new\n {\n subscriber_ID = SubscriberId,\n group_ID = GroupId,\n division_ID = DivisionId,\n group_Coverage_Start = $\"{coverageStart}T00:00:00\",\n start_Date = $\"{startDate}T00:00:00\",\n plan_ID = planId,\n plan_Start = $\"{startDate}T00:00:00\",\n plan_End = $\"{coverageEnd}T00:00:00\",\n use_Volume_Scale = false,\n });\n Console.WriteLine($\"Added plan {planId}\");\n }\n "},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Python","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"../../_samples/playbooks/enroll-employees/enroll_employees.py","language":"python","header":{"controls":{"copy":{}}},"lang":"python","source":" if any(p[\"plan_ID\"] == plan_id for p in api.get(plans_path).data or []):\n print(\"Plan\", plan_id, \"already on the enrollment\")\n else:\n api.post(plans_path, {\n \"subscriber_ID\": SUBSCRIBER_ID,\n \"group_ID\": GROUP_ID,\n \"division_ID\": DIVISION_ID,\n \"group_Coverage_Start\": f\"{coverage_start}T00:00:00\",\n \"start_Date\": f\"{start_date}T00:00:00\",\n \"plan_ID\": plan_id,\n \"plan_Start\": f\"{start_date}T00:00:00\",\n \"plan_End\": f\"{coverage_end}T00:00:00\",\n \"use_Volume_Scale\": False,\n })\n print(\"Added plan\", plan_id)\n "},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"TypeScript","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"../../_samples/playbooks/enroll-employees/enrollEmployees.ts","language":"typescript","header":{"controls":{"copy":{}}},"lang":"typescript","source":" const enrolledPlans: any[] = (await api.get(plansPath)).data ?? [];\n if (enrolledPlans.some((p) => p.plan_ID === planId)) {\n console.log(\"Plan\", planId, \"already on the enrollment\");\n } else {\n await api.post(plansPath, {\n subscriber_ID: SUBSCRIBER_ID,\n group_ID: GROUP_ID,\n division_ID: DIVISION_ID,\n group_Coverage_Start: `${coverageStart}T00:00:00`,\n start_Date: `${startDate}T00:00:00`,\n plan_ID: planId,\n plan_Start: `${startDate}T00:00:00`,\n plan_End: `${coverageEnd}T00:00:00`,\n use_Volume_Scale: false,\n });\n console.log(\"Added plan\", planId);\n }\n "},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"8-confirm-the-plans","__idx":10},"children":["8. Confirm the plans"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/subscriber-enrollment-plans/listsubenrollmentplan"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /subscribers/{subscriberID}/enrollments/{groupID}/{divisionID}/{groupCoverageStart}/{startDate}/plans"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This only reads data. You should see each plan with its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plan_Start"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plan_End"]},"."]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"C#","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"../../_samples/playbooks/enroll-employees/EnrollEmployeesPlaybook.cs","language":"csharp","header":{"controls":{"copy":{}}},"lang":"csharp","source":" foreach (var plan in (await api.GetAsync(plansPath)).Data?.AsArray() ?? new JsonArray())\n Console.WriteLine($\"Enrolled plan {plan![\"plan_ID\"]} {DatePart(plan[\"plan_Start\"])} to {DatePart(plan[\"plan_End\"])}\");\n "},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Python","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"../../_samples/playbooks/enroll-employees/enroll_employees.py","language":"python","header":{"controls":{"copy":{}}},"lang":"python","source":" for plan in api.get(plans_path).data or []:\n print(\"Enrolled plan\", plan[\"plan_ID\"], plan[\"plan_Start\"][:10], \"to\", (plan.get(\"plan_End\") or \"\")[:10])\n "},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"TypeScript","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"../../_samples/playbooks/enroll-employees/enrollEmployees.ts","language":"typescript","header":{"controls":{"copy":{}}},"lang":"typescript","source":" for (const plan of (await api.get(plansPath)).data ?? []) {\n console.log(\"Enrolled plan\", plan.plan_ID, datePart(plan.plan_Start), \"to\", datePart(plan.plan_End));\n }\n "},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"9-request-id-cards","__idx":11},"children":["9. Request ID cards"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/member-id-card-request-types/listidcardrequesttype"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /id-card-request-types"]}]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/member-id-card-requests/createidcardrequest"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /id-card-requests"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An ID card request records that a card should be produced for a member. Request types are configured per database, so read them first and use the right ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["request_Type"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"idCardRequest_Key\": 0,\n \"renewal\": false,\n \"subscriber_ID\": \"DOCS-0001\",\n \"member_Seq\": \"01\",\n \"group_ID\": \"DOCS-GRP1\",\n \"division_ID\": \"DOCS-DIV1\",\n \"request_Type\": \"REQUEST_TYPE_FROM_LOOKUP\",\n \"request_Status\": \"REQ\",\n \"request_Date\": \"2030-01-02T00:00:00\",\n \"as_Of_Date\": \"2030-01-01T00:00:00\",\n \"request_Quantity\": 1,\n \"physical_Card_Requested\": true\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["idCardRequest_Key"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["renewal"]}," are required. Send ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["0"]}," for the key; the database assigns it."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["request_Status"]}," takes a value from ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/id-card-request-statuses/listidcardrequeststatuses"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /id-card-request-statuses"]}]},": ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REQ"]}," (Requested), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COMPLETE"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CANCEL"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["as_Of_Date"]}," is the date the card is effective from."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["issuance_Type"]}," is left out. Which values your card vendor expects is set up per client; ask VBA before you send it."]}]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"C#","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"../../_samples/playbooks/enroll-employees/EnrollEmployeesPlaybook.cs","language":"csharp","header":{"controls":{"copy":{}}},"lang":"csharp","source":" var requestTypes = (await api.GetAsync(\"/id-card-request-types\")).Data!.AsArray();\n var card = (await api.PostAsync(\"/id-card-requests\", new\n {\n idCardRequest_Key = 0, // 0 on create; VBAPI assigns the key\n renewal = false,\n subscriber_ID = SubscriberId,\n member_Seq = insuredSeq,\n group_ID = GroupId,\n division_ID = DivisionId,\n request_Type = requestTypes[0]![\"request_Type\"]!.GetValue(),\n request_Status = \"REQ\",\n request_Date = $\"{DateTime.Today:yyyy-MM-dd}T00:00:00\",\n as_Of_Date = $\"{startDate}T00:00:00\",\n request_Quantity = 1,\n physical_Card_Requested = true,\n })).Data!;\n var cardKey = card[\"idCardRequest_Key\"]!.GetValue();\n Console.WriteLine($\"ID card request {cardKey}\");\n "},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Python","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"../../_samples/playbooks/enroll-employees/enroll_employees.py","language":"python","header":{"controls":{"copy":{}}},"lang":"python","source":" request_types = api.get(\"/id-card-request-types\").data\n card = api.post(\"/id-card-requests\", {\n \"idCardRequest_Key\": 0, # 0 on create; VBAPI assigns the key\n \"renewal\": False,\n \"subscriber_ID\": SUBSCRIBER_ID,\n \"member_Seq\": insured_seq,\n \"group_ID\": GROUP_ID,\n \"division_ID\": DIVISION_ID,\n \"request_Type\": request_types[0][\"request_Type\"],\n \"request_Status\": \"REQ\",\n \"request_Date\": f\"{date.today().isoformat()}T00:00:00\",\n \"as_Of_Date\": f\"{start_date}T00:00:00\",\n \"request_Quantity\": 1,\n \"physical_Card_Requested\": True,\n }).data\n card_key = card[\"idCardRequest_Key\"]\n print(\"ID card request\", card_key)\n "},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"TypeScript","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"../../_samples/playbooks/enroll-employees/enrollEmployees.ts","language":"typescript","header":{"controls":{"copy":{}}},"lang":"typescript","source":" const requestTypes: any[] = (await api.get(\"/id-card-request-types\")).data;\n const card = (\n await api.post(\"/id-card-requests\", {\n idCardRequest_Key: 0, // 0 on create; VBAPI assigns the key\n renewal: false,\n subscriber_ID: SUBSCRIBER_ID,\n member_Seq: insuredSeq,\n group_ID: GROUP_ID,\n division_ID: DIVISION_ID,\n request_Type: requestTypes[0].request_Type,\n request_Status: \"REQ\",\n request_Date: `${new Date().toISOString().slice(0, 10)}T00:00:00`,\n as_Of_Date: `${startDate}T00:00:00`,\n request_Quantity: 1,\n physical_Card_Requested: true,\n })\n ).data;\n const cardKey: number = card.idCardRequest_Key;\n console.log(\"ID card request\", cardKey);\n "},"children":[]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Save from the response:"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["idCardRequest_Key"]}," (step 10)."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"10-check-the-id-card-request","__idx":12},"children":["10. Check the ID card request"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/member-id-card-requests/getidcardrequest"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /id-card-requests/{iDCardRequestKey}"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Read the request back to confirm it was saved. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["request_Status"]}," changes as the request is handled, for example to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["COMPLETE"]},"."]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"C#","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"../../_samples/playbooks/enroll-employees/EnrollEmployeesPlaybook.cs","language":"csharp","header":{"controls":{"copy":{}}},"lang":"csharp","source":" var savedCard = (await api.GetAsync($\"/id-card-requests/{cardKey}\")).Data!;\n Console.WriteLine($\"ID card request {savedCard[\"idCardRequest_Key\"]} status: {savedCard[\"request_Status\"]}\");\n "},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Python","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"../../_samples/playbooks/enroll-employees/enroll_employees.py","language":"python","header":{"controls":{"copy":{}}},"lang":"python","source":" card = api.get(f\"/id-card-requests/{card_key}\").data\n print(\"ID card request\", card[\"idCardRequest_Key\"], \"status:\", card.get(\"request_Status\"))\n "},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"TypeScript","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"../../_samples/playbooks/enroll-employees/enrollEmployees.ts","language":"typescript","header":{"controls":{"copy":{}}},"lang":"typescript","source":" const savedCard = (await api.get(`/id-card-requests/${cardKey}`)).data;\n console.log(\"ID card request\", savedCard.idCardRequest_Key, \"status:\", savedCard.request_Status);\n "},"children":[]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example response (illustrative; field values are fake):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"data\": {\n \"idCardRequest_Key\": 5001,\n \"subscriber_ID\": \"DOCS-0001\",\n \"member_Seq\": \"01\",\n \"group_ID\": \"DOCS-GRP1\",\n \"division_ID\": \"DOCS-DIV1\",\n \"request_Type\": \"NEWENROLL\",\n \"request_Status\": \"REQ\",\n \"request_Date\": \"2030-01-02T00:00:00\",\n \"as_Of_Date\": \"2030-01-01T00:00:00\",\n \"request_Quantity\": 1,\n \"renewal\": false,\n \"physical_Card_Requested\": true\n },\n \"error\": null,\n \"debug\": { \"activityID\": \"00000000-0000-0000-0000-000000000000\" }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"verify-the-result","__idx":13},"children":["Verify the result"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Run steps 6, 8, and 10 again; they only read data. The family should have one enrollment for the contract dates, the elected plans on it, and an ID card request with status ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REQ"]},". ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/subscribers/listallenrollmentssubscriber"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /subscribers/{subscriberID}/list-all-enrollments"]}]}," gives a single view of every enrollment the subscriber has."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"census-variation-many-families-at-once","__idx":14},"children":["Census variation: many families at once"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For a census file, load subscribers and members with the batch operations, then run steps 5 to 10 for each family."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/subscribers/updatebatchsubscribers"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT /subscribers-batch"]}]}," takes an array of subscribers."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/members/updatebatchmembers"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT /subscribers/{subscriberID}/members-batch"]}]}," takes one family's members."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Both create rows that do not exist and update rows that do, and return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["207 Multi-Status"]},". The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," array has one item per row, with its own ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201"]}," created, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]}," updated, or an error status), a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["body"]}," message, and an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," list of key and value pairs that identifies the row. One bad row does not stop the others, so always read every item."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["member_Seq"]}," in the batch. The batch decides between create and update by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subscriber_ID"]}," plus ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["member_Seq"]},", so without it every run adds new members. An update replaces the stored row with what you send, so include every field you want to keep."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The sample reads ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#download"},"children":["census-sample.csv"]},", whose ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["relationship"]}," column holds ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["insured"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["spouse"]},", or a code from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /relationships"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"subscriber_id,member_seq,relationship,first_name,last_name,address,city,state,zip_code\nDOCS-0101,01,insured,Sample,Member,123 Example St,Exampleville,TX,00000\nDOCS-0101,02,spouse,Sample Spouse,Member,123 Example St,Exampleville,TX,00000\nDOCS-0102,01,insured,Test,Person,123 Example St,Exampleville,TX,00000\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Load the subscribers and collect the failures:"]}]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"C#","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"../../_samples/playbooks/enroll-employees/EnrollEmployeesCensusPlaybook.cs","language":"csharp","header":{"controls":{"copy":{}}},"lang":"csharp","source":" var families = ReadCsv(CensusFile()).GroupBy(row => row[\"subscriber_id\"]).ToList();\n var subscribers = families.Select(family =>\n {\n var insured = family.First(r => r[\"relationship\"] == \"insured\");\n return new\n {\n subscriber_ID = family.Key,\n first_Name = insured[\"first_name\"],\n last_Name = insured[\"last_name\"],\n address = insured[\"address\"],\n city = insured[\"city\"],\n state = insured[\"state\"],\n zip_Code = insured[\"zip_code\"],\n };\n }).ToList();\n var response = await api.PutAsync(\"/subscribers-batch\", subscribers); // 207 Multi-Status\n var failedIds = new HashSet();\n foreach (var item in response.Data?.AsArray() ?? new JsonArray())\n {\n if (item![\"status\"]!.GetValue() < 400)\n continue;\n var key = Key(item);\n failedIds.Add(key.GetValueOrDefault(\"Subscriber_ID\"));\n Console.WriteLine($\"Subscriber failed: {key.GetValueOrDefault(\"Subscriber_ID\")} {item[\"status\"]} {item[\"body\"]}\");\n }\n "},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Python","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"../../_samples/playbooks/enroll-employees/enroll_census.py","language":"python","header":{"controls":{"copy":{}}},"lang":"python","source":" with CENSUS_FILE.open(newline=\"\", encoding=\"utf-8\") as file:\n rows = list(csv.DictReader(file))\n families = defaultdict(list)\n for row in rows:\n families[row[\"subscriber_id\"]].append(row)\n\n subscribers = []\n for subscriber_id, family in families.items():\n insured = next(r for r in family if r[\"relationship\"] == \"insured\")\n subscribers.append({\n \"subscriber_ID\": subscriber_id,\n \"first_Name\": insured[\"first_name\"],\n \"last_Name\": insured[\"last_name\"],\n \"address\": insured[\"address\"],\n \"city\": insured[\"city\"],\n \"state\": insured[\"state\"],\n \"zip_Code\": insured[\"zip_code\"],\n })\n response = api.put(\"/subscribers-batch\", subscribers) # 207 Multi-Status\n failed_ids = set()\n for item in failures(response):\n key = {pair[\"key\"]: pair[\"value\"] for pair in item[\"id\"]}\n failed_ids.add(key.get(\"Subscriber_ID\"))\n print(\"Subscriber failed:\", key, item[\"status\"], item[\"body\"])\n "},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"TypeScript","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"../../_samples/playbooks/enroll-employees/enrollCensus.ts","language":"typescript","header":{"controls":{"copy":{}}},"lang":"typescript","source":" const families = new Map[]>();\n for (const row of readCsv(CENSUS_FILE)) {\n families.set(row.subscriber_id, [...(families.get(row.subscriber_id) ?? []), row]);\n }\n const subscribers = [...families].map(([subscriberId, family]) => {\n const insured = family.find((r) => r.relationship === \"insured\")!;\n return {\n subscriber_ID: subscriberId,\n first_Name: insured.first_name,\n last_Name: insured.last_name,\n address: insured.address,\n city: insured.city,\n state: insured.state,\n zip_Code: insured.zip_code,\n };\n });\n const response = await api.put(\"/subscribers-batch\", subscribers); // 207 Multi-Status\n const failedIds = new Set();\n for (const item of response.data ?? []) {\n if (item.status < 400) continue;\n const key = keyOf(item);\n failedIds.add(key.Subscriber_ID);\n console.log(\"Subscriber failed:\", key, item.status, item.body);\n }\n "},"children":[]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Load each family's members, skipping families whose subscriber failed:"]}]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"C#","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"../../_samples/playbooks/enroll-employees/EnrollEmployeesCensusPlaybook.cs","language":"csharp","header":{"controls":{"copy":{}}},"lang":"csharp","source":" foreach (var family in families)\n {\n if (failedIds.Contains(family.Key))\n continue; // fix the subscriber row first, then re-run; the batch updates rows that exist\n var members = family.Select(row => new\n {\n subscriber_ID = family.Key,\n member_Seq = row[\"member_seq\"], // send it so a re-run updates instead of adding a member\n first_Name = row[\"first_name\"],\n last_Name = row[\"last_name\"],\n relationship = codes.GetValueOrDefault(row[\"relationship\"], row[\"relationship\"]),\n adult_Dependent = false,\n continue_Coverage = false,\n initial_Volume_Salary_Pct = false,\n other_Insurance = false,\n smoker = false,\n use_Member_Plan_Year = false,\n }).ToList();\n var memberResponse = await api.PutAsync($\"/subscribers/{family.Key}/members-batch\", members);\n foreach (var item in memberResponse.Data?.AsArray() ?? new JsonArray())\n Console.WriteLine($\"{family.Key} {Key(item!).GetValueOrDefault(\"Member_Seq\")} {item![\"status\"]} {item[\"body\"]}\"); // 201 Created, 200 Updated\n }\n "},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Python","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"../../_samples/playbooks/enroll-employees/enroll_census.py","language":"python","header":{"controls":{"copy":{}}},"lang":"python","source":" for subscriber_id, family in families.items():\n if subscriber_id in failed_ids:\n continue # fix the subscriber row first, then re-run; the batch updates rows that exist\n members = [{\n \"subscriber_ID\": subscriber_id,\n \"member_Seq\": row[\"member_seq\"], # send it so a re-run updates instead of adding a member\n \"first_Name\": row[\"first_name\"],\n \"last_Name\": row[\"last_name\"],\n \"relationship\": codes.get(row[\"relationship\"], row[\"relationship\"]),\n \"adult_Dependent\": False,\n \"continue_Coverage\": False,\n \"initial_Volume_Salary_Pct\": False,\n \"other_Insurance\": False,\n \"smoker\": False,\n \"use_Member_Plan_Year\": False,\n } for row in family]\n response = api.put(f\"/subscribers/{subscriber_id}/members-batch\", members)\n for item in response.data or []:\n key = {pair[\"key\"]: pair[\"value\"] for pair in item[\"id\"]}\n print(subscriber_id, key.get(\"Member_Seq\"), item[\"status\"], item[\"body\"]) # 201 Created, 200 Updated\n "},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"TypeScript","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"file":"../../_samples/playbooks/enroll-employees/enrollCensus.ts","language":"typescript","header":{"controls":{"copy":{}}},"lang":"typescript","source":" for (const [subscriberId, family] of families) {\n if (failedIds.has(subscriberId)) continue; // fix the subscriber row first, then re-run; the batch updates rows that exist\n const members = family.map((row) => ({\n subscriber_ID: subscriberId,\n member_Seq: row.member_seq, // send it so a re-run updates instead of adding a member\n first_Name: row.first_name,\n last_Name: row.last_name,\n relationship: codes[row.relationship] ?? row.relationship,\n adult_Dependent: false,\n continue_Coverage: false,\n initial_Volume_Salary_Pct: false,\n other_Insurance: false,\n smoker: false,\n use_Member_Plan_Year: false,\n }));\n const memberResponse = await api.put(`/subscribers/${subscriberId}/members-batch`, members);\n for (const item of memberResponse.data ?? []) {\n console.log(subscriberId, keyOf(item).Member_Seq, item.status, item.body); // 201 Created, 200 Updated\n }\n }\n "},"children":[]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["207"]}," response (illustrative; field values are fake):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"data\": [\n { \"id\": [{ \"key\": \"Subscriber_ID\", \"value\": \"DOCS-0101\" }], \"status\": 201, \"body\": \"Created\" },\n { \"id\": [{ \"key\": \"Subscriber_ID\", \"value\": \"DOCS-0102\" }], \"status\": 400, \"body\": \"A validation message for this row\" }\n ],\n \"error\": null,\n \"debug\": { \"activityID\": \"00000000-0000-0000-0000-000000000000\" }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Keep batches to a size your system can retry, and stay within the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/developer-portal/concepts/rate-limits-and-performance"},"children":["rate limits"]}," when you loop over families."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"safe-to-re-run","__idx":15},"children":["Safe to re-run?"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The main sample checks before each create: it skips the subscriber if ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /subscribers/{subscriberID}"]}," finds it, skips members whose relationship is already in the family, skips ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["add-enrollment"]}," if the enrollment exists, and skips plans already on it."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["add-enrollment"]}," creates the enrollment row keyed by subscriber, group, division, contract start, and start date, so repeating it with the same dates fails rather than creating a duplicate."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Each ID card request is a new record. Running step 9 twice requests two cards."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The census batches are upserts: re-running them updates the same rows, as long as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["member_Seq"]}," is in the file."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"undo","__idx":16},"children":["Undo"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To remove a test family:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Delete the ID card request with ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/member-id-card-requests/deleteidcardrequest"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE /id-card-requests/{iDCardRequestKey}"]}]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Delete the subscriber with ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/subscribers/deletesubscribers"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE /subscribers/{subscriberID}"]}]},". The database removes the subscriber's enrollments and members with it, and refuses the delete if the subscriber has claims, authorizations, or accumulators."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Deletes return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["204"]},". To remove only one enrollment or one dependent, use ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/subscriber-enrollments/deletesubenrollment"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE /subscribers/{subscriberID}/enrollments/{groupID}/{divisionID}/{groupCoverageStart}/{startDate}"]}]}," or ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/members/deletemembers"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE /subscribers/{subscriberID}/members/{memberSeq}"]}]},". Deleting the insured member this way returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]},"; delete the subscriber instead. For a real member who is leaving, disenroll instead of deleting; see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/developer-portal/playbooks/disenroll-member"},"children":["Disenroll a member"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"common-errors","__idx":17},"children":["Common errors"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Symptom"},"children":["Symptom"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Likely cause"},"children":["Likely cause"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Fix"},"children":["Fix"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}," \"No member exists for the Subscriber ID\" on step 5"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Members were not created"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Run step 4 first"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}," \"The Group Contract does not exsit\" on step 5"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["group_Coverage_Start"]}," does not match a contract's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["coverage_Start"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Use the exact date from step 1"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}," \"The End Date must be populated\" on step 5"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["end_Date"]}," was left out"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Send ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["end_Date"]},", usually the contract's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["coverage_End"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}," on a member, naming ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subscriber_ID"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The body ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subscriber_ID"]}," does not match the path"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Send the same ID in both"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422"]}," \"Maximum of 99 members exceeded\""]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The family already has ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["member_Seq"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["99"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Check for duplicate members"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Batch item with status ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["500"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["That row failed validation"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Read ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["body"]},", fix the row, and re-run; the other rows are already saved"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{\"message\":\"Forbidden\"}"]}," on every call"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-api-key"]}," header is missing or wrong"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/developer-portal/concepts/errors"},"children":["Errors and troubleshooting"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Contacting support"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send VBA support:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["debug.activityID"]}," from the response"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["the date and time of the call, with time zone"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["the method and path, for example ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /claim-batches"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["the full ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]}," object from the response"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["the request body, with passwords, tokens, and personal data removed"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Never send your password, API key, or tokens. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/developer-portal/help/support"},"children":["Support and escalation"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"variations","__idx":18},"children":["Variations"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Member-level plans:"]}," when the group contract's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["benefit_At_Member"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"1\""]},", plans are chosen per member. Read them with ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/member-enrollment-plans/listmemenrollmentplan"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /subscribers/{subscriberID}/members/{memberSeq}/groups/{groupID}/divisions/{divisionID}/enrollments"]}]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Producing the cards:"]}," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi/vbasoftware/vbasoftware.api/adv.-enrollment/idcardrequestreportseries"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /idcardrequest-process-automation"]}]}," takes a list of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["idCardRequest_Key"]}," values and runs the process automation your database has configured for ID card requests. Ask VBA how card production is set up for you."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"set-up-your-environment","__idx":19},"children":["Set up your environment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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:"]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"PowerShell","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"powershell","header":{"controls":{"copy":{}}},"source":"$env:VBAPI_BASE_URL = \"https://vbapi.vbasoftware.com/vbasoftware\"\n$env:VBAPI_API_KEY = \"your-api-key\"\n$env:VBAPI_CLIENT_ID = \"your-client-id\"\n$env:VBAPI_CLIENT_CODE = \"your-client-code\"\n$env:VBAPI_DATABASE = \"YOUR_DATABASE\"\n$env:VBAPI_USERNAME = \"your-api-username\"\n$env:VBAPI_PASSWORD = \"your-api-password\"\n$env:VBAPI_USER_AGENT = \"YourCompany-Integration/1.0\"\n","lang":"powershell"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"bash","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"export VBAPI_BASE_URL=\"https://vbapi.vbasoftware.com/vbasoftware\"\nexport VBAPI_API_KEY=\"your-api-key\"\nexport VBAPI_CLIENT_ID=\"your-client-id\"\nexport VBAPI_CLIENT_CODE=\"your-client-code\"\nexport VBAPI_DATABASE=\"YOUR_DATABASE\"\nexport VBAPI_USERNAME=\"your-api-username\"\nexport VBAPI_PASSWORD=\"your-api-password\"\nexport VBAPI_USER_AGENT=\"YourCompany-Integration/1.0\"\n","lang":"bash"},"children":[]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In production code, load these from your secrets manager instead."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"download","__idx":20},"children":["Download"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The full runnable samples are in the docs repository under ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["_samples/playbooks/enroll-employees/"]},": ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EnrollEmployeesPlaybook.cs"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["enroll_employees.py"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["enrollEmployees.ts"]}," for one family, and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EnrollEmployeesCensusPlaybook.cs"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["enroll_census.py"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["enrollCensus.ts"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["census-sample.csv"]}," for the census variation. See ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["_samples/playbooks/README.md"]}," for how to run them."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related","__idx":21},"children":["Related"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Concepts: ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/developer-portal/concepts/data-model"},"children":["Data model"]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/developer-portal/concepts/ids-and-conventions"},"children":["IDs and conventions"]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/developer-portal/concepts/requests-and-responses"},"children":["Requests and responses"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Previous playbook: ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/developer-portal/playbooks/onboard-employer-group"},"children":["Onboard a new employer group"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Next playbooks: ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/developer-portal/playbooks/member-self-service"},"children":["Member self-service"]},", ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/developer-portal/playbooks/premium-billing-and-payments"},"children":["Bill premiums and apply payments"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Ask the AI: \"Using the Enroll employees playbook, write a Python function that loads a census CSV with the batch endpoints and lists the rows that failed.\""]}]}]},"headings":[{"value":"Enroll employees and dependents, and request ID cards","id":"enroll-employees-and-dependents-and-request-id-cards","depth":1},{"value":"How it fits together","id":"how-it-fits-together","depth":2},{"value":"Steps","id":"steps","depth":2},{"value":"1. Pick the contract and plan","id":"1-pick-the-contract-and-plan","depth":3},{"value":"2. Look up the relationship codes","id":"2-look-up-the-relationship-codes","depth":3},{"value":"3. Create the subscriber","id":"3-create-the-subscriber","depth":3},{"value":"4. Add the employee and dependents","id":"4-add-the-employee-and-dependents","depth":3},{"value":"5. Enroll the family","id":"5-enroll-the-family","depth":3},{"value":"6. Confirm the enrollment","id":"6-confirm-the-enrollment","depth":3},{"value":"7. Add the plan to the enrollment","id":"7-add-the-plan-to-the-enrollment","depth":3},{"value":"8. Confirm the plans","id":"8-confirm-the-plans","depth":3},{"value":"9. Request ID cards","id":"9-request-id-cards","depth":3},{"value":"10. Check the ID card request","id":"10-check-the-id-card-request","depth":3},{"value":"Verify the result","id":"verify-the-result","depth":2},{"value":"Census variation: many families at once","id":"census-variation-many-families-at-once","depth":2},{"value":"Safe to re-run?","id":"safe-to-re-run","depth":2},{"value":"Undo","id":"undo","depth":2},{"value":"Common errors","id":"common-errors","depth":2},{"value":"Variations","id":"variations","depth":2},{"value":"Set up your environment","id":"set-up-your-environment","depth":2},{"value":"Download","id":"download","depth":2},{"value":"Related","id":"related","depth":2}],"frontmatter":{"title":"Enroll employees and dependents, and request ID cards","description":"Add a subscriber and their dependents, enroll the family in an employer group's contract and plan, and request ID cards, for one employee or a whole census file.","seo":{"title":"Enroll employees and dependents, and request ID cards"}},"lastModified":"2026-10-26T21:09:33.693Z","pagePropGetterError":{"message":"","name":""}},"slug":"/developer-portal/playbooks/enroll-employees","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}