Introduction
This document is designed to provide an introduction to the eValuate API. It includes interactive examples of the API operations needed to create time-limited authenticated links for users, to pre-fill and extract data and eValuate results, and to support data mapping.
All of the API operations described below are documented, with additional detail, in OpenAPI 3 YAML format. This file can be imported into tools like Postman and Swagger. You may request a copy of this file from PSG.
API operations are authenticated using a bearer token. You can generate bearer tokens using the eValuate management portal, or PSG can provide them.
When linking users to your eValuate site, they will need a bearer token if the site is configured to require API-driven access. Bearer tokens generated for users are different from the ones you use when making API calls--they have more restricted access to data. For this reason, you should not share your API tokens with users. Instead, you should generate a new bearer token each time you link a user to eValuate, as described below.
Most of the API operations shown here can be made in the test environment without authenticating, as long as you are testing with a site that isn't configured to require authentication. The exceptions are the two API operations to generate user bearer tokens. These must always be authenticated using an API token.
Site Access
The simplest use of the API is to provide users access to an eValuate site that is not open to the public. In that case, you'll need to create a bearer token that allows access to your site for a limited period of time.
In this request, you may optionally specify the amount of time the token should be valid using
any combination of hours, minutes, and seconds. You may instead pass an empty object
{} for the default of 12 hours, which is also the maximum user token lifetime.
You may also optionally specify the user name and email for reporting purposes. The
user property should be omitted if not including this information.
The response is an object containing a bearer token.
The returned bearer token can then be applied when linking the user's browser to eValuate. It is added to the end of the eValuate URL, after a hash symbol:
Once a user is connected to eValuate using a site-level bearer token, they can run multiple eValuate queries and quotes. Because these queries are generated in a browser session, there is no way to pre-fill or extract data from them. For that, query-level integration is needed.
Creating a Query
For more control, including the ability to pre-fill or extract data, you can create queries individually via the API.
When creating a new query, you may optionally pre-fill data as shown below. If you don't need to
pre-fill data, you can just pass an empty object {}.
Keep track of the returned uuid value and use it in subsequent API operations for
this query.
You can update the data associated with a query as shown below. The query data is completely replaced with the new values, and any fields not included are erased. Do not use a single query to evaluate multiple subjects.
Evaulating a Query
Once a query has been created and optionally pre-filled with data, you may create a bearer token to allow a user access to that specific query in eValuate.
In this request, you may optionally specify the amount of time the token should be valid using
any combination of hours, minutes, and seconds. You may instead pass an empty object
{} for the default of 12 hours, which is also the maximum user token lifetime.
The returned bearer token can then be applied when linking the user's browser to eValuate. It is added to the end of the eValuate URL, after a hash symbol:
Once a user is connected to eValuate using a query-level bearer token, they will be able to enter additional data and generate eValuate results, including premium quotes if they are enabled for your site.
When the user is finished with the query, you can use the API to export data from eValuate, including quote results:
Field Mapping
Pre-filling and extracting more than the most basic data from eValuate requires knowledge of how field names like "tobacco-date" correspond to questions like "When did you last smoke cigarettes, use e-cigarettes, or vape?"
PSG is able to provide PDF documentation for these fields, which may be sufficient depending on the amount of data that you want to access programmatically. Alternatively, you may query the API to retrieve all of the prompts associated with an eValuate site:
The results in the example above are limited to a single page for clarity. If you test the API using the "Try It" button, you'll see the full results.
There are several field types supported by eValuate:
- yesno
- A Yes or No question. The value must be "true" for Yes or "false" for No.
- numeric
- A numeric value. Note that all field values are encoded as strings in the JSON.
- date
- A date, represented as "mm/dd/yyyy". The month and day may be omitted if not known, e.g. "5//2019" or "//2019", except for the birth date, which should be complete if provided.
- multiple
- A set of options, of which only one may be selected. Presented as a series of toggle buttons in the eValuate UI.
- pulldown
- A set of options, of which only one may be selected. Presented as a pulldown list in the eValuate UI.
- toggle
- A set of options, of which one or more may be selected. Presented as a series of toggle buttons in the eValuate UI. Multiple reponses should be separated by commas, e.g. "depression,anxiety".
There are a few fields that are used for all eValuate sites and that are not included in the "Get Site Prompts" API response:
- birth-date
- The subject's birth date, like "12/02/1980".
- gender
- The subject's gender: "male" or "female".
- height
- The subject's height, in inches. For example, 5-ft 10-in would be "70".
- weight
- The subject's weight, in pounds, like "180".
In addition, the following fields are used if premium quoting is enabled:
- application-state
- The state where the quote should be run, like "FL".
- term-length
- The term length, if applicable, like "20".
- benefit-amount
- The benefit amount, which should be an integer encoded as a string, like "250000".
Evaluate via API
If you are able to collect all of the relevant data, you may be able to use eValuate without accessing the user interface.
You can trigger eValuate to run via the API, as shown below. Including the optional "fields" parameter with the value "true" will cause eValuate to return a list of the fields that were considered when evaluating the subject. This may be useful when deciding which fields to show in your own user interface.
You may pass an empty object {}, which will use the existing query data.
Alternatively, you may pass the data object as in Update Query
Data to update the data and evaluate the query in a single request.
This completes the documentation of the core functionality of the eValuate API. Additional documentation may be available for specific advanced operations. Please reach out to PSG to discuss the needs of your integration.