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

application/json

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

application/json

Setup API Triggered Successfully

{
  "message": "Configurations are saved"
}

application/json

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"
}

Parameters

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 `200application/json`

1 fields

Setup API Triggered Successfully

Field	Type	Description
`message`	`string`	Message

Response `400application/json`

1 fields

Request data failed validation

Field	Type	Description
`message`	`string`	Message

Response `403application/json`

2 fields

Invalid key for service

Field	Type	Description
`message`	`string`	—
`url`	`string`	—

Response `422application/json`

1 fields

Request data failed validation

Field	Type	Description
`message`	`string`	Message

Response `500application/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

application/json

Request data failed validation

{
  "message": "{'data': ['Missing data for required field.']}"
}

application/json

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"
}

Parameters

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 `400application/json`

1 fields

Request data failed validation

Field	Type	Description
`message`	`string`	Message

Response `403application/json`

2 fields

Invalid key for service

Field	Type	Description
`message`	`string`	—
`url`	`string`	—

Response `422application/json`

1 fields

Request data failed validation

Field	Type	Description
`message`	`string`	Message

Response `500application/json`

1 fields

The product has encountered an internal server error

Field	Type	Description
`message`	`string`	Error Message

Other responses

200404

Operations

POST /insurance

Create Insurance

post-insurance

Request

application/json

{
  "transaction_id": "uhz6t54e-9d74-g17e-99ca-a36b30vdfd35",
  "collection_id": "hg62e49f-9d74-g17e-99ca-a36b30vdfd35",
  "partner_name": "PartnerName"
}

Response

application/json

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

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 `200application/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

Parameter	Type	Example	Description
`x-api-key` required	`string` header	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`	Authorization key

Response `200application/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

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 `400application/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

application/json

Statuses include: * REQUEST_MADE * REQUEST_ACCEPTED * WAITING_FOR_RESPONSE * COMPLETED

{
  "status": "COMPLETED"
}

Parameters

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 `200application/json`

1 fields

Statuses include: * REQUEST_MADE * REQUEST_ACCEPTED * WAITING_FOR_RESPONSE * COMPLETED

Field	Type	Description
`status`	`object`	Current execution status

Response `400application/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

Transaction successfully created.

{
  "transaction_id": "a34c40a6-3c02-44f9-a696-cd7388f506d3"
}

Parameters

Parameter	Type	Example	Description
`x-api-key` required	`string` header	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`	Authorization key

Response `200application/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

{
  "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

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

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 `200application/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

{
  "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

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

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 `200application/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

{
  "transaction_id": "uhz6t54e-9d74-g17e-99ca-a36b30vdfd35",
  "collection_id": "hg62e49f-9d74-g17e-99ca-a36b30vdfd35",
  "partner_name": "PartnerName"
}

Response

application/json

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

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 `200application/json`

2 fields

Mortgage Insurance request created successfully.

Field	Type	Description
`collection_id`	`string`	Collection ID
`message`	`string`	Message

Providers

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

400403404422500

How it works

Dual listing

Operations

Setup

Set Partners Configurations

Arch mapping

NationalMI mapping

Radian mapping

Enact mapping

MGIC mapping

Request

Response

Parameters

Response 200application/json

Response 400application/json

Response 403application/json

Response 422application/json

Response 500application/json

Other responses

Retrieve Partner Configurations Schema

Response

Parameters

Response 400application/json

Response 403application/json

Response 422application/json

Response 500application/json

Other responses

Operations

Create Insurance

Request

Response

Parameters

Request bodyapplication/json

Response 200application/json

Retrieve Elements

Parameters

Response 200application/json

Validate Collection

Parameters

Request bodyapplication/json

Response 400application/json

Other responses

Retrieve Status

Response

Parameters

Response 200application/json

Response 400application/json

Create Transaction

Response

Parameters

Response 200application/json

Create Collection

Request

Response

Parameters

Request bodyapplication/json

Response 200application/json

Update Collection

Request

Response

Parameters

Request bodyapplication/json

Response 200application/json

Create Mortgage Insurance

Request

Response

Parameters

Request bodyapplication/json

Response 200application/json

Providers

Field mapping

Errors

Response `200application/json`

Response `400application/json`

Response `403application/json`

Response `422application/json`

Response `500application/json`

Response `400application/json`

Response `403application/json`

Response `422application/json`

Response `500application/json`

Request body`application/json`

Response `200application/json`

Response `200application/json`

Request body`application/json`

Response `400application/json`

Response `200application/json`

Response `400application/json`

Response `200application/json`

Request body`application/json`

Response `200application/json`

Request body`application/json`

Response `200application/json`

Request body`application/json`

Response `200application/json`