> ## 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.

# Sponsor names and IDs

> Use sponsor names for discovery and canonical sponsor IDs for repeat requests and deduplication.

Sponsor names help you find a brand you already know. A `sponsor_id` identifies
the same sponsor across name variants and later API requests.

## Use the name to find the sponsor

[List sponsorships](/sponsorships/sponsorships) accepts `sponsor_name` as a
convenience filter. Names can vary in spelling, punctuation, and formatting,
so do not store the input string as the sponsor's durable identity.

[List sponsors](/sponsorships/sponsors) discovers sponsors by category or
publication rather than accepting a sponsor-name filter. It groups results by
sponsor name, so multiple results can represent the same brand.

## Store the returned sponsor ID

When a result contains `sponsor_id`, store it and use it for:

* Later sponsor-specific sponsorship searches.
* Sponsor profile and channel requests.
* Saved filters, watchlists, and downstream deduplication.

Two name-grouped sponsor results can share one `sponsor_id`. Treat those as the
same sponsor. The field can be absent when Upriver has not resolved a canonical
identity yet; continue using the name as a convenience until an ID is returned.

## Change an activity filter from name to ID

Do not change filters while following a page cursor. Process the pages you want
from the name-based request, then start the next request with its
`next_sync_token` and the returned `sponsor_id`:

```bash theme={null}
curl --get 'https://api.upriver.ai/v1/sponsorships' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --data-urlencode 'sponsor_id=br_01hzy8k9m4qp7v2wxr3d5abcde' \
  --data-urlencode 'platforms=youtube' \
  --data-urlencode 'since=2025-01-01' \
  --data-urlencode 'sync_token=ast1...'
```

This changes the filter at a polling boundary without repeating the previous
interval.