NAV Navbar
shell

Introduction

Welcome to the IncomeWizard API!.

IncomeWizard API! provides endpoint to create or retrieve annuity products, living benefit riders, withdrawal rates, illustrations etc.

This documentation includes detailed explanations of API endpoints and common data definitions

Making Requests

The base URL for IncomeWizard API requests is https://www.incomewizardpro.com/api/v2

The API is built on RESTful principles with resource-oriented URL endpoints. HTTP status codes are used to indicate any API errors and all responses are returned in JSON format. All requests must be made over an HTTPS connection to ensure a secure transmission of data. Following a RESTful structure, requests should hit API endpoints using the appropriate HTTP method, which will depend on the desired action:

Method Description
GET Use the GET method to retrieve information about your users, their accounts, and any associated financial data. This will always be a read-only request, so queried objects will never be modified by a GET request.
POST Use a POST method to create a new object, such as a new user or connection. Request parameters should be given in JSON format. The response body will typically return the newly created resource.
PUT Use a PUT method to update an object, such as updating connection credentials. As with a POST request, parameters should be given in JSON format. If successful, the response body will typically return the modified object.
DELETE Use a DELETE method to delete an object, such as deleting one of your users. Successful DELETE requests will typically return an empty response body.

Errors

The IncomeWizard API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- The API credentials or access token used are incorrect.
403 Forbidden -- You do not have access to the requested endpoint or action.
404 Not Found -- Returned if the given resource either does not exist or you do not have access to it.
405 Method Not Allowed -- You tried to access an endpoint with an invalid http method.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone -- The requested resource has been removed from our servers.
422 Unprocessable Entity -- There was an issue with the given parameters. This could be due to a missing required field, a malformed parameter, etc.
500 Internal Server Error -- There are internal or API-related errors on our side. Additional requests will not resolve the issue.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Authentication

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl "https://www.incomewizard.com/api/v2/authenticate"
  -H "Authorization: a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e"

Make sure to replace a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e with your API key.

IncomeWizard uses API keys to allow access to the API.

IncomeWizard expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e

Carrier

Get Carrier Details

curl "https://www.incomewizard.com/api/v2/carrier_details"
  -H "Authorization: a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e"

The above command returns JSON structured like this:

{

   "data":{

      "id":1,
      "name":"Carrier Name",

      "a_m_best_rating": "A++",
      "s_and_p_rating": "A",
      "moodys_rating": "A+",
      "created_at":"2019-03-15T09:18:00.000-04:00",
      "updated_at":"2019-03-15T09:18:00.000-04:00"
   }
}

This endpoint retrieves details of your insurance carrier.

HTTP Request

GET https://www.incomewizard.com/api/v2/carrier_details

Products

Get All Products

curl "https://www.incomewizard.com/api/v2/products"
  -H "Authorization: a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e"

The above command returns JSON structured like this:

{

   "data":[

      {

         "id":99,
         "name":"Retirement Plus Multiplier Annuity 5 Year CDSC",
         "carrier_id":1,
         "annuity_type":null,
         "mortality_expense_charge":"0.0",
         "admin_charge_type":null,
         "admin_charge":"0.0",
         "avg_sub_account_exp":null,
         "min_issue_age":null,
         "max_issue_age":null,
         "minimum_premium":null,
         "maximum_premium":null,
         "death_benefit_oftions":null,
         "enhance_death_benefit":null,
         "initial_credit_based_on":null,
         "one_time_credit_percentage":null,
         "one_time_credit_percentage_to_cv":null,
         "vesting":false,
         "created_at":"2019-08-06T10:12:08.000-04:00",
         "updated_at":"2019-08-06T10:12:08.000-04:00"
      },
      {

         "id":98,
         "name":"Retirement Plus Multiplier Annuity",
         "carrier_id":1,
         "annuity_type":null,
         "mortality_expense_charge":"0.0",
         "admin_charge_type":null,
         "admin_charge":"0.0",
         "avg_sub_account_exp":null,
         "min_issue_age":null,
         "max_issue_age":null,
         "minimum_premium":null,
         "maximum_premium":null,
         "death_benefit_oftions":null,
         "enhance_death_benefit":null,
         "initial_credit_based_on":null,
         "one_time_credit_percentage":null,
         "one_time_credit_percentage_to_cv":null,
         "vesting":false,
         "created_at":"2019-08-06T10:08:21.000-04:00",
         "updated_at":"2019-08-06T10:08:21.000-04:00"
      }
   ]
}

