Skip to content
Fandation API Documentation

Policy document journey

Use this guide when your product needs to help a user find or create an artist’s privacy policy, then use Fandation’s current public document data in your product.

The journey has two distinct parts. Your frontend sends the user to Artist Policy Finder. Your backend uses the Public Documents API when it needs current structured data. Keep the API key on your backend throughout the flow.

Choose your path

Section titled “Choose your path”
Your goal Start with API key needed
Let a user find or create a privacy policy in Fandation Artist Policy Finder No
Retrieve current data for the document a user selected This journey, then exact document lookup Yes, on your backend
Retrieve an artist’s current privacy-policy URL and public documents Artist lookup in the Public Documents API Yes, on your backend

If you need either backend API path, first complete partner onboarding to receive an environment-specific API key.

flowchart LR
    product[Partner product]
    cta[Get Privacy Policy]
    finder[Artist Policy Finder]
    selection[User selects or creates a policy]
    hosted[Hosted Fandation document URL]
    backend[Partner backend]
    api[Public Documents API]

    product --> cta --> finder --> selection --> hosted --> backend --> api

The user journey

Section titled “The user journey”
  1. Start with the artist context you already have, such as a Spotify artist ID, artist name, preferred language, and your Fandation source value.
  2. In your frontend, present a Get Privacy Policy CTA that opens Artist Policy Finder. This browser handoff does not require an API key.
  3. Fandation signs the user in when needed. If a published policy already exists, Fandation displays it. Otherwise, the user can add the artist and complete the guided policy setup.
  4. The user copies the hosted Fandation document link and returns it to your product.
  5. Send that hosted URL to your backend when you need current structured data. Extract its publicDocumentId from /docs/{publicDocumentId} and use exact document lookup.
  6. Use the returned hosted URLs as legal links. Use disclosure HTML, text, or Markdown only when a disclosure is present.

Do not embed Artist Policy Finder. Do not call the Public Documents API from a browser, mobile app, or other client-side code.

Send the user to Artist Policy Finder

Section titled “Send the user to Artist Policy Finder”

Build the URL in your frontend. Use the artist context available in your product.

https://app.fandation.com/artist-policy-finder?artistPlatform=spotify&artistPlatformId=5me0Irg2ANcsgc93uaYrpb&artistName=The%20Notorious%20B.I.G.&documentType=privacy_policy&languageCode=en&source=partner-name

Use artistPlatform=spotify and artistPlatformId together when you know the artist’s Spotify ID. If you do not have that ID, provide artistName or use the generic Artist Policy Finder URL instead.

See Artist Policy Finder for all supported link parameters and examples.

Retrieve the selected document on your backend

Section titled “Retrieve the selected document on your backend”

After the user returns with a hosted Fandation document URL, call exact lookup from your backend.

GET /api/v1/documents/{publicDocumentId}?languageCode=en
Authorization: Bearer YOUR_API_KEY

This returns the current public resource data for the selected document, including its hosted URL, resolved language, variants when applicable, and disclosures when applicable. It does not return privacy policy, terms, or giveaway-rule bodies.

Retrieve an artist’s current policy information

Section titled “Retrieve an artist’s current policy information”

Use artist lookup from your backend when you know the artist’s Spotify ID and need the artist’s effective privacy-policy URL or every eligible public document for that artist.

GET /api/v1/artist-documents?artistPlatform=spotify&artistPlatformId=5me0Irg2ANcsgc93uaYrpb&documentType=privacy_policy&languageCode=en&source=partner-name
Authorization: Bearer YOUR_API_KEY

The artist response can include a custom privacyPolicyUrl even when no Fandation documents are available. Use privacyPolicyUrl as the artist’s effective privacy policy link. Use each document and disclosure url as the hosted legal link.

Choose the right lookup

Section titled “Choose the right lookup”
You have Use Why
A hosted Fandation document URL selected by the user Exact document lookup Retrieves the current public data for that exact document.
An artist’s Spotify ID Artist lookup Retrieves the effective privacy-policy URL and eligible public documents.
Neither a selected document URL nor a Spotify artist ID Artist Policy Finder Lets the user search for or add the artist in Fandation.

Keep the boundary clear

Section titled “Keep the boundary clear”
Part of the journey Runs in Uses the API key
Constructing and opening an Artist Policy Finder URL Your frontend No
User sign-in, policy selection, and policy creation Fandation No
Exact document and artist lookups Your backend Yes

Next steps

Section titled “Next steps”