> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upriver.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Sponsorship types

> The classification fields on sponsorship placements - monetization_type, disclosure_tier, is_first_party, and the legacy sponsor_type.

The API classifies each sponsorship placement with these fields:

| Field                | Describes                                                                                                  |
| -------------------- | ---------------------------------------------------------------------------------------------------------- |
| `monetization_type`  | The deal's compensation structure: paid sponsorship, affiliate commission, or gifted product               |
| `disclosure_tier`    | How the relationship was identified: platform data, the creator's disclosure, a link or code, or inference |
| `is_first_party`     | Whether the creator promotes their own product or a third party's                                          |
| `partner_confidence` | The likelihood of a commercial relationship (0 to 1)                                                       |
| `sponsor_type`       | The legacy single-label category, kept for backward compatibility                                          |
| `evidence`           | The excerpt and source that support the placement (returned when `include_evidence=true`)                  |

A **placement** connects a sponsor, one piece of content, and one publication
(such as a creator account or newsletter). For coauthored content, the API can
return one placement for each participating publication, so several results can
point to the same post or video.

Upriver classifies each placement using the content, links, account
relationships, and platform signals available to it. `monetization_type` is a
best-effort inference about the likely arrangement, while `disclosure_tier`
describes the strongest relationship evidence observed. These fields may be
incomplete or incorrect and do not verify the terms of a private agreement,
whether or how compensation was exchanged, or whether a disclosure satisfied
applicable law.

<Tip>
  Prefer `monetization_type` and `disclosure_tier` for new integrations.
  `sponsor_type` is maintained for existing ones.
</Tip>

