Skip to main content
POST
Import Configuration

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, bypass the breaking-change check and import even if the new config would invalidate data already stored under the current config. Existing entity data is left in place (not cleared) and may no longer match the new config. Any value other than true (including omission) is treated as false.

Almost never set this. Only use force when you are 100% certain every existing record is forwards-compatible with the incoming config (nothing stored will be invalidated) — e.g. a dropped field that no record holds a value for. When unsure, clear the affected entity data and re-import without force instead.

Sandbox only. Setting this requires the company.reset permission (the same one as the data wipes), and the Company must be in Sandbox mode: a Live Company answers 409 CompanyModeConflict whoever asks. Demote it to Sandbox first.

dryRun
boolean
default:false

When true, run the import but write nothing. Every gate a real import runs is executed — the full configuration validation and the breaking-change check, honouring force and whether the instance holds entity data — and the request then stops before persisting. No configuration version is written and no import history is recorded.

Because this is the same code path as a real import stopped one step short, the answer is a faithful prediction of what importing this exact body would do right now: 200 means the real import would be accepted, 400 means validation would reject it, and 409 (fmv1-config-breaking-changes) means the breaking-change check would reject it. Combine with ?force=true to preview the forced import instead.

Any value other than true (including omission) is treated as false — i.e. the import commits.

expectedContentHash
string

Optional compare-and-swap precondition. When supplied, the import is admitted only while the company's configuration still has this content hash — the value reported as contentHash by the metadata endpoint (POST .../configuration/metadata) for the canonical body returned by configuration export. Omit it and no precondition is applied.

The check runs inside the import's own transaction, so a caller that read the configuration and then imports cannot be raced by a concurrent configuration write: this turns read-then-import into one atomic operation rather than merely narrowing the window.

A mismatch is a 409 with code fmv1-config-expected-hash-mismatch and nothing is written. The error body carries currentContentHash and currentVersion, so you can re-read, rebase your changes onto the current configuration and retry without an extra round trip. currentContentHash is the hash of the current export projection, even when the immutable stored snapshot uses a legacy wire shape. currentContentHash is null when the company has no configuration version at all — which is also a mismatch, never a pass.

The value must be a sha256 written as 64 lowercase hex characters; anything else is a 400 (fmv1-config-expected-hash-malformed) rather than a silently skipped precondition.

Evaluated under ?dryRun=true as well, so a dry run predicts this verdict exactly as it predicts the validation and breaking-change ones.

Pattern: ^[0-9a-f]{64}$
Example:

"9f2c0b1d4e6a8c3f5b7d9e1a2c4e6f80a1b3c5d7e9f0a2b4c6d8e0f1a3b5c7d9"

Body

application/json

A COMPLETE configuration body. To apply a small edit without sending the whole config, use the typed-change patch endpoint (POST .../configuration/patch) instead — this endpoint rejects a delta/patch body with a 400.

fields
object[]
required

Field definitions, keyed by entity + reference id.

One top-level field definition, keyed by entity + reference id. Declare its type with structured typeInfo. Legacy type and string-encoded typeArgs remain accepted; when both representations are supplied they must agree semantically. A conflict is rejected with the field identity. Exports use typeInfo without the legacy duplicate properties.

pages
object[]
required

Page definitions.

cards
object[]
required

Card definitions.

cardPageRelationships
object[]
required

Placements of cards onto pages.

optionSetTypes
object[]
required

Option-set type declarations.

objectTypes
object[]
required

Custom-object type declarations.

optionSets
object[]
required

Option sets and their options.

objects
object[]
required

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

fieldLocations
object[]
required

Field placements (the layout) onto cards.

ratingWorkflows
object[]
required

Rating workflow definitions.

entityInvariants
object[]
required

Per-entity invariant conditions enforced on every write.

formLogicRules
object[]

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

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.

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.

listColumns
object[]

Declared list columns — the complete tenant-facing column set of each entity list page. Optional: existing payloads predate the slice, and absent ⇒ no declared tenant columns, so each list renders only its platform/system columns.

Rows declare membership, not order or default visibility. The platform's per-page defaults and each user's saved view own those choices; the stored configuration sorts rows canonically by (surface, key).

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

listFilters
object[]

Tenant-defined list filters, one per (surface, key). Together with page-owned system filters, these rows are the complete user-visible filter catalog. listColumns contributes no filters.

Optional for wire compatibility with payloads that predate the slice. Absent or empty means that each entity list offers only its page-owned system filters. Omitted from an export when the company has none.

conversionRules
object[]

Explicitly authored rules determine which values move between Policy and Quote, their destinations, and transformations. Authors maintain each direction and transaction scope independently. Matching field names imply no mapping; an absent optional mapping is valid and causes no conversion write to that destination. A rule may directly assign a source value or transform it, including writing to a differently named destination.

Each rule is identified by its (direction, transactionType, destinationPath) triple; duplicates are rejected. The stored configuration sorts the section canonically by that triple. Import validates explicit rules and requires all framework-pinned rows, including on first import. Omitting or emptying the section is invalid, even with force enabled. Preserve the authored slice through whole-configuration imports. Field edits require reviewing affected rules against business intent.

retirementIdentities
object[]

Server-derived memory for retired data addresses. Records have exactly one of three kinds: top-level field, custom-object subfield, or option-set value. A submitted copy is accepted for export/import round trips but is non-authoritative; the server derives the next set from the previous immutable configuration version. Omitted when empty.

exportPlatformColumns
object[]

Spreadsheet types for built-in (platform) export columns, one per (surface, column). Optional: absent or empty means platform columns keep their built-in formatting. column must name a built-in column of the surface (checked by name at import). Omitted from an export when empty.

Response

Import completed successfully

Result of importing FMV1 configuration

success
boolean
required

Whether the import completed successfully

message
string

Human-readable status message