Understanding FUMS

If your application displays Bible content on a website or other web-based interface, integrating FUMS is a requirement of your API.Bible license. Failure to implement FUMS may place your application out of compliance with your content license. This article explains what FUMS is, why it's required, and how to add it to your app.

What is FUMS?

FUMS stands for Fair Use Management System. It is a small reporting script that records which Bible versions, books, chapters, and verses are being viewed through your application. FUMS records anonymous usage events whenever Scripture is displayed in your application.

This data serves an important purpose: it helps API.Bible demonstrate to Bible publishers and copyright holders how their content is actually being used. That evidence supports the licensing relationships that make translations available through the API — and helps bring more translations on board over time.

Privacy Note: FUMS does not collect any personal information about your users. No names, emails, or identifiable details are recorded. Your application generates anonymous device and session identifiers before sending them to FUMS. API.Bible does not collect names, email addresses, or other personally identifiable information through FUMS.

Who Needs to Implement It?

Required: Any application displaying Bible content from the API on a website, web-based interface, or hybrid app with an embedded web view. Hybrid applications that render Scripture within an embedded web view must implement FUMS for that web content.
Exempt: Fully native mobile apps (meaning users download it directly from the Apple App Store or Google Play Store) that have no web components.

If your app uses a hybrid setup or you are unsure if this applies to you, please reach out to support@api.bible to confirm.

Implementing FUMS (Developer Instructions)

If you are not the developer on your project, pass this section along to whoever is building your app.

How It Works

Every time your app requests Scripture content from the API, the JSON response includes a meta section containing a tracking token called a fumsToken. Your app sends that token back to FUMS each time it displays the content to a user.

The fumsToken is tied to that Scripture response and can be reused whenever that content is displayed, including from cache.

Example API response
{
"data": { ... },
"meta": {
"fumsToken": "example_token_string_123"
}
}

Option 1: JavaScript Tracker (Recommended)

For browser-based applications, add the following to your HTML document — near the footer works well. This prepares the tracker to receive commands:

<script type="text/javascript" src="https://pkg.api.bible/fumsV3.min.js" async></script>
<script>
  window.fumsData = window.fumsData || [];
  window.fums = window.fums || function () { window.fumsData.push(arguments); };
</script>

Once loaded, call the tracker depending on your content type:

Track a Text View:

fums("trackView", fumsToken);

Track an Audio Listen:

fums("trackListen", fumsToken);

Track Multiple Tokens at Once:

fums("trackView", [fumsToken1, fumsToken2]);

Optional Engagement Tracking: If your app has logged-in users, you can optionally pass a user ID. The tracker automatically anonymizes this value before recording it. Do not pass any personal information (like raw emails or usernames).

fums("config", { userId: "your-internal-user-id" });

Option 2: Manual Reporting (Non-Browser Environments)

If your app runs on a server rather than in a browser, you can report FUMS manually via a GET request:

https://fums.api.bible/f3?t=YOUR_FUMS_TOKEN&dId=YOUR_DEVICE_ID&sId=YOUR_SESSION_ID&uId=YOUR_USER_ID

Parameter requirements:

t : The fumsToken from the API response. To report multiple tokens, repeat the parameter: &t=token1&t=token2 .
dId : An anonymous, unique identifier for the device, generated by your application.
sId : An anonymous, unique identifier for the current session, generated by your application.
uId (Optional): An anonymized user identifier.

The identifiers only need to be unique within your own application. They do not need to correspond to any hardware identifier or personally identifiable information.