# Payout(s)

This action retrieves information about Payouts associated with your White Swan account. A payout can consist of several [Commission Line Items](broken://pages/Q1QQvQwW63Yx6uN8iYQ5) and you can also capture downline payouts through the platform.

{% hint style="info" %}
Payout data is only available on the **Digital Agent Plan** and **Concierge Plan**. This endpoint will not return data for accounts on the **Innovator Plan**.
{% endhint %}

**API Method:**

## Fetch Payout(s)

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

Returns information about payouts associated with your White Swan account.

#### 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 | Used to query for specific payout event, not required. |

{% 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
{
  "direction": "Inbound Payout",
  "recipient_company_id": "1776772304993x692932671527100400",
  "recipient_company_external_id": "ext_company_12345",
  "recipient_user_email": "jane.doe@acme.com",
  "recipient_user_external_id": "ext_user_67890",
  "payor_company_name": "John Hancock",
  "payor_company_id": "1776772304993x781245903456120555",
  "payor_company_external_id": "ext_payor_54321",
  "case_id": "1776772304993x781245903456120145",
  "commission_line_item_id": "1776772304993x781245903456120001",
  "page": 1,
  "start_date": "2026-01-01T00:00:00Z",
  "end_date": "2026-12-31T23:59:59Z"
}
```

</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 (or any) parameters.
{% endhint %}

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

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

```json
curl -X POST "https://app.whiteswan.io/api/1.1/wf/payouts" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "direction": "Inbound Payout"
  }'
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

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

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

payload = {
    "direction": "Inbound Payout"
}

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/payouts", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <YOUR_API_KEY>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    direction: "Inbound Payout"
  })
})
  .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, "{ \"direction\": \"Inbound Payout\" }");

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

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

{% endtab %}

{% tab title="PHP" %}

```php
<?php

$payload = [
    "direction" => "Inbound Payout"
];

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

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"
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));

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

echo $response;
```

{% endtab %}

{% tab title="Ruby" %}

```ruby
package main

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

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

	payload := []byte(`{ "direction": "Inbound Payout" }`)

	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")

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

{% tab title="Go" %}

```go
package main

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

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

	payload := []byte(`{ "direction": "Inbound Payout" }`)

	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")

	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. 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>Direction</td><td>direction</td><td>Multiple-Choice</td><td>Inbound Payout</td><td>Used to filter by either "Inbound Payout" or "Outbound Payout"</td></tr><tr><td>Recipient Company White Swan ID</td><td>recipient_company_id</td><td>Text</td><td>5278025803x2957025790</td><td>Used to filter for a specific company by White Swan ID.</td></tr><tr><td>Recipient Company External ID</td><td>recipient_company_external_id</td><td>Text</td><td>12345678</td><td>Used to filter for a specific company by an external ID - this must be created upon agency signup through the <a href="/pages/kad5q4szePjSRsLVb0CA">Onboard Agency API call</a>.</td></tr><tr><td>Recipient User Email</td><td>recipient_user_email</td><td>Text</td><td>john@doe.com</td><td>Used to filter by payout recipient email.</td></tr><tr><td>Recipient User External ID</td><td>recipient_user_external_id</td><td>Text</td><td>12345678</td><td>Used to filter by payout recipient external ID - this must be created upon agency signup through the <a href="/pages/kad5q4szePjSRsLVb0CA">Onboard Agency API call</a>.</td></tr><tr><td>Payor Company Name</td><td>payor_company_name</td><td>Text</td><td>Backnine</td><td>Used to filter by payor company name.</td></tr><tr><td>Payor Company White Swan ID</td><td>payor_company_id</td><td>Text</td><td>5278025803x2957025790</td><td>Used to filter by payor company White Swan ID.</td></tr><tr><td>Payor Company External ID</td><td>payor_company_external_id</td><td>Text</td><td>1241241245</td><td>Used to filter by payor company external ID - this must be created upon agency signup through the <a href="/pages/kad5q4szePjSRsLVb0CA">Onboard Agency API call</a>.</td></tr><tr><td>Plan Request ID</td><td>case_id</td><td>Text</td><td>5278025803x2957025790</td><td>Used to filter by a payout associated plan request ID.</td></tr><tr><td>Commission Line Item ID</td><td>commission_line_item_id</td><td>Text</td><td>5278025803x2957025790</td><td>Used to filter by a payout associated commission line item ID.</td></tr><tr><td>Start Date</td><td>start_date</td><td>Date/Time in ISO 8601</td><td><pre><code>2026-12-31T23:59:59Z
