Onboard Agency

This endpoint can be used to create an onboarding link for new agencies under your company account with White Swan. Any account created through this onboarding link will be in your downline, and data that you provide with this call will be used to pre-fill and streamline onboarding for the user.

Creating an agency onboard link is different from inviting a user to your account. When you invite a user to your account, they will join your company account, meanwhile when you create an agency onboarding link, they will create their own company account, which will be a downline to your company account.

API Method:

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

Creates an agency onboarding link.

Headers

Name

Type

Description

Authorization*

String

Bearer <YOUR API KEY>

Content-Type*

String

application/json

Accept*

String

application/json

user-agent*

String

Request Body

Name

Type

Description

JSON Body*

Object

See specification below

Sample Body Payload

{
  "company_id": "1776772304993x692932671527100400",
  "company_logo": "https://assets.whiteswan.io/logos/acme-logo-light.png",
  "company_darkmode_logo": "https://assets.whiteswan.io/logos/acme-logo-dark.png",
  "company_name": "Acme Insurance Group",
  "company_type": "Agency",
  "company_legal_name": "Acme Insurance Group LLC",
  "company_address": "123 Main St, Austin, TX 78701, USA",
  "company_account_plan": "Digital Agent Plan",
  "company_npn":"123456789",
  "company_scheduling_link": "https://calendly.com/acme-insurance",
  "company_enabled_product_types": [
    "Term Life",
    "Whole Life",
    "Indexed Universal Life"
  ],
  "company_enabled_carriers": [
    "John Hancock",
    "Nationwide",
    "Mutual of Omaha"
  ],
  "company_broker_dealer_legal_name": "Acme Financial Services LLC",
  "company_broker_dealer_address": "500 Market St, San Francisco, CA 94105, USA",
  "company_broker_dealer_website": "https://www.acmefinancial.com",
  "company_broker_dealer_phone_number": "+1-800-555-1122",
  "company_invited_users": [
    {
      "user_email": "[email protected]",
      "user_id": "1776772304993x812345678901234567",
      "user_npn": "12345678",
      "user_first_name": "Jane",
      "user_last_name": "Doe",
      "user_title": "Senior Insurance Advisor",
      "user_scheduling_link": "https://calendly.com/jane-doe",
      "user_phone_number": "+1-512-555-0101",
      "user_profile_picture": "https://assets.whiteswan.io/profiles/jane-doe.jpg",
      "user_licenses": [
        {
          "type": "Life",
          "state": "TX",
          "active": true
        },
        {
          "type": "Health",
          "state": "CA",
          "active": true
        }
      ],
      "user_permission": "Admin"
    },
    {
      "user_email": "[email protected]",
      "user_id": "1776772304993x823456789012345678",
      "user_npn": "87654321",
      "user_first_name": "John",
      "user_last_name": "Smith",
      "user_title": "Insurance Agent",
      "user_scheduling_link": "https://calendly.com/john-smith",
      "user_phone_number": "+1-512-555-0202",
      "user_profile_picture": "https://assets.whiteswan.io/profiles/john-smith.jpg",
      "user_licenses": [
        {
          "type": "Life",
          "state": "FL",
          "active": true
        },
        {
          "type": "Securities",
          "state": "NY",
          "active": false
        }
      ],
      "user_permission": "Agent"
    }
  ]
}

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.

Code Examples - Making the API Call:

curl -X POST "https://app.whiteswan.io/api/1.1/wf/agency_onboard" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "company_id": "1776772304993x692932671527100400",
    "company_name": "Acme Insurance Group",
    "company_type": "Agency",
    "company_account_plan": "Digital Agent Plan",
    "company_enabled_product_types": ["Term Life"],
    "company_enabled_carriers": ["John Hancock"],
    "company_invited_users": [
      {
        "user_email": "[email protected]",
        "user_id": "1776772304993x812345678901234567",
        "user_first_name": "Jane",
        "user_last_name": "Doe",
        "user_licenses": [
          {
            "type": "Life",
            "state": "TX",
            "active": true
          }
        ],
        "user_permission": "Admin"
      }
    ]
  }'

import requests

url = "https://app.whiteswan.io/api/1.1/wf/agency_onboard"

