Start Data Validation Run

curl --request POST \
  --url https://go.aiinsurance.io/api/v1/companies/{companyId}/configuration/data-validation-runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "fields": [],
  "pages": [],
  "cards": [],
  "cardPageRelationships": [],
  "optionSetTypes": [],
  "objectTypes": [],
  "optionSets": [],
  "objects": [],
  "objectPrimitives": [],
  "fieldLocations": [],
  "ratingWorkflows": [],
  "entityInvariants": []
}
'

import requests

url = "https://go.aiinsurance.io/api/v1/companies/{companyId}/configuration/data-validation-runs"

payload = {
    "fields": [],
    "pages": [],
    "cards": [],
    "cardPageRelationships": [],
    "optionSetTypes": [],
    "objectTypes": [],
    "optionSets": [],
    "objects": [],
    "objectPrimitives": [],
    "fieldLocations": [],
    "ratingWorkflows": [],
    "entityInvariants": []
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    fields: [],
    pages: [],
    cards: [],
    cardPageRelationships: [],
    optionSetTypes: [],
    objectTypes: [],
    optionSets: [],
    objects: [],
    objectPrimitives: [],
    fieldLocations: [],
    ratingWorkflows: [],
    entityInvariants: []
  })
};

fetch('https://go.aiinsurance.io/api/v1/companies/{companyId}/configuration/data-validation-runs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://go.aiinsurance.io/api/v1/companies/{companyId}/configuration/data-validation-runs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'fields' => [
        
    ],
    'pages' => [
        
    ],
    'cards' => [
        
    ],
    'cardPageRelationships' => [
        
    ],
    'optionSetTypes' => [
        
    ],
    'objectTypes' => [
        
    ],
    'optionSets' => [
        
    ],
    'objects' => [
        
    ],
    'objectPrimitives' => [
        
    ],
    'fieldLocations' => [
        
    ],
    'ratingWorkflows' => [
        
    ],
    'entityInvariants' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://go.aiinsurance.io/api/v1/companies/{companyId}/configuration/data-validation-runs"

	payload := strings.NewReader("{\n  \"fields\": [],\n  \"pages\": [],\n  \"cards\": [],\n  \"cardPageRelationships\": [],\n  \"optionSetTypes\": [],\n  \"objectTypes\": [],\n  \"optionSets\": [],\n  \"objects\": [],\n  \"objectPrimitives\": [],\n  \"fieldLocations\": [],\n  \"ratingWorkflows\": [],\n  \"entityInvariants\": []\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://go.aiinsurance.io/api/v1/companies/{companyId}/configuration/data-validation-runs")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"fields\": [],\n  \"pages\": [],\n  \"cards\": [],\n  \"cardPageRelationships\": [],\n  \"optionSetTypes\": [],\n  \"objectTypes\": [],\n  \"optionSets\": [],\n  \"objects\": [],\n  \"objectPrimitives\": [],\n  \"fieldLocations\": [],\n  \"ratingWorkflows\": [],\n  \"entityInvariants\": []\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://go.aiinsurance.io/api/v1/companies/{companyId}/configuration/data-validation-runs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"fields\": [],\n  \"pages\": [],\n  \"cards\": [],\n  \"cardPageRelationships\": [],\n  \"optionSetTypes\": [],\n  \"objectTypes\": [],\n  \"optionSets\": [],\n  \"objects\": [],\n  \"objectPrimitives\": [],\n  \"fieldLocations\": [],\n  \"ratingWorkflows\": [],\n  \"entityInvariants\": []\n}"

response = http.request(request)
puts response.read_body

{
  "runId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "outcome": "enqueued"
}

Validate & Compare

Start Data Validation Run

Starts a data validation run: a background scan that reads every stored record of every entity type for this company and classifies each one against a configuration. Returns immediately with a runId — poll GET /configuration/data-validation-runs/{runId} for progress and results.

This is the data-aware companion to validate. Validate checks whether a configuration is well-formed and reads no records at all; a run checks whether the records you have already stored still fit a configuration.

The request body is OPTIONAL — that is how you choose what to scan

Send no body at all → the run scans the company’s live configuration. This answers “do my current records still conform to the config I am running right now?” Nothing is read from the request; the live configuration is snapshotted onto the run. An explicit JSON null body, and an empty JSON object, are accepted the same way and also mean a live scan.
Send a COMPLETE configuration body (the same shape import and validate accept) → the run scans that candidate configuration. Nothing is persisted as the company’s configuration — the body is only snapshotted onto the run — so this is a safe way to ask “which of my records would break if I imported this?” before importing it.

Either way the configuration is snapshotted onto the run when it starts, so a run’s verdict cannot drift: a configuration import that lands mid-scan does not change what the scan is measuring against.

A delta/patch body is rejected with a 400. Typed changes go to the patch endpoint (POST .../configuration/patch); this endpoint, like import and validate, takes a complete body only.

Send the body as `application/json`, or send nothing

