Getting started

Before you can begin sending requests to the APIs, you'll need to activate the application and generate the necessary access keys (production and/or sandbox). This is a detailed description of the process:

1. Click the ‘Applications’ link in the navigation menu in the upper left of the Store. The resulting page shows the default application, ‘DefaultApplication’ (and any other applications you have created within the Store).
2. Click on the ‘DefaultApplication’ under the ‘Name’ column to be taken to its management page.
3. To create an access token for your application, a ‘Consumer Key’ together with a ‘Consumer Secret’ must be generated by clicking ‘Generate keys’ in the ‘Production Keys’ or ‘Sandbox Keys’ tabs of the management page. Doing this will also generate your first access token for your application, which by default has a validity period of 60 minutes. You can change this validity period if you want the token to be available for longer or shorter than 60 minutes.

Production endpoint versus Sandbox endpoint

The Production and Sandbox endpoints are two different environments: the Production endpoint represents EV's production environment, whereas the Sandbox endpoint acts as EV's pre-production environment. As only the Production environment returns a valid response, calls to this environment are included in any credit quota, in line with your chosen Payment Plan. Since the Sandbox environment returns dummy responses, calls to this environment are not included in any limited credit quota.

You can now use the API Console to interact with the API.

1. Expand the operation you're looking to request.
2. Populate the request with data. For each operation listed under the API, you can populate an example request by clicking on the JSON displayed under ‘Example Value’ in the ‘Data Type’ column. This example JSON can then be edited manually to send a specific request that you're interested in.
3. To send the request, click ‘Try it out’.
4. The response will be shown beneath it.

Along with the Curl response, we'll also provide a Request URL. This is the URL that the integrated response should be sent to, along with your token key, in order to access our services. Both these fields are shown on the example Curl below, highlighted in red:

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: Bearer XXX-XXX-XXX' -d '{ *** API Request *** }' 'https://api.evalueproduction.com/XXXXXX' 

For example, this is what the call looks like for the State Benefit Age API. Both the JSON data and the URL have been filled in.

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: Bearer XXX-XXX-XXX' -d '{
	"dateOfBirth": "1980-05-11",
	"gender": "FEMALE"
}' 'https://api.evalueproduction.com/state-benefit/1.0.0/stateBenefitAge/age' 

Your access token is linked to your account. Since you are billed for each call to EV's APIs, it is important that you keep your access token safe.

It is unwise to keep your token client-side, for example in a hidden input field on the page, or hardcoded in a JavaScript file. Instead we recommend keeping the token server-side. We have created two code examples, calling EV's APIs programmatically using Node.js & Express and PHP. Both examples keep the authentication token server-side, away from the client.

You can also set a validity period on your access token. If a third party discovered your token, then they would only have access to EV's APIs for a brief period. To implement this, your application would need to store the token locally, and check its validity. Should the token expire, the application would need to request a fresh token. This can be done programmatically. See the example cURL below.

curl -k -d "grant_type=client_credentials" \
    -H "Authorization: Basic XXX" \
     https://api.evalueproduction.com/token

This would return either the new access token, if the old one has expired, or the existing access token. It would also return the duration of the token (in seconds). Your application would have to record this time. Before making future API requests it would have to use the expiry time to work out if the token was still valid, or if it needed to fetch a fresh token.

{
	"scope": "am_application_scope default",
	"token_type": "Bearer",
	"expires_in": 3285,
	"access_token": "XXX-XXX-XXX"
}