Overview

The FMV1 Configuration API provides endpoints for exporting, validating, comparing, and importing company configuration via Google Spreadsheets. This is the programmatic interface to the onboarding spreadsheet pipeline.

Authentication

These endpoints require an API key created with the FMV1_CONFIGURATION_MANAGER role. Standard API keys (e.g., those with CARRIER_ADMIN) will not have the required permissions.

To create an API key with this role, go to Settings > API Keys and select the FMV1 Configuration Manager role when generating the key.

Google OAuth Token

All endpoints require the caller to provide a googleOAuthToken — a Google OAuth2 access token with permission to read from (or write to) the target spreadsheet. The server does not use its own Google credentials for these operations.

You can obtain a token via Google’s OAuth2 flow with the https://www.googleapis.com/auth/spreadsheets scope.

---

Workflow

The typical round-trip workflow is:

1. Generate — Create a new blank configuration spreadsheet template (or use Export to populate an existing one with current config)
2. Edit the spreadsheet manually
3. Validate — Check the spreadsheet for structural or data errors
4. Compare — Preview what changes the import would apply
5. Import — Apply the changes from the spreadsheet to the database

---

API Endpoints

• Generate Spreadsheet — Create a blank configuration template spreadsheet
• Export Configuration — Write current config to an existing spreadsheet
• Validate Configuration — Check spreadsheet for errors
• Compare Configuration — Diff spreadsheet against database
• Import Configuration — Apply spreadsheet changes to database

---

Permissions

Operation	Required Permission
Generate	company.configuration:export
Export	company.configuration:export
Validate	company.configuration:export
Compare	company.configuration:export
Import	company.configuration:import

---

Configuration Categories

The compare endpoint returns change counts for each category:

Category	Description
fieldDefinitions	Field definitions (name, type, reference ID, etc.)
optionSets	Option set values for dropdown fields
customObjects	Custom object type definitions
cardDefinitions	UI card layout definitions
cardSections	Sections within cards
fieldLocations	Where fields appear on cards
rowExclusions	Rows excluded from export