LOS

The general origination-system adapter: the layer that makes a lender's system of record a swap-in target rather than a rewrite.

Every mortgage product needs to read from and write to the lender's origination system, and each system exposes a different model. This product carries the mapping in one place, so a product calls the adapter rather than the vendor.

Vendor-specific integrations sit under Providers. The adapter is what they plug into.

How it works

The dual listing under Adapters is the same slot seen from the other side: it is a systems-integration product, and it is also the reason every other mortgage product can reach the loan file at all.

Field-level translation between a system's own vocabulary and the canonical model is the same mechanism every vendor integration uses — see Translation.

Dual listing

LOS is filed under two categories. The other listing is LOS under Adapters, and the recorded specifications resolve there — its 24 operations render on that page.

Operations

Loan

POST /createLoan

Create Loan

invokeProductFlow

CreateLoan

Create Lead

This API can be used to create "loan/lead" with "Lendingpad" partner.

In payload, user should provide:

borrower/coborrower information
loan information
property information
credit information

And relationship information between borrower/coborrower, loan, credit and property.

Example request payload:

Show the rest

 {
 "request_data": {
 "people": [
 {
 "@id": "person_1",
 "@type": "person",
 "first_name": "borrower",
 "last_name": "user1",
 "email_address": "test1@staircase.co",
 "phone_number": "1234567890"
 },
 {
 "@id": "person_2",
 "@type": "person",
 "first_name": "coborrower",
 "last_name": "user2",
 "email_address": "test2@staircase.co",
 "phone_number": "1234567891"
 }
 ],
 "loans": [
 {
 "@id": "loan_1",
 "@type": "loan",
 "loan_purpose": "purchase",
 "loan_type": "conventional",
 "occupancy": "primary_residence",
 "appraisal_value": 100
 "loan_amount": 1000
 }
 ],
 "properties": [
 {
 "@id": "property_1",
 "@type": "property",
 "full_address_txt": "full_address_txt",
 "city_name": "city_name",
 "state_name": "VA",
 "postal_code": "postal_code",
 "property_type": "Attached",
 "unit": "1",
 "purchase_price": 1000
 }
 ],
 "credits": [
 {
 "@id": "credit_1",
 "@type": "credit",
 "credit_identifier": "credit_identifier",
 "credit_score": 799
 }
 ],
 "relationships": [
 {
 "@id": "relationship_1",
 "@type": "finance_relation",
 "has_person": "person_1",
 "has_loan": "loan_1",
 "has_property": "property_1",
 "main_applicant": true
 },
 {
 "@id": "relationship_2",
 "@type": "finance_relation",
 "has_person": "person_2",
 "has_loan": "loan_1",
 "has_property": "property_1",
 "main_applicant": false
 },
 {
 "@id": "relationship_3",
 "@type": "person_credit",
 "has_person": "person_1",
 "has_credit": "credit_1"
 }
 ]
 }
 }

You can retrieve this invocation status using this API. Parameter product_name should be lendingpad-los and invocation_id parameter should be the invocation_id value in the product flow invocation response body.

Retrieve a Transaction's Collection

You can use this API to retrieve a transaction's collection.

When you retrieve response collection, you can see loan guid and loan identifier/number in Lendingpad ecosystem.

Example response collection:

{
 "loans": [
 {
 "@id": "202bdccb-44cf-4aee-acf1-339d20d70213",
 "@type": "loan",
 "loan_identifier": "R001586"
 }
 ]
 }

Request

application/json

{
  "request_data": {
    "loans": [
      {
        "@id": "loan_id",
        "@type": "loan",
        "loan_purpose": "purchase",
        "loan_type": "conventional",
        "occupancy": "primary_residence",
        "appraisal_value": 100,
        "loan_amount": 1000
      }
    ],
    "people": [
      {
        "@id": "person_1",
        "@type": "person",
        "first_name": "borrower",
        "last_name": "user1",
        "email_address": "test1@staircase.co",
        "phone_number": "1234567890"
      },
      {
        "@id": "person_2",
        "@type": "person",
        "first_name": "coborrower",
        "last_name": "user2",
        "email_address": "test2@staircase.co",
        "phone_number": "1234567891"
      }
    ],
    "properties": [
      {
        "@id": "property_1",
        "@type": "property",
        "full_address_txt": "full_address_txt",
        "city_name": "city_name",
        "state_name": "VA",
        "postal_code": "postal_code",
        "property_type": "Attached",
        "purchase_price": 1000,
        "unit": "1"
      }
    ],
    "relationships": [
      {
        "@id": "relationship_1",
        "@type": "finance_relation",
        "has_person": "person_1",
        "has_loan": "loan_1",
        "has_property": "property_1",
        "main_applicant": true
      },
      {
        "@id": "relationship_2",
        "@type": "finance_relation",
        "has_person": "person_2",
        "has_loan": "loan_1",
        "has_property": "property_1",
        "main_applicant": false
      }
    ]
  }
}

