Connected Underwriting Life Create Case API

Introduction

The Create Case API version 1 provides an endpoint for external systems to create a new case in your Connected Underwriting Life Workbench solution. Clients of the API are able to specify data about a case in the body of their requests. Upon successful validation of their request, the caller receives a successful response containing the case ID of the newly created case. The structure of the Create Case API mimics the structure and process of the manual creation of a case, and the same data points and validations are used in the API and the Create a Case wizard.

Endpoint

The Create Case API has a default endpoint of connected-underwriting-life-case-create. Additionally, you can append the API version to the end of the endpoint. For example, connected-underwriting-life-case-create/v1 indicates a call to the Create Case API version 1. Note that if you do not provide a version path in the endpoint, the CU Life application will use version 1 of the Create Case API by default.

Expected Request Structure

Headers

Clients must send a Content-Type header as application/json. This is standard behavior for Appian API objects.

Query Parameters

There are no expected query parameters that should be sent in a request to the Create Case API.

Body

The expected structure of a request body can be seen below:

Variable Name	Datatype	Required
productType	code	Required
isExistingCoverage	boolean	Required
existingCarrierName	text	Conditional
proposedEffectiveDate	date	Required
applicationSignedDate	date	Required
coverages	list of dictionary	Required
proposedInsured	dictionary	Required
beneficiaries	List of dictionary	Required
agent	dictionary	Required
payer	dictionary	Required
owners	List of dictionary	Required
occupation	dictionary	Optional
drivingInfo	dictionary	Optional
risk	dictionary	Optional
externalPointers	List of dictionary	Optional

coverage Dictionary

Within each coverage dictionary, the following structure is expected:

Variable Name	Datatype	Required
coverageIndicator	code	Required
coverageType	code	Required
amount	integer	Conditional
benefits	List of dictionary	Optional
benefitType	code	Required
amount	integer	Optional

benefit Dictionary

Within each benefit dictionary contained in a coverage dictionary, the following structure is expected:

Variable Name	Datatype	Required
benefitType	code	Required
amount	integer	Optional

proposedInsured Dictionary

The following structure is expected in the proposedInsured dictionary:

Variable Name	Datatype	Required
firstName	text	Required
lastName	text	Required
suffix	text	Optional
maritalStatus	code	Optional
gender	code	Optional
dateOfBirth	date	Optional
countryOfBirth	code	Optional
citizenship	code	Required
socialSecurityNumber	text	Conditional
immigrationNumber	text	Conditional
addressLine1	text	Optional
addressLine2	text	Optional
addressCity	text	Optional
addressState	code	Optional
addressZip	text	Optional
yearsAtAddress	integer	Optional
phoneNumberType	code	Optional
phoneNumber	text	Optional
email	text	Optional

beneficiary Dictionary

Within each dictionary in the beneficiaries field, the following structure is expected:

Variable Name	Datatype	Required
beneficiaryLevel	code	Required
allocationPercentage	integer	Required
entityType	code	Required
relationshipToInsured	code	Optional
firstName	text	Conditional
lastName	text	Conditional
suffix	text	Optional
dateOfBirth	date	Optional
governmentIdType	code	Optional
governmentId	text	Optional
organizationType	code	Optional
organizationName	text	Conditional

payer Dictionary

The following structure is expected in the payer dictionary:

Variable Name	Datatype	Required
entityType	code	Required
relationshipToInsured	code	Optional
firstName	text	Conditional
lastName	text	Conditional
suffix	text	Optional
organizationType	code	Optional
organizationName	text	Conditional

owners Dictionary

Within each dictionary in the owners field, the following structure is expected:

Variable Name	Datatype	Required
entityType	code	Required
relationshipToInsured	code	Optional
firstName	text	Conditional
lastName	text	Conditional
suffix	text	Optional
organizationType	code	Optional
organizationName	text	Conditional

occupation Dictionary

The following structure is expected in the occupation dictionary:

Variable Name	Datatype	Required
estimatedNetWorth	integer	Optional
estimatedSalary	integer	Optional
occupation	text	Optional
employerName	text	Optional
businessAddressLine1	text	Optional
businessAddressCity	text	Optional
businessAddressState	code	Optional
businessAddressZip	text	Optional
yearsOfEmployment	integer	Optional
employmentDuties	text	Optional

drivingInfo Dictionary

The following structure is expected in the drivingInfo dictionary:

Variable Name	Datatype	Required
hasDriversLicense	boolean	Optional
driversLicenseCountry	code	Optional
driversLicenseState	code	Optional
driversLicenseId	text	Optional
driversLicenseExpirationDate	date	Optional

risk Dictionary

The following structure is expected in the risk dictionary:

Variable Name	Datatype	Required
usesNicotine	boolean	Optional
usesControlledSubstances	boolean	Optional
usesAlcohol	boolean	Optional
weight	decimal	Optional
height	decimal	Optional
isTreatmentRecommended	boolean	Optional
isRecentlyHospitalized	boolean	Optional
medicalConditions	List of dictionary	Optional
criminalHistory	List of dictionary	Optional
plannedHazardousActivities	List of code	Optional
travelInformation	List of dictionary	Optional

medicalCondition Dictionary

Within each medicalCondition dictionary, the following structure is expected:

Variable Name	Datatype	Required
medicalCondition	code	Required
applicability	code	Required

criminalHistory Dictionary

Within each criminalHistory dictionary, the following structure is expected:

Variable Name	Datatype	Required
typeOfCharge	code	Required
convictionDate	date	Required
crimeDescription	text	Required

travelInformation Dictionary

Within each travelInformation dictionary, the following structure is expected:

Variable Name	Datatype	Required
typeOfTravel	code	Required
country	code	Required

externalPointer Dictionary

Within each externalPointer dictionary, the following structure is expected:

Variable Name	Datatype	Required
typeOfTravel	code	Required
country	code	Required

Code Fields

A few of the fields listed above have a code datatype. This means that requests must have a specific value from a predefined list provided for these fields. In the backend, these fields correspond to a specific reference data list. Failure to provide a valid value for any of these fields will result in a 400 error response.

A list of codes valid for a particular field can be found in the externalCode column of the corresponding reference data table. As additional pieces of reference data are added, values in this column can be updated so that this API or other APIs can accept the new piece of reference data across the application.

Possible Responses

A few possible response codes can be sent back to the caller of the Create Case API:

Response Code 200

This response code indicates a successful request and creation of a case in Appian. The provided response body will contain the case ID of the newly-created case.

Response Code 400

This response indicates the caller sent a bad request. Cases will not be made from requests that return a 400 error response. The response body will provide additional information on why the request was bad. Possible errorCodes contained in the response body include:

• MISSING_REQUIRED_FIELD: A field that was required in the request body was not present. The field that was missing will be provided.
• INVALID_CODE: A field that expects a code datatype did not have a valid value. The associated reference data point that had an invalid value will be provided.
• DATA_INTEGRITY_VIOLATION: Additional validations on the request body were violated. This can include a range of possibilities and mimic any additional validations present in the manual creation of a case. Possible reasons include sending duplicate medicalCondition codes, failing to have coverage with an indicator of Base, or sending an applicationSignedDate that is in the future.
• DATABASE_LENGTH_VIOLATION: A field provided in the request breached its maximum length allowed in the database. The field or fields that were too long will be provided.

Response Code 404

This response code is an Appian default and indicates a problem authenticating.

Response Code 500

This response code is an Appian default and indicates there was a backend expression or process error.

Feedback