# 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.

{% hint style="info" %}
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.
{% endhint %}

**API Method:**

<mark style="color:green;">`POST`</mark> `https://app.whiteswan.io/api/1.1/wf/agency_onboard`

Creates an agency onboarding link.

{% tabs %}
{% tab title="200: OK Call success" %}

{% endtab %}

{% tab title="400: Bad Request Call failure" %}

{% endtab %}

{% tab title="401: Unauthorized Permission denied" %}

{% endtab %}

{% tab title="404: Not Found Not found" %}

{% endtab %}

{% tab title="405: Method Not Allowed Wrong method" %}

{% endtab %}

{% tab title="429: Too Many Requests Too many requests" %}

{% endtab %}

{% tab title="500: Internal Server Error Internal bug" %}

{% endtab %}

{% tab title="503: Service Unavailable Service unavailable" %}

{% endtab %}
{% endtabs %}

#### Headers

| Name                                            | Type   | Description            |
| ----------------------------------------------- | ------ | ---------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer \<YOUR API KEY> |
| Content-Type<mark style="color:red;">\*</mark>  | String | application/json       |
| Accept<mark style="color:red;">\*</mark>        | String | application/json       |
| user-agent<mark style="color:red;">\*</mark>    | String | \<YOUR APP>            |

#### Request Body

| Name                                        | Type   | Description             |
| ------------------------------------------- | ------ | ----------------------- |
| JSON Body<mark style="color:red;">\*</mark> | Object | See specification below |

<details>

<summary>Sample Body Payload</summary>

```json
{
  "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": "jane.doe@acme.com",
      "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": "john.smith@acme.com",
      "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"
    }
  ]
}
```

</details>

{% hint style="info" %}
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.&#x20;
{% endhint %}

**Code Examples - Making the API Call:**

{% tabs %}
{% tab title="cURL" %}

```json
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": "jane.doe@acme.com",
        "user_id": "1776772304993x812345678901234567",
        "user_first_name": "Jane",
        "user_last_name": "Doe",
        "user_licenses": [
          {
            "type": "Life",
            "state": "TX",
            "active": true
          }
        ],
        "user_permission": "Admin"
      }
    ]
  }'
```

{% endtab %}

{% tab title="Python" %}

```python
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": "jane.doe@acme.com",
            "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())
```

{% endtab %}

{% tab title="Javascript" %}

```javascript
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: "jane.doe@acme.com",
        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));
```

{% endtab %}

{% tab title="Java" %}

```java
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\": \"jane.doe@acme.com\",\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());
```

{% endtab %}

{% tab title="PHP" %}

```php
<?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" => "jane.doe@acme.com",
            "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;
```

{% endtab %}

{% tab title="Ruby" %}

```ruby
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: "jane.doe@acme.com",
      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
```

{% endtab %}

{% tab title="Go" %}

