> ## 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.
# Compare Configuration
> Compares an FMV1 configuration spreadsheet against the current database state and returns
a diff summary. Each configuration category (field definitions, option sets, custom objects,
etc.) includes counts of additions, updates, deletes, and unchanged items.
Use this to preview what an import would change before applying it.
The caller must provide their own Google OAuth2 access token with read permission on the
target spreadsheet.
**Required permission:** `company.configuration:export`
This endpoint requires an API key created with the **FMV1_CONFIGURATION_MANAGER** role.
See [Authentication](/api-reference/authentication) for how to create API keys with specific roles.
## OpenAPI
````yaml /openapi/generated-external-api.yaml post /api/v1/external/companies/{companyId}/configuration/compare
openapi: 3.0.3
info:
title: AI Insurance External API
description: External API for AI Insurance platform
version: 1.0.0
contact:
email: support@aiinsurance.io
servers:
- url: https://app.aiinsurance.io
description: Production
security:
- ApiKeyAuth: []
paths:
/api/v1/external/companies/{companyId}/configuration/compare:
post:
tags:
- FMV1 Configuration
summary: Compare Configuration
description: >
Compares an FMV1 configuration spreadsheet against the current database
state and returns
a diff summary. Each configuration category (field definitions, option
sets, custom objects,
etc.) includes counts of additions, updates, deletes, and unchanged
items.
Use this to preview what an import would change before applying it.
The caller must provide their own Google OAuth2 access token with read
permission on the
target spreadsheet.
**Required permission:** `company.configuration:export`
This endpoint requires an API key created with the
**FMV1_CONFIGURATION_MANAGER** role.
See [Authentication](/api-reference/authentication) for how to create
API keys with specific roles.
operationId: compareFmv1Configuration
parameters:
- $ref: '#/components/parameters/companyId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigurationSpreadsheetRequest'
examples:
default:
summary: Compare spreadsheet against database
value:
spreadsheetId: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms
googleOAuthToken: ya29.a0AfH6SM...
responses:
'200':
description: Comparison completed
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigurationCompareResponse'
examples:
noChanges:
summary: No changes detected
value:
fieldDefinitions:
additions: 0
updates: 0
deletes: 0
unchanged: 42
optionSets:
additions: 0
updates: 0
deletes: 0
unchanged: 8
customObjects:
additions: 0
updates: 0
deletes: 0
unchanged: 3
cardDefinitions:
additions: 0
updates: 0
deletes: 0
unchanged: 12
cardSections:
additions: 0
updates: 0
deletes: 0
unchanged: 6
fieldLocations:
additions: 0
updates: 0
deletes: 0
unchanged: 38
withChanges:
summary: Changes detected
value:
fieldDefinitions:
additions: 2
updates: 1
deletes: 0
unchanged: 40
optionSets:
additions: 1
updates: 0
deletes: 0
unchanged: 8
customObjects:
additions: 0
updates: 0
deletes: 0
unchanged: 3
cardDefinitions:
additions: 0
updates: 1
deletes: 0
unchanged: 11
cardSections:
additions: 1
updates: 0
deletes: 0
unchanged: 6
fieldLocations:
additions: 3
updates: 0
deletes: 0
unchanged: 38
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
components:
parameters:
companyId:
name: companyId
in: path
required: true
schema:
type: string
format: uuid
description: Company identifier
schemas:
ConfigurationSpreadsheetRequest:
type: object
description: Request body for FMV1 configuration spreadsheet operations
required:
- spreadsheetId
- googleOAuthToken
properties:
spreadsheetId:
type: string
description: The ID of the target Google Spreadsheet
googleOAuthToken:
type: string
description: >-
A valid Google OAuth2 access token with Google Sheets access
permission
ConfigurationCompareResponse:
type: object
description: Diff between a spreadsheet and the current database configuration
required:
- fieldDefinitions
- optionSets
- customObjects
- cardDefinitions
- cardSections
- fieldLocations
properties:
fieldDefinitions:
$ref: '#/components/schemas/ConfigurationChangeCounts'
optionSets:
$ref: '#/components/schemas/ConfigurationChangeCounts'
customObjects:
$ref: '#/components/schemas/ConfigurationChangeCounts'
cardDefinitions:
$ref: '#/components/schemas/ConfigurationChangeCounts'
cardSections:
$ref: '#/components/schemas/ConfigurationChangeCounts'
fieldLocations:
$ref: '#/components/schemas/ConfigurationChangeCounts'
ConfigurationChangeCounts:
type: object
description: Change counts for a single configuration category
required:
- additions
- updates
- deletes
- unchanged
properties:
additions:
type: integer
description: Number of new items that would be added
updates:
type: integer
description: Number of existing items that would be modified
deletes:
type: integer
description: Number of existing items that would be removed
unchanged:
type: integer
description: Number of items that are identical
ErrorResponse:
type: object
description: Standard error response for all external API endpoints
required:
- error
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
description: Machine-readable error code
example: VALIDATION_ERROR
message:
type: string
description: Human-readable error message
example: 'submissionId: Required field is missing'
details:
type: array
description: Additional details for validation errors (field-level errors)
items:
type: object
properties:
field:
type: string
description: The field that caused the error
example: submissionId
message:
type: string
description: Description of the field error
example: Required field is missing
responses:
Unauthorized:
description: Unauthorized - Invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
missingApiKey:
summary: Missing API key
value:
error:
code: UNAUTHORIZED
message: Authorization header is required
bearerTokenNotAllowed:
summary: Bearer token used instead of API key
value:
error:
code: UNAUTHORIZED
message: External API endpoints require API key authentication
Forbidden:
description: Forbidden - Insufficient permissions
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
insufficientPermissions:
summary: Insufficient permissions
value:
error:
code: FORBIDDEN
message: Insufficient permissions to perform this action
InternalServerError:
description: Internal Server Error - Unexpected error occurred
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
internalError:
summary: Unexpected server error
value:
error:
code: INTERNAL_ERROR
message: An unexpected error occurred. Please try again later.
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
description: >-
API key authentication. Include your API key in the Authorization
header.
````