FieldOrchestrator

DocumentationReferenceAPI Reference

API Reference

Complete reference for the FieldOrchestrator REST API: authentication, scopes, endpoints, rate limits, error codes, and versioning policy.

Overview

Base URL

/api/v1/

All versioned endpoints are prefixed with /api/v1/

Format

JSON

All request and response bodies use application/json

Auth

API Key

Pass your key in the x-api-key request header

The FieldOrchestrator REST API is designed for system-to-system integration — connecting ERP systems, mobile sync agents, and compliance platforms to the FieldOrchestrator data layer. All endpoints require API key authentication. The API uses consistent JSON request and response bodies across all resources.

Authentication

Include your API key in the x-api-key request header on every request. There is no session or OAuth flow — each request is authenticated independently.

Example Request Header

x-api-key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx

API keys are scoped — each key is authorized for exactly one set of operations. Using a key on an endpoint outside its scope returns HTTP 403 SCOPE_UNAUTHORIZED. Create separate keys for each integration to follow the principle of least privilege.

API Key Scopes

Three scopes are available. Each scope grants write or read access to a specific data domain. Keys are created and managed in Settings → API Keys (ADMIN role required).

Scope	Authorized Operations	Typical Use Case
`INGEST_SALES`	Import sell-out data records	ERP or pharmacy data pipeline
`SYNC_VISITS`	Upload visit records from mobile offline queue	Mobile app background sync agent
`WORKFLOW_LOG`	Write workflow audit events	External compliance or automation systems

Endpoints

Sell-Out Data

POST/api/v1/sales-dataINGEST_SALES

Import sell-out records

Bulk import sell-out records. Request body: array of sales objects (see Integration Guide for schema). Returns an import summary including inserted, updated, and rejected row counts.

Visit Sync

POST/api/v1/sync/visitsSYNC_VISITS

Bulk upload offline visit records

Upload an array of visit log objects from the mobile offline queue. This endpoint is idempotent — duplicate records with the same visit identifier are safely ignored.

HCP

GET/api/v1/hcps

List HCPs

Returns a paginated list of HCP records. Supported query parameters: territory (filter by territory ID), tier (A, B, or C), search (name substring match), page, and limit (maximum 100 per page).

GET/api/v1/hcps/:id

Get a single HCP record

Returns the full HCP record for the given identifier, including tier, territory, last visit date, and engagement metrics.

Route Plans

GET/api/v1/routes

Get route plans for a rep on a given date

Returns the approved route plan for a representative on the specified date. Required query parameters: date (YYYY-MM-DD) and rep (representative ID). Returns stops in optimised visit order with time windows and HCP details.

Health

GET/api/health

Service liveness check

Returns a lightweight liveness response from the application process without probing external dependencies. No authentication required. Suitable for load balancer and uptime checks.

GET/api/health/db

Database readiness check

Returns the current database connectivity status. No authentication required. Use for readiness probes and operator diagnostics, not high-frequency public uptime polling.

Rate Limits

API requests are rate-limited per key. Exceeding the limit returns HTTP 429 with a Retry-After header indicating how many seconds to wait before retrying.

Scope	Limit
`INGEST_SALES`	1,000 records / minute
`SYNC_VISITS`	500 records / minute
`WORKFLOW_LOG`	200 events / minute

Rate Limit Response

HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/json

{
  "error": "RATE_LIMITED",
  "message": "Rate limit exceeded. Retry after 30 seconds.",
  "statusCode": 429
}

Error Responses

All error responses use a consistent JSON envelope format. Machine-readable error codes allow integrations to handle errors programmatically.

Error Response Shape

{
  "error": "string  // machine-readable error code",
  "message": "string  // human-readable description",
  "statusCode": 400
}

Error Code	HTTP	Description
`INVALID_API_KEY`	401	The API key is missing, malformed, or has been revoked.
`SCOPE_UNAUTHORIZED`	403	The key does not have permission for the requested endpoint.
`VALIDATION_ERROR`	400	The request body or query parameters failed schema validation. The message field describes which fields are invalid.
`RATE_LIMITED`	429	The per-key rate limit has been exceeded. Retry after the duration indicated in the Retry-After header.
`NOT_FOUND`	404	The requested resource does not exist.

Versioning Policy

Current Version

/api/v1/

Stable and backwards-compatible. No breaking changes will be introduced.

Breaking Changes

New major version only

Breaking changes are introduced only in a new major version (e.g. /api/v2/).

Deprecation Notice

12 months

Deprecated versions receive a 12-month notice period before being retired.

The /api/v1/ contract is stable. You can build integrations against it without concern about silent breaking changes. Version deprecation notices are announced via email to the contact address on your SymbioWave account and in the platform's Release Notes.

API integration support

Questions about the API, custom integrations, or webhook requirements? Reach out to our team.

support@symbiowave.com