A body that arrives and cannot be read as JSON is a 400 (UNREADABLE_REQUEST_BODY) — it is never treated as an omitted body. This covers a body sent with a Content-Type other than application/json, a body sent with no Content-Type at all, and a body that is not valid JSON (a truncated or corrupted payload). Failing loudly is the point: silently falling back to a live scan would return a clean result for a candidate configuration nobody ever measured.

force is a query parameter only. A force key inside the request body is part of the configuration document, not a control flag, and is ignored — use ?force=true.

Duplicate starts collapse onto the run already in flight

If a run is already in flight (queued or running) for this company and it is scanning the exact same configuration, this endpoint does not start a second scan. It returns 200 with that run’s id and outcome: "duplicate".

duplicate is a normal, successful answer and not an error — a client looping starts, or retrying after a timeout, should treat it as “the scan you asked for is already happening, poll this id”. Configurations are matched by content, so a body that differs anywhere is a different scan and starts a new run. Pass ?force=true to start a new run even when a matching one is in flight.

At most 3 runs in flight per company

A company may have 3 runs in flight (queued or running) at once. A 4th distinct configuration is refused with a 429 whose body carries inFlightRunIds — the ids of the runs already in flight — so you can poll those instead of retrying blind. Wait for one to reach a terminal status, then start again.

?force=true does not lift this limit; it only overrides the duplicate check described above. The limit exists because scans share one background work queue with everything else the platform runs (parsing, extraction, invoicing), so an unbounded number of scans for one company would starve unrelated work.

Required permission: company.configuration:export

This endpoint requires an API key created with the FMV1_CONFIGURATION_MANAGER role. See Authentication for how to create API keys with specific roles.

POST

api

companies

{companyId}

configuration

data-validation-runs

Start Data Validation Run

curl --request POST \
  --url https://go.aiinsurance.io/api/v1/companies/{companyId}/configuration/data-validation-runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "fields": [],
  "pages": [],
  "cards": [],
  "cardPageRelationships": [],
  "optionSetTypes": [],
  "objectTypes": [],
  "optionSets": [],
  "objects": [],
  "objectPrimitives": [],
  "fieldLocations": [],
  "ratingWorkflows": [],
  "entityInvariants": []
}
'

import requests

url = "https://go.aiinsurance.io/api/v1/companies/{companyId}/configuration/data-validation-runs"

payload = {
    "fields": [],
    "pages": [],
    "cards": [],
    "cardPageRelationships": [],
    "optionSetTypes": [],
    "objectTypes": [],
    "optionSets": [],
    "objects": [],
    "objectPrimitives": [],
    "fieldLocations": [],
    "ratingWorkflows": [],
    "entityInvariants": []
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    fields: [],
    pages: [],
    cards: [],
    cardPageRelationships: [],
    optionSetTypes: [],
    objectTypes: [],
    optionSets: [],
    objects: [],
    objectPrimitives: [],
    fieldLocations: [],
    ratingWorkflows: [],
    entityInvariants: []
  })
};

fetch('https://go.aiinsurance.io/api/v1/companies/{companyId}/configuration/data-validation-runs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://go.aiinsurance.io/api/v1/companies/{companyId}/configuration/data-validation-runs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'fields' => [
        
    ],
    'pages' => [
        
    ],
    'cards' => [
        
    ],
    'cardPageRelationships' => [
        
    ],
    'optionSetTypes' => [
        
    ],
    'objectTypes' => [
        
    ],
    'optionSets' => [
        
    ],
    'objects' => [
        
    ],
    'objectPrimitives' => [
        
    ],
    'fieldLocations' => [
        
    ],
    'ratingWorkflows' => [
        
    ],
    'entityInvariants' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://go.aiinsurance.io/api/v1/companies/{companyId}/configuration/data-validation-runs"

	payload := strings.NewReader("{\n  \"fields\": [],\n  \"pages\": [],\n  \"cards\": [],\n  \"cardPageRelationships\": [],\n  \"optionSetTypes\": [],\n  \"objectTypes\": [],\n  \"optionSets\": [],\n  \"objects\": [],\n  \"objectPrimitives\": [],\n  \"fieldLocations\": [],\n  \"ratingWorkflows\": [],\n  \"entityInvariants\": []\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://go.aiinsurance.io/api/v1/companies/{companyId}/configuration/data-validation-runs")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"fields\": [],\n  \"pages\": [],\n  \"cards\": [],\n  \"cardPageRelationships\": [],\n  \"optionSetTypes\": [],\n  \"objectTypes\": [],\n  \"optionSets\": [],\n  \"objects\": [],\n  \"objectPrimitives\": [],\n  \"fieldLocations\": [],\n  \"ratingWorkflows\": [],\n  \"entityInvariants\": []\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://go.aiinsurance.io/api/v1/companies/{companyId}/configuration/data-validation-runs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"fields\": [],\n  \"pages\": [],\n  \"cards\": [],\n  \"cardPageRelationships\": [],\n  \"optionSetTypes\": [],\n  \"objectTypes\": [],\n  \"optionSets\": [],\n  \"objects\": [],\n  \"objectPrimitives\": [],\n  \"fieldLocations\": [],\n  \"ratingWorkflows\": [],\n  \"entityInvariants\": []\n}"

