Start Personal Plan Request

This action can be used to start a new customized plan request for an end-user. It will return a URL which you can either link out to or embed in your website/app to allow the end-user or someone on your team to finish the request.

Any information provided in the input of this action will skip the corresponding question in the plan request. This action can also be used to standardize choices and package life insurance offerings for the end-user.

API Method:

Start Personal Plan Request

POST https://app.whiteswan.io/api/1.1/wf/new_request

Starts a new personal plan request and returns a URL that can be embedded or linked out to.

Headers

Name	Type	Description
Authorization*	String	Bearer <YOUR API KEY>
Content-Type*	String	application/json
Accept*	String	application/json
user-agent*	String	<YOUR APP>

Request Body

Name	Type	Description
JSON Body*	Object	See specification below

200: OK Call success

400: Bad Request Call failure

401: Unauthorized Permission denied

404: Not Found Not found

405: Method Not Allowed Wrong method

429: Too Many Requests Too many requests

500: Internal Server Error Internal bug

503: Service Unavailable Service unavailable

Sample Body Payload

{
"name": "John Doe",
"email": "[e-mail]",
"policy_type": "Variable Universal Life",
"main_goal": "Accumulation",
"phone": "123456789",
"resident_state": "Ohio",
"death_benefit": 1000000,
"payment_schedule": "Monthly",
"paid_up_period": "10 Years",
"term_duration": "10 Years",
"premium_budget": 1000,
"gender": "Male",
"health_rating": "Excellent",
"date_of_birth": "20000123T012345.678+0900",
"tobacco": true,
"marijuana": true,
"height_feet": 6,
"height_inches": 5,
"weight_pounds": 100,
"risk_profile": "Aggressive",
"expedited_products": true,
"convertability": true,
"riders": [
  "Paid Up Additions (Whole Life Only)",
  "Waiver of Premium Rider"
],
"additional_premium_room": 0,
"one_time_deposit_amount": 0,
"allocation_accounts": [
  {
    "account_type": "S&P 500 Fund (Variable Universal Life)",
    "allocation_percentage": 0.5
  },
  {
    "account_type": "International Markets Funds (Variable Universal Life Only)",
    "allocation_percentage": 0.5
  }
],
"uncapped_accounts": true,
"fee_accounts": true,
"planned_retirement_income": true,
"retirement_start_age": 60,
"retirement_length": 20,
"supplemental_term_amount": 1000000,
"supplemental_term_length": 10,
"custom_account_allocation": true,
"associated_person": "[e-mail]",
"ws_follow_up": true,
"coms_recipients": "Client & Me",
"contact_id": "918503x139058213",
"request_comment": "Make it really explosive for accumulation"
}

Please note that the sample body payload above contains all possible parameters for your reference. In an actual call, you don't need to use all parameters, and some parameters are only relevant for certain policy types of plan goals.

Code Examples - Making the API Call:

cURL

curl -X POST "https://app.whiteswan.io/api/1.1/wf/new_request" \
     -H "Authorization: Bearer <YOUR API KEY>" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "user-agent: <YOUR APP>" \
     -d '{
         "name": "John Doe",
         "email": "[e-mail]",
         "policy_type": "Variable Universal Life",
         "main_goal": "Accumulation"
     }'

Python

import requests

url = "https://app.whiteswan.io/api/1.1/wf/new_request"
headers = {
    "Authorization": "Bearer <YOUR API KEY>",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "user-agent": "<YOUR APP>"
}
data = {
    "name": "John Doe",
    "email": "[e-mail]",
    "policy_type": "Variable Universal Life",
    "main_goal": "Accumulation"
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

Javascript

const url = "https://app.whiteswan.io/api/1.1/wf/new_request";
const headers = {
    "Authorization": "Bearer <YOUR API KEY>",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "user-agent": "<YOUR APP>"
};
const data = {
    name: "John Doe",
    email: "[e-mail]",
    policy_type: "Variable Universal Life",
    main_goal: "Accumulation"
};

fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error("Error:", error));

Java

import okhttp3.*;

public class WhiteSwanApiCall {

