# FAQ This page is for developers who are integrating with VBAPI and want a quick answer. Each answer is short and links to the page that covers the topic in full. ## First-call errors | What you see | Likely cause | Fix | | --- | --- | --- | | `401` from `POST /user-authentication` | Wrong username or password, or the wrong client ID, client code, or database for that user. | Check each value with whoever issued your credentials. | | `challengeName: NEW_PASSWORD_REQUIRED` instead of tokens | The user still has a temporary password. | Set a permanent password with [`POST /change-temporary-password`](/openapi/vbasoftware/vbasoftware.api/user/userchangetemppassword), then log in again. | | `401` on a data call | The ID token is missing, expired, or not sent as `Bearer`. | Log in again, and send `Authorization: Bearer `. | | `403` with `{"message":"Forbidden"}` on every call | The `x-api-key` header is missing or wrong. | Send your API key in `x-api-key` on every request, login included. | | `429` | More than 25 requests per second (burst 50) on your API key. | Slow down and retry with backoff. The samples do this for you. | | Login or data calls fail for a database you expect to use | The `vbasoftware-database` value does not match a database your user can reach. | Use the database name you were given, exactly as issued. | ## Access and credentials ### Which URL do I call? Every client calls production: `https://vbapi.vbasoftware.com/vbasoftware`. See [Credentials and environments](/developer-portal/get-started/credentials-and-environments). ### Is there a sandbox? Clients have access to the production API only. You choose the database with the `vbasoftware-database` header, so use a non-production database for testing if VBA has given you one. See [Credentials and environments](/developer-portal/get-started/credentials-and-environments). ### Does "Try it" in the API reference call the real API? Yes. "Try it" sends real requests to production, so write operations there create or change real records. See [Try it in the browser](/developer-portal/get-started/try-it). ### Which headers does every call need? `x-api-key`, `Authorization: Bearer `, and `vbasoftware-database`, plus a descriptive `User-Agent` (recommended). Logging in uses a different set. See [Requests and responses](/developer-portal/concepts/requests-and-responses). ## Authentication ### How do I get a token? Call [`POST /user-authentication`](/openapi/vbasoftware/vbasoftware.api/user/userauthentication) with HTTP Basic credentials, your API key, `vbasoftware-client-id`, `vbasoftware-client-code`, and `vbasoftware-database`. Send the returned `idToken` as `Authorization: Bearer `. See [Authentication and tokens](/developer-portal/concepts/authentication). ### How long does a token last? For the number of seconds in `expiresIn` in the login response. Log in again before it expires. See [Authentication and tokens](/developer-portal/concepts/authentication). ### Login returned `challengeName` instead of tokens. What now? The user has a challenge to complete, for example `NEW_PASSWORD_REQUIRED` for a temporary password. Set a permanent password with [`POST /change-temporary-password`](/openapi/vbasoftware/vbasoftware.api/user/userchangetemppassword), then log in again. See [Authentication and tokens](/developer-portal/concepts/authentication). ## Requests and responses ### Why does every call return `403`? The API key is missing or wrong: send it in `x-api-key` on every call, login included. The body is `{"message":"Forbidden"}`. See [Errors and troubleshooting](/developer-portal/concepts/errors). ### My create call returned `200`, not `201`. Did it work? Yes. Creates return `200` with the new record in `data`. Deletes return `204` with no body, batch updates (`PUT /-batch`) return `207` with one result per item, and queued work returns `202`. See [Requests and responses](/developer-portal/concepts/requests-and-responses). ### What is `activityID`? `debug.activityID` in every response identifies the request in VBA's logs. Log it with every failure and include it when you contact support. The name has a capital `ID`. See [Support and escalation](/developer-portal/help/support). ### How fast can I call the API? 25 requests per second sustained, with bursts up to 50, per API key. Above that you get `429`; retry with backoff. See [Rate limits and performance](/developer-portal/concepts/rate-limits-and-performance). ### How do I page through a list? Pages start at 1 and `pageSize` defaults to 100. The server sets no maximum page size, so choose one your client can handle. Totals are in the `X-Pagination` response header. See [Pagination and sorting](/developer-portal/concepts/pagination-and-sorting). ### How is paging different for the Search API? [`POST /search`](/openapi/vbasoftware/vbasoftware.api/search-request/searchrequest) uses `page` and `pageCount`. Pages start at 1 (page 0 also returns the first page), `pageCount` defaults to 750, and values above 750 are rejected. The `X-Pagination` totals are only accurate when you send `include_Result_Details: true`. See [Search API](/developer-portal/concepts/search) and [Extract data with the Search API](/developer-portal/playbooks/search-extract). ### Which SearchConfig should I use? Pick one whose tables cover your data, then confirm it in your database with [`GET /search-configs/{searchConfigId}`](/openapi/vbasoftware/vbasoftware.api/search-config/getsearchconfig), because SearchConfigs can differ between databases. See the [SearchConfig reference](/developer-portal/reference/search-config-reference). ## Enrollment ### What is the difference between a subscriber and a member? A subscriber is the family unit, identified by `subscriber_ID`. A member is one person in that family, identified by `subscriber_ID` plus `member_Seq`. See [IDs, keys and field names](/developer-portal/concepts/ids-and-conventions) and the [Glossary](/developer-portal/reference/glossary). ### How do I terminate a member's coverage? With [`POST /subscribers/{subscriberID}/members/{memberSeq}/disenroll`](/openapi/vbasoftware/vbasoftware.api/adv.-enrollment/memberdisenroll). It waits for VBA's disenroll process and returns a `VBAProcess` record. `disenrollFamily`, `disenrollFuture`, and `terminateAuth` decide whether family members, future enrollments, and authorizations are affected. See [Disenroll a member or group](/developer-portal/playbooks/disenroll-member). ### Can I see the premium impact before disenrolling? Yes. [`GET /subscribers/{subscriberID}/as-of-date/{asOfDate}/disenroll-adjustments`](/openapi/vbasoftware/vbasoftware.api/adv.-billing/listdisenrolladjustment) lists the invoice adjustments a disenrollment on that date would create, without changing anything. See [Disenroll a member or group](/developer-portal/playbooks/disenroll-member). ## Claims and authorizations ### What is the difference between adjudicating and processing a claim? [Adjudicating](/openapi/vbasoftware/vbasoftware.api/claim-adjudication/adjudicateclaim) runs the benefit rules and returns the result, but the claim stays in its claim batch. [Processing](/openapi/vbasoftware/vbasoftware.api/claim-adjudication/processclaim) adjudicates and, if no business rule stops it, moves the claim out of the claim batch into processed claims. See [Enter claims and adjudicate them](/developer-portal/playbooks/claims-intake-and-adjudication). ### Processing a claim returned `202`. What happened? The claim was not moved out of the claim batch, for example because it pended. Send `includeDetails=true` to get the claim details back. See [Enter claims and adjudicate them](/developer-portal/playbooks/claims-intake-and-adjudication). ### How do I process a whole claim queue? [`POST /claim-queues/{claimQueueKey}/process`](/openapi/vbasoftware/vbasoftware.api/claim-adjudication/processclaimqueue) runs the queue in the background and returns `202`. See [Enter claims and adjudicate them](/developer-portal/playbooks/claims-intake-and-adjudication). ### Why must I send `auth_Number` twice when adding codes to an authorization? The procedure and diagnosis code calls take the authorization number in the path and in the body, and the API rejects the request if they differ. See [Create an authorization](/developer-portal/playbooks/create-authorization). ## Billing ### Can I change a premium invoice after it is finalized? No. Finalized invoices cannot be changed. See [Bill premiums and apply payments](/developer-portal/playbooks/premium-billing-and-payments). ### How do I read the results of a batch update? A batch `PUT` returns `207` with one result per item, each with its own status, so check every item rather than the overall status. See [Requests and responses](/developer-portal/concepts/requests-and-responses). ## AI and MCP ### Does the MCP server call the API? No. The portal's MCP server, at `/mcp`, is documentation-only: it answers from the published documentation and makes no live API calls. See [AI and MCP overview](/developer-portal/ai/overview) and [Connect your AI tools](/developer-portal/ai/connect-your-tools). ## Still stuck? See [Support and escalation](/developer-portal/help/support) for what to send VBA.