[`/v1/sponsorships`](/sponsorships/sponsorships) returns these fields on each
placement. Fields without a value are omitted (see
[Older and missing data](#older-and-missing-data)), and `evidence` is
returned only with `include_evidence=true`.
[`/v1/sponsors`](/sponsorships/sponsors) returns `monetization_type`,
`disclosure_tier`, and `sponsor_type` for only the sponsor's most recent
placement, under `most_recent_ad`.

## Filter by these fields

`/v1/sponsorships` accepts `sponsor_type`, `monetization_type`, and
`disclosure_tier` as filter parameters, each passed as one value or repeated
for several, plus the single-value `is_first_party`:

```text theme={null}
GET /v1/sponsorships?sponsor_name=Notion&monetization_type=affiliate
GET /v1/sponsorships?categories=fitness&disclosure_tier=platform_verified&disclosure_tier=creator_disclosed
```

* Filtering by `monetization_type` or `disclosure_tier` matches only placements
  where the field is populated. Older placements that predate these fields do
  not match.
* Requesting `disclosure_tier=inferred` returns inferred placements without
  also setting `include_inferred=true`.
* `is_first_party=true` returns placements promoting the creator's own
  product, service, or store, which are excluded by default.
* Filters combine with AND; a repeated parameter's values combine with OR.

## Where the fields diverge

A single label cannot cleanly describe both the likely deal and how the
relationship was identified; a creator may disclose an affiliate relationship
while a platform also marks the post as commercial content. The separate
fields matter most where they diverge. This placement has an Instagram
paid-partnership label that names the sponsor, but nothing identifies the deal
itself:

```json theme={null}
{
  "sponsor_type": "explicit_ad",
  "monetization_type": "unknown",
  "disclosure_tier": "platform_verified"
}
```

Platform data verifies the relationship, but the deal could be cash, gifted
product, or commission. The single `sponsor_type` value cannot make that
distinction.

Compare a creator who wrote "gifted by" in the caption of a haul post:

```json theme={null}
{
  "sponsor_type": "explicit_ad",
  "monetization_type": "gifted",
  "disclosure_tier": "creator_disclosed"
}
```

Both placements are `explicit_ad`, so `sponsor_type` alone cannot separate a
platform-verified partnership of unknown terms from a self-disclosed gift.

## Relationship confidence: `partner_confidence`

`partner_confidence` estimates the likelihood, from 0 to 1, that the creator
and sponsor have a commercial relationship. It does not estimate the
likelihood of any particular payment arrangement. The `confidence_threshold`
parameter (default 0.5) sets the minimum for returned placements; it is not
applicable to affiliate placements.

## Compensation structure: `monetization_type`

This field describes what the creator appears to receive from the arrangement.

| Value              | Meaning                                                                                                                            |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| `paid_partnership` | The available evidence points to a paid sponsorship. A generic platform disclosure label alone is not enough to assign this value. |
| `affiliate`        | The creator appears to earn commission from attributed purchases, sign-ups, or similar actions.                                    |
| `gifted`           | The creator appears to have received a product, service, access, or experience. This value does not imply a cash payment.          |
| `unknown`          | The post appears commercial, but the available evidence does not identify the deal type.                                           |

Some older placements may return `promotion`, `self_promotion`, or
`merch_store`. These values come from the legacy `sponsor_type` categories;
they are not new deal types.

## Relationship evidence: `disclosure_tier`

This field describes the strongest evidence that linked the creator to the
named sponsor.

| Value               | Meaning                                                                                                                                         |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `platform_verified` | Platform data identifies the creator and named sponsor as commercial partners. It does not say whether the deal was paid, affiliate, or gifted. |
| `creator_disclosed` | The creator's text or speech discloses the commercial relationship.                                                                             |
| `commercial_signal` | A link, code, or similar commercial cue connects the creator and sponsor, but no stronger disclosure was found.                                 |
| `inferred`          | The content suggests a commercial relationship, but no platform confirmation, creator disclosure, or direct commercial cue was found.           |

Placements with `disclosure_tier: inferred` are excluded by default. Set
`include_inferred=true` to include them alongside other tiers, or filter for
them directly with `disclosure_tier=inferred`. Use each result's
`partner_confidence` to apply your own threshold.

## First-party content: `is_first_party`

`is_first_party` is true when the placement promotes the creator's own
product, service, or store, false when a third-party sponsor was identified,
and omitted when the counterparty could not be determined. First-party
placements are excluded from results by default; filter with
`is_first_party=true` to retrieve them.

`monetization_type` describes payment by a third party, so it never carries a
real deal type on first-party placements: today those placements repeat the
legacy `self_promotion` or `merch_store` value there, and newer data omits the
field.

## Platform labels: Instagram and TikTok

Platform labels are useful evidence, but the same-looking label does not always
carry the same information.

<Tabs>
  <Tab title="Instagram">
    Instagram's **Paid partnership with *account*** label names a specific
    partner. Upriver can therefore return `platform_verified` for that
    creator-sponsor relationship.

    Instagram can use this label for several kinds of exchange, including cash,
    gifts, or affiliate commission. Unless other evidence identifies the deal,
    `monetization_type` remains `unknown`.

    A brand coauthor is not the same as a named paid-partnership relationship.
    Coauthorship can support the relationship, but does not make it
    `platform_verified` on its own.
  </Tab>

  <Tab title="TikTok">
    TikTok can display **Paid Partnership** without identifying the sponsor in
    the data available to Upriver. That label shows that the post was declared
    as commercial content, but it cannot by itself verify a relationship with a
    specific sponsor or establish `monetization_type: paid_partnership`.

    A structured **Creator earns commission** signal can support
    `monetization_type: affiliate`. A product or shop link shows commerce
    context, but does not by itself prove that the merchant compensated the
    creator.

    A promoted post or ad flag describes how the content was distributed. It
    does not by itself identify the creator's deal, disclosure, or sponsor.
  </Tab>
</Tabs>

`platform_verified` is an Upriver value, not the exact text shown in the app.
The API does not return the native label text in a separate field.

## Legacy field: `sponsor_type`

`sponsor_type` remains supported, with no scheduled removal date. On new
placements it stays consistent with the newer fields. The `explicit_ad` and
`implicit_ad` values combine ideas that the newer fields keep separate, so do
not treat their names as literal statements about payment or disclosure.

| Value                            | Meaning                                                                                                                                                                                        |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `explicit_ad`                    | The legacy broad category for a clearly presented sponsorship. It is also used for gifted content at any disclosure tier, so it does not prove cash payment or a platform-verified disclosure. |
| `implicit_ad`                    | The legacy broad category for content that appears commercial without a stronger disclosure signal. It does not mean Upriver determined that the creator hid an ad or broke a rule.            |
| `affiliate`                      | The available evidence points to an affiliate relationship. Use `disclosure_tier` to see how that relationship was identified.                                                                 |
| `promotion`                      | The content includes a promotion or call to action, often a code or discount. This does not by itself prove that the creator earns commission.                                                 |
| `self_promotion` / `merch_store` | The creator is promoting their own product, service, or store. These placements return `is_first_party: true`.                                                                                 |
| `unknown`                        | The available evidence does not support a more specific category.                                                                                                                              |

## Older and missing data

For some older placements, `monetization_type` and `disclosure_tier` were
translated from `sponsor_type` rather than determined separately. In those
records, the two newer fields repeat the same original signal; do not count them
as two independent pieces of evidence.

<Warning>
  Translated values are limited to what the legacy label recorded: `gifted` does
  not occur on those placements, `platform_verified` appears only where a
  platform label was recorded, and `paid_partnership` also covers deals that
  would be classified as gifted today. Comparisons that span mid-2026 mix this
  classification change with any real change in sponsorship activity; account
  for the transition before reading trends in these fields.
</Warning>

* An omitted field means it was not populated for that placement.
* `unknown` means the field was populated, but the available evidence did not
  support a more specific value.

It is valid for a placement to have `disclosure_tier: platform_verified` and
`monetization_type: unknown`. In that case, platform data identifies the named
commercial relationship, but the API cannot tell whether it was paid,
affiliate, gifted, or another arrangement.