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
• 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 - Retrieve paginated list of submissions with filtering and sorting
• Create Submission - Create a new submission
• Get Submission - Retrieve a single submission by ID
• Update Submission - Update an existing submission
• Delete Submission - Soft delete a submission
• Attach Files to Submission - Attach one or more PDF files to a submission
• Get Submission Loss History - Retrieve the loss history entries on a submission
• Set Submission Loss History - Replace the loss history entries on a submission
• 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

Use quote as the type for new business submissions. The API maps this to new_business internally.

---

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

{
  "quoteIds": [
    "660e8400-e29b-41d4-a716-446655440001",
    "660e8400-e29b-41d4-a716-446655440002"
  ]
}

You can request expanded quote details with expand=quotes:

{
  "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 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

{
  "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

{
  "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
}

---