This endpoint retrieves all products.

HTTP Request

GET https://www.incomewizard.com/api/v2/products

Query Parameters

Parameter Default Description
status active/in-review If set to active, the result will includes only active products.

Create Annuity Product

curl "https://www.incomewizard.com/api/v2/products"
  -X POST
  -H "Authorization: a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e"
  -d '{"name":"SecureLink Future",
      "carrier_id":1,
      "annuity_type":"FIA",
      "mortality_expense_charge":"0.0",
      "admin_charge_type":1,
      "admin_charge":"0.0",
      "avg_sub_account_exp":"0.0",
      "min_issue_age":0,
      "max_issue_age":80,
      "minimum_premium":"10000.0",
      "maximum_premium":"2000000.0",
      "death_benefit_oftions":true,
      "enhance_death_benefit":false,
      "initial_credit_based_on":null,
      "one_time_credit_percentage":null,
      "one_time_credit_percentage_to_cv":null,
      "vesting":false}'

The above command returns JSON structured like this:

{ 
  "success" :"true"
}

This endpoint create annuity product.

HTTP Request

POST https://www.incomewizard.com/api/v2/products

URL Parameters

Parameter Description
name The name of the annuity product
carrier_id The id of insurance carrier of this product
annuity_type Type of annuity product must be in ['VA','FIA','FI','SPIA']
mortality_expense_charge Mortality and Expense ratio of this product. eg 1.25
admin_charge_type value 1 if charge is in percentage and 2 if charge is in dollar value
admin_charge value
avg_sub_account_exp Percentage value of average sub account expense
min_issue_age Minimum issue age for a annuity product
max_issue_age Maximum issue age for a annuity product
minimum_premium Minimum premium amount for a annuity product
maximum_Premium Maximum premium amount for a annuity product
death_benefit_oftions true if product offers death benefits
enhance_death_benefit true if product offers enhanced death benefits
initial_credit_based_on contract_value if credit/bonus is applied only on contract value, benefit_base if credit/bonus is applied only on benefit base , both of bonus applied on both
one_time_credit_percentage Initial credit percentage for Benefit Base
one_time_credit_percentage_cv Initial credit percentage for Contract Value
vesting true if there is vesting option

Get a Specific Product

curl "https://www.incomewizard.com/api/v2/products/2"
  -H "Authorization: a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e"

The above command returns JSON structured like this:

{

   "data":{

      "id":2,
      "name":"SecureLink Future",
      "carrier_id":1,
      "annuity_type":"FIA",
      "mortality_expense_charge":"0.0",
      "admin_charge_type":1,
      "admin_charge":"0.0",
      "avg_sub_account_exp":"0.0",
      "min_issue_age":0,
      "max_issue_age":80,
      "minimum_premium":"10000.0",
      "maximum_premium":"2000000.0",
      "death_benefit_oftions":true,
      "enhance_death_benefit":false,
      "initial_credit_based_on":null,
      "one_time_credit_percentage":null,
      "one_time_credit_percentage_to_cv":null,
      "vesting":false,
      "created_at":"2019-03-15T09:18:00.000-04:00",
      "updated_at":"2019-03-15T09:18:00.000-04:00"
   }
}

This endpoint retrieves a specific annuity product.

HTTP Request

GET https://www.incomewizard.com/api/v2/products/{id}

shell