Getting Started

Get an API Key

You can use the VBAPIs in test mode, which does not affect your live data, or interact with your live data in production. The API key you use to authenticate the request determines whether the request is live mode or test mode.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Contact your Account Executive to request an API Key.

Get an API Client

The easiest way to get started is to use one of our pre-generated clients. Our generated clients are a first-class SDKs that follows the OpenAPI specification to interact with VBAPI APIs.

Web-based npm Clients Hosted on npm. Download to your local machine with the command npm install

Local Clients Download, extract and run from your local machine.

B.Y.O.C. - Build Your Own Client You can build your own client in any of the 50+ languages using the OpenAPI Generator.

Login To APIs

Every API request needs to be authenticated using a valid VBASoftware user. See the Create User API or have a VBASoftware Administrator create your user account using the VBASoftware application.

The following code snippet shows how to perform a user authentication request using the C-Sharp programming language. The result will be an id-token that can be used in subsequent requests.

Copy
Copied
    using Newtonsoft.Json.Linq;
    using RestSharp;


    private string Get_Id_Token()
    {
        // create a client
        var client = new RestClient("https://vbapi.vbasoftware.com/vbasoftware/");

        // create a request 
        var request = new RestRequest("/user-authentication", Method.POST); 

        // set headers required in the request
        request.AddHeader("x-api-key", {your_api_key});
        request.AddHeader("Authorization", $"Basic {base64_encoded_username_and_password}");
        request.AddHeader("vbasoftware-client-id", {your_client_id});
        request.AddHeader("vbasoftware-client-code", {your_client_code});
        request.AddHeader("vbasoftware-database", {your_desired_database});

        // make the call
        var response = client.Execute(request);

        // parse the response 
        var jsonResponse = JObject.Parse(response.Content);

        // get the data object - see responses page for information on how all VBAPI responses are formatted
        JObject dataJson = (JObject)jsonResponse.GetValue("data");

        // get the authenticationResult object
        JObject authenticationResultJson = (JObject)dataJson.GetValue("authenticationResult");

        // get the idToken value
        string idToken = (string)authenticationResultJson.GetValue("idToken");

        // return the id-token
        return idToken;
    }

Next, we can use the id-token to perform an authenticated request. In the next example, we will make a call to reqtrieve a specific benefit. The id-token from the previous example is added to the Authorization header in the format of Bearer {id-token}.

Copy
Copied
    // get the id token using the previous example
    string idToken = Get_Id_Token();

    // create the request
    RestRequest getRequest = new RestRequest($"/benefits/{Benefit_Code}", Method.GET);

    // add the id-token to the authorization header
    request.AddHeader("x-api-key", {your_api_key});
    request.AddHeader("Authorization", $"Bearer {idToken}");
    request.AddHeader("vbasoftware-database", {your_desired_database});


    // execute the request 
    IRestResponse response = httpClient.Execute(getRequest);

    // get the response 
    var getJsonResponse = JObject.Parse(response.Content);

    // get the data object - see responses page for information on how all VBAPI responses are formatted
    JObject getDataJson = (JObject)getJsonResponse.GetValue("data");

    // convert the response to an object using Newtonsoft
    BenefitCodes benefitCode = getDataJson.ToObject<BenefitCodes>();