FieldOps BI API¶

The FieldOps BI API provides a secure, analytics-ready interface for accessing your organization's operational data.

It is designed for business intelligence, reporting, analytics, and data integration tools that can connect to authenticated HTTPS APIs and process JSON data.

This allows your organization to use FieldOps as an operational data source while building reports, dashboards, and analytical workflows in external tools.

The FieldOps BI API provides:

Organization-scoped authentication
Dedicated BI datasets
Analytics-ready response structures
Filtering and advanced query support
Pagination for larger datasets
Dataset discovery
Schema discovery
Query safeguards
Optimized BI responses
Response metadata for BI clients

How it works¶

FieldOps maintains a dedicated BI data layer for reporting and analytics.

External tools access this data through authenticated BI endpoints.

The general flow is:

FieldOps operational data
        ↓
FieldOps BI data layer
        ↓
Authenticated BI API
        ↓
BI, reporting, or analytics tool
        ↓
Reports and dashboards

External reporting tools do not require direct access to the FieldOps application database.

Instead, they retrieve organization-scoped data through the FieldOps BI API.

Important

The BI API is the supported interface for external analytics access. External tools should not connect directly to the FieldOps application database.

Before you begin¶

You need:

A valid FieldOps BI Access Token
Access to the FieldOps organization whose data you want to analyze
A BI, reporting, analytics, or data integration tool that can make authenticated HTTPS requests

If you have not created a BI Access Token, complete that step first:

Create a BI Access Token

Production base URL¶

The FieldOps production application is available at:

https://app.fieldopsafrica.com

BI API endpoints are available under:

https://app.fieldopsafrica.com/api/bi

Always use HTTPS when connecting to FieldOps in production.

Authentication¶

Every protected BI API request requires a valid FieldOps BI Access Token.

Send the token as a Bearer token in the HTTP Authorization header.

Use this format:

Authorization: Bearer YOUR_BI_ACCESS_TOKEN

Example:

Authorization: Bearer fldops_bi_XXXXXXXX

You should also request JSON responses:

Accept: application/json

A complete authenticated request follows this pattern:

GET /api/bi/tables/bi_visits
Authorization: Bearer YOUR_BI_ACCESS_TOKEN
Accept: application/json

Warning

Treat your BI Access Token like a password. Never include a real token in public documentation, screenshots, source code repositories, or support messages.

Organization-scoped access¶

Every BI Access Token belongs to a FieldOps organization.

When a request is authenticated, FieldOps uses the token to determine the organization whose data can be accessed.

This means:

You do not need to provide an Organization ID
Results are restricted to the organization associated with the token
A token created for one organization cannot access another organization's data

Important

Create and use the BI Access Token from the organization whose data you want to access.

BI table endpoint¶

The primary BI data endpoint follows this structure:

GET /api/bi/tables/{table}

Replace:

{table}

with the BI table you want to retrieve.

Example:

GET /api/bi/tables/bi_visits

Production endpoint:

https://app.fieldopsafrica.com/api/bi/tables/bi_visits

Request example¶

Using cURL:

curl \
  -H "Authorization: Bearer YOUR_BI_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  "https://app.fieldopsafrica.com/api/bi/tables/bi_visits?page=1"

Replace:

YOUR_BI_ACCESS_TOKEN

with the BI Access Token generated in FieldOps.

BI-ready response structure¶

FieldOps returns analytics-ready responses rather than simple database records.

A typical BI API response contains:

meta
data
query_guard
pagination
dataset_signature
cache_key
execution_time_ms

Example structure:

{
  "meta": {
    "table": "bi_visits",
    "resolved_table": "bi_daily_visit_metrics",
    "aggregated": true,
    "org_id": 1,
    "organization_name": "Example Organization",
    "count": 15
  },
  "data": [
    {
      "organization_id": 1,
      "organization_name": "Example Organization",
      "program_name": "Community Health Programme",
      "project_name": "Primary Healthcare Project",
      "site_name": "Community Health Centre",
      "visit_date": "2026-05-23",
      "total_visits": 1
    }
  ]
}

