# Sixfold API

URL: [https://sixfold.ai](https://sixfold.ai)

# Release Notes

## Version: 2024-05

- Enhances the case creation endpoint to accept documents to attach to the new case

- Add a new endpoint to attach one or more documents to an existing case

- Defines a new schema for cases and related entities

- Add Life API support for creating cases


## Version: 2023-12

For more detailed documentation of this version, refer to our [legacy API docs site](https://sixfoldai.notion.site/16cd8f2ff2e4401ab5341b7cd1618cb4?pvs=25#72d8ead57a1c49b9a3322cf002ffb32f).

# Introduction

Greetings from [Sixfold](http://sixfold.ai/)! We're excited to provide you with documentation for our API that allows you to seamlessly interact with our generative AI solution for insurance underwriters.

## Key Features

- **Analyze a risk** by [creating a case with or without documents](#operation/createCase)

- **Check in on the progress of a case** by [fetching it](#operation/getCase)

- **Receive real-time updates** on the progress of a case [via a webhook](#tag/2024-05-Webhooks)

- **Add one or more documents** [to an existing case](#operation/addDocumentsToCase)

# Getting Started

To get started with the Sixfold API, use the guides, code examples, and reference documentation on this page.

We will coordinate with you to complete the following set-up steps:

- **Base URL**: Receive a base URL specific to your environment
- **API Key**: Receive a an API key
- **Webhook URL**: Share a URL where we can send important events about a case (optional)

Read more about these steps below.

## Base URL

We will provide a base URL for your dedicated environment. This URL will be unique to your tenancy.

## API Key

We will generate and share an API key for your environment via secure send.


For more details on how to use your API key, refer to the [_Authorization_](#section/Authorization) section below.

## Webhooks

If you provide us with a [webhook](https://hookdeck.com/webhooks/guides/what-are-webhooks-how-they-work) URL, we can send you events about your cases in real time. This is an optional step, but it can be helpful if you need to know quickly when a case changes state.


For more details on how to use webhooks, refer to the [_Webhooks_ section](#tag/2024-05-Webhooks) below.

## Integrations

To configure an integration with a third-party (such as an external file management service such as FileNet), please refer to [this section](#tag/Integrations-Overview) for additional information.

We currently support integrations with the following services:

- **FileNet**: [IBM's document management system](https://www.ibm.com/products/filenet-content-manager)
  - see [this section](#tag/IBM-FileNet-Content-Manager) for more information on this integration



# Security

## Transport Layer Security

We require all API calls to be made over secure connections using HTTPS. We require a minimum of TLS 1.2.

## Authorization

You MUST include the Sixfold API key you were issued in a custom header for each API request.


**Example:** `SIXFOLD-API-KEY: <your key>`


# Field Types

| Type | Description | Example |
| --- | --- | --- |
| IDS | Object identifiers are unique opaque strings. Clients should not attach any specific semantic meaning to the format of our IDs. For example, our object IDs are [UUIDs](https://en.wikipedia.org/wiki/Universally_unique_identifier) today, but clients should not count on that behavior, because we may stop using UUIDs at any time.  | `c4fb4c10-5b2e-4220-90d2-96d94337e8e6` |
| STRINGS | Strings are encoded using UTF-8. They do not have character limits. | `Diamond West Construction` |
| DATES | All dates are represented in ISO 8601 format `YYYY-MM-DD`. | `2024-01-10` |
| TIMESTAMPS | All object responses will include a `createdAt` and `updatedAt` in timestamp format. All timestamps are UTC and represented in ISO 8601 format `YYYY-MM-DDThh:mm:ssZ`. | `2024-01-10T16:00:30Z` |
| BOOLEANS | Boolean values are represented as as `true` or `false`. | `true` |
| NULL | All optional fields are set to `null` unless a default value is set. | `null` |

# Status Codes & Errors

## Status Codes

| Code | Description |
| --- | ----------- |
| 200 | OK. Indicates the request was successful. |
| 201 | Created. Indicates that the request was successful and has led to the creation of a resource. |

## Error Codes

| Code | Description |
| --- | --- |
| 400 | Bad Request. Occurs when your request is malformed in some way that does not match a more specific 4xx code. |
| 401 | Unauthorized. Occurs when your request omitted an API key or specified an invalid key. |
| 404 | Not Found. Occurs when you requested a resource which doesn’t exist. This could signify an incorrect API endpoint URL or an incorrect object ID. |
| 413 | Content Too Large. Occurs when the size of the request entity exceeds the limit defined in the request limits section below. |
| 429 | Too Many Requests. Occurs when exceeding the request rate limit defined in the request limits section below.  |
| 500 | Internal Server Error. Occurs when Sixfold encounters an error serving the request. This is a usually a temporary occurrence, so your best bet is to retry again after a short time. |
| 503 | Service Unavailable. Typically occurs when the API is down for maintenance. |

## Document Errors

When creating a case or attaching documents to a case, each document must be uploaded as a separate file.

### Partial Success

When uploading multiple documents, the API supports **partial success**: some documents may be accepted while others are rejected in the same request.

| Scenario | HTTP Status | Response |
| --- | --- | --- |
| All documents valid | 201 | `data` array with all uploaded documents |
| Some documents valid, some invalid | 201 | `data` array with valid documents, `errors` array with rejected documents |
| All documents invalid | 422 | `errors` array only |

**Important:** Clients should always check for the presence of an `errors` array even when receiving a `2xx` response. A successful status code indicates at least one document was processed, but some documents may have been rejected.

### Example: Partial Success Response

```json
{
  "data": [
    {
      "id": "c4fb4c10-5b2e-4220-90d2-96d94337e8e6",
      "type": "commercialDocuments",
      "attributes": {
        "filename": "policy.pdf",
        "contentType": "application/pdf",
        "byteSize": 102400,
        "createdAt": "2024-05-01T12:00:00Z",
        "updatedAt": "2024-05-01T12:00:00Z"
      }
    }
  ],
  "errors": [
    {
      "title": "Invalid document",
      "detail": "data.csv failed: Content type is not supported. Check the list of supported content types",
      "code": "invalid-document",
      "source": {
        "document": "data.csv"
      },
      "status": 422
    }
  ]
}
```

### Common Rejection Reasons

Documents may be rejected for the following reasons:

- **Unsupported content type**: The file type is not in the list of accepted content types (see [Document Types](#section/Limits/Document-Types) below). For example, CSV files (`text/csv`) are not supported.
- **Encrypted files**: Password-protected or encrypted Microsoft Office files cannot be processed.

# Versioning

Our API uses URI date-based versioning.


**Example**: `POST /api/2023-12/cases`


We will always issue a new version of our API if we need to make changes that would break existing clients. Some examples of breaking changes include:

- Removing functionality

- Renaming parameters

- Changing endpoint requirements


We may include backward-compatible changes in the current version of our API. These changes are designed to improve the API without breaking existing clients. Examples include:


- Adding new API endpoints

- Adding new optional request parameters to existing API methods

- Adding new fields to existing API responses

# Limits

This section describes how limits are applied in the Sixfold API.

## Document Types

There is restrictions on what types of documents can be uploaded. 

### Commercial
The following content types are accepted for commercial cases:

| Content Type | Extension   |
| --- |-------------|
|  application/pdf   | .pdf        |
|  application/json   | .json       |
|  image/jpeg   | .jpeg, .jpg |
|  image/tiff   | .tiff, .tif |
|  image/png   | .png        |
|  text/plain   | .txt        |
|  text/html   | .html       |
|  application/msword   | .doc        |
|  application/vnd.openxmlformats-officedocument.wordprocessingml.document   | .docx       |
|  application/vnd.ms-powerpoint   | .ppt        |
|  application/vnd.openxmlformats-officedocument.presentationml.presentation   | .pptx       |
|  application/vnd.ms-excel   | .xls        |
|  application/vnd.openxmlformats-officedocument.spreadsheetml.sheet   | .xlsx       |
|  application/rtf   | .rtf        |
|  image/bmp   | .bmp        |
|  image/gif   | .gif        |

### Life

The following content types are accepted for life cases:

| Content Type | Extension   |
| --- |-------------|
|  application/pdf | .pdf        |
|  application/json | .json       |
|  image/jpeg  | .jpeg, .jpg |
|  image/tiff  | .tiff, .tif |
|  image/png   | .png        |
|  text/plain  | .txt        |
|  text/html   | .html       |
|  application/xhtml+xml | .xml        |

## Request Rate

You may not send more than 300 requests per minute. If you exceed this limit, the server will respond with `429 - Too Many Requests` and block further requests for a short time.

## Request Size

No request body may be larger than **50 megabytes**. If you exceed this limit, the server will respond with `413 - Content Too Large`.

Version: 2024-05

## Servers

The tenant-specific subdomain.
```
https://{tenant}.sixfold.{tld}/api
```

Variables:
- `tenant`: The tenant-specific subdomain.
Default: "api"
- `tld`: The tld (top-level domain) of a customer's Sixfold tenant. In most cases the tld will be `app`.
Default: "app"

## Security

### ApiKeyAuth

Your API key should be included as a custom authorization header

Type: apiKey
In: header
Name: SIXFOLD-API-KEY

## Download OpenAPI description

[Sixfold API](https://sixfold-api-documentation.redocly.app/_bundle/openapi/openapi.yaml)

## Cases

Create, retrieve, and manage commercial insurance cases

### Create a commercial case

 - [POST /2024-05/commercial/cases](https://sixfold-api-documentation.redocly.app/openapi/openapi/2024-05-commercial-cases/createcase.md): If the request omits name or insured information, the endpoint automatically extracts the missing company information from uploaded documents.

Note: Document upload is required when relying on automatic field extraction.

### Get all commercial cases

 - [GET /2024-05/commercial/cases](https://sixfold-api-documentation.redocly.app/openapi/openapi/2024-05-commercial-cases/getallcases.md)

### Get a commercial case

 - [GET /2024-05/commercial/cases/{case_id}](https://sixfold-api-documentation.redocly.app/openapi/openapi/2024-05-commercial-cases/getcase.md)

### Export a commercial case as PDF

 - [GET /2024-05/commercial/cases/{case_id}.pdf](https://sixfold-api-documentation.redocly.app/openapi/openapi/2024-05-commercial-cases/exportcaseaspdf.md)

### Export case narrative as Word document

 - [GET /2024-05/commercial/cases/{case_id}/narrative.docx](https://sixfold-api-documentation.redocly.app/openapi/openapi/2024-05-commercial-cases/exportcasenarrativeasdocx.md): Export the underwriting narrative for a commercial case as a Microsoft Word document (.docx).

The narrative contains AI-generated sections summarizing key aspects of the case analysis,
including risk assessment, business classification, and underwriting recommendations.

Note: This endpoint will return a 409 Conflict error if the case is still being processed.
Wait for the case analysis to complete before requesting the narrative export.

## Documents

Add documents to commercial insurance cases for analysis

### Add documents to a commercial case

 - [POST /2024-05/commercial/cases/{case_id}/documents](https://sixfold-api-documentation.redocly.app/openapi/openapi/2024-05-commercial-documents/adddocumentstocase.md)

## Quotes

Retrieve AI-generated insurance quotes based on case analysis

### Set or update case quote status

 - [POST /2024-05/commercial/cases/{case_id}/quote](https://sixfold-api-documentation.redocly.app/openapi/openapi/2024-05-commercial-quotes/addorupdatequotetocase.md): Creates or updates the quote status for a commercial case. Use the status parameter (recommended) with one of
quoted, not_quoted, bound, not_taken_up, or declined. Send status: null to clear the quote status.

The quoted boolean is deprecated; use status instead. Requests that send only quoted will succeed but
return Deprecation: true and X-Deprecation-Warning response headers.

### Remove quote status from a commercial case

 - [DELETE /2024-05/commercial/cases/{case_id}/quote](https://sixfold-api-documentation.redocly.app/openapi/openapi/2024-05-commercial-quotes/deletequotefromcase.md): Deletes the quote record for the case. Returns 204 even if the case had no quote. Requires case delete permission.

## Cases

Create, retrieve, and manage life insurance cases

### Create a life case

 - [POST /2024-05/life/cases](https://sixfold-api-documentation.redocly.app/openapi/openapi/2024-05-life-cases/createlifecase.md)

### Get all life cases

 - [GET /2024-05/life/cases](https://sixfold-api-documentation.redocly.app/openapi/openapi/2024-05-life-cases/getalllifecases.md)

### Get a life case

 - [GET /2024-05/life/cases/{case_id}](https://sixfold-api-documentation.redocly.app/openapi/openapi/2024-05-life-cases/getlifecase.md)

### Export a life case as PDF

 - [GET /2024-05/life/cases/{case_id}.pdf](https://sixfold-api-documentation.redocly.app/openapi/openapi/2024-05-life-cases/exportlifecaseaspdf.md)

## Documents

Add documents to life insurance cases for analysis

### Add documents to a life case

 - [POST /2024-05/life/cases/{case_id}/documents](https://sixfold-api-documentation.redocly.app/openapi/openapi/2024-05-life-documents/adddocumentstolifecase.md): Add documents to a life case by providing an array of documents to be uploaded. When submitting via multipart/form-data, use indexed notation (documents0, documents0, etc.).

## Facts

Retrieve facts extracted from case documents

### Get all facts for a case

 - [GET /2024-05/life/cases/{case_id}/facts](https://sixfold-api-documentation.redocly.app/openapi/openapi/2024-05-life-facts/getlifecasefacts.md): Retrieves all facts for a case with pagination. Facts include medications, diagnoses, procedures, clinical data, family history, and lifestyle information. Conditions are accessed via the /conditions endpoints.

### Get a single fact for a life case

 - [GET /2024-05/life/cases/{case_id}/facts/{fact_id}](https://sixfold-api-documentation.redocly.app/openapi/openapi/2024-05-life-facts/getlifecasefact.md): Retrieves a single fact by its unique identifier

## Conditions

Retrieve medical conditions and their supporting evidence

### Get all conditions for a life case

 - [GET /2024-05/life/cases/{case_id}/conditions](https://sixfold-api-documentation.redocly.app/openapi/openapi/2024-05-life-conditions/getlifecaseconditions.md): Retrieves all conditions for a case with pagination. Each condition includes an array of related facts that support or provide evidence for the condition.

### Get a single condition for a life case

 - [GET /2024-05/life/cases/{case_id}/conditions/{condition_id}](https://sixfold-api-documentation.redocly.app/openapi/openapi/2024-05-life-conditions/getlifecasecondition.md): Retrieves a single condition by its unique identifier, including an array of related facts that support or provide evidence for the condition.

### Get facts related to a condition

 - [GET /2024-05/life/cases/{case_id}/conditions/{condition_id}/facts](https://sixfold-api-documentation.redocly.app/openapi/openapi/2024-05-life-conditions/getlifecaseconditionfacts.md): Retrieves a paginated list of facts that provide supporting evidence for the condition (medications, diagnoses, procedures, clinical data, etc.). Note that relatedConditions is not included in the response for this endpoint since the relationship to the condition is already implied.

## Integrations

Manage integration metadata for external systems

### Add metadata to an integration of a life case

 - [PATCH /2024-05/life/cases/{case_id}/integrations/{integration_id}](https://sixfold-api-documentation.redocly.app/openapi/openapi/2024-05-life-integrations/adddetailstointegrationoflifecase.md): Add to an integration by providing metadata to the integration spec