Skip to content
/
Orientation

VBAPI Orientation

VBAPI is a powerful solution designed for clients utilizing VBASoftware. Traditionally, clients have had read-only access to their databases. With VBAPI, organizations can directly interact with their production database, enabling seamless integration with internal and external systems. By leveraging VBAPI, companies can operate more autonomously and reduce reliance on VBA for vendor interfaces or custom solution development.

Types of Endpoints

Data Access Endpoints

These endpoints allow retrieval and manipulation of structured data within VBASoftware. Each database table corresponds to multiple API endpoints supporting standard CRUD operations:

  • Create – Insert new records.
  • List – Retrieve multiple records.
  • Get – Fetch a specific record.
  • Update – Modify existing data.
  • Delete – Remove records.
  • Batch Operations – Process multiple records in a single request.

Advanced Endpoints

Advanced endpoints go beyond basic CRUD data access. The Advanced APIs contain additional business logic and perform complex tasks. Some examples are:

  • Adjudicating a Claim
  • Disenrolling a Member

Request Handling

Overview

The VBAPI follows the REST architecture, offering predictable resource-oriented URLs, JSON-encoded request bodies, JSON-encoded responses, and standard HTTP methods and response codes. All API requests must be made over HTTPS; plain HTTP requests will be rejected.

Required Headers

User-Agent Header

Every request must include a User-Agent header. Best practice is to provide your company's use case information within this header to help us optimize API performance and usage analytics.

Authorization Headers

VBAPI supports three authentication schemes:

  1. API Keys: All endpoints require an API key in the x-api-key header. Example:
    x-api-key: (your_api_key)
  2. Basic Authentication: Some endpoints require base64-encoded username:password in the Authorization header. Example:
    Authorization: Basic (base64_encoded_username:password)
  3. Bearer Authentication: Upon successful login, a JWT token is issued. Include it in the Authorization header for subsequent requests. Example:
    Authorization: Bearer (id_token)

:::attention Contact your Account Executive to request an API Key. :::

HTTP Methods and Idempotency

Idempotent Requests

Idempotency ensures that repeated identical requests result in the same outcome, preventing unintended side effects.

POST

  • Not idempotent
  • Used for creating new resources
  • Returns 201 Created on success
const resp = await fetch('https://vbapi-dev.vbasoftware.com/vbasoftware/counties', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer id-token',
        'vbasoftware-database': 'string',
        'x-api-key': 'YOUR_API_KEY_HERE'
    },
    body: JSON.stringify({
        county_Code: 'string',
        county_Name: 'string',
        state: 'st'
    })
});
const data = await resp.json();
console.log(data);

GET

  • Idempotent
  • Read-only operation with no side effects
  • Responses can be cached
  • Returns 200 OK on success
const countyCode = 'YOUR_countyCode_PARAMETER';
const resp = await fetch(`https://vbapi-dev.vbasoftware.com/vbasoftware/counties/${countyCode}`, {
    method: 'GET',
    headers: {
        'Authorization': 'Bearer id-token',
        'vbasoftware-database': 'string',
        'x-api-key': 'YOUR_API_KEY_HERE'
    }
});
const data = await resp.text();
console.log(data);

PUT

  • Idempotent
  • Used for full updates (all-or-nothing updates)
  • Returns 200 OK on success
const countyCode = 'YOUR_countyCode_PARAMETER';
const resp = await fetch(`https://vbapi-dev.vbasoftware.com/vbasoftware/counties/${countyCode}`, {
    method: 'PUT',
    headers: {
        'Authorization': 'Bearer id-token',
        'vbasoftware-database': 'string',
        'x-api-key': 'YOUR_API_KEY_HERE'
    },
    body: JSON.stringify({
        county_Code: 'ONE',
        county_Name: 'County UNO',
        state: 'SC'
    })
});
const data = await resp.json();
console.log(data);

PATCH

  • Not supported
  • Use PUT for updates

DELETE

  • Idempotent
  • Used to delete resources
  • Returns 204 No Content on success
const countyCode = 'YOUR_countyCode_PARAMETER';
const resp = await fetch(`https://vbapi-dev.vbasoftware.com/vbasoftware/${countyCode}`, {
    method: 'DELETE',
    headers: {
        'Authorization': 'Bearer id-token',
        'vbasoftware-database': 'string',
        'x-api-key': 'YOUR_API_KEY_HERE'
    }
});
const data = await resp.text();
console.log(data);

BATCH PUT

  • Idempotent for updates, non-idempotent for creates
  • Supports bulk create and update operations
  • Returns 207 Multi-Status, with individual response codes for each item
const resp = await fetch(`https://vbapi-dev.vbasoftware.com/vbasoftware/counties-batch`, {
    method: 'PUT',
    headers: {
        'Authorization': 'Bearer id-token',
        'vbasoftware-database': 'string',
        'x-api-key': 'YOUR_API_KEY_HERE'
    },
    body: JSON.stringify([
        {
            county_Code: 'ONE',
            county_Name: 'County One',
            state: 'SC'
        },
        {
            county_Code: 'TWO',
            county_Name: 'County Two',
            state: 'SC'
        }
    ])
});
const data = await resp.json();
console.log(data);

API Response Handling

HTTP Response Codes

VBAPI adheres to conventional HTTP response codes to indicate the success or failure of an API request.

Success Responses (2xx)

  • 200 OK – The request was successful, and the response contains the requested data.
  • 201 Created – The request successfully created a resource.

Client Errors (4xx)

  • 400 Bad Request – The request was malformed or invalid.
  • 401 Unauthorized – Authentication is required or failed.
  • 403 Forbidden – The authenticated user lacks necessary permissions.
  • 404 Not Found – The requested resource does not exist.

Server Errors (5xx)

  • 500 Internal Server Error – A generic server error occurred.

Response Payload Structure

Every response from VBAPI follows a standardized envelope format, ensuring consistency across successful and error responses.

{
    "data": single object | array of objects | null on error,
    "error": single object | null,
    "debug": {
        "activityId": "unique request identifier"
    }
}

Data Object

Successful responses include a data field, which contains either a single object or an array of objects. The error field remains null, and the debug object contains an activityId.

Example:

{
    "data": [
        { "id": 1, "name": "Example" }
    ],
    "error": null,
    "debug": {
        "activityId": "a62d1412-9fe9-4ac0-9dc7-3a3e35d202fd"
    }
}

Error Object

If an error occurs, the data field is null, and an error object provides details. The debug object still contains an activityId.

Error Object Fields:

  • type – A URL linking to additional information about the error.
  • title – A brief, user-friendly summary of the error.
  • status – The HTTP status code corresponding to the error.
  • detail – A descriptive message explaining the error.
  • instance – The specific API endpoint where the error occurred.

Example:

{
    "data": null,
    "error": {
        "type": "https://httpstatuses.com/404",
        "title": "Not Found",
        "status": 404,
        "detail": "The requested resource (xyz) was not found.",
        "instance": "/clients/abc/products/xyz"
    },
    "debug": {
        "activityId": "a62d1412-9fe9-4ac0-9dc7-3a3e35d202fd"
    }
}

Debug Object

Each response includes a debug object containing a unique activityId. This identifier links all internal logs related to a specific request. When seeking support, providing the activityId ensures the fastest resolution.

By structuring responses in this format, VBAPI ensures consistency, traceability, and ease of troubleshooting for developers.

 
Next page