</code></pre></td><td>Used to filter for payout events occurring after a certain date.</td></tr><tr><td>End Date</td><td>end_date</td><td>Date/Time in ISO 8601</td><td><pre><code>2026-12-31T23:59:59Z
</code></pre></td><td>Used to filter for payout events occurring before a certain date.</td></tr></tbody></table>

***

<details>

<summary>Sample Return Payload</summary>

<pre class="language-json"><code class="lang-json">{
  "payouts": [
<strong>    {
</strong>      "payout_id": "1776772304993x900000000000000001",
      "payout_external_id": "ext_payout_001",
      "direction": "Inbound Payout",
      "source_system": "BackNine",
      "amount": 1250.75,
      "payment_date": "2026-04-18T10:15:00Z",
      "payment_method": "ACH",
      "status": "Completed",
      "status_note": "Funds settled successfully",
      "recipient": {
        "type": "Agency",
        "id": "1776772304993x692932671527100400",
        "name": "Acme Insurance Group",
        "email": "payments@acme.com",
        "phone": "+1-512-555-1000",
        "address": {
          "street_address": "123 Main St",
          "city": "Austin",
          "state": "TX",
          "zip": "78701",
          "country": "US",
          "address_type": "Business"
        }
      },
      "payor": {
        "id": "1776772304993x900000000000000010",
        "name": "John Hancock",
        "email": "payments@jhancock.com",
        "phone": "+1-800-555-2000",
        "address": {
          "street_address": "200 Berkeley St",
          "city": "Boston",
          "state": "MA",
          "zip": "02116",
          "country": "US",
          "address_type": "Headquarters"
        }
      },
      "linked_commission_line_item_ids": [
        "1776772304993x900000000000000100",
        "1776772304993x900000000000000101"
      ],
      "linked_case_ids": [
        "1776772304993x900000000000000200"
      ]
    }
  ],
  "page": 1,
  "page_size": 1,
  "total": 1,
  "has_next_page": false
}
</code></pre>

