Skip to content

FieldOps BI API

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

It is designed for use with 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 operators
  • Pagination for larger datasets
  • Dataset discovery
  • Schema discovery
  • Query safeguards
  • Optimized and aggregated BI data
  • 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

This means external reporting tools do not need 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

For example:

Authorization: Bearer fldops_bi_XXXXXXXX

You should also request a JSON response:

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 to select an organization
  • Results are restricted to the organization associated with the token
  • A token created for one organization cannot be used to access another organization's BI 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.

For example:

GET /api/bi/tables/bi_visits

The production endpoint is:

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

Available BI tables

FieldOps currently provides the following BI tables:

BI table Purpose
bi_visits Visit-level operational and monitoring data
bi_visit_responses Responses captured during visits
bi_daily_visit_metrics Daily aggregated visit metrics
bi_program_performance_snapshots Programme-level performance snapshots
bi_question_response_aggregates Aggregated monitoring question responses

Visits

GET /api/bi/tables/bi_visits

Production endpoint:

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

Visit responses

GET /api/bi/tables/bi_visit_responses

Production endpoint:

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

Daily visit metrics

GET /api/bi/tables/bi_daily_visit_metrics

Production endpoint:

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

Programme performance snapshots

GET /api/bi/tables/bi_program_performance_snapshots

Production endpoint:

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

Question response aggregates

GET /api/bi/tables/bi_question_response_aggregates

Production endpoint:

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

Example request

To request visit data:

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 more than a simple array of database records.

The BI API response provides the requested data together with metadata that helps external analytics tools and integrations understand how the request was handled.

A typical response contains:

meta
data
query_guard
pagination
dataset_signature
cache_key
execution_time_ms

Conceptually, the response follows this 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_id": 1,
      "program_name": "Community Health Programme",
      "project_id": 1,
      "project_name": "Primary Healthcare Project",
      "site_id": 1,
      "site_name": "Community Health Centre",
      "visit_date": "2026-05-23",
      "total_visits": 1,
      "submitted_visits": 0,
      "reviewed_visits": 0,
      "approved_visits": 1,
      "rejected_visits": 0
    }
  ],
  "query_guard": {
    "allowed": true,
    "violations": [],
    "warnings": [
      "Raw table query limit forced to 1000"
    ],
    "enforced_limit": 1000
  },
  "pagination": {
    "page": 1,
    "limit": 1000,
    "offset": 0,
    "total": 15,
    "has_next": false,
    "has_prev": false,
    "total_pages": 1
  },
  "dataset_signature": "example_signature",
  "cache_key": "example_cache_key",
  "execution_time_ms": 0.94
}

Note

The fields returned inside data depend on the requested BI table and how FieldOps resolves the query.

Response metadata

The meta object describes the dataset returned by the request.

It may include:

Field Description
table The BI table requested by the client
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 name of the authenticated organization
count Number of records returned

For example, a broad request to bi_visits may be resolved to an optimized aggregated BI table when appropriate.

This allows FieldOps to serve analytics-oriented data without requiring the client to understand the underlying BI storage strategy.

The data array

The data array contains the records that a BI or reporting tool can load and analyze.

Where available, FieldOps includes both identifiers and human-readable dimensions.

For example:

program_id
program_name

project_id
project_name

site_id
site_name

This makes the response easier to use in reporting tools because dashboards can work with readable Programme, Project, and Site names without requiring a separate lookup for every identifier.

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

total_visits
submitted_visits
reviewed_visits
approved_visits
rejected_visits

Safe and optimized BI queries

FieldOps automatically evaluates BI queries to help protect system performance and return data efficiently.

When a request is very broad or could retrieve a large amount of operational data, FieldOps may apply safeguards or use an optimized BI dataset to serve the request.

For example, a request such as:

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

does not necessarily mean that FieldOps will perform an unrestricted query against the underlying raw visit data.

Depending on the request, FieldOps may:

  • Apply a safe maximum result limit
  • Return a warning describing an applied safeguard
  • Restrict a query that does not meet safe query requirements
  • Serve the request from an optimized or aggregated BI table
  • Provide pagination for retrieving additional results

The response explains how the request was handled.

For example:

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

In this example:

  • table is the BI table requested by the client
  • resolved_table is the optimized BI table used to serve the request
  • aggregated indicates that the returned data is aggregated
  • allowed indicates that the query was permitted
  • warnings explains any safeguards applied
  • enforced_limit shows the maximum result limit applied by FieldOps

