# Policy Search

The policy search endpoint can be used to fetch quotes when you're requesting full quotes through the [Submit Complete Plan Request](/partner-knowledge-base/api-documentation/action-calls/submit-complete-plan-request.md). After calling the complete plan request endpoint with a valid body to get quotes, a policy search ID will be returned which you can use to poll the Policy Search endpoint and get access to data like status, quotes, and errors.

**API Method:**

## Policy Search

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

Returns information about a policy search.

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

{% 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 %}

<details>

<summary>Sample Body Payload</summary>

```json
{
"policy_search":"1755962938878x653642511385623700"
}
```

</details>

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

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

```json
curl -X POST "https://app.whiteswan.io/api/1.1/wf/policy_search" \
     -H "Authorization: Bearer <YOUR API KEY>" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "User-Agent: <YOUR APP>" \
     -d '{
               "policy_search": "1755962938878x653642511385623700"
          }'
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://app.whiteswan.io/api/1.1/wf/policy_search"
headers = {
    "Authorization": "Bearer <YOUR API KEY>",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "User-Agent": "<YOUR APP>"
}

data = {
    "policy_search": "1755962938878x653642511385623700"
}

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

{% endtab %}

{% tab title="Javascript" %}

```javascript
const url = "https://app.whiteswan.io/api/1.1/wf/policy_search";
const headers = {
    "Authorization": "Bearer <YOUR API KEY>",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "user-agent": "<YOUR APP>"
};
const data = {
    "policy_search": "1755962938878x653642511385623700"
};

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));
```

{% endtab %}

{% tab title="Java" %}

```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, "{\"policy_search\":\"1755962938878x653642511385623700\"}");

        Request request = new Request.Builder()
            .url("https://app.whiteswan.io/api/1.1/wf/policy_search")
            .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();
        }
    }
}
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php

$ch = curl_init();

$data = array(
    "policy_search" => "1755962938878x653642511385623700"
);

$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/policy_search");
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);
?>
```

{% endtab %}

{% tab title="Ruby" %}

```ruby
require 'net/http'
require 'json'
require 'uri'

uri = URI.parse("https://app.whiteswan.io/api/1.1/wf/policy_search")
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 = {
    policy_search: "1755962938878x653642511385623700"
}

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

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

{% endtab %}

{% tab title="Go" %}

```go
package main

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

func main() {
	url := "https://app.whiteswan.io/api/1.1/wf/policy_search"
	data := `{
    			"policy_search" : "1755962938878x653642511385623700"
		}`

	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)
}
```

