Overview

The Custom Objects API allows you to manage company-defined entity types with dynamic fields and relationships. Custom object types are configured per company — use the List Types endpoint to discover available types.

Key Concepts:

• Discovery: Call GET /custom-objects to list available types, then use the type value as the objectType path parameter for all other endpoints.
• Configuration: Call GET /custom-objects/{objectType}/configuration to get a JSON Schema for data fields and metadata about relationship fields.
• Data vs relationships: Responses include separate data (regular field values) and relationships (linked entity IDs) objects. Create and update only accept data — relationship fields are rejected with a clear error directing you to the relationship management endpoints.
• Relationship management: Dedicated PUT / DELETE endpoints for linking and unlinking entities. Use the fieldRefId from the configuration endpoint.
• Object type format: Object types use snake_case in URLs and responses.

---

Discovery

Call GET /v1/custom-objects to list the custom object types configured for your company:

{
  "items": [
    { "id": "...", "type": "vehicle", "displayNameExpression": "vehicleMake + \" \" + vehicleModel" },
    { "id": "...", "type": "building_info", "displayNameExpression": null }
  ]
}

Use the type value (e.g., vehicle) as the {objectType} path parameter in all other endpoints.

---

Configuration

Call GET /v1/custom-objects/{objectType}/configuration to get:

• data: JSON Schema (draft 2020-12) describing the available fields, their types, and which are required.
• relationships: Array of relationship metadata, each with fieldRefId, label, targetType, and cardinality.

---

Data vs Relationships

GET responses split the object’s data into two sections:

{
  "id": "...",
  "type": "vehicle",
  "displayName": "Toyota Camry",
  "data": {
    "vehicleMake": "Toyota",
    "vehicleModel": "Camry",
    "year": 2024
  },
  "relationships": {
    "ownerExposure": "550e8400-e29b-41d4-a716-446655440200"
  }
}

• data: Regular field values. Can be set via create/update.
• relationships: Linked entity IDs keyed by fieldRefId. Single-cardinality relationships have a string value; multi-cardinality relationships have an array of strings. Managed via the relationship endpoints only.

---

Relationship Management

Use the dedicated relationship endpoints to link and unlink entities:

• Add: PUT /custom-objects/{objectType}/{objectId}/relationships/{fieldRefId}/{targetId}
• Remove: DELETE /custom-objects/{objectType}/{objectId}/relationships/{fieldRefId}/{targetId}

Cardinality behavior:

Cardinality	Add Behavior
one_to_one	Replaces any existing link on both sides
one_to_many	Replaces existing link from the source (the “one” side); target can have many
many_to_one	Appends link; existing links to the target from the “one” side are replaced
many_to_many	Appends link; both sides can have multiple

Both operations are idempotent — adding an existing link returns created: false, removing a non-existent link returns removed: false.

---

API Endpoints

• List Custom Object Types - Discover available types
• Get Configuration - JSON Schema and relationship metadata
• List Custom Objects - Paginated list for a type
• Get Custom Object - Retrieve by ID
• Create Custom Object - Create a new object
• Update Custom Object - Full replacement update (PUT)
• Delete Custom Object - Delete an object
• Add Relationship - Link to another entity
• Remove Relationship - Unlink from another entity

---

Permissions

Operation	Required Permission
List Types	company.fmv1_custom_object:read
Get Configuration	company.fmv1_custom_object:read
List Custom Objects	company.fmv1_custom_object:read
Get Custom Object	company.fmv1_custom_object:read
Create Custom Object	company.fmv1_custom_object:create
Update Custom Object	company.fmv1_custom_object:update
Delete Custom Object	company.fmv1_custom_object:delete
Add Relationship	company.fmv1_custom_object:update
Remove Relationship	company.fmv1_custom_object:update

---

Sorting (List Custom Objects)

Sort Field	Description
createdAt	Sort by creation date (default)
updatedAt	Sort by last update date
displayName	Sort by computed display name