Skip to content
UpriverUpriverUpriver API Docs

Guides

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 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 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:

Terminal window
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.