Frequently Asked Questions
      Back to home
      1. Knowledge Base
      2. APIs
      3. Frequently Asked Questions

      How to integrate our API service with your site or application?

      Our API platform is scalable and secure, providing easy, instant access to our financial planning calculations. All our APIs conform to the REST style and use HTTP for exchange, with the majority using JSON as representation. Follow the steps below;

      1. Browsing the APIs
      2. Signing up and accessing the Store
      3. Generating access keys
      4. Subscribing to individual APIs
      5. Using the API console
      6. Pricing Plans
      7. Securing your access key
      8. Troubleshooting the API's

      Browsing the APIs

      Our full suite of APIs is available to try before buying. The inputs have been slightly restricted in order to represent the key features of the API, along with a formatted output of the results. Associated JSON requests/responses and credit costs are also listed.

      If you see something that aligns with your business requirements and is interested in exploring its full capabilities, please sign up and access our Store.

      Signing up and accessing the Store

      To gain full access to our API Console and documentation, you'll need to sign up in the API Store. You can get started with just your name and email.

      On initial sign up, you'll have access to our full suite of APIs on a limited request quota against the Sandbox environment which is set-up to return dummy responses.

      You'll also have access to our API documentation. We provide both a simple and complex ‘how to’ real-life example, a Request-Response diagram and an API document listing each field.

      Once you're signed up, please begin by generating access keys as described below.

      Generating access keys

      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 EValue'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.

      Subscribing to individual APIs

      Once you have a valid access token for your application, you're ready to subscribe to an API.

      After initial sign-up, you'll have access to our full suite of APIs on a limited request quota against the Sandbox environment which is set-up to return dummy responses.

      1. Navigate to the ‘APIs’ section of the Store from the menu.
      2. Select the API you want. Each product page covers everything you need to know plus full documentation and an ‘API Console’ that you can use to test drive. Please note: If you click on the ‘API Console’ tab, you'll be reminded that you must first subscribe to the API before it can be used.
      3. Select the ‘Subscribe’ button at the top right of the page. A ‘Subscription Successful’ dialogue box will confirm when you're subscribed.

      You'll then be able to see that your access key has been added as a request header at the top of the API Console within your chosen API.

      Using the API Console

      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'
      Calling the API using cURL

      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'

       

      Pricing Plans

      Pricing is set on an enterprise basis and can be structured to accommodate all levels of intended usage and specified APIs. 

      The majority of these pricing plans can be purchased via the Store. However, if you would prefer to discuss this in further detail and perhaps require some advice on your specific requirements, please contact our team at apiteam@ev.uk

      Accessing the production environment

      Once you've signed up, you can then access our Production environment. The APIs will not automatically pick up new access keys and subscriptions, so please repeat the above steps in order to access the live responses.

      Securing your access token

      Your access token is linked to your account. Since you are billed for each call to EValue'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
      Generating an access 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"
      }

       

      Troubleshooting the APIs

      Should you experience any issues or technical difficulties with our APIs, please see the FAQ section of the Developer Portal. This will be frequently updated and maintained in order to provide the best self-support service.

      Alternatively, we understand that there will be questions outside of the FAQ coverage and we, therefore, have a dedicated Support team at apiteam@ev.uk.

      Content support is available only to Subscribed Users

      As the Sandbox APIs returns dummy responses, we're unable to provide any support relating to queries on the content of the APIs themselves. However, both Subscribed and non-subscribed Users have access to Technical, Billing and Account Management support services.