Response

application/json

Successfully started flow invocation.

{
  "invocation_id": "01GY76GA0AKNMVTBS85EMYWN5E",
  "transaction_id": "01GY76GA0AKNMVTBS85EMYWN5E",
  "request_collection_id": "01GY76GA0AKNMVT9V85EMYWN5E",
  "response_collection_id": "01GY76G9V6QN22ZVPFN77EFSP5"
}

application/json

403 invalid error

{
  "message": "Please check the key you used to call this service",
  "url": "https://api.staircase.co/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`	Environment API Key.

Request body`application/json`

5 fields

Field	Type	Description
`transaction_id`	`string`	Transaction ID used for invocation.
`request_collection_id`	`string`	Request Collection ID.
`response_collection_id`	`string`	Response Collection ID.
`callback_url`	`string (uri)`	Callback URL.
`request_data`required	`object`	Request JSON body.

Response `201application/json`

4 fields

Successfully started flow invocation.

Field	Type	Description
`invocation_id`	`string`	Invocation ID.
`transaction_id`	`string`	Transaction ID.
`request_collection_id`	`string`	Request collection ID.
`response_collection_id`	`string`	Response collection ID.

Response `400application/json`

1 fields

Request data failed validation

Field	Type	Description
`message`	`one of`	Message

Response `403application/json`

2 fields

403 invalid error

Field	Type	Description
`message`	`string`	Error message.
`url`	`string`	Error additional URL.

Response `404application/json`

1 fields

Resource not found

Field	Type	Description
`message`	`string`	Message

POST /loanList

Get Loans

invokeLoanListRetrieval

Get Loans List

This API can be used to retrieve all "loans" from "Lendingpad" partner. No request body is required for this endpoint.

The status of your request can be tracked from this API. Parameter product_name should be lendingpad-los and invocation_id parameter should be the invocation_id value in the response body.

Retrieve a Transaction's Collection

You can use this API to retrieve a transaction's collection.

Show the rest

When you retrieve response collection, you can see list of staircase collection identifiers that hold each loan separately.

Example Response:

{
 "loan_collections": [
 "01GY745DS3MQ6VHQXYX67J2A7M",
 "01GY745E39JH7P0E8XXVMCGMVV",
 "01GY745E54P9D6M2ZSTW46CRXX",
 "01GY745E3HNJ47KTXMN8ZD9K54",
 "01GY745E3KEGNQRJ29P3K8C9NS"
 ]
 }

Each of the collections can be retrieved from the same endpoint, this time use identifier from loan_collections array for collection_id parameter. Typical Loan would look like this:

{
 "loans": [
 {
 "@id": "4598b1f0-b115-43d7-ab65-e9ee5ada745f",
 "@type": "loan",
 "loan_identifier": "030431",
 "occupancy ": "primary_residence",
 "loan_purpose ": "cash_out_refinance",
 "loan_status ": "prospect",
 "loan_status_date ": "2022-12-07T00:00:00Z",
 "loan_term": 10,
 "appraisal_value ": 500000.0,
 "loan_amount ": 500000.0,
 "loan_type": "conventional",
 "end_date": "2023-12-07T00:00:00Z"
 }
 ],
 "incomes": [
 {
 "@id": "4598b1f0-b115-43d7-ab65-e9ee5ada745f_income",
 "@type": "income",
 "annual_income ": 0.0
 }
 ],
 "properties": [
 {
 "@id": "4598b1f0-b115-43d7-ab65-e9ee5ada745f_property",
 "@type": "property",
 "city_name": "Hackettstown",
 "state_code": "NJ",
 "full_address_txt": "124 Main Street",
 "postal_code": "07840"
 }
 ],
 "people": [
 {
 "@type": "borrower",
 "@id": "ffa60a88-d044-433d-aac9-eca09443ec9a",
 "first_name": "Borrower",
 "last_name": "A",
 "has_credit": [
 "ffa60a88-d044-433d-aac9-eca09443ec9a_credit"
 ]
 },
 {
 "@type": "coborrower",
 "@id": "cbae653c-02f1-4cd9-bb6c-3f6f452e7053",
 "first_name": "Borrower",
 "last_name": "B"
 }
 ],
 "credits": [
 {
 "@id": "ffa60a88-d044-433d-aac9-eca09443ec9a_credit",
 "@type": "credit",
 "credit_identifier": "2224165",
 "credit_score ": 780
 }
 ],
 "relationships": [
 {
 "@id": "4598b1f0-b115-43d7-ab65-e9ee5ada745f_ffa60a88-d044-433d-aac9-eca09443ec9a",
 "@type": "finance_relation",
 "has_loan": "4598b1f0-b115-43d7-ab65-e9ee5ada745f",
 "has_property": "4598b1f0-b115-43d7-ab65-e9ee5ada745f_property",
 "main_applicant": true,
 "has_person": "ffa60a88-d044-433d-aac9-eca09443ec9a"
 },
 {
 "@id": "4598b1f0-b115-43d7-ab65-e9ee5ada745f_cbae653c-02f1-4cd9-bb6c-3f6f452e7053",
 "@type": "finance_relation",
 "has_loan": "4598b1f0-b115-43d7-ab65-e9ee5ada745f",
 "has_property": "4598b1f0-b115-43d7-ab65-e9ee5ada745f_property",
 "main_applicant": false,
 "has_person": "cbae653c-02f1-4cd9-bb6c-3f6f452e7053"
 }
 ]
}

Response

application/json

Successfully started flow invocation.

{
  "invocation_id": "01GY76GA0AKNMVTBS85EMYWN5E",
  "transaction_id": "01GY76GA0AKNMVTBS85EMYWN5E",
  "response_collection_id": "01GY76G9V6QN22ZVPFN77EFSP5"
}

application/json

403 invalid error

{
  "message": "Please check the key you used to call this service",
  "url": "https://api.staircase.co/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`	Environment API Key.

Response `201application/json`

3 fields

Successfully started flow invocation.

Field	Type	Description
`invocation_id`	`string`	Invocation ID.
`transaction_id`	`string`	Transaction ID.
`response_collection_id`	`string`	Response collection ID.

Response `400application/json`

1 fields

Request data failed validation

Field	Type	Description
`message`	`one of`	Message

Response `403application/json`

2 fields

403 invalid error

Field	Type	Description
`message`	`string`	Error message.
`url`	`string`	Error additional URL.

Response `404application/json`

1 fields

Resource not found

Field	Type	Description
`message`	`string`	Message

Operations

POST /los

Create LOS

post-los

Request

application/json

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

Response

application/json

LOS 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

LOS request created successfully.

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

GET /los/elements

Retrieve Elements

get-los-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 /los/elements/complete

Validate Collection

post-los-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

POST /los/lexicon/elements

Retrieve Lexicon Elements

You can retrieve element structure by providing specific element names (XPaths).

Request body`application/json`

1 fields

Field	Type	Description
`elements`	`string[]`	An XPath to a valid staircase element

Other responses

200

GET /los/status/{transaction_id}/{collection_id}

Retrieve Status

get-los-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 /los/transactions

Create Transaction

post-los-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 /los/transactions/{transaction_id}/collections

Create Collection

post-los-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 /los/transactions/{transaction_id}/collections/{collection_id}

Update Collection

put-los-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

Providers

Errors

400403404

How it works

Dual listing

Operations

Loan

Create Loan

Create Lead

Retrieve a Transaction's Collection

Request

Response

Parameters

Request bodyapplication/json

Response 201application/json

Response 400application/json

Response 403application/json

Response 404application/json

Get Loans

Get Loans List

Retrieve a Transaction's Collection

Response

Parameters

Response 201application/json

Response 400application/json

Response 403application/json

Response 404application/json

Operations

Create LOS

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 Lexicon Elements

Request bodyapplication/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

Providers

Errors

Request body`application/json`

Response `201application/json`

Response `400application/json`

Response `403application/json`

Response `404application/json`

Response `201application/json`

Response `400application/json`

Response `403application/json`

Response `404application/json`

Request body`application/json`

Response `200application/json`

Response `200application/json`

Request body`application/json`

Response `400application/json`

Request body`application/json`

Response `200application/json`

Response `400application/json`

Response `200application/json`

Request body`application/json`

Response `200application/json`

Request body`application/json`

Response `200application/json`