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

# Spotify Integration

> Fanaura uses the Spotify Search API for artist onboarding and metadata lookup. Pre-saves use Fanaura's native notification system — no Spotify OAuth required.

Fanaura integrates with Spotify in a **read-only** capacity: artist search during onboarding and track/album metadata lookup when creating music assets. Fanaura does **not** use Spotify OAuth for pre-saves or library modifications.

## What This Integration Does

* **Artist search (onboarding)**: When an artist signs up, they search for their Spotify artist profile to connect their identity.
* **Track metadata lookup**: When creating a music asset, Fanaura searches the Spotify catalog to auto-fill song title, artist name, artwork, ISRC, and release date.
* **Artist tracks**: The favorite song picker during fan onboarding pulls an artist's top tracks from Spotify.

## What This Integration Does NOT Do

* **No library saves** — Fanaura does not save tracks to fans' Spotify libraries
* **No OAuth from fans** — Fans never authorize Spotify access through Fanaura
* **No OAuth from artists** — Artists do not connect their Spotify for Artists account

<Info>
  Pre-saves in Fanaura use a **native notification system** instead of Spotify OAuth. See the "How Pre-Saves Actually Work" section below.
</Info>

## How Pre-Saves Actually Work

Fanaura deliberately chose **not** to implement traditional OAuth-based pre-saves (where a song is silently added to a fan's Spotify library). Instead, Fanaura uses a native notification system that is platform-independent and drives higher engagement.

**Why not OAuth pre-saves?**

* Spotify requires 250,000 monthly active users for extended API access — an insurmountable barrier for any pre-revenue startup
* Other platforms (Amazon Music, Deezer) have similar restrictions or closed developer registration entirely
* A song silently added to a library generates no engagement moment — fans may never notice it

**How Fanaura's native pre-saves work:**

<Steps>
  <Step title="Fan Visits Smart Link">
    Fan visits the artist's smart link or pre-save page.
  </Step>

  <Step title="Fan Authenticates">
    Fan signs in with Fanaura (phone or email OTP). No Spotify login required.
  </Step>

  <Step title="Fan Selects Platform">
    Fan picks their preferred streaming platform (Spotify, Apple Music, YouTube Music, etc.).
  </Step>

  <Step title="Pre-Save Recorded">
    Fanaura records the pre-save internally and awards fan reward points.
  </Step>

  <Step title="Release Day Notification">
    On release day, Fanaura sends the fan a direct message (email or SMS) with a link to stream on their chosen platform.
  </Step>

  <Step title="Fan Streams">
    Fan clicks the link, which opens directly in their streaming app. The song starts playing immediately.
  </Step>
</Steps>

This approach creates an **active engagement moment** rather than a passive library addition, and works across every streaming platform — not just those with open APIs.

## Artist Search and Metadata

When you create a new music asset in Fanaura:

<Steps>
  <Step title="Search">
    You enter the song title or artist name.
  </Step>

  <Step title="Results">
    Fanaura searches the Spotify catalog using the Spotify Search API. Matching results appear with artwork, title, artist, and album.
  </Step>

  <Step title="Auto-Fill">
    Select the correct match and metadata auto-fills into your asset.
  </Step>
</Steps>

### What Metadata Gets Imported

| Field              | Source                            |
| ------------------ | --------------------------------- |
| Song title         | Spotify catalog                   |
| Artist name(s)     | Spotify catalog                   |
| Album/single title | Spotify catalog                   |
| Artwork            | Spotify catalog (high-resolution) |
| Release date       | Spotify catalog                   |
| ISRC               | Spotify catalog                   |
| Spotify URI        | Generated from match              |

## No Artist Spotify Account Required

<Info>
  You do not need to connect your Spotify for Artists account to Fanaura. Metadata uses the public catalog. Fans use their own streaming apps — Fanaura just facilitates the connection through direct links, not library access.
</Info>

## Setup

Spotify search integration is configured at the platform level by Fanaura. There is no per-artist setup required.

### For Your Team to Know

* No API keys to enter.
* No OAuth to authorize from your end.
* Artist search and metadata lookup work automatically.

## Spotify API Endpoints Used

| Endpoint                          | Purpose                                |
| --------------------------------- | -------------------------------------- |
| `GET /v1/search?type=artist`      | Artist search during onboarding        |
| `GET /v1/search?type=track`       | Track metadata lookup                  |
| `GET /v1/artists/{id}/top-tracks` | Favorite song picker in fan onboarding |
| `GET /v1/artists/{id}/albums`     | Artist discography lookup              |
| `GET /v1/albums?ids=`             | Album track listings                   |

All endpoints use Spotify's **Client Credentials** flow (app-level access) — no user OAuth tokens are involved.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Artist not found during onboarding">
    * Ensure the artist name is spelled correctly. The search is fuzzy but works best with exact names.
    * Very new or very small artists may not appear in Spotify's catalog yet.
  </Accordion>

  <Accordion title="Metadata not auto-filling">
    * Check that the song exists on Spotify. Unreleased songs won't appear in search results.
    * Try searching by ISRC if the title search returns too many results.
  </Accordion>

  <Accordion title="Pre-save notification not received">
    * This is handled by Fanaura's native notification system, not Spotify. Check the fan's email/SMS delivery status in the activity logs.
  </Accordion>
</AccordionGroup>