response = http.request(request)
puts response.read_body

{
  "runId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "outcome": "enqueued"
}

Authorizations

Authorization

string

header

required

User-principal OAuth 2.0 Bearer authentication. Send a user-scoped Auth0 access token (audience = the app API audience) as Authorization: Bearer <jwt>. The request resolves to the user's identity and is authorized by their Role on the {companyId} in the path — the same role-based permissions the web app enforces. This is the path the MCP connector uses to act on a user's behalf; endpoints that accept it list both BearerAuth and ApiKeyAuth.

Path Parameters

companyId

string<uuid>

required

Company identifier

Query Parameters

force

boolean

default:false

When true, start a new run even if a run is already in flight for this company scanning the same configuration — i.e. skip the duplicate check and always mint a fresh run. Any value other than true (including omission) is treated as false.

This does not raise the limit of 3 runs in flight per company: a ?force=true request past that limit still gets a 429.

Unlike force on import, this needs no additional permission and destroys nothing — the only cost of forcing is a redundant scan.

Body

application/json

OPTIONAL. Omit the body entirely to scan the company's live configuration — that is the documented way to ask for a live scan, and no query flag is needed for it.

When a body IS sent it must be a COMPLETE configuration document matching the schema below, and the run scans that candidate configuration instead; nothing is persisted. A delta/patch body is rejected with a 400, and so is a body that cannot be read as JSON.

Structured FMV1 configuration body. This is both the body the import endpoint accepts and the body the export endpoint returns, so export → (edit) → import is a lossless round-trip. Each property is an array of config rows; the import runs them through the full validate → compare → apply pipeline.

The per-element schemas below are the canonical FMV1 configuration model and the single source of truth for this payload.

fields

object[]

required

Field definitions, keyed by entity + reference id.

Show child attributes

pages

object[]

required

Page definitions.

Show child attributes

cards

object[]

required

Card definitions.

Show child attributes

cardPageRelationships

object[]

required

Placements of cards onto pages.

Show child attributes

optionSetTypes

object[]

required

Option-set type declarations.

Show child attributes

objectTypes

object[]

required

Custom-object type declarations.

Show child attributes

optionSets

object[]

required

Option sets and their options.

Show child attributes

objects

object[]

required

Custom-object sub-field definitions, joined to object types.

Show child attributes

objectPrimitives

object[]

required

Object-primitive sub-field definitions (Address / Date / Currency).

Show child attributes

fieldLocations

object[]

required

Field placements (the layout) onto cards.

Show child attributes

ratingWorkflows

object[]

required

Rating workflow definitions.

Show child attributes

entityInvariants

object[]

required

Per-entity invariant conditions enforced on every write.

Show child attributes

formLogicRules

object[]

Forms-logic rules (quote-flow auto-add rules). Optional — existing payloads predate the "Forms" tab; absent ⇒ no rules.

Show child attributes

smartTags

object[]

Smart tags — the named values resolved into generated documents. Optional: existing payloads predate the slice, and absent ⇒ no smart tags, which is also how a company that has not yet moved to this format is recognised.

Omitted from an export when the company has none, rather than emitted as an empty array.

Show child attributes

exportSurfaces

object[]

Declared export columns — the tenant-facing column set of each export surface (the seven entity exports plus the bordereau). Optional: existing payloads predate the slice, and absent ⇒ no declared columns, which is also how a surface that still offers every configured field is recognised.

Activation is per surface: a surface with at least one row here resolves its whole tenant column set through those rows, in the order they appear; a surface with none behaves exactly as it did before this section existed.

Omitted from an export when the company has declared none, rather than emitted as an empty array.

Show child attributes

Response

The run to poll. outcome: "enqueued" means a new scan was started; outcome: "duplicate" means runId is a run already in flight scanning this same configuration and no second scan was started.

The run to poll after starting a data-validation run. outcome is a policy verdict delivered as a successful 200, not an error: duplicate means a run scanning this same configuration was already in flight, so runId is that run and no second scan was started.

runId

string<uuid>

required

The run to poll via GET /api/v1/companies/{companyId}/configuration/data-validation-runs/{runId}

outcome

enum<string>

required

enqueued when a new scan was started; duplicate when a run already in flight was scanning this same configuration (pass ?force=true to start a new run anyway)

Available options:

enqueued,

duplicate

⌘I

Getting Started

User

Entities

Event Lifecycle

Policy Transactions

Financials

Rating

Notes

Tasks

Configuration Management

Company Files

Forms

Document Generation

Submission Parsing

Reference

Start Data Validation Run

The request body is OPTIONAL — that is how you choose what to scan

Send the body as `application/json`, or send nothing

Duplicate starts collapse onto the run already in flight

At most 3 runs in flight per company

Authorizations

Path Parameters

Query Parameters

Body

Response