# Insurance
# Insurance
Which mortgage-insurance carriers a loan qualifies for, determined across the carrier roster in a committed order.
A caller sends the loan and borrower. The product works down the carrier ordering below and returns the carriers willing to insure the loan, with the terms each offered.
The carriers are the licensed mortgage-insurance writers; the ordering is the committed sequence in the product's own configuration.
## How it works
Eligibility and pricing are separate steps here. A carrier can be eligible and uncompetitive, so the response carries every carrier that qualified rather than a single selection, and the choice is left to the caller.
The premium structures this feeds are modelled on the contract side, in Insurance, which carries the four premium types and their effect on closing costs.
## Dual listing
Insurance is filed under two categories. The other listing is Insurance under Contract, and neither listing carries a recorded specification.
## Operations
### Setup
`POST` `/{partner_name}/partners-configurations`
#### Set Partners Configurations
`setConfigurations`
Set Partner Configurations
By using Set partners Configurations API we allow our customers to configure partners' connectivity data in customer environment.
If you want to use your own partner contract for Checking Eligibility Insurance, please check Request body Schema example for required values from partner side and run Set partner Configurations API.
You can check the partner status by calling the Retrieve Partners endpoint
Show the rest
#### Arch mapping
| partner attribute | mapped attribute | description |
| --- | --- | --- |
| "masterPolicyNumber" | partners[0].with_partner_configuration.with_customer.has_organization_identifier.has_value | Customer's Arch MI provided active master policy number |
| "email_id" | partners[0].with_partner_configuration.with_customer.contact_at.has_email_address.has_value | Customer email address |
| "loanProgram" | partners[0].with_partner_configuration.with_customer.with_custom_field | Customer's Special pricing value, optional |
| "quotename" | partners[0].with_partner_configuration.with_customer.with_custom_field | Customer's Arch MI quote name |
| "nmls_no" | partners[0].with_partner_configuration.with_customer.with_license.has_license_identifier.has_value | Customer's "NMLS" number of the user requesting the quote. |
| "OriginationChannel" | partners[0].with_partner_configuration.with_customer.with_role.has_party_role_type.has_value | Customer is Lender or Broker |
| "secondary_provider_identifier" | partners[0].with_partner_configuration.with_secondary_provider.has_organization_identifier.has_value | A unique number assigned by Arch MI to identify secondary service providers. |
| "environment type" | partners[0].with_partner_configuration.with_partner_environment.has_partner_environment_type.has_value | Test/Production |
#### NationalMI mapping
| partner attribute | mapped attribute | description |
| --- | --- | --- |
| "email_id" | partners[0].with_partner_configuration.with_customer.contact_at.has_email_address.has_value | Customer's email address |
| "nmls_id" | partners[0].with_partner_configuration.with_customer.with_license.has_license_identifier.has_value | Customer's "NMLS" number |
| "LenderIdentifier" | partners[0].with_partner_configuration.with_customer.has_organization_identifier.has_value | Customer's unique number identifier. |
| "environment type" | partners[0].with_partner_configuration.with_partner_environment.has_partner_environment_type.has_value | Test/Production |
#### Radian mapping
| partner attribute | mapped attribute | description |
| --- | --- | --- |
| "email_id" | partners[0].with_partner_configuration.with_customer.contact_at.has_email_address.has_value | Customer Email Address |
| "MILenderIdentifier" | partners[0].with_partner_configuration.with_customer.has_organization_identifier.has_value | Customer's unique number identifier. |
| "environment type" | partners[0].with_partner_configuration.with_partner_environment.has_partner_environment_type.has_value | Test/Production |
#### Enact mapping
| partner attribute | mapped attribute | description |
| --- | --- | --- |
| "originator_postal_code" | partners[0].with_partner_configuration.with_customer.with_address.has_postal_code.has_value | Customer's postal code |
| "originator_state_code" | partners[0].with_partner_configuration.with_customer.with_address.has_state_code.has_value | Customer's state code |
| "originator_address" | partners[0].with_partner_configuration.with_customer.with_address.has_address_line_1_text.has_value | Customer's address |
| "MILenderIdentifier" | partners[0].with_partner_configuration.with_customer.has_organization_identifier.has_value | Customer's unique number identifier. |
| "environment type" | partners[0].with_partner_configuration.with_partner_environment.has_partner_environment_type.has_value | Test/Production |
#### MGIC mapping
| partner attribute | mapped attribute | description |
| --- | --- | --- |
| "MILenderIdentifier" | partners[0].with_partner_configuration.with_customer.has_organization_identifier.has_value | Customer's unique number identifier. |
| "originator_channel" | partners[0].with_partner_configuration.with_secondary_provider.has_organization_identifier.has_value | Customer is Lender or Broker |
| "secondary_provider_identifier" | partners[0].with_partner_configuration.with_secondary_provider.has_organization_identifier.has_value | A unique number assigned by MGIC to identify secondary service providers. |
| "environment type" | partners[0].with_partner_configuration.with_partner_environment.has_partner_environment_type.has_value | Test/Production |
##### Request
Arch Configuration ExampleMGIC Configurations ExampleNationalMI Configurations ExampleEssent Configuration ExampleEnact Configurations ExampleRadian Configurations Example
application/json Copy
```
{
"partners": [
{
"@type": "partner",
"has_organization_name": {
"has_value": "arch"
},
"with_partner_configuration": [
{
"@type": "partner_configuration",
"with_customer": [
{
"@type": "customer",
"has_organization_identifier": {
"has_value": "lenderidentifier/policy_number"
},
"with_license": [
{
"@type": "license",
"has_license_identifier": {
"has_value": "nmlsno"
}
}
],
"with_role": [
{
"@type": "role",
"has_party_role_type": {
"has_value": "lender"
}
}
],
"contact_at": [
{
"@type": "contact_information",
"has_email_address": {
"has_value": "emailId"
}
}
]
}
],
"with_partner_environment": [
{
"@type": "partner_environment",
"has_partner_environment_type": {
"has_value": "test"
}
}
]
}
]
}
]
}
```
application/json Copy
```
{
"partners": [
{
"@type": "partner",
"has_organization_name": {
"has_value": "mgic"
},
"with_partner_configuration": [
{
"@type": "partner_configuration",
"with_customer": [
{
"@type": "customer",
"has_organization_identifier": {
"has_value": "lenderidentifier/policy_number"
},
"with_role": [
{
"@type": "role",
"has_party_role_type": {
"has_value": "lender"
}
}
]
}
],
"with_partner_environment": [
{
"@type": "partner_environment",
"has_partner_environment_type": {
"has_value": "test"
}
}
],
"with_secondary_provider": [
{
"@type": "secondary_provider",
"has_organization_identifier": {
"has_value": "secondaryProviderIdentifier"
}
}
]
}
]
}
]
}
```
application/json Copy
```
{
"partners": [
{
"@type": "partner",
"has_organization_name": {
"has_value": "nationalmi"
},
"with_partner_configuration": [
{
"@type": "partner_configuration",
"with_customer": [
{
"@type": "customer",
"has_organization_name": {
"has_value": "customer_name"
},
"has_organization_identifier": {
"has_value": "lenderidentifier/policy_number"
},
"with_license": [
{
"@type": "license",
"has_license_identifier": {
"has_value": "nmlsno"
}
}
],
"contact_at": [
{
"@type": "contact_information",
"has_email_address": {
"has_value": "emailId"
}
}
]
}
],
"with_partner_environment": [
{
"@type": "partner_environment",
"has_partner_environment_type": {
"has_value": "test"
}
}
]
}
]
}
]
}
```
application/json Copy
```
{
"partners": [
{
"@type": "partner",
"has_organization_name": {
"has_value": "essent"
},
"with_partner_configuration": [
{
"@type": "partner_configuration",
"with_customer": [
{
"@type": "customer",
"has_organization_name": {
"has_value": "customer_name"
},
"has_organization_identifier": {
"has_value": "lenderidentifier/policy_number"
}
}
],
"with_partner_environment": [
{
"@type": "partner_environment",
"has_partner_environment_type": {
"has_value": "test"
}
}
]
}
]
}
]
}
```
application/json Copy
```
{
"partners": [
{
"@type": "partner",
"has_organization_name": {
"has_value": "enact"
},
"with_partner_configuration": [
{
"@type": "partner_configuration",
"with_customer": [
{
"@type": "customer",
"has_organization_name": {
"has_value": "customer_name"
},
"has_organization_identifier": {
"has_value": "lenderidentifier/policy_number"
},
"with_address": [
{
"@type": "address",
"has_postal_code": {
"has_value": "customer postal_code"
},
"has_state_code": {
"has_value": "customer state_code"
},
"has_address_line_1_text": {
"has_value": "customer address"
}
}
]
}
],
"with_partner_environment": [
{
"@type": "partner_environment",
"has_partner_environment_type": {
"has_value": "test"
}
}
]
}
]
}
]
}
```
application/json Copy
```
{
"partners": [
{
"@type": "partner",
"has_organization_name": {
"has_value": "radian"
},
"with_partner_configuration": [
{
"@type": "partner_configuration",
"with_customer": [
{
"@type": "customer",
"has_organization_identifier": {
"has_value": "lenderidentifier/policy_number"
},
"has_organization_name": {
"has_value": "customer_name"
},
"contact_at": [
{
"@type": "contact_information",
"has_email_address": {
"has_value": "emailId"
}
}
]
}
],
"with_partner_environment": [
{
"@type": "partner_environment",
"has_partner_environment_type": {
"has_value": "test"
}
}
]
}
]
}
]
}
```
##### Response
200400403422500
application/json Copy Setup API Triggered Successfully
```
{
"message": "Configurations are saved"
}
```
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
application/json Copy The product has encountered an internal server error
```
{
"message": "The product has encountered an internal server error"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Staircase Environment API Key |
| `partner_name` required | `string` path | `nationalmi` | Partner name |
##### Response `200``application/json`
1 fields
Setup API Triggered Successfully
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `422``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `500``application/json`
1 fields
The product has encountered an internal server error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
##### Other responses
`404`
`GET` `/{partner_name}/partner-configuration-schema`
#### Retrieve Partner Configurations Schema
`getConfigurations`
Get Partners Configurations Schema
Get Partner configurations schema for specific partner. You can use retrieved schema for updating the partner configurations.
##### Response
400403422500
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
application/json Copy Invalid key for service
```
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
```
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
application/json Copy The product has encountered an internal server error
```
{
"message": "The product has encountered an internal server error"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Staircase Environment API Key |
| `partner_name` required | `string` path | `nationalmi` | Partner name |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `403``application/json`
2 fields
Invalid key for service
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | — |
| `url` | `string` | — |
##### Response `422``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `500``application/json`
1 fields
The product has encountered an internal server error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message |
##### Other responses
`200``404`
### Operations
`POST` `/insurance`
#### Create Insurance
`post-insurance`
##### Request
application/json Copy
```
{
"transaction_id": "uhz6t54e-9d74-g17e-99ca-a36b30vdfd35",
"collection_id": "hg62e49f-9d74-g17e-99ca-a36b30vdfd35",
"partner_name": "PartnerName"
}
```
##### Response
application/json Copy Insurance request created successfully.
```
{
"collection_id": "e4502ed2-8df8-4b8f-84bd-a1097e999a77",
"message": "When ready, data will be available under the following collection_id. Use this new collection_id to get the execution status."
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Authorization key |
##### Request body`application/json`
3 fields
| Field | Type | Description |
| --- | --- | --- |
| `transaction_id`required | `string` | Transaction ID |
| `collection_id`required | `string` | Collection ID |
| `partner_name`required | `string` | — |
##### Response `200``application/json`
2 fields
Insurance request created successfully.
| Field | Type | Description |
| --- | --- | --- |
| `collection_id` | `string` | Collection ID |
| `message` | `string` | Message |
`GET` `/insurance/elements`
#### Retrieve Elements
`get-insurance-elements`
Retrieve Elements provides a list of the elements needed to invoke a partner product.
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Authorization key |
##### Response `200``application/json`
1 fields
Elements needed for request.
| Field | Type | Description |
| --- | --- | --- |
| `elements` | `object` | List of elements |
`POST` `/insurance/elements/complete`
#### Validate Collection
`post-insurance-collection-complete`
Validate Collection validates that a collection contains all of the elements needed to invoke a partner product.
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Authorization key |
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `collection`required | `object` | — |
##### Response `400``application/json`
2 fields
Collection is invalid.
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message |
| `errors` | `object` | List of elements that are missing |
##### Other responses
`200`
`GET` `/insurance/status/{transaction_id}/{collection_id}`
#### Retrieve Status
`get-insurance-status`
Retrieve Status checks status of your request. Possible statuses:
- REQUEST_MADE
- REQUEST_ACCEPTED
- WAITING_FOR_RESPONSE
- COMPLETED
##### Response
200400
application/json Copy Statuses include: * REQUEST_MADE * REQUEST_ACCEPTED
* WAITING_FOR_RESPONSE
* COMPLETED
```
{
"status": "COMPLETED"
}
```
application/json Copy Status is unavailable
```
{
"error": "Request for specified transaction_id and collection_id was not found!"
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `transaction_id` required | `string` path | `9u8z7t65-cb71-4f20-8e40-7a829b52e91e` | Transaction ID |
| `collection_id` required | `string` path | `e4502ed2-8df8-4b8f-84bd-a1097e999a77` | Collection ID |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Authorization key |
##### Response `200``application/json`
1 fields
Statuses include: * REQUEST_MADE
* REQUEST_ACCEPTED
* WAITING_FOR_RESPONSE
* COMPLETED
| Field | Type | Description |
| --- | --- | --- |
| `status` | `object` | Current execution status |
##### Response `400``application/json`
1 fields
Status is unavailable
| Field | Type | Description |
| --- | --- | --- |
| `error` | `string` | Error message |
`POST` `/insurance/transactions`
#### Create Transaction
`post-insurance-transaction`
Create Transaction creates a transaction in Staircase. A transaction in Staircase is an acknowledgement that you want to call a Staircase product. It's a container for everything associated with that product invocation, and is correlated with a collection related to the product (e.g. a document). You need to create a new transaction every time you want to connect with a Staircase product. Staircase then associates everything, from a data and API execution standpoint, to that transaction.
##### Response
application/json Copy Transaction successfully created.
```
{
"transaction_id": "a34c40a6-3c02-44f9-a696-cd7388f506d3"
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Authorization key |
##### Response `200``application/json`
1 fields
Transaction successfully created.
| Field | Type | Description |
| --- | --- | --- |
| `transaction_id` | `string` | Transaction ID |
`POST` `/insurance/transactions/{transaction_id}/collections`
#### Create Collection
`post-insurance-collection`
Create Collection creates a collection of elements . The elements within the collection are required.
##### Request
application/json Copy
```
{
"sets": {
"set": [
{
"elements": {
"element": [
{
"property_entry": {
"property_entries": {
"datetime": "2020-08-25",
"description": "Description of property",
"event_type": "TestType"
}
},
"property_class": {
"property_clases": {
"type": "STATEMENT"
},
"name": "Test",
"period_start_date": "2020-07-01",
"period_end_date": "2020-07-31"
},
"content": {
"foreign_object": "7e62ce76-d93d-4f31-92d3-45c2cb8255ea"
}
}
]
}
}
]
}
}
```
##### Response
application/json Copy Collection successfully created.
```
{
"collection_id": "hg62e49f-9d74-g17e-99ca-a36b30vdfd35",
"data": {
"sets": {
"set": [
{
"elements": {
"element": [
{
"property_entry": {
"property_entries": {
"datetime": "2020-08-25",
"description": "Description of property",
"event_type": "TestType"
}
},
"property_class": {
"property_clases": {
"type": "STATEMENT"
},
"name": "Test",
"period_start_date": "2020-07-01",
"period_end_date": "2020-07-31"
},
"content": {
"foreign_object": "7e62ce76-d93d-4f31-92d3-45c2cb8255ea"
}
}
]
}
}
]
}
},
"metadata": {},
"transaction_id": "6t5r4wq1-9d74-g17e-99ca-a36b30vdfd35"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `transaction_id` required | `string` path | `3wet53r4-cb71-8u74-8e40-7a829b52e91e` | Transaction ID |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Authorization key |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `data`required | `object` | — |
| `metadata` | `object` | — |
##### Response `200``application/json`
4 fields
Collection successfully created.
| Field | Type | Description |
| --- | --- | --- |
| `transaction_id` | `object` | Transaction ID |
| `collection_id` | `object` | Collection ID |
| `data` | `object` | Data object |
| `metadata` | `object` | Metadata object |
`PUT` `/insurance/transactions/{transaction_id}/collections/{collection_id}`
#### Update Collection
`put-insurance-collection`
Update Collection updates a collection of elements by new elements.
##### Request
application/json Copy
```
{
"sets": {
"set": [
{
"properties": {
"property": [
{
"propety_entry": {
"propety_entries": {
"datetime": "2020-05-05",
"description": "Test Description",
"event_type": "TestType"
}
},
"propety_class": {
"propety_classes": {
"type": "TestType"
},
"name": "TestName",
"period_start_date": "2019-01-01",
"period_end_date": "2019-12-31"
},
"content": {
"foreign_object": "7z6t5r4e-d93d-4f31-92d3-45c2cb8255ea"
}
}
]
}
}
]
}
}
```
##### Response
application/json Copy Collection successfully updated
```
{
"collection_id": "hg62e49f-9d74-g17e-99ca-a36b30vdfd35",
"data": {
"sets": {
"set": [
{
"properties": {
"property": [
{
"property_data": {
"property_class": {
"datetime": "2020-05-05",
"description": "Info",
"event_type": "TestEvent"
}
},
"document_classification": {
"document_classes": {
"type": "TestType"
},
"name": "TestName",
"period_start_date": "2019-01-01",
"period_end_date": "2019-12-31"
},
"content": {
"foreign_object": "7z6t5r4e-d93d-4f31-92d3-45c2cb8255ea"
}
}
]
}
}
]
}
},
"metadata": {},
"transaction_id": "6t5r4wq1-9d74-g17e-99ca-a36b30vdfd35"
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `transaction_id` required | `string` path | `3wet53r4-cb71-8u74-8e40-7a829b52e91e` | Transaction ID |
| `collection_id` required | `string` path | `9u8z7t65-cb71-8u74-8e40-7a829b52e91e` | Transaction ID |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | API Key |
##### Request body`application/json`
2 fields
| Field | Type | Description |
| --- | --- | --- |
| `data`required | `object` | — |
| `metadata` | `object` | — |
##### Response `200``application/json`
4 fields
Collection successfully updated
| Field | Type | Description |
| --- | --- | --- |
| `transaction_id` | `object` | Transaction ID |
| `collection_id` | `object` | Collection ID |
| `data` | `object` | Data object |
| `metadata` | `object` | Metadata object |
`POST` `/mortgage-insurance`
#### Create Mortgage Insurance
`post-mortgage-insurance`
Create Mortgage Insurance creates views of rate finders, MI servicing and loss management services from your choice of products and partners.
##### Request
application/json Copy
```
{
"transaction_id": "uhz6t54e-9d74-g17e-99ca-a36b30vdfd35",
"collection_id": "hg62e49f-9d74-g17e-99ca-a36b30vdfd35",
"partner_name": "PartnerName"
}
```
##### Response
application/json Copy Mortgage Insurance request created successfully.
```
{
"collection_id": "e4502ed2-8df8-4b8f-84bd-a1097e999a77",
"message": "When ready, data will be available under the following collection_id. Use this new collection_id to get the execution status."
}
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Authorization key |
##### Request body`application/json`
3 fields
| Field | Type | Description |
| --- | --- | --- |
| `transaction_id`required | `string` | Transaction ID |
| `collection_id`required | `string` | Collection ID |
| `partner_name`required | `string` | — |
##### Response `200``application/json`
2 fields
Mortgage Insurance request created successfully.
| Field | Type | Description |
| --- | --- | --- |
| `collection_id` | `string` | Collection ID |
| `message` | `string` | Message |
## Providers
- Arch MI
- Enact
- Essent
- MGIC
- National MI
- Radian
## Field mapping
| Provider | Flow | Canonical in | Vendor in | Vendor out | Canonical out |
| --- | --- | --- | --- | --- | --- |
| Essent | `essent-insurance-flow` | `staircase-graph` | `essent-input` | `essent-output` | `staircase-graph` |
## Errors
`400``403``404``422``500`
## More in Eligibility
- Previous product: Government
- Next product: Rating