Important

BI clients should inspect the response metadata, query guard, and pagination information instead of assuming that every request returns unrestricted raw data.

Query guard responses

The query_guard object describes how FieldOps evaluated the request.

It may contain:

Field Description
allowed Whether the query was permitted
violations Query rules that prevented or restricted the request
warnings Information about safeguards applied to the request
enforced_limit The maximum result limit applied by FieldOps

A query that is allowed may still contain warnings.

For example:

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

This means the request was successful, but FieldOps applied a safe result limit.

Optimized and aggregated datasets

A requested BI table may sometimes be served from another optimized BI table.

For example:

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

This means:

  1. The client requested bi_visits
  2. FieldOps determined that an aggregated BI dataset could serve the request
  3. The response was generated from bi_daily_visit_metrics
  4. The response indicates that the result is aggregated

This behaviour allows FieldOps to optimize broad analytical requests while keeping the requested BI interface consistent.

Note

External tools should use the response metadata to determine whether the returned result is aggregated.

Writing efficient BI queries

For the best performance, request only the data required for your analysis.

Where appropriate:

  • Filter by Programme
  • Filter by Project
  • Filter by Site
  • Filter by User
  • Filter by Status
  • Use date ranges
  • Use supported query operators
  • Use result limits
  • Use pagination for larger result sets

For example, instead of repeatedly requesting an unrestricted dataset:

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

you can request a specific reporting period:

https://app.fieldopsafrica.com/api/bi/tables/bi_visits?visit_date=between:2026-01-01,2026-06-30

Or a specific Programme:

https://app.fieldopsafrica.com/api/bi/tables/bi_visits?program_id=eq:1

This reduces unnecessary data transfer and can improve refresh performance in external reporting tools.

Pagination

BI responses include pagination information for requests that may contain multiple pages of data.

The pagination object may contain:

Field Description
page Current page number
limit Maximum records for the current request
offset Record offset
total Total number of matching records
has_next Whether another page is available
has_prev Whether a previous page is available
total_pages Total number of available pages

For example:

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

Use the page query parameter to request a specific page.

For example:

https://app.fieldopsafrica.com/api/bi/tables/bi_visits?page=1

If has_next is true, request the next page:

https://app.fieldopsafrica.com/api/bi/tables/bi_visits?page=2

Tip

BI integrations retrieving larger datasets should use the pagination metadata rather than assuming that a single request contains every matching record.

Technical response metadata

The BI response may also include technical metadata.

Dataset signature

dataset_signature

A signature associated with the returned dataset state.

Cache key

cache_key

Information associated with the BI result cache.

Execution time

execution_time_ms

The approximate time taken to execute the BI query.

These fields can assist with diagnostics and understanding API behaviour and performance.

Dataset discovery

You do not need to rely only on a manually maintained list of BI datasets.

FieldOps provides a dataset discovery endpoint:

GET /api/bi/datasets

Production endpoint:

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

Use this endpoint to discover the BI datasets currently available through FieldOps.

Send your BI Access Token with the request:

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

Tip

Dataset discovery is useful for integrations that need to inspect the BI capabilities currently available through FieldOps.

View a dataset and its dimensions

Use the dataset endpoint to inspect an available dataset.

The endpoint follows this structure:

GET /api/bi/datasets/{dataset}

For example:

GET /api/bi/datasets/visits

Production endpoint:

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

Use this endpoint to inspect information about the visits dataset, including the dimensions available for working with that dataset.

Schema discovery

FieldOps also provides schema discovery for BI tables.

The endpoint follows this structure:

GET /api/bi/schema/{table}

For example:

GET /api/bi/schema/bi_visits

Production endpoint:

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

Schema discovery helps an external tool or developer understand the structure of a BI table before retrieving or processing its data.

This is particularly useful when:

  • Building a new reporting integration
  • Inspecting available fields
  • Preparing transformations
  • Validating expected columns
  • Building dynamic data pipelines

Filtering BI data

BI table endpoints support filtering through query parameters.

For example:

https://app.fieldopsafrica.com/api/bi/tables/bi_visit_responses?site_id=3&program_id=1&project_id=2&user_id=10&status=active&date_from=2026-01-01&date_to=2026-06-15&limit=5000

This request applies multiple filters to the same BI query:

  • Site ID 3
  • Programme ID 1
  • Project ID 2
  • User ID 10
  • Status active
  • Date range from January 1, 2026 to June 15, 2026
  • Requested limit of 5000

