This content applies solely to Connected Underwriting Life, which must be purchased separately from the Appian base platform. This content was written for Appian 23.4 and may not reflect the interfaces or functionality of other Appian versions. |
IntroductionCopy link to clipboard
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.
EndpointCopy link to clipboard
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 StructureCopy link to clipboard
HeadersCopy link to clipboard
Clients must send a Content-Type header as application/json
. This is standard behavior for Appian API objects.
Query ParametersCopy link to clipboard
There are no expected query parameters that should be sent in a request to the Create Case API.
BodyCopy link to clipboard
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 DictionaryCopy link to clipboard
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 DictionaryCopy link to clipboard
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 DictionaryCopy link to clipboard
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 |
text | Optional |
beneficiary DictionaryCopy link to clipboard
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 DictionaryCopy link to clipboard
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 DictionaryCopy link to clipboard
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 DictionaryCopy link to clipboard
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 DictionaryCopy link to clipboard
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 DictionaryCopy link to clipboard
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 DictionaryCopy link to clipboard
Within each medicalCondition dictionary, the following structure is expected:
Variable Name | Datatype | Required |
---|---|---|
medicalCondition | code | Required |
applicability | code | Required |
criminalHistory DictionaryCopy link to clipboard
Within each criminalHistory dictionary, the following structure is expected:
Variable Name | Datatype | Required |
---|---|---|
typeOfCharge | code | Required |
convictionDate | date | Required |
crimeDescription | text | Required |
travelInformation DictionaryCopy link to clipboard
Within each travelInformation dictionary, the following structure is expected:
Variable Name | Datatype | Required |
---|---|---|
typeOfTravel | code | Required |
country | code | Required |
externalPointer DictionaryCopy link to clipboard
Within each externalPointer dictionary, the following structure is expected:
Variable Name | Datatype | Required |
---|---|---|
typeOfTravel | code | Required |
country | code | Required |
Code FieldsCopy link to clipboard
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 ResponsesCopy link to clipboard
A few possible response codes can be sent back to the caller of the Create Case API:
Response Code 200Copy link to clipboard
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 400Copy link to clipboard
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 anapplicationSignedDate
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 404Copy link to clipboard
This response code is an Appian default and indicates a problem authenticating.
Response Code 500Copy link to clipboard
This response code is an Appian default and indicates there was a backend expression or process error.