> ## 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.
# Validate Configuration Spreadsheet
> Validates the structure and data of an FMV1 configuration spreadsheet without applying
any changes. Use this to check for errors before running an import.
Returns a list of validation errors with details about the sheet, column, and row
where each issue was found.
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/validate
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/validate:
post:
tags:
- FMV1 Configuration
summary: Validate Configuration Spreadsheet
description: >
Validates the structure and data of an FMV1 configuration spreadsheet
without applying
any changes. Use this to check for errors before running an import.
Returns a list of validation errors with details about the sheet,
column, and row
where each issue was found.
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: validateFmv1Configuration
parameters:
- $ref: '#/components/parameters/companyId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigurationSpreadsheetRequest'
examples:
default:
summary: Validate a configuration spreadsheet
value:
spreadsheetId: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms
googleOAuthToken: ya29.a0AfH6SM...
responses:
'200':
description: Validation completed
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigurationValidateResponse'
examples:
valid:
summary: Spreadsheet is valid
value:
isValid: true
errors: []
spreadsheetName: Allied Professionals Configuration
invalid:
summary: Spreadsheet has errors
value:
isValid: false
errors:
- type: INVALID_COLUMN_HEADER
message: Unknown column 'Foo' in sheet 'Field Definitions'
details:
sheet: Field Definitions
column: Foo
- type: INVALID_VALUE
message: >-
Invalid field type 'Checkbox' — expected one of: Text,
Number, Boolean, Option Set, Date, Object
details:
sheet: Field Definitions
column: Type
row: 5
available:
- Text
- Number
- Boolean
- Option Set
- Date
- Object
spreadsheetName: Allied Professionals Configuration
'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
ConfigurationValidateResponse:
type: object
description: Result of validating an FMV1 configuration spreadsheet
required:
- isValid
- errors
- spreadsheetName
properties:
isValid:
type: boolean
description: Whether the spreadsheet passed all validation checks
errors:
type: array
description: List of validation errors (empty when isValid is true)
items:
$ref: '#/components/schemas/ConfigurationValidationError'
spreadsheetName:
type: string
description: The name of the spreadsheet that was validated
ConfigurationValidationError:
type: object
description: A single validation error from configuration validation
properties:
type:
type: string
description: Error type identifier
message:
type: string
description: Human-readable error message
details:
type: object
description: Additional context about the error location
properties:
sheet:
type: string
description: The sheet name where the error was found
column:
type: string
description: The column where the error was found
row:
type: integer
description: The row number where the error was found
available:
type: array
items:
type: string
description: Valid values when the error is a value mismatch
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.
````