Note

FieldOps may enforce a safer result limit when necessary. Check query_guard.enforced_limit and the pagination metadata in the response.

Advanced query operators

FieldOps supports operator-based filters using this syntax:

?field=operator:value

Supported operators include:

Operator Purpose
eq Equal to
neq Not equal to
in Match any value in a list
like Partial text match
gt Greater than
lt Less than
between Between two values

Examples include:

?status=eq:approved

?program_id=in:1,2,3

?site_name=like:kibera

?visit_date=between:2026-01-01,2026-01-31

The detailed query guide explains filtering and operators in more depth.

Learn how to query BI data

Query examples

Approved visits

https://app.fieldopsafrica.com/api/bi/tables/bi_visits?status=eq:approved

Visits in Programme 1 or 2

https://app.fieldopsafrica.com/api/bi/tables/bi_visits?program_id=in:1,2

Search by Site name

https://app.fieldopsafrica.com/api/bi/tables/bi_visits?site_name=like:kibera

Visit date range

https://app.fieldopsafrica.com/api/bi/tables/bi_visits?visit_date=between:2026-01-01,2026-01-31

Responses to a specific question

https://app.fieldopsafrica.com/api/bi/tables/bi_visit_responses?question_id=eq:10

Testing with cURL

To retrieve visits:

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

To retrieve approved visits:

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

To retrieve visits within a date range:

curl \
  -H "Authorization: Bearer YOUR_BI_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  "https://app.fieldopsafrica.com/api/bi/tables/bi_visits?visit_date=between:2026-01-01,2026-01-31"

Testing with Postman

To test a BI endpoint in Postman:

  1. Create a new GET request.
  2. Enter the FieldOps BI endpoint.
  3. Open the Authorization tab.
  4. Select Bearer Token.
  5. Paste your FieldOps BI Access Token into the token field.
  6. Add Accept: application/json under Headers if required.
  7. Select Send.

For example:

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

Postman sends the token in the request as:

Authorization: Bearer YOUR_BI_ACCESS_TOKEN

Common problems

The API returns an unauthorized response

Check that:

  • The complete BI Access Token was supplied
  • The token starts with fldops_bi_
  • The token has not been removed or revoked
  • There are no extra spaces before or after the token
  • The token was sent as a Bearer token
  • The request uses the correct FieldOps production URL

The endpoint returns no records

Confirm that:

  • Your organization has data in the requested BI table
  • The selected filters match existing data
  • The date range is correct
  • The IDs used in the query belong to your organization

The response contains fewer records than requested

Check:

  • query_guard.warnings
  • query_guard.enforced_limit
  • pagination.limit
  • pagination.has_next
  • pagination.total_pages

FieldOps may apply a safe query limit, and additional records may be available through pagination.

The returned table is different from the requested table

Check:

  • meta.table
  • meta.resolved_table
  • meta.aggregated

FieldOps may use an optimized or aggregated BI table to serve a broad analytical request.

Security recommendations

When accessing the BI API:

  • Always use HTTPS in production
  • Keep BI Access Tokens private
  • Use separate tokens for separate integrations
  • Do not place tokens in public browser-side code
  • Do not commit tokens to Git or other source control systems
  • Remove tokens that are no longer required
  • Replace exposed tokens immediately
  • Request only the data required for the reporting workflow

Why the FieldOps BI API is ready for analytics workflows

The FieldOps BI API is designed to provide more than raw application records.

It provides an analytics-oriented interface with:

  • Dedicated BI tables
  • Organization-scoped authentication
  • Human-readable dimensions
  • Aggregated metrics
  • Query filtering
  • Advanced query operators
  • Safe query controls
  • Optimized dataset resolution
  • Pagination
  • Dataset discovery
  • Schema discovery
  • BI-oriented response metadata

This allows organizations to use FieldOps as an operational intelligence source while retaining flexibility in how they analyze, integrate, and visualize their data.

Important

The exact connection process depends on the external BI or analytics tool being used. FieldOps provides authenticated, analytics-ready BI endpoints that compatible tools can retrieve and process.

What to do next

The next guide explains how to build BI queries using:

  • Filters
  • Multiple conditions
  • Query operators
  • Date ranges
  • Text searches
  • Lists of values
  • Result limits
  • Pagination

Query BI data

Review BI Access Tokens