# LOS
# 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 Copy
```
{
"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
201400403404
application/json Copy Successfully started flow invocation.
```
{
"invocation_id": "01GY76GA0AKNMVTBS85EMYWN5E",
"transaction_id": "01GY76GA0AKNMVTBS85EMYWN5E",
"request_collection_id": "01GY76GA0AKNMVT9V85EMYWN5E",
"response_collection_id": "01GY76G9V6QN22ZVPFN77EFSP5"
}
```
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
application/json Copy 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"
}
```
text/html Copy Resource not found
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
1
| 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 `201``application/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 `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Message |
##### Response `403``application/json`
2 fields
403 invalid error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message. |
| `url` | `string` | Error additional URL. |
##### Response `404``application/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
201400403404
application/json Copy Successfully started flow invocation.
```
{
"invocation_id": "01GY76GA0AKNMVTBS85EMYWN5E",
"transaction_id": "01GY76GA0AKNMVTBS85EMYWN5E",
"response_collection_id": "01GY76G9V6QN22ZVPFN77EFSP5"
}
```
application/json Copy Request data failed validation
```
{
"message": "{'data': ['Missing data for required field.']}"
}
```
application/json Copy 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"
}
```
text/html Copy Resource not found
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. |
##### Response `201``application/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 `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Message |
##### Response `403``application/json`
2 fields
403 invalid error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message. |
| `url` | `string` | Error additional URL. |
##### Response `404``application/json`
1 fields
Resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
### Operations
`POST` `/los`
#### Create LOS
`post-los`
##### 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 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
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
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
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` `/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
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`
`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
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` `/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 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` `/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 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` `/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 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 |
## Providers
- Blend
- Byte Software
- ICE Mortgage Technology
- LendingPad
- Sales Boomerang
## Errors
`400``403``404`
## More in Integration
- Previous product: Closing
- Next product: POS