FieldOrchestrator

DocumentationReferenceAPI Reference

API Reference

Complete reference for the customer-visible 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 customer-managed system-to-system integration, connecting ERP systems, mobile sync agents, and compliance platforms to the FieldOrchestrator data layer. Provider-managed service endpoints are documented only where needed for approved interoperability and are not operated by customer teams. Customer-managed machine endpoints require API key authentication; public health probes remain unauthenticated. The API uses consistent JSON request and response bodies across all resources.

Use this reference for customer-managed integrations. If you need an additional managed-service interface, contact SymbioWave support rather than trying to infer it from customer-facing endpoints.

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 issued through the governed platform backoffice flow after an approved customer request; they are not created from ordinary browser settings.

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

The shipped app-side limiter is a shared database-backed fixed-window counter. Machine endpoints on /api/v1/* use per-key budgets, expensive workflows add concurrency locks, Retry-After is returned in the header, and health-based adaptive throttling is not currently shipped.

Scope	Limit
`externalApiKey`	60 requests / minute per API key on /api/v1/*
`auth`	5 attempts / 15 minutes on public auth and installer validation entry points
`expensiveWorkflows`	Fixed-window budgets plus concurrency locks on AI, reports, routing, and connector execution

Rate Limit Response

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

{
  "error": "Too many requests. Please try again later.",
  "success": false,
  "code": 429,
  "errorCode": "RATE_LIMIT_EXCEEDED"
}

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  // human-readable description",
  "success": false,
  "code": 422,
  "errorCode": "VALIDATION_ERROR",
  "requestId": "string  // optional correlation id",
  "details": "array | object | undefined"
}

Error Code	HTTP	Description
`UNAUTHORIZED`	401	The request is missing a valid session or API key.
`FORBIDDEN`	403	The authenticated actor does not have permission for the requested endpoint.
`VALIDATION_ERROR`	422	The request body or query parameters failed schema validation. Structured details are returned when available.
`RATE_LIMIT_EXCEEDED`	429	The fixed-window request budget or concurrency lock was exhausted. Retry after the duration indicated in the Retry-After header.
`QUOTA_EXCEEDED`	429	A managed proxy tenant quota was exhausted on a surface where tenant quotas are implemented.
`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