# 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. {% hint style="info" %} Agencies appear in your downlines when they are onboarded through the [Onboard Agency](/partner-knowledge-base/api-documentation/action-calls/onboard-agency.md) endpoint. As the upline, you have the ability to configure certain account settings for your downline agencies. {% endhint %} ## API Method {% hint style="success" %} **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. {% endhint %} ### Headers | Name | Type | Description | | --------------- | ---- | ---------------------- | | Authorization\* | Text | Bearer \ | | Content-Type\* | Text | application/json | | Accept\* | Text | application/json | | user-agent\* | Text | \ | ### 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](/partner-knowledge-base/api-documentation/action-calls/onboard-agency.md). | | 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](/partner-knowledge-base/api-documentation/action-calls/onboard-agency.md). | | page | Integer | Page number for paginated results. |
Sample Body Payload {% code overflow="wrap" %} ```json { "company_id": "1776772304993x692932671527100400", "company_external_id": "ext_company_12345", "user_email": "jane.doe@acme.com", "user_external_id": "ext_user_158015", "page": 1 } ``` {% endcode %}
{% 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 %} ### 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 {% code overflow="wrap" %} ```json { "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": [ "jane.doe@acme.com", "admin@acme.com" ], "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": "jane.doe@acme.com", "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 } ``` {% endcode %}
### 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](/partner-knowledge-base/api-documentation/action-calls/onboard-agency.md) 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](/partner-knowledge-base/api-documentation/action-calls/onboard-agency.md). | | carrier\_restrictions | Text Array | Enabled carriers for this company — see options in [Onboard Agency](/partner-knowledge-base/api-documentation/action-calls/onboard-agency.md). 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. | --- # 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/downline-s.md?ask= ``` 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.