Every top-level Field Model V1 entity is managed through one parametric CRUD
surface, keyed on {entityType}:
| Method | Path |
|---|
GET | /api/v1/external/companies/{companyId}/entities/{entityType} (list) |
POST | /api/v1/external/companies/{companyId}/entities/{entityType} (create) |
GET | /api/v1/external/companies/{companyId}/entities/{entityType}/{entityId} |
PATCH | /api/v1/external/companies/{companyId}/entities/{entityType}/{entityId} |
DELETE | /api/v1/external/companies/{companyId}/entities/{entityType}/{entityId} |
GET | /api/v1/external/companies/{companyId}/entities/{entityType}/configuration |
GET | /api/v1/external/companies/{companyId}/entity-types (discovery) |
{entityType} path segment is the lowercase kebab-case slug (exposure,
not Exposure); the PascalCase form is rejected. The set of available fields for
each type is configured per company — discover it via the /configuration
endpoint below.
The six entity types
There are exactly six CRUD entity types. Each links to its configuration schema:
Policy is not a CRUD entity. Policy has a read-only /configuration schema
(its slug policy is valid on the configuration endpoint) but no generic
create/update/delete — its writes go through the Policy Transaction
endpoints. It is intentionally absent from the
CRUD surface and from the /entity-types discovery response. Custom objects are embedded-only. A custom object is never a top-level
CRUD entity and never appears here or in /entity-types. Custom objects surface
only as Object / Object List field definitions inside an entity’s
/configuration response (for example, an embedded coverage list on a Quote).
You read and write them as nested values on their owning entity — there is no
/entities/{customObject} route.
Response envelope
Get and list responses use the generic entity envelope — identical for every
entity type. All entity-specific field values live inside fieldModelV1Data
(keyed by field referenceId); the envelope adds only system metadata:
| Field | Description |
|---|
id | Entity identifier (UUID). |
fieldModelV1Data | Object of field values keyed by referenceId, including calculated/auto-set values and join field IDs. |
createdAt | Creation time, epoch seconds. |
createdBy | User ID of the creator, or null. |
updatedAt | Last update time, epoch seconds (equals createdAt if never updated). |
updatedBy | User ID of the last updater, or null. |
createdByName | Display name resolved from createdBy, or null. |
updatedByName | Display name resolved from updatedBy, or null. |
companyId and no cross-entity enrichment — linked entities
are not embedded; query them separately. List responses wrap the envelopes as
{ items: [...], hasMore, totalCount }.
{
"id": "550e8400-e29b-41d4-a716-446655440301",
"fieldModelV1Data": {
"exposureName": "Acme Corp HQ",
"exposureType": "company"
},
"createdAt": 1736937000,
"createdBy": "google-oauth2|123456789",
"updatedAt": 1736937000,
"updatedBy": null,
"createdByName": "Jane Adjuster",
"updatedByName": null
}
createdAt/updatedAt are epoch-second integers, not ISO strings.
referenceId-keyed request bodies
The request body for create and update is a flat JSON object whose
keys are field referenceIds from the company’s field configuration — the same
shape for every entity type:
{
"exposureName": "Acme Corporation",
"exposureType": "company",
"numberOfEmployees": 150
}
referenceIds (and which are required) via the
/configuration endpoint. Date fields are objects, not plain strings:
{ "date": "YYYY-MM-DD", "timezone": "America/New_York" }.
Create returns { id }; delete returns { id, deleted: true }.
PATCH merge semantics (never PUT)
Updates are PATCH only. The handler does a partial merge onto the
existing fieldModelV1Data:
- A field provided with a value → updated.
- A field set to
null → cleared.
- A field omitted → left unchanged.
Never PUT. PUT would imply full replacement, which these endpoints do not
do. A PUT to a by-id entity route is rejected with 405 Method Not Allowed
and an Allow: PATCH header. Use PATCH.
Configuration discovery
GET /entities/{entityType}/configuration returns a JSON Schema (draft
2020-12) describing the fields available for creating or updating that type. The
required array lists fields that must be provided; option-set fields carry an
enum/oneOf of valid values; calculated and server-managed fields are included
but annotated readOnly: true + x-calculated: true. Embedded objects (custom
objects) appear here as nested Object/Object List properties under their join
field.
The configuration endpoint also accepts policy (read-only schema), in addition
to the six CRUD slugs.
Entity-type discovery
GET /entity-types is the top-level discovery endpoint. It returns the fixed set
of six CRUD entity-type descriptors — each with display names, links to its
/entities/{entityType} collection and /entities/{entityType}/configuration
schema, and the per-action permission keys a client needs. It takes no inputs
beyond the path companyId and is gated on company.configuration:export. Use
it to bootstrap a client that doesn’t already know the entity model.
Permissions
Permissions follow the format company.{entity}:{action} (action ∈
read | create | update | delete). However, the exact key varies by type —
the platform reuses existing permission families rather than minting a new one
per entity. Treat these as the source of truth (and confirm at runtime via the
per-type permissions block in the /entity-types response):
| Type | Read | Create | Update | Delete |
|---|
| Exposure | company.insured:read | company.insured:create | insured:update | insured:delete |
| Event | company.claim:read | company.claim:create | company.claim:create | company.claim:delete |
| Quote | company.quote:read (list) / company.policy:read (get) | company.policy:create | company.policy:create | company.quote:delete |
| Submission | company.submission:read | company.submission:create | company.submission:update | company.submission:delete |
| Person | company.fmv1_custom_object:read | company.fmv1_custom_object:create | company.fmv1_custom_object:update | company.fmv1_custom_object:delete |
| Organization | company.fmv1_custom_object:read | company.fmv1_custom_object:create | company.fmv1_custom_object:update | company.fmv1_custom_object:delete |
/configuration endpoint has its own read permission (e.g.
company.event:export for Event, company.insured:read for Exposure) — see the
Get Entity Configuration
endpoint.
Listing, filtering & sorting
The list endpoint supports:
| Parameter | Description |
|---|
filterText | Free-text search against the type’s configured display field. |
sortBy | createdAt (default), updatedAt, or any configured field referenceId. |
sortDirection | asc or desc. |
pageNumber | Zero-based page index (default 0). |
pageSize | Items per page (default 51). |
