Public Documents API

The Public Documents API lets a partner retrieve an artist’s published public document links and disclosure representations. Use it when your product needs an artist’s effective privacy-policy URL, Fandation-hosted document URLs, or email and SMS disclosures.

The API returns approved public data only. It never returns the body of a privacy policy, terms document, or giveaway rules. Use the URLs in each response to link to those documents.

Environments and authentication

Fandation issues a separate API key for each environment. Contact Fandation Support to register an integration and receive the appropriate credentials.

Environment	Base URL	Key prefix
Staging	`https://staging.fandation.com`	`fnd_test_`
Production	`https://app.fandation.com`	`fnd_live_`

Keys are environment-specific and don’t work against another environment’s base URL.

Send exactly one bearer token in the Authorization header.

Authorization: Bearer YOUR_API_KEY
Accept: application/json

Treat the API key as a backend secret. Fandation displays a raw key only when it is issued. If a key is lost or exposed, contact Fandation to revoke and replace it.

Get an artist’s public documents

Use this endpoint when you know the artist’s Spotify ID and need the artist’s effective privacy-policy URL, or all supported Fandation document links.

GET /api/v1/artist-documents?artistPlatform=spotify&artistPlatformId=3AA28KZvwAUcZuOKwyblJQ&artistName=Gorillaz&languageCode=en&source=fanvids
Authorization: Bearer YOUR_API_KEY

Query parameters

Parameter	Required	Description
`artistPlatform`	Yes	`spotify`. Spotify is the supported artist platform in this version of the API.
`artistPlatformId`	Yes	The exact 22-character Spotify artist ID.
`artistName`	No	Optional human-readable context. It doesn’t affect the lookup.
`documentType`	No	Filter to `privacy_policy`, `terms`, or `giveaway_rules`. Omit it to receive every supported type.
`languageCode`	No	Preferred lowercase BCP 47 language tag. Defaults to `en`. Each returned resource reports the language actually used.
`source`	No	A lowercase attribution slug, such as `fanvids`. Use the value provided by Fandation, or a lowercase hyphenated slug for your company or brand when none was provided.

Use each functional parameter once. The API rejects repeated parameters, internal Fandation identifiers, and unknown functional parameters. You may add utm_* parameters for marketing attribution.

Example response

This example shows an artist with a custom privacy-policy URL, a Fandation privacy policy with a variant and disclosures, terms, and giveaway rules.

{
  "artist": {
    "name": "Gorillaz",
    "platform": "spotify",
    "platformId": "3AA28KZvwAUcZuOKwyblJQ"
  },
  "requestedLanguageCode": "en",
  "privacyPolicyUrl": "https://gorillaz.com/privacy",
  "privacyPolicyUrlSource": "artist_override",
  "documents": [
    {
      "publicDocumentId": "9dd9b24d-5d20-4e31-aa47-d84c8bfcad6c",
      "parentPublicDocumentId": null,
      "documentType": "privacy_policy",
      "name": "Privacy Policy",
      "variantName": null,
      "languageCode": "en",
      "availableLanguageCodes": ["en", "es"],
      "url": "https://app.fandation.com/docs/9dd9b24d-5d20-4e31-aa47-d84c8bfcad6c?lng=en",
      "disclosures": [
        {
          "type": "email",
          "languageCode": "en",
          "url": "https://app.fandation.com/docs/9dd9b24d-5d20-4e31-aa47-d84c8bfcad6c?lng=en&type=email",
          "content": {
            "html": "<p>By signing up, you agree to receive promotional emails from Gorillaz.</p>",
            "text": "By signing up, you agree to receive promotional emails from Gorillaz.",
            "markdown": "By signing up, you agree to receive promotional emails from Gorillaz.\n"
          }
        }
      ],
      "variants": [
        {
          "publicDocumentId": "45e0811e-c7d8-4d6b-a426-549b5db96fa1",
          "parentPublicDocumentId": "9dd9b24d-5d20-4e31-aa47-d84c8bfcad6c",
          "documentType": "privacy_policy",
          "name": "Privacy Policy",
          "variantName": "Gorillaz Official Store",
          "languageCode": "en",
          "availableLanguageCodes": ["en", "es"],
          "url": "https://app.fandation.com/docs/45e0811e-c7d8-4d6b-a426-549b5db96fa1?lng=en",
          "disclosures": [],
          "variants": []
        }
      ]
    },
    {
      "publicDocumentId": "3e427768-52ad-4ca8-bd31-731378f46eee",
      "parentPublicDocumentId": null,
      "documentType": "terms",
      "name": "Terms of Service",
      "variantName": null,
      "languageCode": "en",
      "availableLanguageCodes": ["en"],
      "url": "https://app.fandation.com/docs/3e427768-52ad-4ca8-bd31-731378f46eee?lng=en",
      "disclosures": [],
      "variants": []
    },
    {
      "publicDocumentId": "cc5a7ebf-96fd-4df2-9ed4-fd3579d49a73",
      "parentPublicDocumentId": null,
      "documentType": "giveaway_rules",
      "name": "Gorillaz World Tour Giveaway Rules",
      "variantName": null,
      "languageCode": "en",
      "availableLanguageCodes": ["en"],
      "url": "https://app.fandation.com/docs/cc5a7ebf-96fd-4df2-9ed4-fd3579d49a73?lng=en",
      "disclosures": [],
      "variants": []
    }
  ]
}