headers = {
    "Authorization": "Bearer <YOUR_API_KEY>",
    "Content-Type": "application/json",
    "Accept": "application/json"
}

payload = {
    "company_id": "1776772304993x692932671527100400",
    "company_name": "Acme Insurance Group",
    "company_type": "Agency",
    "company_account_plan": "Digital Agent Plan",
    "company_enabled_product_types": ["Term Life"],
    "company_enabled_carriers": ["John Hancock"],
    "company_invited_users": [
        {
            "user_email": "[email protected]",
            "user_id": "1776772304993x812345678901234567",
            "user_first_name": "Jane",
            "user_last_name": "Doe",
            "user_licenses": [
                {
                    "type": "Life",
                    "state": "TX",
                    "active": True
                }
            ],
            "user_permission": "Admin"
        }
    ]
}

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

fetch("https://app.whiteswan.io/api/1.1/wf/agency_onboard", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <YOUR_API_KEY>",
    "Content-Type": "application/json",
    "Accept": "application/json"
  },
  body: JSON.stringify({
    company_id: "1776772304993x692932671527100400",
    company_name: "Acme Insurance Group",
    company_type: "Agency",
    company_account_plan: "Digital Agent Plan",
    company_enabled_product_types: ["Term Life"],
    company_enabled_carriers: ["John Hancock"],
    company_invited_users: [
      {
        user_email: "[email protected]",
        user_id: "1776772304993x812345678901234567",
        user_first_name: "Jane",
        user_last_name: "Doe",
        user_licenses: [
          {
            type: "Life",
            state: "TX",
            active: true
          }
        ],
        user_permission: "Admin"
      }
    ]
  })
})
  .then(res => res.json())
  .then(data => console.log(data));

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n" +
  "  \"company_id\": \"1776772304993x692932671527100400\",\n" +
  "  \"company_name\": \"Acme Insurance Group\",\n" +
  "  \"company_type\": \"Agency\",\n" +
  "  \"company_account_plan\": \"Digital Agent Plan\",\n" +
  "  \"company_enabled_product_types\": [\"Term Life\"],\n" +
  "  \"company_enabled_carriers\": [\"John Hancock\"],\n" +
  "  \"company_invited_users\": [\n" +
  "    {\n" +
  "      \"user_email\": \"[email protected]\",\n" +
  "      \"user_id\": \"1776772304993x812345678901234567\",\n" +
  "      \"user_first_name\": \"Jane\",\n" +
  "      \"user_last_name\": \"Doe\",\n" +
  "      \"user_licenses\": [\n" +
  "        {\n" +
  "          \"type\": \"Life\",\n" +
  "          \"state\": \"TX\",\n" +
  "          \"active\": true\n" +
  "        }\n" +
  "      ],\n" +
  "      \"user_permission\": \"Admin\"\n" +
  "    }\n" +
  "  ]\n" +
  "}");

Request request = new Request.Builder()
  .url("https://app.whiteswan.io/api/1.1/wf/agency_onboard")
  .post(body)
  .addHeader("Authorization", "Bearer <YOUR_API_KEY>")
  .addHeader("Content-Type", "application/json")
  .addHeader("Accept", "application/json")
  .build();

Response response = client.newCall(request).execute();
System.out.println(response.body().string());

<?php

$payload = [
    "company_id" => "1776772304993x692932671527100400",
    "company_name" => "Acme Insurance Group",
    "company_type" => "Agency",
    "company_account_plan" => "Digital Agent Plan",
    "company_enabled_product_types" => ["Term Life"],
    "company_enabled_carriers" => ["John Hancock"],
    "company_invited_users" => [
        [
            "user_email" => "[email protected]",
            "user_id" => "1776772304993x812345678901234567",
            "user_first_name" => "Jane",
            "user_last_name" => "Doe",
            "user_licenses" => [
                [
                    "type" => "Life",
                    "state" => "TX",
                    "active" => true
                ]
            ],
            "user_permission" => "Admin"
        ]
    ]
];

$ch = curl_init("https://app.whiteswan.io/api/1.1/wf/agency_onboard");

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer <YOUR_API_KEY>",
    "Content-Type: application/json",
    "Accept: application/json"
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));