{% 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. 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>Field Label</th><th>Field Key</th><th>Field Type</th><th>Example Value</th><th>Description</th></tr></thead><tbody><tr><td>Policy Search</td><td>policy_search</td><td>Text</td><td>1755962938878x653642511385623700</td><td>The ID of the policy search to poll.</td></tr></tbody></table>

***

<details>

<summary>Sample Return Payload</summary>

```json
{
    "policy_search_id": "1755962938878x653642511385623700",
    "status": "Found Policies",
    "linked_plan_request": "1755962937306x171818994560791740",
    "policy_type": "Term Life",
    "goal": "Protection",
    "death_benefit": 1000000,
    "premium_budget": null,
    "policies": [
        {
            "personal_plan_url": "https://app.whiteswan.io/personal_plan/john-doe-16",
            "client_name": "John Doe",
            "client_email": "john@whiteswan.io",
            "client_phone": "123456789",
            "intended_owner": "John Doe",
            "intended_insured": "John Doe",
            "expiration_date": "2025-08-24T15:29:00.816Z",
            "servicing_agent": {
                "name": "Jane Smith",
                "email": "jane@smith.com",
                "phone": "123 435 9610",
                "meeting_link": "https://meet.com"
            },
            "personal_message": "Hi John! I'm Jane, and I'm here to help you through the process of getting a plan that suits your needs. While this quote has been automatically generated, I can find you a custom quote or answer any of your questions if you schedule a time with me or request a custom quote below.",
            "started_applied_for": false,
            "insurer": {
                "name": "North American",
                "logo": "//762d0145e332a78fcb6f9b9f529c26ab.cdn.bubble.io/f1715082967264x994153174517765200/north_american_reduced_size_square%20%281%29%201.svg",
                "am_best_rating": "A+",
                "established_year": 1886
            },
            "product": {
                "name": "ADDvantage 20 (guar 20)",
                "guaranteed_issue": false,
                "instant_decision_underwriting": false,
                "dual_insureds": false,
                "average_approval_time": "44 Days",
                "e_delivery": true,
                "binder_premium_payment_required": false,
                "convertible_to_permanent": true,
                "conversion_details": "To any permanent product throughout the level term period or through age 70, whichever is earlier. However, the conversion period is never less than five years, regardless of issue age!",
                "disclosure": "",
                "consumer_guide": "",
                "agent_guide": "",
                "underwriting_guide": ""
            },
            "illustration_pdf": "",
            "prospectus_pdf": null,
            "term_length": "20 Years",
            "term_length_numerical": 20,
            "assumed_annual_return": null,
            "initial_death_benefit": 1000000,
            "premium_modality": "Monthly",
            "recurring_premium": 110,
            "one_time_deposit": 0,
            "policy_type": "Term Life",
            "main_goal": "Protection",
            "health_rating": "Super Preferred",
            "annual_retirement_income": null,
            "total_retirement_income": null,
            "years_of_retirement_income": null,
            "annual_target_premium": null,
            "annual_total_premium": 1320,
            "paid_up_period": "20 Years",
            "paid_up_period_numerical": 20,
            "guaranteed_projected_cash_values": null,
            "non_guaranteed_projected_cash_values": null,
            "projected_death_benefits": null,
            "future_cash_values_irr": null,
            "future_death_benefits_irr": null,
            "riders": [],
            "allocation_accounts": [],
            "monthly_ltc_benefit": null,
            "ltc_pool_of_money": null,
            "ltc_elimination_period": null,
            "ltc_benefit_limit": null,
            "shared_care_rider": false,
            "joint_waiver_of_premium": false,
            "home_health_care_rider": false,
            "ltc_discounts": [
                "No Employer/Association Discount",
                "Partner/Spouse Discount"
            ],
            "conversion_privilege_expiration_date": null,
            "medical_exam_required_underwriting": "Exam Is Required",
            "medical_exam_details": "requires a complimentary exam. In a few steps you'll schedule your exam at a time and place convenient for you.",
            "plan_id": "1755962955969x276667317413269220",
            "associated_request_id": "1755962937306x171818994560791740"
        }
    ],
    "error_message": ""
}
```

</details>

**Returned Parameters Specification:**

<table data-full-width="true"><thead><tr><th>Field Label</th><th>Field Key</th><th>Field Type</th><th>Example Value</th><th>Description</th><th>Alternatives (if Multiple-Choice)</th></tr></thead><tbody><tr><td>Policy Search ID</td><td>policy_search_id</td><td>Text</td><td>1755962938878x653642511385623700</td><td>The ID of the policy search that is being polled.</td><td>-</td></tr><tr><td>Status</td><td>status</td><td>Multiple-Choice</td><td>Found Policies</td><td>The current status of the policy search.</td><td>Found Policies, Fetching Quotes, No Policies Found</td></tr><tr><td>Linked Plan Request ID</td><td>linked_plan_request</td><td>Text</td><td>1755962937306x171818994560791740</td><td>The ID of the plan request that is associated with this policy search.</td><td>-</td></tr><tr><td>Policy Type</td><td>policy_type</td><td>Multiple-choice</td><td>Term Life</td><td>The policy type associated with this policy search.</td><td>Term Life, Return of Premium 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>Goal</td><td>goal</td><td>Multiple-choice</td><td>Protection</td><td>The goal of this policy search.</td><td>Protection, Balanced, Accumulation</td></tr><tr><td>Death Benefit</td><td>death_benefit</td><td>Number</td><td>1000000</td><td>The amount of death benefit sought after in this policy search.</td><td>-</td></tr><tr><td>Premium Budget</td><td>premium_budget</td><td>Number</td><td>1000</td><td>The target premium budget associated with this policy search.</td><td>-</td></tr><tr><td>Policies</td><td>policies</td><td><a href="/pages/IMHlzpl1wVDVq3IPIuiv">Personal Plan</a> Object List</td><td>-</td><td>A list of the policies found for this policy search. See full data structure of policy objects on the <a href="/pages/IMHlzpl1wVDVq3IPIuiv">Personal Plan page</a>. </td><td>-</td></tr><tr><td>Error Message</td><td>error_message</td><td>Text</td><td>-</td><td>If we had any errors with finding policies based on the input for this policy search, you can access details here.</td><td>-</td></tr><tr><td>URL To View Quotes</td><td>policies_view_url</td><td>Text</td><td>https://app.whiteswan.io/get_started/1756132114502x277128707509505020?policy_search=1756132116084x494781508118696400&#x26;request=1756132113128x587035433367457300&#x26;block=s</td><td>A URL where the list of policies, if any, can be viewed.</td><td>-</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/information-calls/policy-search.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.