Overview

This guide is intended as an introduction and getting started guide for customers connecting third-party systems to NOVARA Flex. It covers authentication, data import and export patterns, practical filtering and rate-limit strategies, and tips for testing endpoints.

About the NOVARA Flex API

The Flex API exposes an open REST architecture with JSON-RPC request/response model over HTTPS. Authentication is performed with API tokens. The default rate limit is 80 requests per minute, so designs should consider batch operations, page through results, and implement retries/backoff.

Architecture: Open REST, JSON-RPC request/response
Transport: HTTPS (GET/POST)
Authentication: API Token
Rate limit: 80 requests/minute
Reference docs: https://api.novaraflex.com/

How to Make a Basic API Call

All endpoints follow a JSON-RPC style body: specify the method, include required parameters, and send via HTTPS. Responses include a result object or an error structure. For automation, use tools like Postman, API Dog or PowerShell and scripting languages such as Python, curl or Node.js.

Connecting Flex to a Third-Party System

Your integration approach depends on what the external vendor supports (e.g., open API, SFTP, or report exports). At a high level: request data from the third-party system, translate it into Flex dataload format, push it to Flex via API, and optionally pull data from Flex to send back to the third party.

Pull data from a third-party system
Transform to Flex dataload CSV templates
Import via Flex API (dataload.create)
Optionally retrieve data from Flex via API and push to a third party

POST — Importing Data

Data imports occur via the dataload.create method. Submit a dataload file by either providing a signed URL (recommended) or an inline base64-encoded CSV file. Templates are available from the Flex Control Panel.

API Method: dataload.create
Parameters: url (signed S3 URL recommended) or file (base64-encoded CSV)
Templates: Access from Control Panel > Dataload
Example templates: available upon request

Supported Dataload Record Types

Employee, EmployeeNumberChange
Locations, Regions, Companies, ClientLocation
JobTitle
Training, CompletedTraining
Equipment, EquipmentTypeChange, EquipmentInspection, SerialNumberChange
DataListItem
Resource, Resource Tags
HistoricalFormResponse
OSHACase, OSHAHours, OSHAEstablishment
SDS
Project
Contractors, ContractorContacts

How to Import with dataload.create (Step-by-Step)

Gather source data from your HRIS/CMMS/LMS or other system
Download the correct Flex dataload CSV template from Control Panel > Dataload
Map your source fields to the template columns, including required fields and codes
Add/populate UpdatePolicy column with “Always” where you need to force updates (see Dataload instructions)
Upload the file to cloud storage and generate a signed URL (preferred) or base64-encode the CSV
Call dataload.create API endpoint with url or file parameter
Monitor the API response; log errors and correct validation issues, as needed
Re-run imports only after fixing validation errors to avoid duplicates

Data Strategies

Pushing Data to Flex — Avoid Validation Errors

Load list updates (e.g., job titles, departments) before employee records for dynamic lists
Use UpdatePolicy to force field updates where needed

Pulling Data from Flex — Filtering & Paging

Use parameters to filter: last_page (paging), before/after (submission date), updated_before/updated_after (date updated), deleted (include deleted form responses), etc.
Loop through pages for large datasets and use sleep/timeout to stay under rate limits

Getting Started — Tokens

Tokens are managed in Flex by Flex Admins and generated with read or read/write privileges. While each Flex site supports up to five active tokens at a time, often a single token can be used for all API calls to meet data transfer needs. Tokens should be deactivated to revoke API access when no longer needed or if token security has been compromised.

Token Management

From your Flex site Home page, Click "Control Panel"

Click "API"

Click "Generate a token"

Click "Can write" (optional) for read + write token access.

Add a Note (optional).

Click "Deactivate" to remove access to a token.

Documentation

Each endpoint page includes method details, parameters, example request/response, and error structures. Examples are provided in curl and Node to get you started; production integrations should add robust error handling, retries, paging, and rate-limit awareness.