$response = curl_exec($ch);
curl_close($ch);

echo $response;

require "net/http"
require "uri"
require "json"

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

request = Net::HTTP::Post.new(uri.request_uri)
request["Authorization"] = "Bearer <YOUR_API_KEY>"
request["Content-Type"] = "application/json"
request["Accept"] = "application/json"

request.body = {
  company_id: "1776772304993x692932671527100400",
  company_name: "Acme Insurance Group",
  company_type: "Agency",
  company_account_plan: "Digital Agent Plan",
  company_enabled_product_types: ["Term Life"],
  company_enabled_carriers: ["John Hancock"],
  company_invited_users: [
    {
      user_email: "[email protected]",
      user_id: "1776772304993x812345678901234567",
      user_first_name: "Jane",
      user_last_name: "Doe",
      user_licenses: [
        {
          type: "Life",
          state: "TX",
          active: true
        }
      ],
      user_permission: "Admin"
    }
  ]
}.to_json

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

package main

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

func main() {
	url := "https://app.whiteswan.io/api/1.1/wf/agency_onboard"

	payload := []byte(`{
		"company_id": "1776772304993x692932671527100400",
		"company_name": "Acme Insurance Group",
		"company_type": "Agency",
		"company_account_plan": "Digital Agent Plan",
		"company_enabled_product_types": ["Term Life"],
		"company_enabled_carriers": ["John Hancock"],
		"company_invited_users": [
			{
				"user_email": "[email protected]",
				"user_id": "1776772304993x812345678901234567",
				"user_first_name": "Jane",
				"user_last_name": "Doe",
				"user_licenses": [
					{
						"type": "Life",
						"state": "TX",
						"active": true
					}
				],
				"user_permission": "Admin"
			}
		]
	}`)

	req, err := http.NewRequest("POST", url, bytes.NewBuffer(payload))
	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")

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

	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}

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.

Body Parameters Specification:

Field Label

Field Key

Field Type

Required

Example Value

Description

Alternatives (if Multiple-Choice)

Company External ID

company_id

Text

1813426016

Any ID you may have in your own systems to identify a certain company. This ID can later be queried in the API.

Company Logo

company_logo

File URL

https://assets.whiteswan.io/logos/acme-logo-light.png

A publicly accessible URL (eg. S3) containing the logo image of the company.

Company Darkmode Logo

company_darkmode_logo

File URL

https://assets.whiteswan.io/logos/acme-logo-light.png

A publicly accessible URL (eg. S3) containing the darkmode logo image of the company.

Company Name

company_name

Text

Acme

The name of the company.

Company Type

company_type

Multiple-Choice

Independent Life Insurance Agency/Brokerage

What type of company this is.

Independent Life Insurance Agency/Brokerage, Captive Life Insurance Agency/Brokerage, Broker-General-Agent (BGA), Independent Marketing Organization (IMO), Field Marketing Organization (FMO), Life Insurance Carrier, Registered Investment Advisor (RIA), Broker-Dealer (BD), Fintech Company, Mortgage Provider, Property & Casualty Insurance Provider, Legal Services Provider, Other

Company National Producer Number (NPN)

company_npn

Text

123456789

The national producer number (NPN) of the entity.

Company Legal Name

company_legal_name

Text

Acme Inc LLC

The legal name of the company.

Company Address

company_address

Text

123 Main St, City, State, Zip, Country

The address of the company.

Company Account Plan

company_account_plan

Multiple-Choice

Digital Agent Plan

The subscription type this company should have. The invited user will have to confirm this plan selection.

Digital Agent Plan, Concierge Plan, Innovator Plan

Company Scheduling Link

company_scheduling_link

Text

https://calendly.com/acme-insurance

The general scheduling link for the company.

Company Enabled Product Types

company_enabled_product_types

Text Array

["Term Life","Whole Life"]

The policy types that should be allowed for this company. If left empty the company will have the same allowed policy types as your company.

Term Life, Guaranteed Universal Life, Whole Life, Indexed Universal Life, Variable Universal Life, Private Placement Life, Final Expense, Linked Benefit, Long Term Care, Accidental Death

Company Enabled Carriers

company_enabled_carriers

Text Array

["John Hancock","Nationwide"]

