> ## Documentation Index > Fetch the complete documentation index at: https://docs.goyappr.com/llms.txt > Use this file to discover all available pages before exploring further. # List sub-affiliates > The partners enrolled beneath you, and the tier-2 override you have earned through each. Driven from the referral graph rather than from revenue, so a partner enrolled yesterday with no customers yet is a row of zeros rather than a missing row. Required scope `affiliates:read`. Enrolment is an explicit act by Yappr — a customer who happens to share their own referral link never appears here, and their name and revenue are never disclosed to you. Most workspaces get an empty list. All amounts are integer US cents. `downline_revenue_cents` is the revenue base, not your commission; `my_override_cents` is what you earned on it, and `my_override_payable_cents` is the part past the hold window. The partners enrolled beneath you, and the second-tier override you have earned through each of them. Required scope: `affiliates:read`. Most workspaces get `{"data": []}` here. Sub-affiliates are part of a partner arrangement, not a self-serve feature — see [Who appears here](#who-appears-here). ## Scoping Like [`GET /affiliates/stats`](/api-reference/affiliates/stats), this endpoint always reports on the workspace that issued the API key. There is no company id parameter anywhere in the request, and supplying `company_id` returns `400`. There are no query parameters and no request body. ## Who appears here A row exists only for a partner Yappr has explicitly enrolled beneath you. Two consequences worth being clear about: * A customer who happens to share their own referral link does **not** become your sub-affiliate, does not appear in this list, and their customers' revenue is never disclosed to you. * A partner enrolled yesterday who has referred nobody yet **does** appear — as a row of zeros. The list is built from the referral graph, not from revenue, so "enrolled, nothing yet" is a visible state rather than an absent one. Do not treat a zero row as a bug or filter it out. Enrolment is also what starts the clock: you earn an override on a sub-affiliate's customers from the moment the referral is made, never retroactively on revenue those customers generated beforehand. ## Response fields Every row is one enrolled sub-affiliate. All amounts are integer **US cents** — divide by 100 for dollars. | Field | Type | Meaning | | --------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `company_id` | uuid | The sub-affiliate's workspace. | | `name` | string | Their company name. | | `ref_code` | string | Their own referral code — the code their customers signed up with. | | `customers` | integer | Paying customers they referred that generate an override for you. | | `downline_revenue_cents` | integer | Billed revenue those customers generated. This is the **base**, not your commission. | | `my_override_cents` | integer | Your tier-2 commission on `downline_revenue_cents`, at `override_rate_pct` from `GET /affiliates/stats`. | | `my_override_payable_cents` | integer | The part of `my_override_cents` that has aged past `hold_days` and is claimable now. | | `my_direct_cents` | integer | Your tier-1 commission on this partner's **own** spend with Yappr. They are your direct referral as well as your recruiter, and this column is that side of the relationship. | Your override does not come out of your sub-affiliate's commission. They earn their own full rate on their own customers; yours is paid on top by Yappr. `my_override_cents` and `my_override_payable_cents` differ for exactly the reason described under "Earned vs payable" on [Affiliate stats](/api-reference/affiliates/stats) — recent revenue is still inside the hold window and is not yet claimable. Summing `my_override_cents` across every row reconciles to `summary.override_earned_cents` on `GET /affiliates/stats`, and summing `my_direct_cents` gives the part of `summary.direct_earned_cents` that came from your sub-affiliates' own spend rather than from your ordinary customers. ## Example request ```bash theme={null} curl "https://api.goyappr.com/affiliates/downline" \ -H "Authorization: Bearer $YAPPR_API_KEY" ``` ## Example response ```json theme={null} { "data": [ { "company_id": "3f2a91c4-7d18-4e26-b053-9c1a5e8f0021", "name": "Bright Harbor Media", "ref_code": "EF56GH78", "customers": 1, "downline_revenue_cents": 40000, "my_override_cents": 1000, "my_override_payable_cents": 0, "my_direct_cents": 1200 }, { "company_id": "a25e1162-3c4d-4f88-9b01-1d5e7c2a0004", "name": "Meridian Growth Studio", "ref_code": "7C13B0AE", "customers": 0, "downline_revenue_cents": 0, "my_override_cents": 0, "my_override_payable_cents": 0, "my_direct_cents": 0 } ] } ``` The second row is a partner enrolled recently who has not referred anyone yet. That is the expected shape, not an empty result. ## Errors | HTTP | Code | When | | ---- | --------------------- | -------------------------------------------------- | | 400 | — | A `company_id` parameter was supplied. | | 401 | `INSUFFICIENT_SCOPE` | API key lacks `affiliates:read`. | | 401 | `INVALID_KEY` | Key not found, revoked, or expired. | | 403 | `AFFILIATE_FORBIDDEN` | Affiliate data is not readable for this workspace. | | 429 | `RATE_LIMIT` | 60 requests/minute exceeded. | | 500 | — | The figures could not be computed. Safe to retry. | ## OpenAPI ````yaml GET /affiliates/downline openapi: 3.1.0 info: title: Yappr API description: > Create and manage AI voice agents, purchase phone numbers, configure tools, and initiate calls — all via REST. version: 1.0.0 contact: url: https://goyappr.com servers: - url: https://api.goyappr.com description: Production security: - apiKey: [] paths: /affiliates/downline: get: tags: - Affiliates summary: List sub-affiliates description: > The partners enrolled beneath you, and the tier-2 override you have earned through each. Driven from the referral graph rather than from revenue, so a partner enrolled yesterday with no customers yet is a row of zeros rather than a missing row. Required scope `affiliates:read`. Enrolment is an explicit act by Yappr — a customer who happens to share their own referral link never appears here, and their name and revenue are never disclosed to you. Most workspaces get an empty list. All amounts are integer US cents. `downline_revenue_cents` is the revenue base, not your commission; `my_override_cents` is what you earned on it, and `my_override_payable_cents` is the part past the hold window. operationId: listAffiliateDownline responses: '200': description: Sub-affiliates content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/AffiliateDownlineRow' '400': description: A `company_id` parameter was supplied. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized, or the key is missing `affiliates:read`. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: >- `AFFILIATE_FORBIDDEN` — affiliate data is not readable for this workspace. content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: AffiliateDownlineRow: type: object description: > One enrolled sub-affiliate. Only partners deliberately enrolled by Yappr appear here — an ordinary customer who happens to share their own referral link does not. A freshly enrolled partner is a row of zeros, not an absent row. properties: company_id: type: string format: uuid name: type: string description: The sub-affiliate's company name. ref_code: type: string description: The sub-affiliate's own referral code. customers: type: integer description: >- Paying customers they have referred that generate an override for you. downline_revenue_cents: type: integer description: >- Billed revenue those customers generated, in US cents. This is the base your override is computed on, not your commission. my_override_cents: type: integer description: Your tier-2 commission earned through this partner. my_override_payable_cents: type: integer description: The part of `my_override_cents` past the hold window. my_direct_cents: type: integer description: >- Your tier-1 commission on this partner's *own* spend with Yappr — they are also your direct referral. Error: type: object properties: error: type: string code: type: string securitySchemes: apiKey: type: http scheme: bearer bearerFormat: API Key description: >- Your Yappr API key (e.g. `ypr_live_...`). Generate one in the dashboard under **Settings → API Keys**. ````