Downline(s)

Use this endpoint to retrieve information about the agencies and agents you have onboarded as downlines. You can filter results by company/user and page through large lists. Each downline record includes the agency's profile, subscription details, linked cases and users, and a full history of terms accepted during onboarding.

Agencies appear in your downlines when they are onboarded through the Onboard Agency endpoint. As the upline, you have the ability to configure certain account settings for your downline agencies.

API Method

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

Returns a paginated list of your downline agencies and agents, optionally filtered by the query parameters below.

Headers

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

Query Parameters

All query parameters are optional.

Parameter	Type	Description
company_id	Text	Filter by White Swan company ID.
company_external_id	Text	Filter by your internal company ID. This ID must be defined when you Onboard Agency.
user_email	Text	Filter by a user's email address.
user_external_id	Text	Filter by your internal user ID. This ID must be defined when you Onboard Agency.
page	Integer	Page number for paginated results.

Sample Body Payload

{
  "company_id": "1776772304993x692932671527100400",
  "company_external_id": "ext_company_12345",
  "user_email": "[email protected]",
  "user_external_id": "ext_user_158015",
  "page": 1
}

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.

Pagination

Responses are paginated. Use the page query parameter to navigate through results. The response always includes the following pagination fields:

Field	Type	Description
page	Integer	Current page number.
page_size	Integer	Number of downline records returned on this page.
total	Integer	Total count of downlines matching your filters.
has_next_page	Boolean	Whether a subsequent page of results exists.

Response Codes

Code	Description
200 OK	Call succeeded
400 Bad Request	Call failure
401 Unauthorized	Permission denied
429 Too Many Requests	Rate limit exceeded
500 Internal Server Error	Internal error

Sample return payload

{
  "downlines": [
    {
      "company_id": "1776772304993x692932671527100400",
      "company_name": "Acme Insurance Group",
      "company_address": "123 Main St, Austin, TX 78701, USA",
      "company_legal_name": "Acme Insurance Group LLC",
      "company_subscription": "Digital Agent",
      "company_allowed_policy_types": [
        "Term Life",
        "Whole Life"
      ],
      "company_allowed_carriers": [
        "John Hancock",
        "Nationwide"
      ],
      "company_upline": "Premier Brokerage Network",
      "linked_case_ids": [
        "1776772304993x900000000000000201",
        "1776772304993x900000000000000202"
      ],
      "linked_user_emails": [
        "[email protected]",
        "[email protected]"
      ],
      "linked_payments": [
        "1776772304993x900000000000000301"
      ],
      "has_completed_onboarding": true,
      "linked_terms": [
        {
          "acceptance_id": "1776772304993x900000000000000401",
          "accepted": true,
          "accepted_date": "2026-03-10T12:15:00Z",
          "consent_text_shown": "I agree to the White Swan Partner Agreement",
          "consenting_user_email": "[email protected]",
          "accepted_contract": "https://app.whiteswan.io/contracts/partner-agreement-v2.pdf",
          "contract_type": "Partner Agreement",
          "acceptance_url": "https://app.whiteswan.io/onboard/terms"
        }
      ]
    }
  ],
  "page": 1,
  "page_size": 1,
  "total": 1,
  "has_next_page": false
}

Response Fields

The response returns a downlines array alongside pagination fields. Each downline object has the following shape:

Field	Type	Description
company_id	Text	White Swan company ID.
company_external_id	Text	The external ID of the company, if used with the Onboard Agency call.
company_name	Text	Company display name.
company_address	Text	Company address.
company_legal_name	Text	Company legal name.
company_subscription	Text	Active subscription — either Digital Agent Plan , Innovator Plan, or Concierge Plan.
company_allowed_policy_types	Text Array	Enabled product types for this company — see enum in Onboard Agency.
carrier_restrictions	Text Array	Enabled carriers for this company — see options in Onboard Agency. If this list is empty all carriers are allowed.
company_upline	Text	Name of the upline account for this company.
linked_case_ids	Text Array	IDs of cases associated with this company.
linked_user_emails	Text Array	Email addresses of users linked to this company.
linked_payments	Text Array	IDs of payouts linked to this company.
has_completed_onboarding	Boolean	Whether the agency has completed the onboarding flow.
linked_terms	Object	Record of terms accepted during onboarding — see terms object below.

Terms Object (linked_terms)

Field	Type	Description
acceptance_id	Text	ID of this acceptance record.
accepted	Boolean	Whether the terms were accepted.
accepted_date	Text	Date of acceptance (ISO 8601).
consent_text_shown	Text	The text displayed next to the acceptance checkbox.
consenting_user_email	Text	Email of the user who accepted the terms.
accepted_contract	Text	URL to the accepted contract document.
contract_type	Text	Type of contract.
acceptance_url	Text	URL where the user accepted the terms.