The carriers that should be allowed for this company. If left empty the company will have the same allowed carriers as your company.

John Hancock, Nationwide, Life Insurance Company of the Southwest, Principal National Life Insurance, Transamerica, Corebridge Financial, Protective, Pacific Life - Lynchburg, Banner, Savings Bank Life Insurance, Lincoln National Life, Prudential Financial, North American, Assurity, American National, Principal Life Insurance Company, Allianz, National Western, John Hancock New York, William Penn, United of Omaha, Mutual of Omaha, U.S. Life, Nationwide New York, Prudential Life Insurance Company Of New Jersey (NY Only), Fidelity and Guaranty, Athene Annuity, Gerber, National Guardian Life, MassMutual Ascend, Protective New York, National Life Group, Thrivent, Global Atlantic, Guaranty Income life Insurance Company, American Equity, Equitrust, Revol One Insurance Company, Axonic, Symetra

Company Broker Dealer Legal Name

company_broker_dealer_legal_name

Text

Broker Dealer Inc

The legal name of the broker-dealer used by the company.

Company Broker Dealer Address

company_broker_dealer_address

Text

123 Main St, City, State, Zip, Country

The address of the broker-dealer used by the company.

Company Broker Dealer Website

company_broker_dealer_website

Text

https://brokerdealer.com

The website of the broker-dealer used by the company.

Company Broker Dealer Phone Number

company_broker_dealer_phone_number

Text

123-454-6789

The US phone number excluding country code of the broker-dealer used by the company

Company Invited User(s)

company_invited_users

Object Array

Each object defined below

An array of objects where each object represents an invited user to the new company account. At least one invitee has to be specified.

-Email

user_email

Text

Yes

[email protected]

Email of an invited person.

-External ID

user_id

DateTime

3683206808

An ID that you use to identify the invited person in your own system. This ID can later be used in API calls.

-National Producer Number (NPN)

user_npn

Text

12345678

The national producer number of an invited person.

-First Name

user_first_name

Text

John

The first name of an invited person.

-Last Name

user_last_name

Text

Doe

The last name of an invited person.

-Title

user_title

Text

CEO

The title of an invited person.

-Scheduling Link

user_scheduling_link

Text

https://calendly.com/john-doe

The scheduling link of an invited person.

-Phone number

user_phone_number

Text

123-455-6789

The US phone number excluding country code of an invited person.

-Profile Picture

user_profile_picture

Text

https://assets.whiteswan.io/logos/acme-logo-light.png

A publicly accessible URL pointing to a profile picture.

-User Permission

user_permission

Multiple-Choice

Admin

The permission level of the user - admin gives company wide access while agent limits access. If this user is the first user under this company, they will automatically be Admin, no matter what is specified here.

Admin, Agent

-User Licenses

user_licenses

Object List

An array of objects where each object represents one license. For each object, all parameters must be used.

--License Type

type

Multiple-Choice

Life

The type of license the invited person carries.

Life, Health, Securities, Property, Casualty

--License State

state

Multiple-Choice

The state in which the invited person carrier a license, expressed in a 2 letter abbreviation format.

AL, AK, AZ, AR, CA, CO, CT, DE, FL, GA, HI, ID, IL, IN, IA, KS, KY, LA, ME, MD, MA, MI, MN, MS, MO, MT, NE, NV, NH, NJ, NM, NY, NC, ND, OH, OK, OR, PA, RI, SC, SD, TN, TX, UT, VT, VA, WA, WV, WI, WY

--License is Active

active

Boolean

true

Whether the license is active.

Sample Return Payload

{
    "onboarding_link": "https://app.whiteswan.io/partner_invited_agency/1776780288105x468735435515101200?invited_agency=1776795336668x822717914476142700"
}

Returned Parameters Specification:

Field Name

Field Key

Field Type

Example Value

Description

Onboarding Link

onboarding_link

Text

https://app.whiteswan.io/partner_invited_agency/1776780288105x468735435515101200?invited_agency=1776795336668x822717914476142700

An onboarding link that can be used to onboard the new agency.

PreviousAdd Case Party NextInformation Calls

Last updated 3 days ago

Was this helpful?

hashtagHeaders

hashtagRequest Body

Headers

Request Body