</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></tr></thead><tbody><tr><td>Payouts</td><td>payouts</td><td>Object Array</td><td>See specification below.</td><td>An array of payout objects.</td></tr><tr><td>-Payout ID</td><td>payout_id</td><td>Text</td><td>1670721321811x149164079586738180</td><td>The amount credited for the earnings event.</td></tr><tr><td>-Payout External ID</td><td>payout_external_id</td><td>Text</td><td>123512364</td><td>The name of the client associated with the earnings event (only for Closed Case Events).</td></tr><tr><td>-Payout Direction</td><td>direction</td><td>Multiple-Choice</td><td>Inbound Payout</td><td>The email address of the client associated with the earnings event (only for Closed Case Events).</td></tr><tr><td>-Payout Source System</td><td>source_system</td><td>Text</td><td>Backnine</td><td>The ID of the plan request associated with the earnings event.</td></tr><tr><td>-Payout Amount</td><td>amount</td><td>Number</td><td>Acme Inc</td><td>The name of the partner associated with the earnings event (only for Referred Partner Earning Events).</td></tr><tr><td>-Payout Date</td><td>payment_date</td><td>Date/Time in ISO 8601</td><td>https://s3.amazonaws.com/appforest_uf/f167656056312330177020/Crediting%20Invoice%20.docx</td><td>A link to the credit invoice for the earnings event (only for Paid Compensation Events)</td></tr><tr><td>-Payout Method</td><td>payment_method</td><td>Text</td><td>Axel Doe</td><td>The name of the account user associated with the earnings event.</td></tr><tr><td>-Payout Status</td><td>status</td><td>Text</td><td>Paid via ACH</td><td>The current status of the payout.</td></tr><tr><td>-Payout Note</td><td>status_note</td><td>Text</td><td>Updated to new checking account.</td><td>A note to the payout.</td></tr><tr><td>-Payout Recipient</td><td>recipient</td><td>Object</td><td>See below</td><td>The recipient of the payment.</td></tr><tr><td>--Payout Recipient Type</td><td>type</td><td>Multiple-Choice</td><td>Agent</td><td>Either Agent or Agency.</td></tr><tr><td>--Payout Recipient ID</td><td>id</td><td>Text</td><td>280512805x85025802580</td><td>The ID of the payout recipient.</td></tr><tr><td>--Payout Recipient Name</td><td>name</td><td>Text</td><td>John Doe</td><td>The name of the payout recipient.</td></tr><tr><td>--Payout Recipient Email</td><td>email</td><td>Text</td><td>john@doe.com</td><td>The email of the payout recipient.</td></tr><tr><td>--Payout Recipient Phone</td><td>phone</td><td>Text</td><td>312-52-2158</td><td>The phone of the payout recipient.</td></tr><tr><td>--Payout Recipient Address</td><td>address</td><td>Object</td><td>See below</td><td>The address of the payout recipient.</td></tr><tr><td>---Payout Recipient Address Street</td><td>street_address</td><td>Text</td><td>12 Longstreet</td><td>The street address.</td></tr><tr><td>---Payout Recipient Address City</td><td>city</td><td>Text</td><td>Monkton</td><td>The city.</td></tr><tr><td>---Payout Recipient Address State</td><td>state</td><td>Text</td><td>CA</td><td>The state.</td></tr><tr><td>---Payout Recipient Address Zip</td><td>zip</td><td>Text</td><td>28750</td><td>The zip.</td></tr><tr><td>---Payout Recipient Address Country</td><td>country</td><td>Text</td><td>United States</td><td>The country.</td></tr><tr><td>---Payout Recipient Address Type</td><td>address_type</td><td>Text</td><td>Business address</td><td>The address type.</td></tr><tr><td>-Payor </td><td>payor</td><td>Object</td><td>See below.</td><td>The payor of this Payout.</td></tr><tr><td>--Payor ID</td><td>id</td><td>Text</td><td>280512805x85025802580</td><td>The ID of the payor of this payout.</td></tr><tr><td>--Payor Name</td><td>name</td><td>Text</td><td>Backnine Insurance</td><td>The company name of the payor of this payout.</td></tr><tr><td>--Payor Email</td><td>email</td><td>Text</td><td>billing@acme.com</td><td>The email address of the payor of this payout.</td></tr><tr><td>--Payor Phone</td><td>phone</td><td>Text</td><td>312-52-2158</td><td>The phone number of the payor of this payout.</td></tr><tr><td>--Payor Address</td><td>address</td><td>Object</td><td>See below.</td><td>The address of the payor of this payout.</td></tr><tr><td>---Payor Address Street</td><td>street_address</td><td>Text</td><td>12 Longstreet</td><td>The street address.</td></tr><tr><td>---Payor Address City</td><td>city</td><td>Text</td><td>Monkton</td><td>The city.</td></tr><tr><td>---Payor Address State</td><td>state</td><td>Text</td><td>CA</td><td>The state.</td></tr><tr><td>---Payor Address Zip</td><td>zip</td><td>Text</td><td>78231</td><td>The zip code.</td></tr><tr><td>---Payor Address Country</td><td>country</td><td>Text</td><td>United States</td><td>The country.</td></tr><tr><td>---Payor Address Type</td><td>address_type</td><td>Text</td><td>Business Address</td><td>The address type.</td></tr><tr><td>-Linked Commission Line Items IDs</td><td>linked_commission_line_item_its</td><td>Text Array</td><td>["218502580x28502580","1802582501x2580128"]</td><td>The IDs of the commission line items associated with this payout.</td></tr><tr><td>-Linked Plan Request IDs</td><td>linked_case_ids</td><td>Text Array</td><td>["218502580x28502580","1802582501x2580128"]</td><td>The IDs of the plan requests associated with this payout.</td></tr><tr><td>Page Number</td><td>page</td><td>Number</td><td>1</td><td>The currently viewed page of payouts. Use the payout parameter to change page.</td></tr><tr><td>Count Shown on Page</td><td>page_size</td><td>Number</td><td>50</td><td>The current number of payouts shown in the payout array.</td></tr><tr><td>Total Payout Count</td><td>total</td><td>Number</td><td>100</td><td>The total number of payouts available based on the query.</td></tr><tr><td>Next Page Available</td><td>has_next_page</td><td>Boolean</td><td>true</td><td>Whether another page of entries exists after the current page.</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/payout-s.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.