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

Submissions are containers for quotes in AI Insurance. The Submissions API allows you to programmatically create, read, update, and delete submissions.

**Key Concepts:**

* Submissions are containers for **quotes** - create a submission first, then add quotes via the [Quotes API](/api-legacy-reference/quotes/overview)
* Submissions progress through various **statuses** from creation to binding
* Submissions have a **type** indicating if it's new business, renewal, endorsement, or cancellation
* For renewals, submissions can reference the **renewing policy** via `renewingPolicyId`

***

## API Endpoints

* **[List Submissions](/api-reference/submissions/list-submissions)** - Retrieve paginated list of submissions with filtering and sorting
* **[Create Submission](/api-reference/submissions/create-submission)** - Create a new submission
* **[Get Submission](/api-reference/submissions/get-submission)** - Retrieve a single submission by ID
* **[Update Submission](/api-reference/submissions/update-submission)** - Update an existing submission
* **[Delete Submission](/api-reference/submissions/delete-submission)** - Soft delete a submission
* **[Attach Files to Submission](/api-reference/submissions/attach-files-to-submission)** - Attach one or more PDF files to a submission
* **[Get Submission Loss History](/api-reference/submissions/get-submission-loss-history)** - Retrieve the loss history entries on a submission
* **[Set Submission Loss History](/api-reference/submissions/set-submission-loss-history)** - Replace the loss history entries on a submission
* **[Add Submission Loss History Entries](/api-reference/submissions/add-submission-loss-history-entries)** - Append entries to the loss history on a submission

***

## Submission Status

Submissions progress through the following statuses:

| Status              | Description                                    |
| ------------------- | ---------------------------------------------- |
| `in_progress`       | Submission is being prepared                   |
| `submitted`         | Submission has been submitted for review       |
| `quote_in_progress` | Quote is being prepared                        |
| `quoted`            | Quote has been generated                       |
| `bound`             | Quote has been bound and converted to a policy |
| `declined`          | Submission was declined                        |
| `expired`           | Submission has expired                         |
| `cancelled`         | Submission was cancelled                       |

***

## Submission Type

When creating a submission via the API, use these type values:

| API Type        | Description                           |
| --------------- | ------------------------------------- |
| `quote`         | New business submission               |
| `renewal`       | Renewal of an existing policy         |
| `endorsement`   | Mid-term change to an existing policy |
| `cancellation`  | Cancellation of an existing policy    |
| `reinstatement` | Reinstatement of a cancelled policy   |

<Note>
  Use `quote` as the type for new business submissions. The API maps this to `new_business` internally.
</Note>

***

## Submission Workflow

```
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Create         │────▶│  Add Quotes     │────▶│  Bind Quote     │
│  Submission     │     │  (Quotes API)   │     │  (Creates       │
│                 │     │                 │     │   Policy)       │
└─────────────────┘     └─────────────────┘     └─────────────────┘
```

1. **Create Submission** - Use `POST /submissions` to create a new submission
2. **Add Quotes** - Use the [Quotes API](/api-legacy-reference/quotes/overview) to add quotes to the submission
3. **Bind Quote** - When a quote is bound, it becomes a policy

***

## Associated Quotes

When using `GET /submissions/{submissionId}`, submissions include a `quoteIds` array by default:

```json theme={null}
{
  "quoteIds": [
    "660e8400-e29b-41d4-a716-446655440001",
    "660e8400-e29b-41d4-a716-446655440002"
  ]
}
```

You can request expanded quote details with `expand=quotes`:

```json theme={null}
{
  "quotes": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "number": "Q00000001-01",
      "status": "complete",
      "submissionId": "550e8400-e29b-41d4-a716-446655440001",
      "applicationId": null,
      "policyId": null,
      "description": "General Liability Coverage",
      "policyCurrency": "USD",
      "grandTotal": 2500.00,
      "createdAt": "2024-01-15T11:00:00.000Z",
      "updatedAt": "2024-01-15T12:00:00.000Z"
    }
  ]
}
```

***

## List vs Get Response

The **List Submissions** endpoint returns minimal fields for performance:

