> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiinsurance.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Warning>
  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.
</Warning>

## 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](/api-reference/fmv1-configuration/generate-configuration-spreadsheet)** — Create a blank configuration template spreadsheet
* **[Export Configuration](/api-reference/fmv1-configuration/export-configuration)** — Write current config to an existing spreadsheet
* **[Validate Configuration](/api-reference/fmv1-configuration/validate-configuration-spreadsheet)** — Check spreadsheet for errors
* **[Compare Configuration](/api-reference/fmv1-configuration/compare-configuration)** — Diff spreadsheet against database
* **[Import Configuration](/api-reference/fmv1-configuration/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                       |

***

## Smart Tag Configuration Walkthrough

<iframe width="100%" height="400" src="https://www.loom.com/embed/3cd0ebe544d7438fbb40585e9a5fec10" frameBorder="0" webkitallowfullscreen="true" mozallowfullscreen="true" allowFullScreen />