Privacy-policy URL

privacyPolicyUrl is the effective privacy-policy URL for the artist. Link to it when you need the artist’s main privacy policy.

privacyPolicyUrlSource describes where it came from.

Value	Meaning
`artist_override`	The artist has supplied a custom privacy-policy URL.
`fandation`	Fandation provides the hosted privacy-policy URL.
`null`	Neither a custom URL nor a public Fandation privacy policy is available.

An artist can have a custom privacy-policy URL with no Fandation documents. In that case, documents is an empty array and privacyPolicyUrl still contains the custom URL.

Documents, variants, and disclosures

Each resource in documents is a parent document. Its variants array contains the public variants of that document. A variant has its own publicDocumentId, URL, language, and disclosures, and its parentPublicDocumentId points to the parent document.

Use each resource’s url to link to its hosted public document. The URL has the resolved language in its lng query parameter. Every resource reports the language that was actually selected in languageCode, because language fallback can resolve differently for each document or disclosure. If the requested language isn’t available, Fandation falls back to English.

disclosures can contain email and sms disclosures. Each disclosure has a hosted URL plus equivalent html, text, and markdown content. These representations are provided for disclosures only, not for policy, terms, or giveaway-rule bodies.

Get one public document by public ID

Use this exact lookup when you already have a Fandation public document URL and need its current public resource data. It complements the artist lookup above.

GET /api/v1/documents/45e0811e-c7d8-4d6b-a426-549b5db96fa1?languageCode=en
Authorization: Bearer YOUR_API_KEY

The path value is the publicDocumentId from the artist response. It is also the public identifier in a hosted document URL. It is commonly UUID-shaped, but it is a public embedKey, not an internal database UUID.

https://app.fandation.com/docs/45e0811e-c7d8-4d6b-a426-549b5db96fa1?lng=en
                                 ^ publicDocumentId

Only languageCode is accepted as a functional query parameter. A direct parent lookup includes its public variants. A direct variant lookup includes its parentPublicDocumentId and returns an empty variants array.

The response wraps the same resource shape in a document property.

{
  "document": {
    "publicDocumentId": "45e0811e-c7d8-4d6b-a426-549b5db96fa1",
    "parentPublicDocumentId": "9dd9b24d-5d20-4e31-aa47-d84c8bfcad6c",
    "documentType": "privacy_policy",
    "name": "Privacy Policy",
    "variantName": "Gorillaz Official Store",
    "languageCode": "en",
    "availableLanguageCodes": ["en", "es"],
    "url": "https://app.fandation.com/docs/45e0811e-c7d8-4d6b-a426-549b5db96fa1?lng=en",
    "disclosures": [],
    "variants": []
  }
}

Continue from Artist Policy Finder

When a user needs to find or create a policy in Fandation, send them to Artist Policy Finder with the same artist context. This browser handoff doesn’t authenticate an API request or expose your API key.

https://staging.fandation.com/artist-policy-finder?artistPlatform=spotify&artistPlatformId=3AA28KZvwAUcZuOKwyblJQ&artistName=Gorillaz&documentType=privacy_policy&languageCode=en&source=fanvids

After the user selects a policy, your product can retain the hosted public URL. Extract the publicDocumentId only when an exact API lookup is needed.

See the policy document journey for the complete frontend handoff and backend retrieval flow.

Caching and rate limits

Successful responses include a deterministic strong ETag, Cache-Control: private, no-cache, and Vary: Authorization. Store the ETag with the response and send it in If-None-Match on a later request. A matching resource returns 304 Not Modified without a response body. Authentication, rate limiting, validation, and public lookup still occur before a conditional response.

The initial limit is 60 requests per minute for each endpoint action and credential. Responses include RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset. On 429 Too Many Requests, wait for the Retry-After value before retrying.

Errors

Errors contain an error string.

Status	Meaning
`400`	Invalid or unsupported request parameters.
`401`	Missing or invalid API key.
`403`	API key doesn’t have the required `documents:read` scope.
`404`	The artist or document isn’t available through the public API.
`405`	Unsupported HTTP method.
`429`	Rate limit reached.
`500`	Unexpected server error. Retry only when appropriate for your integration.

The API is a request-time snapshot. It doesn’t send updates or webhooks. Request the current resource again when your application needs fresh data.