Note

Fields returned inside data depend on the requested BI table and available dataset structure.

Response metadata¶

The meta object describes the dataset returned by the request.

It may include:

Field	Description
`table`	The BI table requested
`resolved_table`	The BI table used to serve the request
`aggregated`	Whether the returned result is aggregated
`org_id`	The authenticated organization
`organization_name`	The organization name
`count`	Number of records returned

FieldOps may use optimized BI tables internally while maintaining a consistent API interface.

For example:

{
  "table": "bi_visits",
  "resolved_table": "bi_daily_visit_metrics",
  "aggregated": true
}

This means:

The client requested bi_visits
FieldOps selected an optimized BI dataset
The response was returned using the requested BI interface

The data array¶

The data array contains the records available for reporting and analysis.

Where available, FieldOps includes both identifiers and readable dimensions.

Example:

program_id
program_name

project_id
project_name

site_id
site_name

This allows reporting tools to build dashboards without requiring additional lookups.

Depending on the dataset, responses may also contain analytical measures such as:

total_visits
submitted_visits
reviewed_visits
approved_visits
rejected_visits

Dataset discovery¶

FieldOps provides dataset discovery so integrations can identify available BI datasets.

Endpoint:

GET /api/bi/datasets

Production endpoint:

https://app.fieldopsafrica.com/api/bi/datasets

Example:

curl \
  -H "Authorization: Bearer YOUR_BI_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  "https://app.fieldopsafrica.com/api/bi/datasets"

For available datasets, see:

Available Datasets

Schema discovery¶

FieldOps provides schema discovery for BI tables.

Endpoint:

GET /api/bi/schema/{table}

Example:

GET /api/bi/schema/bi_visits

Production endpoint:

https://app.fieldopsafrica.com/api/bi/schema/bi_visits

Schema discovery helps integrations understand:

Available fields
Field names
Dataset structure
Expected response columns

This is useful when:

Building reporting integrations
Preparing transformations
Creating automated data pipelines
Validating dashboard requirements

Querying BI data¶

The BI API supports querying capabilities including:

Filtering
Date ranges
Multiple conditions
Advanced query operators
Result limits
Pagination

For detailed query syntax and examples:

Query BI Data

Pagination¶

BI responses include pagination information when retrieving larger datasets.

The pagination object may contain:

Field	Description
`page`	Current page
`limit`	Maximum records returned
`offset`	Record offset
`total`	Total matching records
`has_next`	Whether another page exists
`has_prev`	Whether a previous page exists
`total_pages`	Total pages available

Example:

{
  "page": 1,
  "limit": 1000,
  "offset": 0,
  "total": 15,
  "has_next": false,
  "has_prev": false,
  "total_pages": 1
}

Query safeguards¶

FieldOps automatically evaluates BI requests to protect system performance.

Depending on the request, FieldOps may:

Apply safe result limits
Return warnings
Restrict unsafe queries
Use optimized BI datasets
Provide pagination

The response explains how the request was handled through:

query_guard
pagination
meta

Example:

{
  "query_guard": {
    "allowed": true,
    "violations": [],
    "warnings": [
      "Raw table query limit forced to 1000"
    ],
    "enforced_limit": 1000
  }
}

Common problems¶

The API returns an unauthorized response¶

Check that:

The BI Access Token is correct
The token has not been revoked
The token is sent as a Bearer token
The request uses the correct production URL

The authorization header should be:

Authorization: Bearer YOUR_BI_ACCESS_TOKEN

The endpoint returns no records¶

Confirm that:

Your organization has data in the requested dataset
Filters match available data
The selected date range is valid

The response contains fewer records than expected¶

Check:

query_guard
pagination
meta

FieldOps may apply safe limits or return paginated results.

Connecting BI tools¶

Once you have a BI Access Token, connect FieldOps to your preferred analytics tool:

What to do next¶

Continue with:

View Available Datasets

Query BI Data