| Field                  | List | Get |
| ---------------------- | ---- | --- |
| `id`                   | ✓    | ✓   |
| `companyId`            |      | ✓   |
| `number`               | ✓    | ✓   |
| `name`                 | ✓    | ✓   |
| `status`               | ✓    | ✓   |
| `type`                 | ✓    | ✓   |
| `primaryInsuredName`   | ✓    | ✓   |
| `applicationId`        | ✓    | ✓   |
| `renewingPolicyId`     |      | ✓   |
| `renewingPolicyNumber` |      | ✓   |
| `declineReason`        |      | ✓   |
| `quoteIds`             |      | ✓   |
| `createdAt`            | ✓    | ✓   |
| `updatedAt`            | ✓    | ✓   |
| `closedAt`             |      | ✓   |
| `boundAt`              |      | ✓   |

***

## Nullable Fields

The following fields may be `null` in the response:

| Field                  | When null                            |
| ---------------------- | ------------------------------------ |
| `name`                 | Submission name not set              |
| `primaryInsuredName`   | No primary insured on the submission |
| `applicationId`        | Application not linked               |
| `renewingPolicyId`     | Not a renewal or policy not linked   |
| `renewingPolicyNumber` | Not a renewal or policy not linked   |
| `declineReason`        | Submission not declined              |
| `updatedAt`            | Submission has never been updated    |
| `closedAt`             | Submission not closed                |
| `boundAt`              | Submission not bound                 |

***

## Filtering and Sorting

List endpoints support comprehensive filtering and sorting options:

### Filter Parameters

| Parameter    | Type            | Description                          |
| ------------ | --------------- | ------------------------------------ |
| `status`     | string or array | Filter by submission status          |
| `type`       | string or array | Filter by submission type            |
| `filterText` | string          | Text search across submission fields |

### Sorting Parameters

| Parameter       | Type   | Default     | Description                                                       |
| --------------- | ------ | ----------- | ----------------------------------------------------------------- |
| `sortBy`        | string | `createdAt` | Field to sort by (`createdAt`, `updatedAt`, `primaryInsuredName`) |
| `sortDirection` | string | `desc`      | Sort direction (`asc` or `desc`)                                  |

### Pagination

| Parameter | Type    | Default | Description                         |
| --------- | ------- | ------- | ----------------------------------- |
| `page`    | integer | 1       | Page number (1-based, page size 50) |

**Response includes:**

* `items` - Array of submissions for the current page
* `totalCount` - Total number of matching submissions across all pages

***

## Deleting Submissions

Submissions with associated quotes cannot be deleted. You must delete all quotes first using the [Quotes API](/api-legacy-reference/quotes/overview) before deleting the submission.

***

## Permissions

Access to submissions requires the appropriate permissions based on your API key:

| Operation                  | Required Permission         |
| -------------------------- | --------------------------- |
| List Submissions           | `company.submission:read`   |
| Get Submission             | `company.submission:read`   |
| Create Submission          | `company.submission:create` |
| Update Submission          | `company.submission:update` |
| Delete Submission          | `company.submission:delete` |
| Attach Files to Submission | `submission.file:create`    |
| Set Loss History           | `submission:update`         |
| Add Loss History Entries   | `submission:update`         |

***

## Example List Response

```json theme={null}
{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "number": "SUB-2024-001",
      "name": "Acme Corp Submission",
      "status": "quoted",
      "type": "new_business",
      "primaryInsuredName": "Acme Corporation",
      "applicationId": "550e8400-e29b-41d4-a716-446655440010",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-16T14:20:00.000Z"
    }
  ],
  "totalCount": 150
}
```

***

## Example Get Response

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "companyId": "660e8400-e29b-41d4-a716-446655440000",
  "number": "SUB-2024-001",
  "name": "Acme Corp Submission",
  "status": "quoted",
  "type": "new_business",
  "primaryInsuredName": "Acme Corporation",
  "applicationId": "550e8400-e29b-41d4-a716-446655440010",
  "renewingPolicyId": null,
  "renewingPolicyNumber": null,
  "declineReason": null,
  "quoteIds": [
    "660e8400-e29b-41d4-a716-446655440001",
    "660e8400-e29b-41d4-a716-446655440002"
  ],
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-16T14:20:00.000Z",
  "closedAt": null,
  "boundAt": null
}
```

***