Summary
The Great American Insurance Documents API is a REST-based API for document storage and retrieval and working with cases that are used for underwriting related workflows.
| Environment | External URL |
|---|---|
DEV |
|
UAT |
|
PROD |
Authorization
All endpoints on this API are secured with OAuth 2.0, using the client_credentials grant type.
| Environment | External URL |
|---|---|
DEV |
|
UAT |
|
PROD |
Example HTTP Request
POST /oauth/token HTTP/1.1
Authorization: Basic {{base64 encoded clientId:clientSecret}}
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentialsExample HTTP Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"api_product_list_json": [
"document-dev",
"rating-dev"
],
"token_type": "Bearer",
"access_token": "",
"expires_in": 3599,
}| Field | Type | Description |
|---|---|---|
api_product_list_json |
array |
Array of strings indicating the authorities granted to the client. |
token_type |
string |
This value should be placed in the Authorization header for API requests.
|
access_token |
string |
This value should be placed in the Authorization header for API requests.
|
expires_in |
number |
The time in seconds when the access token will expire. |
Overview
Usage notes
-
Date values must be specified in the ISO format: YYYY-MM-DD[Thh:mm:ss] (e.g.
2019-06-01,2019-06-01T14:00:00)
Documents API
Key concepts
-
Documents are categorized by a "document category" such as "claims", "underwriting", "corporate", etc.
-
Within each category, documents are defined by a "document type" such as "PolicyForms", "SpecialtyClaims", etc.
-
Each document is assigned a set of associated "metadata properties" such as "ClaimID", "AgentName", etc.
-
A single document may contain the contents of multiple files if more than one file was provided when the document was added. Each file is considered a separate "content element" identified by a unique id (e.g. 0, 1, 2). Most documents only contain a single content element with the id "0".
Adding documents
To add a document with content, send a multipart/form-data POST request with the file(s) that make up the document’s contents encoded in the files parameter.
The add documents endpoint is…
POST /api/{category}/documents/{documentType}
e.g. POST /api/underwriting/documents/PolicyForms
…and the request parameters and contents are described below.
API Path Parameters
The document category and type are specified as segments of the API endpoint URI.
| Parameter | Description |
|---|---|
|
The document category. |
|
The specific document type. |
API Request Parts
The document’s contents and metadata are specified as multipart request parts.
| Part | Description |
|---|---|
|
The file(s) to upload. |
|
The document metadata properties as a JSON object. |
The Content-type of the metadata request part must be specified as application/json.
Example requests
PolicyForms
This is an example of adding an underwriting document of type PolicyForms.
AgencyAdmin
This is an example of adding a corporate document of type AgencyAdmin.
AgencyAdminProducerContracts
This is an example of adding a corporate document of type AgencyAdminProducerContracts.
Retrieving document metadata
The endpoint for retrieving document metadata is…
GET /api/{category}/documents/{documentId}
e.g. GET /api/corporate/documents/BAD3B8B9-5FB5-CBC0-85FE-77D0B3A00000
…and the request parameters are described below.
API Path Parameters
The document category and id are specified as segments of the API endpoint URI.
| Parameter | Description |
|---|---|
|
The document category. |
|
The document id. |
Example request
This is an example of retrieving a document’s metadata.
Retrieving document content
The endpoint for retrieving the contents of a document is…
GET /api/{category}/documents/{documentId}/contents
e.g. GET /api/corporate/documents/BAD3B8B9-5FB5-CBC0-85FE-77D0B3A00000/contents
…and the request parameters are described below.
API Path Parameters
The document category and id are specified as segments of the API endpoint URI.
| Parameter | Description |
|---|---|
|
The document category. |
|
The document id. |
API Request Parameters
| Parameter | Description |
|---|---|
|
Optional. If download=true is specified, the value of the Content-Disposition header will be set to 'attachment' instead of 'inline' (the default) |
|
Optional. An explicit filename for the downloaded file. If a filename is not specified, the RetrievalName property of the requested content element will be used which is typically the name of the file that was originally uploaded. |
Example request
This is an example of retrieving a document’s contents.
Updating document metadata
The endpoint for updating a document’s metadata properties is…
PATCH /api/{category}/documents/{documentId}
e.g. PATCH /api/corporate/documents/BAD3B8B9-5FB5-CBC0-85FE-77D0B3A00000
…and the request parameters are described below.
API Path Parameters
The document category and id are specified as segments of the API endpoint URI.
| Parameter | Description |
|---|---|
|
The document category. |
|
The document id. |
Example requests
This is an example of updating a portion of the metadata for a document.
Underwriting Cases API
The cases API is used for working with cases that are associated with underwriting-based workflows.
Adding a new case
Create a new case of a specific type. The properties to associate with the newly created case are specified in the body of the request. The response will contain the complete set of properties for the newly created case.
API path parameters
| Parameter | Description |
|---|---|
|
The case category. |
|
The business unit id or name. |
|
The case type. |
Updating a case
The case properties to update are specified in the body of the request. The response will contain the complete set of properties for the updated case.
API path parameters
| Parameter | Description |
|---|---|
|
The case category. |
|
The case id. |
Retrieving a case
The response will contain the complete set of properties for the case id specified in the request URL.
API path parameters
| Parameter | Description |
|---|---|
|
The case category. |
|
The case id. |
Filing documents to a case
Filing an existing document to a case
File a document already stored in a repository to the case specified in the request URL. The response will be the added document’s metadata properties.
API path parameters
| Parameter | Description |
|---|---|
|
The case category. |
|
The case id. |
|
The document id. |
Uploading a new document and filing it to a case
To upload a new document and file it to an existing case, send a multipart/form-data POST request.
Usage Notes
-
The document content is specified as a request part parameter named
files. -
The document metadata is specified as a JSON object included as a request part parameter named
metadatathat has a content type ofapplication/json. -
Metadata date values must be specified in the ISO format: YYYY-MM-DD[Thh:mm:ss] (e.g.
2019-06-01,2019-06-01T14:00:00)
API path parameters
| Parameter | Description |
|---|---|
|
The case category. |
|
The case id. |
|
The document class. |
Getting documents filed to a case
The response will contain a list of the metadata for the documents files to the specified case.
API path parameters
| Parameter | Description |
|---|---|
|
The case category. |
|
The case id. |
Searching for cases
API path parameters
| Parameter | Description |
|---|---|
|
The case category. |
|
The business unit id or name. |
|
The case type. |
API query parameters
| Parameter | Description |
|---|---|
|
The page size |
|
The sorting parameters |
|
The page number to retrieve |
API Error Reporting
If an error occurs during the processing of an API request, a non-2xx HTTP status code is returned and the response body will contain detailed error information. The format of the response body is consistent for all errors returned to ease the implementation effort for clients consuming the API. Here is an example of an API request that returns an error response…
POST /api/documents/Claimz/SpecialtyClaims
The response status returned:
HTTP/1.1 404 Not Found
…and the body of the response containing detailed error information:
{
"timestamp": "2020-12-21T11:19:53.048309",
"status": "NOT_FOUND",
"statusCode": 404,
"errorMessage": "A repository with the specified name could not be located",
"detailedErrors": [
{
"@type": "detailedError",
"errorMessage": "The requested item was not found. Repository Claimz not found."
}
]
}Error response format
The body of the response returned for an API request that resulted in an error will contain an object with the follow properties…
| Property | Type | Description |
|---|---|---|
timestamp |
|
Date and time when the error occurred (ISO-8601 format) |
status |
|
The HTTP status description |
statusCode |
|
The HTTP status code |
errorMessage |
|
The primary error message |
detailedErrors |
|
(see below) |
The detailedErrors[] array can be used to provide fine-grained detail when an API request results in multiple errors occurring. The type of the array elements may vary on a per-error condition basis. Here is an example request with detailed error messages returned…
POST /api/documents/Business/PolicyForms
The response status returned:
HTTP/1.1 500 Internal Server Error
The body of the response contains the primary error along with more detailed error messages…
{
"timestamp": "2020-12-08T14:43:09.214229",
"status": "CONFLICT",
"statusCode": 409,
"errorMessage": "One or more validation errors occurred",
"detailedErrors": [
{
"errorMessage": "A value is required for the SubmissionId metadata property."
},
{
"errorMessage": "The provided value for the Description metadata property exceeds the maximum length of 64"
}
]
}HTTP Status Codes
Listed below are the most common HTTP status codes that are returned with the response to an API request.
Dynamic Documentation
/api/endpoints
Call this endpoint first to determine which endpoints are available to you, as a consumer. This API serves multiple business divisions, and a variety of complex insurance products. Therefore, not all endpoints apply to all consumers.
Example HTTP Request
GET /api/endpoints HTTP/1.1
Authorization: Bearer {{access_token}}Example HTTP Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"endpoints": [
"/api/example1",
"/api/example2"
]
}/api/docs
Call this endpoint to get specific request and response body details, which can vary based on factors such as the consumer, business division and product.
The /api/docs endpoint provides dynamic documentation based on those factors.
Determine the request body required by an endpoint.
Example HTTP Request
POST /api/docs HTTP/1.1
Authorization: Bearer {{access_token}}
Content-Type: application/json
{
"type": "request",
"endpoint": "/api/example1",
"format": "json",
"scope": {
"state": "OH"
}
}Determine the response body returned by an endpoint.
Example HTTP Request
POST /api/docs HTTP/1.1
Authorization: Bearer {{access_token}}
Content-Type: application/json
{
"type": "response",
"endpoint": "/api/example1",
"format": "json"
}| Field | Type | Required | Description |
|---|---|---|---|
type |
string |
true |
Valid values: |
endpoint |
string |
true |
One of the available API endpoints. |
format |
string |
true |
Valid values: |
scope |
object |
false |
Additional scoping necessary for the request. |
Endpoints
/api/application
Retrieve PDF of prefilled Application.
Example HTTP Request
POST /api/application HTTP/1.1
Authorization: Bearer {{access_token}}
Content-Type: application/json
{
see /api/docs for a sample request
}Example HTTP Response
HTTP/1.1 200 OK
Content-Type: application/json
{
see /api/docs for a sample response
}