```go
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": "jane.doe@acme.com",
				"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))
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
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.
{% endhint %}

***

**Body Parameters Specification:**

<table data-full-width="true"><thead><tr><th width="441">Field Label</th><th width="251">Field Key</th><th width="146">Field Type</th><th width="132">Required</th><th width="208">Example Value</th><th width="466">Description</th><th width="517">Alternatives (if Multiple-Choice)</th></tr></thead><tbody><tr><td>Company External ID</td><td>company_id</td><td>Text</td><td>No</td><td>1813426016</td><td>Any ID you may have in your own systems to identify a certain company. This ID can later be queried in the API.</td><td>-</td></tr><tr><td>Company Logo</td><td>company_logo</td><td>File URL</td><td>No</td><td><pre><code>https://assets.whiteswan.io/logos/acme-logo-light.png
</code></pre></td><td>A publicly accessible URL (eg. S3) containing the logo image of the company.</td><td>-</td></tr><tr><td>Company Darkmode Logo</td><td>company_darkmode_logo</td><td>File URL</td><td>No</td><td><pre><code>https://assets.whiteswan.io/logos/acme-logo-light.png
</code></pre></td><td>A publicly accessible URL (eg. S3) containing the darkmode logo image of the company.</td><td>-</td></tr><tr><td>Company Name</td><td>company_name</td><td>Text</td><td>No</td><td>Acme</td><td>The name of the company.</td><td>-</td></tr><tr><td>Company Type</td><td>company_type</td><td>Multiple-Choice</td><td>No</td><td>Independent Life Insurance Agency/Brokerage</td><td>What type of company this is.</td><td>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 &#x26; Casualty Insurance Provider, Legal Services Provider, Other</td></tr><tr><td>Company National Producer Number (NPN)</td><td>company_npn</td><td>Text</td><td>No</td><td>123456789</td><td>The national producer number (NPN) of the entity.</td><td>-</td></tr><tr><td>Company Legal Name</td><td>company_legal_name</td><td>Text</td><td>No</td><td>Acme Inc LLC</td><td>The legal name of the company.</td><td>-</td></tr><tr><td>Company Address</td><td>company_address</td><td>Text</td><td>No</td><td>123 Main St, City, State, Zip, Country</td><td>The address of the company.</td><td>-</td></tr><tr><td>Company Account Plan</td><td>company_account_plan</td><td>Multiple-Choice</td><td>No</td><td>Digital Agent Plan</td><td>The subscription type this company should have. The invited user will have to confirm this plan selection.</td><td>Digital Agent Plan, Concierge Plan, Innovator Plan</td></tr><tr><td>Company Scheduling Link</td><td>company_scheduling_link</td><td>Text</td><td>No</td><td>h<a href="https://calendly.com/acme-insurance">ttps://calendly.com/acme-insurance</a></td><td>The general scheduling link for the company.</td><td>-</td></tr><tr><td>Company Enabled Product Types</td><td>company_enabled_product_types</td><td>Text Array</td><td>No</td><td>["Term Life","Whole Life"]</td><td>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.</td><td>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</td></tr><tr><td>Company Enabled Carriers</td><td>company_enabled_carriers</td><td>Text Array</td><td>No</td><td>["John Hancock","Nationwide"]</td><td>The carriers that should be allowed for this company. If left empty the company will have the same allowed carriers as your company.</td><td>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</td></tr><tr><td>Company Broker Dealer Legal Name</td><td>company_broker_dealer_legal_name</td><td>Text</td><td>No</td><td>Broker Dealer Inc</td><td>The legal name of the broker-dealer used by the company.</td><td>-</td></tr><tr><td>Company Broker Dealer Address</td><td>company_broker_dealer_address</td><td>Text</td><td>No</td><td>123 Main St, City, State, Zip, Country</td><td>The address of the broker-dealer used by the company.</td><td>-</td></tr><tr><td>Company Broker Dealer Website</td><td>company_broker_dealer_website</td><td>Text</td><td>No</td><td>https://brokerdealer.com</td><td>The website of the broker-dealer used by the company.</td><td>-</td></tr><tr><td>Company Broker Dealer Phone Number</td><td>company_broker_dealer_phone_number</td><td>Text</td><td>No</td><td>123-454-6789</td><td>The US phone number excluding country code of the broker-dealer used by the company</td><td>-</td></tr><tr><td>Company Invited User(s)</td><td>company_invited_users</td><td>Object Array</td><td>No</td><td>Each object defined below</td><td>An array of objects where each object represents an invited user to the new company account. At least one invitee has to be specified.</td><td>-</td></tr><tr><td>-Email</td><td>user_email</td><td>Text</td><td>Yes</td><td>john@acme.com</td><td>Email of an invited person.</td><td>-</td></tr><tr><td>-External ID</td><td>user_id</td><td>DateTime</td><td>No</td><td>3683206808</td><td>An ID that you use to identify the invited person in your own system. This ID can later be used in API calls.</td><td>-</td></tr><tr><td>-National Producer Number (NPN)</td><td>user_npn</td><td>Text</td><td>No</td><td>12345678</td><td>The national producer number of an invited person.</td><td>-</td></tr><tr><td>-First Name</td><td>user_first_name</td><td>Text</td><td>No</td><td>John</td><td>The first name of an invited person.</td><td>-</td></tr><tr><td>-Last Name</td><td>user_last_name</td><td>Text</td><td>No</td><td>Doe</td><td>The last name of an invited person.</td><td>-</td></tr><tr><td>-Title</td><td>user_title</td><td>Text</td><td>No</td><td>CEO</td><td>The title of an invited person.</td><td>-</td></tr><tr><td>-Scheduling Link</td><td>user_scheduling_link</td><td>Text</td><td>No</td><td>h<a href="https://calendly.com/acme-insurance">ttps://calendly.com/</a>john-doe</td><td>The scheduling link of an invited person.</td><td>-</td></tr><tr><td>-Phone number</td><td>user_phone_number</td><td>Text</td><td>No</td><td>123-455-6789</td><td>The US phone number excluding country code of an invited person.</td><td>-</td></tr><tr><td>-Profile Picture</td><td>user_profile_picture</td><td>Text</td><td>No</td><td><pre><code>https://assets.whiteswan.io/logos/acme-logo-light.png
</code></pre></td><td>A publicly accessible URL pointing to a profile picture.</td><td>-</td></tr><tr><td>-User Permission</td><td>user_permission</td><td>Multiple-Choice</td><td>No</td><td>Admin</td><td>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.</td><td>Admin, Agent</td></tr><tr><td>-User Licenses</td><td>user_licenses</td><td>Object List</td><td>No</td><td>-</td><td>An array of objects where each object represents one license. For each object, all parameters must be used.</td><td>-</td></tr><tr><td>--License Type</td><td>type</td><td>Multiple-Choice</td><td>No</td><td>Life</td><td>The type of license the invited person carries.</td><td>Life, Health, Securities, Property, Casualty</td></tr><tr><td>--License State</td><td>state</td><td>Multiple-Choice</td><td>No</td><td>CA</td><td>The state in which the invited person carrier a license, expressed in a 2 letter abbreviation format.</td><td>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</td></tr><tr><td>--License is Active</td><td>active</td><td>Boolean</td><td>No</td><td>true</td><td>Whether the license is active.</td><td>-</td></tr></tbody></table>

***

<details>

<summary>Sample Return Payload</summary>

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

</details>

**Returned Parameters Specification:**

<table data-full-width="true"><thead><tr><th>Field Name</th><th>Field Key</th><th>Field Type</th><th>Example Value</th><th>Description</th></tr></thead><tbody><tr><td>Onboarding Link</td><td>onboarding_link</td><td>Text</td><td><pre><code>https://app.whiteswan.io/partner_invited_agency/1776780288105x468735435515101200?invited_agency=1776795336668x822717914476142700
</code></pre></td><td>An onboarding link that can be used to onboard the new agency.</td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.whiteswan.io/partner-knowledge-base/api-documentation/action-calls/onboard-agency.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.