    public static void main(String[] args) {
        OkHttpClient client = new OkHttpClient();

        MediaType mediaType = MediaType.parse("application/json");
        RequestBody body = RequestBody.create(mediaType, "{\"name\":\"John Doe\",\"email\":\"[e-mail]\",\"policy_type\":\"Variable Universal Life\",\"main_goal\":\"Accumulation\"}");

        Request request = new Request.Builder()
            .url("https://app.whiteswan.io/api/1.1/wf/new_request")
            .post(body)
            .addHeader("Authorization", "Bearer <YOUR API KEY>")
            .addHeader("Content-Type", "application/json")
            .addHeader("Accept", "application/json")
            .addHeader("user-agent", "<YOUR APP>")
            .build();

        try {
            Response response = client.newCall(request).execute();
            System.out.println(response.body().string());
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}

PHP

<?php

$ch = curl_init();

$data = array(
    "name" => "John Doe",
    "email" => "[e-mail]",
    "policy_type" => "Variable Universal Life",
    "main_goal" => "Accumulation"
);

$headers = array(
    "Authorization: Bearer <YOUR API KEY>",
    "Content-Type: application/json",
    "Accept: application/json",
    "user-agent: <YOUR APP>"
);

curl_setopt($ch, CURLOPT_URL, "https://app.whiteswan.io/api/1.1/wf/new_request");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$response = curl_exec($ch);

if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
} else {
    echo $response;
}

curl_close($ch);
?>

Ruby

require 'net/http'
require 'json'
require 'uri'

uri = URI.parse("https://app.whiteswan.io/api/1.1/wf/new_request")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

headers = {
  'Authorization' => 'Bearer <YOUR API KEY>',
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'User-Agent' => '<YOUR APP>'
}

data = {
  name: "John Doe",
  email: "[e-mail]",
  policy_type: "Variable Universal Life",
  main_goal: "Accumulation"
}

request = Net::HTTP::Post.new(uri.path, headers)
request.body = data.to_json

response = http.request(request)
puts response.body

Go

package main

import (
	"bytes"
	"fmt"
	"net/http"
)

func main() {
	url := "https://app.whiteswan.io/api/1.1/wf/new_request"
	data := `{
		"name": "John Doe",
		"email": "[e-mail]",
		"policy_type": "Variable Universal Life",
		"main_goal": "Accumulation"
	}`

	req, err := http.NewRequest("POST", url, bytes.NewBuffer([]byte(data)))
	if err != nil {
		panic(err)
	}

	req.Header.Set("Authorization", "Bearer <YOUR API KEY>")
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Accept", "application/json")
	req.Header.Set("User-Agent", "<YOUR APP>")

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	fmt.Println("Response Status:", resp.Status)
}

Code examples are available in cURL, Python, Javascript, Java, PHP, Ruby, and Go, but can be constructed for other languages and tools. Some code examples include dependencies that may need to be installed in your codebase to ensure functionality. Please note that the code examples above does not contain all available input fields. Feel free to edit using the specification below. Also remember to replace any values in the code that looks like <VALUE> and to adapt the parameter values passed.

If the Policy Type and the Main Goal is provided with the request, the returned URL will go straight to the personal plan request, if not, the returned URL will go to the plan recommendation engine.

---

Body Parameters Specification:

Field Label	Field Key	Field Type	Required	Example Value	Description	Alternatives (if Multiple-Choice)
Name	name	Text	No	John Doe	The full name of the person who the request is made on behalf of.	-
Email	email	Text	No	[e-mail]	The email of the person who the request is made on behalf of.	-
Intended Insured Name	intended_insured_name	Text	No	Jack Doe	If the intended insured is not the same person as the policy holder, include the full name of the intended insured.	-
Second Insured Name	name_2	Text	No	Jane Doe	If covering two people, the full name of the second insured.	-
Policy type	policy_type	Multiple-Choice	No	Term Life	The policy type that this request is made for. If this and the main goal is provided with the request, the returned URL will go straight to the personal plan request, if not, the returned URL will go to the plan recommendation engine.	Variable Universal Life, Indexed Universal Life, Whole Life, Term Life, Guaranteed Universal Life, Private Placement Life
Main Goal	main_goal	Multiple-Choice	No	Accumulation	The primary goal of this plan request, either Protection, Balanced or Accumulation. If this and the policy type is provided with the request, the returned URL will go straight to the personal plan request, if not, the returned URL will go to the plan recommendation engine.	Accumulation, Balanced, Protection
Embed URL	embed_url	Boolean	No	false	If Embed URL is true, this action will return a URL that can be embedded in the same way that normal pages can be embedded through White Swan.	-
Turbo Request Mode (Skip Extras Section)	extras	Boolean	No	false	If this option is set as true, this request will skip the extras section, which contains deeper plan customization options such as retirement income planning, account selection, rider selection, and more.	-
Pre-fill Application Data ID	contact_id	Text	No	12345	If you have already created a pre-fill information you can pass its ID by using this parameter to associate that info with this request.	-
Custom Success Page (URL)	redirect_url	Text	No	https://example.com/success	If this is provided this request will be redirected to your custom URL when the request is finished, which you can use to nurture client relationships or cross sell other products/services.	-
Case Associated Person (Email)	associated_person	Text	No	[e-mail]	Optionally this case can be associated with a specific user on your White Swan account by including their email here. If left blank, it will be the person who set up this zap.	-
Phone Number	phone	Text	No	[phone]	The phone number of the person who the request is made on behalf of.	-
Resident State	resident_state	Multiple-Choice	No	California	The state in which the insured person is a resident.	All 50 States in the United States, written out in full in a capitalized form like example value.
Death Benefit Need	death_benefit	Number	No	500000	The amount of death benefit that is required for this plan. To opt for the lowest amount possible given a certain premium budget, use 0.	-
Payment Schedule	payment_schedule	Multiple-Choice	No	Monthly	How often premiums should be paid on this plan.	Monthly, Quarterly, Yearly
Paid Up Period	paid_up_period	Multiple-Choice	No	10 Years	How many years premiums should be paid on the policy (N/A for term life).	One-time, 10 Years, 20 Years, 30 Years, Lifetime
Term Life Coverage Period	term_duration	Multiple-Choice	No	20 Years	If this request is for term life, how many years the policy should cover the insured.	Less than 10 years, 10 Years, 15 Years, 20 Years, 30 Years, 40 Years
Premium Budget	premium_budget	Number	No	1000	The budget for premium payments (only applicable for plan requests with Accumulation as the main goal).	-
Gender	gender	Multiple-Choice	No	Male	Whether the intended insured person is Male or Female.	Male, Female
Second Insured Gender	gender_2	Multiple-Choice	No	Female	If covering two people, if the second insured is Male or Female.	Male, Female
Date of Birth	date_of_birth	DateTime	No	19850716T000000+0100	The date of birth of the intended insured person.	-
Second Insured Date of Birth	date_of_birth_2	DateTime	No	19850716T000000+0100	If covering two people, the date of birth of the second insured.	-
Health Rating	health_rating	Multiple-Choice	No	Good	How the insured person would rate their own general health.	Average, Good, Excellent
Second Insured Health Rating	health_rating2	Multiple-Choice	No	Excellent	If covering two people, how would the second insured rate their general health.	Average, Good, Excellent
Insured Uses Tobacco/Nicotine	tobacco	Boolean	No	false	Whether the intended insured person uses tobacco/nicotine products or not.	-
Second Insured Uses Tobacco/Nicotine	tobacco_2	Boolean	No	false	If covering two people, whether the second insured uses tobacco/nicotine products or not.	-
Insured Uses Marijuana/THC	marijuana	Boolean	No	false	Whether the intended insured person uses marijuana/THC products or not.	-
Second Insured Uses Marijuana/THC	marijuana_2	Boolean	No	false	If covering two people, whether the second insured uses marijuana/THC products or not.	-
Insured Height in Feet	height_feet	Number	No	6	The height in feet of the intended insured person.	-
Insured Height in Inches	height_inches	Number	No	2	The height in inches of the intended insured person.	-
Second Insured Height in Feet	height_feet_2	Number	No	5	If covering two people, the height in feet of the second insured.	-
Second Insured Height in Inches	height_inches_2	Number	No	6	If covering two people, the height in inches of the second insured.	-
Insured Weight in Pounds	weight_pounds	Number	No	180	The weight in pounds of the intended insured person.	-
Second Insured Weight in Pounds	weight_pounds_2	Number	No	170	If covering two people, the weight in pounds of the second insured.	-
Risk Profile (Only Variable Universal Life)	risk_profile	Multiple-Choice	No	Moderate	The risk appetite of the intended policy owner. Only applicable for Variable Universal Life.	Conservative, Moderate, Aggressive
Expedited Product Preference	expedited_products	Boolean	No	false	Whether this request should be for a product with expedited underwriting, which are policies that can be issued in 1-2 days.	-
Convertability Preference (Term life only)	convertability	Boolean	No	false	Whether a term life insurance should have the option to be converted into a permanent life insurance policy.	-
Riders for the Plan	riders	Text	No	Paid Up Additions (Whole Life Only)	The riders that should be included in this plan.	Paid Up Additions (Whole Life Only), Guaranteed Insurability Rider, Waiver of Premium Rider, Terminal Illness Rider, Return of Premium Rider, Child Insurance Rider, Supplemental Term Rider, Charitable Benefit Rider, Overloan Protection Rider, No Lapse Guarantee Rider, Enhanced Cash Surrender Value Rider, Conversion Extension (Term Life Only), Chronic/Critical Illness Rider, Waiver of Premium Rider, Return of Premium Rider
Supplemental Term Coverage Length	supplemental_term_length	Multiple-Choice	No	10 Years	If Supplemental term is included as a rider, this value refers to the number of years that the supplemental term rider will cover the insured.	10 Years, 20 Years, 30 Years, Life
Supplemental Term Amount	supplemental_term_amount	Number	No	100000	If Supplemental term is included as a rider, this value refers to the amount of death benefit on the supplemental term rider.	-
Room for additional premium	additional_premium_room	Number	No	5000	The amount of additional future premium that should be able to be paid for this plan while maintaining tax advantages.	-
One-Time Deposit Amount	one_time_deposit_amount	Number	No	10000	The additional (if any) one-time amount that is planned to be deposited with the first premium of this policy.	-
Uncapped Account Preference (Only Indexed Universal Life)	uncapped_accounts	Boolean	No	false	Whether requests for indexed universal life should include accounts without caps (ceiling on yearly crediting rate).	-
Fee Account Preference (Only Indexed Universal Life)	fee_accounts	Boolean	No	false	Whether requests for indexed universal life should include accounts with fees, which may come with additional benefits.	-
Planned Retirement Income	planned_retirement_income	Boolean	No	false	Whether the intended owner of this policy plans to use the policy to access retirement income.	-
Starting Age of Retirement Income	retirement_start_age	Number	No	65	The age the intended owner intends to start distributing retirement income from this policy.	-
Years of Retirement Income	retirement_length	Number	No	20	The amount of years the intended owner intends to distribute retirement income from this policy.	-
Custom Allocation Mix	custom_account_allocation	Boolean	No	false	With this option selected as true, you can customize the recommended account allocations. If it is set to false, White Swan will recommend an appropriate allocation mix for this case.	-
Cash Value Allocations	allocation_accounts	Object List	No	-	For Indexed Universal Life/Variable Universal Life, the accounts to which the cash value of this plan should initially be allocated to.
-Account Type	account_type	Multiple-Choice	No	Fixed Interest Account	The type of account/fund for this allocation slot. Note that account availability varies.	Fixed Interest Account, Domestic Indexed Accounts (Indexed Universal Life Only), International Indexed Accounts (Indexed Universal Life Only), Multi Indexed Accounts (Indexed Universal Life Only), Managed Volatility Accounts (Indexed Universal Life Only), Overall Index Funds (Variable Universal Life Only), Overall Specialty Funds (Variable Universal Life Only), Overall Bond Funds (Variable Universal Life Only), Overall Downside Protected Accounts (Variable Universal Life Only), S&P 500 Index Fund (Variable Universal Life Only), International Markets Funds (Variable Universal Life Only), Emerging Markets Funds (Variable Universal Life Only), Technology & Innovation Funds (Variable Universal Life Only), Real Estate Funds (Variable Universal Life Only), Healthcare Funds (Variable Universal Life Only), Energy Funds (Variable Universal Life Only), Utilities Funds (Variable Universal Life Only), Long Term Bond Funds (Variable Universal Life Only), High Yield Bond Funds (Variable Universal Life Only), Inflation Protected Bond Funds (Variable Universal Life Only), Index-linked Accounts (Variable Universal Life Only)
-Allocation Percentage	allocation_percentage	Number	No	50	If custom allocation is selected, the percentage allocated to each account/fund. Note that for variable universal life, percentage allocations for all non Overall Allocation options indicate the allocation as a percentage of the allocation to that Overall category.	-
White Swan Follow Up	ws_follow_up	Boolean	No	true	If this is set to true, White Swan will follow up with this client after the personal plan has been sent.	-
Who Receives Communications for Case	coms_recipients	Multiple-Choice	No	Client & Me	This input could be used to control who receives communications related to this case. If left empty, both you and the client will receive communications.	Client & Me, Only Client, Only Me
Plan Comment	request_comment	Text	No	I might want my wife covered under this plan too - let's discuss	This can be used to leave an optional comment for this case.	-

When using the input to customize cash value allocations for variable universal life, bear in mind that percentages are defined on two levels - overall category allocation, and specific category component allocation. As an example for this, a 50% allocation to Overall Index Funds and a 50% allocation to S&P 500 Index Funds would result in an actual allocation of 25% to S&P 500 Index Funds.

---

Sample Return Payload

{
"url_to_complete_request": "https://app.whiteswan.io/get_started/your_page?request=1813426016",
"url_to_view_request": "https://app.whiteswan.io/partner_case/1813426016",
"request_id": "1813426016"
}

Returned Parameters Specification:

Field Label	Field Key	Field Type	Example Value	Description
URL to Complete Request	url_to_complete_request	Text	https://app.whiteswan.io/get_started/your_page?request=1813426016	URL for the user to complete the request.
URL to View Request Internally	url_to_view_request	Text	https://app.whiteswan.io/partner_case/1813426016	Internal URL to view the request.
Plan Request Unique ID	request_id	Text	20181342x96601656	Unique ID for the plan request.