> ## 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.

# 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](#discovery) 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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](/api-reference/field-model-custom-objects/list-custom-object-types)** - Discover available types
* **[Get Configuration](/api-reference/field-model-custom-objects/get-custom-object-configuration)** - JSON Schema and relationship metadata
* **[List Custom Objects](/api-reference/field-model-custom-objects/list-custom-objects)** - Paginated list for a type
* **[Get Custom Object](/api-reference/field-model-custom-objects/get-custom-object)** - Retrieve by ID
* **[Create Custom Object](/api-reference/field-model-custom-objects/create-custom-object)** - Create a new object
* **[Update Custom Object](/api-reference/field-model-custom-objects/update-custom-object)** - Full replacement update (PUT)
* **[Delete Custom Object](/api-reference/field-model-custom-objects/delete-custom-object)** - Delete an object
* **[Add Relationship](/api-reference/field-model-custom-objects/add-custom-object-relationship)** - Link to another entity
* **[Remove Relationship](/api-reference/field-model-custom-objects/remove-custom-object-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   |