# Appraisal
# Appraisal
Appraisal ordering and intake: placing the order, receiving the report, and normalising it against the loan file.
An appraisal arrives as a form with a defined field set, and normalising it means reading those fields into the canonical model — subject characteristics, comparables with their adjustments, and the reconciled value.
Checking the report for internal correctness is the dual-listed slot, Appraisal under Validation. Intake and validation are separated because a report can be received and stored before anyone has decided whether it is acceptable.
The operations below come from the collateral service, which routes appraisal alongside valuation, inspection and hazard insurance. Ordering an appraisal and ordering an automated valuation are the same shape of call against different evidence, which is why they share a surface.
## Dual listing
Appraisal is filed under two categories. The other listing is Appraisal under Validation, and neither listing carries a recorded specification.
## Operations
### Workflow
`POST` `/products/collateral-underwriting/invocations`
#### Invoke Product Flow
`InvokeSpecificProductFlow`
This endpoint allows you to underwrite an appraisal document.
#### Usage
- Before running this endpoint, you need to create a Staircase Blob with appraisal report content. Then, you can set `$.documents.0.has_staircase_blob_identifier.has_value` to this blob identifier.
- A unique identifier for this loan should be given in the following path `$.loans.0.has_loan_identifier_value.has_value`
- After invocation is completed, Collateral Underwriting will watch status changes in partner, and whenever there is a status changed an `ORDER_STATUS_UPDATED` Job event will be published. You can process these events by catching with this trigger expression.
```
{
"name": "collateral-underwriting-trigger",
"description": "Event Trigger",
"type": "EVENT",
"filter_expression": {
"source_name": [
"collateral-underwriting"
],
"event_type": [
"ORDER_STATUS_UPDATED"
]
},
"actions": {
"target_jobs": [
"collateral-underwriting-test-job"
]
}
}
```
When `vendor_name` is set to `"homevision"`, the captured event will be in the following format:
Show the rest
```
{
"transaction_id": "01G390E72SN9KK98146AG1WCRX",
"flow_name": "homevision-flow",
"homevision_loan_identifier": "01G390E72SN9KK98146AG1WCRX",
"response_collection_id": "01G390EH4QYS7CNVPVZSP7AZ3S",
"request_collection_id": "01G390EH4QYS7CNVPVZSP7AZ3S",
"domain": "aus-dev.staircaseapi.com",
"homevision_event_type": 4,
"homevision_order_id": 8109,
"homevision_internal_url": "",
"homevision_order_status": "Order Completed",
"homevision_message": "A new event has occurred for this order",
"homevision_pdf_url": "",
"homevision_xml_url": "",
"homevision_env_url": "",
"event_type": "ORDER_STATUS_UPDATED"
}
```
##### Request
Flow Invocation with Collection IDConventional ExampleFha Example
application/json Copy
```
{
"vendor_name": "homevision",
"transaction_id": "01F6NAMXWN2XVBD1YJ92A6S6R4",
"request_collection_id": "01F6QF1QJF20DMSXH4SYXKB1SN"
}
```
application/json Copy
```
{
"vendor_name": "homevision",
"request_data": {
"addresses": [
{
"@id": "address_id",
"@type": "business_address",
"has_state_code": {
"has_value": "CA"
},
"has_city_name": {
"has_value": "Bankville"
},
"has_postal_code": {
"has_value": 2138
},
"has_address_line_1_text": {
"has_value": "123 Lending Lane"
}
},
{
"@id": "subject_property_address_id",
"@type": "subject_property_address",
"has_county_name": {
"has_value": "Pinellas"
},
"has_state_code": {
"has_value": "TX"
},
"has_city_name": {
"has_value": "Salem"
},
"has_postal_code": {
"has_value": "2138"
},
"has_address_line_1_text": {
"has_value": "456 Main Street"
}
},
{
"@id": "borrower_address_id",
"@type": "residential_address",
"has_state_code": {
"has_value": "TX"
},
"has_city_name": {
"has_value": "Salem"
},
"has_postal_code": {
"has_value": "2138"
},
"has_address_line_1_text": {
"has_value": "456 Main Street"
}
}
],
"documents": [
{
"@id": "document_id",
"@type": "document",
"has_staircase_blob_identifier": {
"has_value": "01G2YVWSGPQC9Y9A6AXTHYMDET"
}
}
],
"loans": [
{
"@id": "loan_id",
"@type": "loan",
"has_loan_identifier_value": {
"has_value": "01G313MDG9KVKW62YK8S1WNMWB"
}
}
],
"loan_terms": [
{
"@id": "loan_term_id",
"@type": "loan_terms",
"has_loan_purpose_type": {
"has_value": "refinance"
}
}
],
"organizations": [
{
"@id": "organization_id",
"@type": "organization",
"has_organization_name": {
"has_value": "Liberty Lending"
},
"with_address": [
"address_id"
]
}
],
"people": [
{
"@id": "appraiser_id",
"@type": "appraiser",
"has_appraisal_sub_committee_appraiser_identifier": {
"has_value": "A12345"
},
"has_full_name": {
"has_value": "Alan Appraiser"
}
},
{
"@id": "borrower_id",
"@type": "borrower",
"has_full_name": {
"has_value": "Jane Doe"
},
"lives_at": [
"residence_id"
]
},
{
"@id": "co_borrower_id",
"@type": "borrower",
"has_full_name": {
"has_value": "John Doe"
}
}
],
"properties": [
{
"@id": "subject_property_id",
"@type": "subject_property",
"with_address": [
"subject_property_address_id"
],
"with_sales_contract": [
"sales_contract_id"
]
}
],
"property_valuations": [
{
"@id": "property_valution_id",
"@type": "property_valuation",
"has_property_inspection_type_other_description": {
"has_value": "1004"
}
}
],
"residences": [
{
"@id": "residence_id",
"@type": "residence",
"with_address": [
"borrower_address_id"
]
}
],
"roles": [
{
"@id": "role_id",
"@type": "role",
"with_appraiser": [
"appraiser_id"
]
}
],
"sales_contracts": [
{
"@id": "sales_contract_id",
"@type": "property_sales_contract",
"has_sales_contract_amount": {
"has_value": 123456
}
}
]
}
}
```
application/json Copy
```
{
"vendor_name": "homevision",
"request_data": {
"addresses": [
{
"@id": "address_id",
"@type": "business_address",
"has_state_code": {
"has_value": "CA"
},
"has_city_name": {
"has_value": "Bankville"
},
"has_postal_code": {
"has_value": 2138
},
"has_address_line_1_text": {
"has_value": "123 Lending Lane"
}
},
{
"@id": "subject_property_address_id",
"@type": "subject_property_address",
"has_county_name": {
"has_value": "Pinellas"
},
"has_state_code": {
"has_value": "TX"
},
"has_city_name": {
"has_value": "Salem"
},
"has_postal_code": {
"has_value": "2138"
},
"has_address_line_1_text": {
"has_value": "456 Main Street"
}
},
{
"@id": "borrower_address_id",
"@type": "residential_address",
"has_state_code": {
"has_value": "TX"
},
"has_city_name": {
"has_value": "Salem"
},
"has_postal_code": {
"has_value": "2138"
},
"has_address_line_1_text": {
"has_value": "456 Main Street"
}
}
],
"documents": [
{
"@id": "document_id",
"@type": "document",
"has_staircase_blob_identifier": {
"has_value": "01G2YVWSGPQC9Y9A6AXTHYMDET"
}
}
],
"government_loans": [
{
"@id": "government_loan_id",
"@type": "government_loan",
"has_fha_case_number": {
"has_value": "FHA111111111"
}
}
],
"loans": [
{
"@id": "loan_id",
"@type": "loan",
"has_loan_identifier_value": {
"has_value": "01G313MDG9KVKW62YK8S1WNMWB"
},
"with_government_loan": [
"government_loan_id"
]
}
],
"loan_terms": [
{
"@id": "loan_term_id",
"@type": "loan_terms",
"has_loan_purpose_type": {
"has_value": "refinance"
}
}
],
"organizations": [
{
"@id": "organization_id",
"@type": "organization",
"has_organization_name": {
"has_value": "Liberty Lending"
},
"with_address": [
"address_id"
]
}
],
"people": [
{
"@id": "appraiser_id",
"@type": "appraiser",
"has_appraisal_sub_committee_appraiser_identifier": {
"has_value": "A12345"
},
"has_full_name": {
"has_value": "Alan Appraiser"
}
},
{
"@id": "borrower_id",
"@type": "borrower",
"has_full_name": {
"has_value": "Jane Doe"
},
"lives_at": [
"residence_id"
]
},
{
"@id": "co_borrower_id",
"@type": "borrower",
"has_full_name": {
"has_value": "John Doe"
}
}
],
"properties": [
{
"@id": "subject_property_id",
"@type": "subject_property",
"with_address": [
"subject_property_address_id"
],
"with_sales_contract": [
"sales_contract_id"
]
}
],
"property_valuations": [
{
"@id": "property_valution_id",
"@type": "property_valuation",
"has_property_inspection_type_other_description": {
"has_value": "1004"
}
}
],
"residences": [
{
"@id": "residence_id",
"@type": "residence",
"with_address": [
"borrower_address_id"
]
}
],
"roles": [
{
"@id": "role_id",
"@type": "role",
"with_appraiser": [
"appraiser_id"
]
}
],
"sales_contracts": [
{
"@id": "sales_contract_id",
"@type": "property_sales_contract",
"has_sales_contract_amount": {
"has_value": 123456
}
}
]
}
}
```
##### Response
201400403404500
application/json Copy Successfully started flow invocation.
```
{
"product_flow_name": "collateral-underwriting",
"metadata": {},
"request_collection_id": "01FFHJ4JCWGHV38SC1NJ8TVNFY",
"invocation_id": "08f0f7bd-0158-4ab8-845c-f94eafa3859c",
"invocation_status": "STARTED",
"transaction_id": "01FFHJ2ZVS4P7N4AV5W0993QMD"
}
```
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://staircase.stoplight.io/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
```
application/json Copy Internal server error
```
{
"message": "The product has encountered an internal server error. If you\nhave used a transaction_id to call our services, please submit it to\nStaircase support"
}
```
##### Parameters
1
| Parameter | Type | Description |
| --- | --- | --- |
| `x-api-key` required | `string` header | Environment API Key. |
##### Response `201``application/json`
7 fields
Successfully started flow invocation.
| Field | Type | Description |
| --- | --- | --- |
| `invocation_id` | `string` | Invocation ID. |
| `invocation_status` | `string` | The status of the invocation.`STARTED` |
| `transaction_id` | `string` | Transaction ID. |
| `product_flow_name` | `string` | Product flow name.`collateral-underwriting` |
| `metadata` | `object` | The metadata of the invoked product flow. |
| `callback_url` | `string` | Callback URL. |
| `request_data` | `object` | The data for the request collection. |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | 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 |
##### Response `500``application/json`
1 fields
Internal server error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message. |
`GET` `/products/collateral-underwriting/invocations/{invocation_id}`
#### Retrieve Invocation Status
`RetrieveProductFlowInvocationStatus`
Retrieve status of a Product Flow Invocation
Retrieves the status of running Product flow invocation.
##### Response
200400403404500
application/json Copy Successfully returned status of the Product flow Invocation.
```
{
"request_collection_id": "01FFHJ4JCWGHV38SC1NJ8TVNFY",
"response_collection_id": "01FFHKS6W9J0JDTGTQJB9Y2RWB",
"metadata": {},
"invocation_id": "08f0f7bd-0158-4ab8-845c-f94eafa3859c",
"invocation_status": "RUNNING",
"transaction_id": "01FFHJ2ZVS4P7N4AV5W0993QMD",
"product_flow_name": "collateral-underwriting",
"request_collection": {
"metadata": {
"created_at": "2021-09-14T03:08:00.284090-04:00",
"validation": false
},
"transaction_id": "01FFHJ2ZVS4P7N4AV5W0993QMD",
"collection_id": "01FFHJ4JCWGHV38SC1NJ8TVNFY",
"data": {
"addresses": [
{
"@id": "address_id",
"@type": "business_address",
"has_state_code": {
"has_value": "CA"
},
"has_city_name": {
"has_value": "Bankville"
},
"has_postal_code": {
"has_value": 2138
},
"has_address_line_1_text": {
"has_value": "123 Lending Lane"
}
},
{
"@id": "subject_property_address_id",
"@type": "subject_property_address",
"has_county_name": {
"has_value": "Pinellas"
},
"has_state_code": {
"has_value": "TX"
},
"has_city_name": {
"has_value": "Salem"
},
"has_postal_code": {
"has_value": "2138"
},
"has_address_line_1_text": {
"has_value": "456 Main Street"
}
},
{
"@id": "borrower_address_id",
"@type": "residential_address",
"has_state_code": {
"has_value": "TX"
},
"has_city_name": {
"has_value": "Salem"
},
"has_postal_code": {
"has_value": "2138"
},
"has_address_line_1_text": {
"has_value": "456 Main Street"
}
}
],
"documents": [
{
"@id": "document_id",
"@type": "document",
"has_staircase_blob_identifier": {
"has_value": "01G2YVWSGPQC9Y9A6AXTHYMDET"
}
}
],
"loans": [
{
"@id": "loan_id",
"@type": "loan",
"has_loan_identifier_value": {
"has_value": "01G313MDG9KVKW62YK8S1WNMWB"
}
}
],
"loan_terms": [
{
"@id": "loan_term_id",
"@type": "loan_terms",
"has_loan_purpose_type": {
"has_value": "refinance"
}
}
],
"organizations": [
{
"@id": "organization_id",
"@type": "organization",
"has_organization_name": {
"has_value": "Liberty Lending"
},
"with_address": [
"address_id"
]
}
],
"people": [
{
"@id": "appraiser_id",
"@type": "appraiser",
"has_appraisal_sub_committee_appraiser_identifier": {
"has_value": "A12345"
},
"has_full_name": {
"has_value": "Alan Appraiser"
}
},
{
"@id": "borrower_id",
"@type": "borrower",
"has_full_name": {
"has_value": "Jane Doe"
},
"lives_at": [
"residence_id"
]
},
{
"@id": "co_borrower_id",
"@type": "borrower",
"has_full_name": {
"has_value": "John Doe"
}
}
],
"properties": [
{
"@id": "subject_property_id",
"@type": "subject_property",
"with_address": [
"subject_property_address_id"
],
"with_sales_contract": [
"sales_contract_id"
]
}
],
"property_valuations": [
{
"@id": "property_valution_id",
"@type": "property_valuation",
"has_property_inspection_type_other_description": {
"has_value": "1004"
}
}
],
"residences": [
{
"@id": "residence_id",
"@type": "residence",
"with_address": [
"borrower_address_id"
]
}
],
"roles": [
{
"@id": "role_id",
"@type": "role",
"with_appraiser": [
"appraiser_id"
]
}
],
"sales_contracts": [
{
"@id": "sales_contract_id",
"@type": "property_sales_contract",
"has_sales_contract_amount": {
"has_value": 123456
}
}
]
}
},
"response_collection": {
"metadata": {
"created_at": "2021-09-14T03:36:45.193268-04:00",
"validation": false
},
"transaction_id": "01FFHJ2ZVS4P7N4AV5W0993QMD",
"collection_id": "01FFHKS6W9J0JDTGTQJB9Y2RWB",
"data": {
"services": [
{
"@id": "service_id",
"@type": "service",
"has_service_name": {
"has_value": "Collateral Underwriting"
},
"has_service_vendor_name": {
"has_value": "homevision"
},
"with_foreign_object": [
"f1",
"f2",
"f3",
"f4"
]
}
],
"foreign_objects": [
{
"@id": "f1",
"@type": "foreign_object",
"has_object_name": {
"has_value": "internal_url"
},
"has_object_url_value": {
"has_value": "https://app.homevision.co/xmlqc/2394077"
}
},
{
"@id": "f2",
"@type": "foreign_object",
"has_object_name": {
"has_value": "pdf_url"
},
"has_object_url_value": {
"has_value": "https://app.homevision.co/123456/pdf.pdf"
}
},
{
"@id": "f3",
"@type": "foreign_object",
"has_object_name": {
"has_value": "xml_url"
},
"has_object_url_value": {
"has_value": "https://app.homevision.co/123456/xml.xml"
}
},
{
"@id": "f4",
"@type": "foreign_object",
"has_object_name": {
"has_value": "env_url"
},
"has_object_url_value": {
"has_value": "https://app.homevision.co/123456/env.env"
}
}
]
}
}
}
```
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://staircase.stoplight.io/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
```
application/json Copy Internal server error
```
{
"message": "The product has encountered an internal server error. If you\nhave used a transaction_id to call our services, please submit it to\nStaircase support"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | — | Environment API Key. |
| `invocation_id` required | `string (ulid)` path | `01F0KHKADN0HRFXMCQQXPA6AFZ` | Product flow invocation identifier |
##### Response `200``application/json`
9 fields
Successfully returned status of the Product flow Invocation.
| Field | Type | Description |
| --- | --- | --- |
| `invocation_status`required | `string` | Invocation Status.`ACTION_REQUIRED``COMPLETED``FAILED``RUNNING``STARTED` |
| `transaction_id`required | `string` | Transaction ID used for invocation. |
| `request_collection_id` | `string` | Request Collection ID. |
| `request_collection` | `object` | Collection. |
| `transaction_id` | `string (ulid)` | Transaction ID.Example `01EZQ32PJQGKRA6HR8D72Q9FFF` |
| `collection_id` | `string (ulid)` | Collection ID.Example `01EZQ32PJQGKRA6HR8D72Q9FFF` |
| `data` | `object` | Data in Staircase language schema. |
| `metadata` | `object` | Metadata about collection, f.e version of used Staircase schema. |
| `response_collection_id` | `string` | Response Collection ID. |
| `response_collection` | `object` | Collection. |
| `transaction_id` | `string (ulid)` | Transaction ID.Example `01EZQ32PJQGKRA6HR8D72Q9FFF` |
| `collection_id` | `string (ulid)` | Collection ID.Example `01EZQ32PJQGKRA6HR8D72Q9FFF` |
| `data` | `object` | — |
| `services`required | `object[]` | — |
| `@id`required | `string` | — |
| `@type`required | `string` | — |
| `has_service_name`required | `object` | — |
| `has_service_vendor_name`required | `object` | — |
| `with_foreign_object`required | `string[]` | — |
| `foreign_objects`required | `object[]` | — |
| `@id`required | `string` | — |
| `@type`required | `string` | — |
| `has_object_name`required | `object` | — |
| `has_object_url_value` | `object` | — |
| `metadata` | `object` | Metadata about collection, f.e version of used Staircase schema. |
| `callback_url` | `string` | URL that was specified in flow invocation and will be used to send the callback when flow invocation will be finished. |
| `widget_url` | `string (uri)` | URL of the widget. |
| `metadata` | `object` | Response Collection ID. |
##### Response `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | 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 |
##### Response `500``application/json`
1 fields
Internal server error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message. |
`GET` `/products/collateral-underwriting/request-schema`
#### Retrieve Request Schema
`retrieveRequestSchema`
Retrieve Request Schema retrieves a JSON schema for the request collection that you can provide to the invocation.
If you'd like to retrieve some examples for the request collection, use `return_examples=True` query parameter.
##### Response
200 Schema200 Schema with Examples400 InvalidReturnExamplesValue400 text/html403404 GetProduct404 text/html500
application/json Copy Request schema (possibly with examples) is successfully returned.
```
{
"schema": {
"type": "object",
"required": [
"addresses",
"documents",
"loans",
"loan_terms",
"organizations",
"people",
"properties",
"property_valuations",
"residences",
"roles",
"sales_contracts"
],
"properties": {
"addresses": {
"type": "array",
"items": {
"type": "object",
"required": [
"@id",
"@type",
"has_state_code",
"has_city_name",
"has_postal_code",
"has_address_line_1_text"
],
"properties": {
"@id": {
"type": "string"
},
"@type": {
"type": "string"
},
"has_state_code": {
"type": "object",
"required": [
"has_value"
],
"properties": {
"has_value": {
"type": "string"
}
}
},
"has_city_name": {
"type": "object",
"required": [
"has_value"
],
"properties": {
"has_value": {
"type": "string"
}
}
},
"has_postal_code": {
"type": "object",
"required": [
"has_value"
],
"properties": {
"has_value": {
"type": "string"
}
}
},
"has_address_line_1_text": {
"type": "object",
"required": [
"has_value"
],
"properties": {
"has_value": {
"type": "string"
}
}
},
"has_county_name": {
"type": "object",
"required": [
"has_value"
],
"properties": {
"has_value": {
"type": "string"
}
}
}
}
}
},
"documents": {
"type": "array",
"items": {
"type": "object",
"properties": {
"@id": {
"type": "string"
},
"@type": {
"type": "string"
},
"has_staircase_blob_identifier": {
"type": "object",
"required": [
"has_value"
],
"properties": {
"has_value": {
"type": "string"
}
}
}
},
"required": [
"@id",
"@type",
"has_staircase_blob_identifier"
]
}
},
"loans": {
"type": "array",
"items": {
"type": "object",
"properties": {
"@id": {
"type": "string"
},
"@type": {
"type": "string"
},
"with_government_loan": {
"type": "array",
"items": {
"type": "string"
}
},
"has_loan_identifier_value": {
"type": "object",
"required": [
"has_value"
],
"properties": {
"has_value": {
"type": "string"
}
}
}
},
"required": [
"@id",
"@type",
"has_loan_identifier_value"
]
}
},
"government_loans": {
"type": "array",
"items": {
"type": "object",
"required": [
"@id",
"@type",
"has_fha_case_number"
],
"properties": {
"@id": {
"type": "string"
},
"@type": {
"type": "string"
},
"has_fha_case_number": {
"type": "object",
"properties": {
"has_value": {
"type": "string"
}
},
"required": [
"has_value"
]
}
}
}
},
"loan_terms": {
"type": "array",
"items": {
"type": "object",
"required": [
"@id",
"@type",
"has_loan_purpose_type"
],
"properties": {
"@id": {
"type": "string"
},
"@type": {
"type": "string"
},
"has_loan_purpose_type": {
"type": "object",
"required": [
"has_value"
],
"properties": {
"has_value": {
"type": "string"
}
}
}
}
}
},
"organizations": {
"type": "array",
"items": {
"type": "object",
"required": [
"@id",
"@type",
"has_organization_name",
"with_address"
],
"properties": {
"@id": {
"type": "string"
},
"@type": {
"type": "string"
},
"has_organization_name": {
"type": "object",
"required": [
"has_value"
],
"properties": {
"has_value": {
"type": "string"
}
}
},
"with_address": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"people": {
"type": "array",
"items": {
"type": "object",
"required": [
"@id",
"@type",
"has_full_name"
],
"properties": {
"@id": {
"type": "string"
},
"@type": {
"type": "string"
},
"has_appraisal_sub_committee_appraiser_identifier": {
"type": "object",
"required": [
"has_value"
],
"properties": {
"has_value": {
"type": "string"
}
}
},
"has_full_name": {
"type": "object",
"required": [
"has_value"
],
"properties": {
"has_value": {
"type": "string"
}
}
},
"lives_at": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"properties": {
"type": "array",
"items": {
"type": "object",
"required": [
"@id",
"@type",
"with_address",
"with_sales_contract"
],
"properties": {
"@id": {
"type": "string"
},
"@type": {
"type": "string"
},
"with_address": {
"type": "array",
"items": {
"type": "string"
}
},
"with_sales_contract": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"property_valuations": {
"type": "array",
"items": {
"type": "object",
"required": [
"@id",
"@type",
"has_property_inspection_type_other_description"
],
"properties": {
"@id": {
"type": "string"
},
"@type": {
"type": "string"
},
"has_property_inspection_type_other_description": {
"type": "object",
"required": [
"has_value"
],
"properties": {
"has_value": {
"type": "string"
}
}
}
}
}
},
"residences": {
"type": "array",
"items": {
"type": "object",
"required": [
"@id",
"@type",
"with_address"
],
"properties": {
"@id": {
"type": "string"
},
"@type": {
"type": "string"
},
"with_address": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"roles": {
"type": "array",
"items": {
"type": "object",
"required": [
"@id",
"@type",
"with_appraiser"
],
"properties": {
"@id": {
"type": "string"
},
"@type": {
"type": "string"
},
"with_appraiser": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"sales_contracts": {
"type": "array",
"items": {
"type": "object",
"required": [
"@id",
"@type",
"has_sales_contract_amount"
],
"properties": {
"@id": {
"type": "string"
},
"@type": {
"type": "string"
},
"has_sales_contract_amount": {
"type": "object",
"required": [
"has_value"
],
"properties": {
"has_value": {
"type": "integer"
}
}
}
}
}
}
},
"description": "The data that is needed for invocation. It should follow the request schema"
}
}
```
application/json Copy Request schema (possibly with examples) is successfully returned.
```
{
"schema": {
"type": "object",
"required": [
"addresses",
"documents",
"loans",
"loan_terms",
"organizations",
"people",
"properties",
"property_valuations",
"residences",
"roles",
"sales_contracts"
],
"properties": {
"addresses": {
"type": "array",
"items": {
"type": "object",
"required": [
"@id",
"@type",
"has_state_code",
"has_city_name",
"has_postal_code",
"has_address_line_1_text"
],
"properties": {
"@id": {
"type": "string"
},
"@type": {
"type": "string"
},
"has_state_code": {
"type": "object",
"required": [
"has_value"
],
"properties": {
"has_value": {
"type": "string"
}
}
},
"has_city_name": {
"type": "object",
"required": [
"has_value"
],
"properties": {
"has_value": {
"type": "string"
}
}
},
"has_postal_code": {
"type": "object",
"required": [
"has_value"
],
"properties": {
"has_value": {
"type": "string"
}
}
},
"has_address_line_1_text": {
"type": "object",
"required": [
"has_value"
],
"properties": {
"has_value": {
"type": "string"
}
}
},
"has_county_name": {
"type": "object",
"required": [
"has_value"
],
"properties": {
"has_value": {
"type": "string"
}
}
}
}
}
},
"documents": {
"type": "array",
"items": {
"type": "object",
"properties": {
"@id": {
"type": "string"
},
"@type": {
"type": "string"
},
"has_staircase_blob_identifier": {
"type": "object",
"required": [
"has_value"
],
"properties": {
"has_value": {
"type": "string"
}
}
}
},
"required": [
"@id",
"@type",
"has_staircase_blob_identifier"
]
}
},
"loans": {
"type": "array",
"items": {
"type": "object",
"properties": {
"@id": {
"type": "string"
},
"@type": {
"type": "string"
},
"with_government_loan": {
"type": "array",
"items": {
"type": "string"
}
},
"has_loan_identifier_value": {
"type": "object",
"required": [
"has_value"
],
"properties": {
"has_value": {
"type": "string"
}
}
}
},
"required": [
"@id",
"@type",
"has_loan_identifier_value"
]
}
},
"government_loans": {
"type": "array",
"items": {
"type": "object",
"required": [
"@id",
"@type",
"has_fha_case_number"
],
"properties": {
"@id": {
"type": "string"
},
"@type": {
"type": "string"
},
"has_fha_case_number": {
"type": "object",
"properties": {
"has_value": {
"type": "string"
}
},
"required": [
"has_value"
]
}
}
}
},
"loan_terms": {
"type": "array",
"items": {
"type": "object",
"required": [
"@id",
"@type",
"has_loan_purpose_type"
],
"properties": {
"@id": {
"type": "string"
},
"@type": {
"type": "string"
},
"has_loan_purpose_type": {
"type": "object",
"required": [
"has_value"
],
"properties": {
"has_value": {
"type": "string"
}
}
}
}
}
},
"organizations": {
"type": "array",
"items": {
"type": "object",
"required": [
"@id",
"@type",
"has_organization_name",
"with_address"
],
"properties": {
"@id": {
"type": "string"
},
"@type": {
"type": "string"
},
"has_organization_name": {
"type": "object",
"required": [
"has_value"
],
"properties": {
"has_value": {
"type": "string"
}
}
},
"with_address": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"people": {
"type": "array",
"items": {
"type": "object",
"required": [
"@id",
"@type",
"has_full_name"
],
"properties": {
"@id": {
"type": "string"
},
"@type": {
"type": "string"
},
"has_appraisal_sub_committee_appraiser_identifier": {
"type": "object",
"required": [
"has_value"
],
"properties": {
"has_value": {
"type": "string"
}
}
},
"has_full_name": {
"type": "object",
"required": [
"has_value"
],
"properties": {
"has_value": {
"type": "string"
}
}
},
"lives_at": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"properties": {
"type": "array",
"items": {
"type": "object",
"required": [
"@id",
"@type",
"with_address",
"with_sales_contract"
],
"properties": {
"@id": {
"type": "string"
},
"@type": {
"type": "string"
},
"with_address": {
"type": "array",
"items": {
"type": "string"
}
},
"with_sales_contract": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"property_valuations": {
"type": "array",
"items": {
"type": "object",
"required": [
"@id",
"@type",
"has_property_inspection_type_other_description"
],
"properties": {
"@id": {
"type": "string"
},
"@type": {
"type": "string"
},
"has_property_inspection_type_other_description": {
"type": "object",
"required": [
"has_value"
],
"properties": {
"has_value": {
"type": "string"
}
}
}
}
}
},
"residences": {
"type": "array",
"items": {
"type": "object",
"required": [
"@id",
"@type",
"with_address"
],
"properties": {
"@id": {
"type": "string"
},
"@type": {
"type": "string"
},
"with_address": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"roles": {
"type": "array",
"items": {
"type": "object",
"required": [
"@id",
"@type",
"with_appraiser"
],
"properties": {
"@id": {
"type": "string"
},
"@type": {
"type": "string"
},
"with_appraiser": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"sales_contracts": {
"type": "array",
"items": {
"type": "object",
"required": [
"@id",
"@type",
"has_sales_contract_amount"
],
"properties": {
"@id": {
"type": "string"
},
"@type": {
"type": "string"
},
"has_sales_contract_amount": {
"type": "object",
"required": [
"has_value"
],
"properties": {
"has_value": {
"type": "integer"
}
}
}
}
}
}
},
"description": "The data that is needed for invocation. It should follow the request schema"
},
"examples": [
{
"addresses": [
{
"@id": "address_id",
"@type": "business_address",
"has_state_code": {
"has_value": "CA"
},
"has_city_name": {
"has_value": "Bankville"
},
"has_postal_code": {
"has_value": 2138
},
"has_address_line_1_text": {
"has_value": "123 Lending Lane"
}
},
{
"@id": "subject_property_address_id",
"@type": "subject_property_address",
"has_county_name": {
"has_value": "Pinellas"
},
"has_state_code": {
"has_value": "TX"
},
"has_city_name": {
"has_value": "Salem"
},
"has_postal_code": {
"has_value": "2138"
},
"has_address_line_1_text": {
"has_value": "456 Main Street"
}
},
{
"@id": "borrower_address_id",
"@type": "residential_address",
"has_state_code": {
"has_value": "TX"
},
"has_city_name": {
"has_value": "Salem"
},
"has_postal_code": {
"has_value": "2138"
},
"has_address_line_1_text": {
"has_value": "456 Main Street"
}
}
],
"documents": [
{
"@id": "document_id",
"@type": "document",
"has_staircase_blob_identifier": {
"has_value": "01G2YVWSGPQC9Y9A6AXTHYMDET"
}
}
],
"loans": [
{
"@id": "loan_id",
"@type": "loan",
"has_loan_identifier_value": {
"has_value": "01G313MDG9KVKW62YK8S1WNMWB"
}
}
],
"loan_terms": [
{
"@id": "loan_term_id",
"@type": "loan_terms",
"has_loan_purpose_type": {
"has_value": "refinance"
}
}
],
"organizations": [
{
"@id": "organization_id",
"@type": "organization",
"has_organization_name": {
"has_value": "Liberty Lending"
},
"with_address": [
"address_id"
]
}
],
"people": [
{
"@id": "appraiser_id",
"@type": "appraiser",
"has_appraisal_sub_committee_appraiser_identifier": {
"has_value": "A12345"
},
"has_full_name": {
"has_value": "Alan Appraiser"
}
},
{
"@id": "borrower_id",
"@type": "borrower",
"has_full_name": {
"has_value": "Jane Doe"
},
"lives_at": [
"residence_id"
]
},
{
"@id": "co_borrower_id",
"@type": "borrower",
"has_full_name": {
"has_value": "John Doe"
}
}
],
"properties": [
{
"@id": "subject_property_id",
"@type": "subject_property",
"with_address": [
"subject_property_address_id"
],
"with_sales_contract": [
"sales_contract_id"
]
}
],
"property_valuations": [
{
"@id": "property_valution_id",
"@type": "property_valuation",
"has_property_inspection_type_other_description": {
"has_value": "1004"
}
}
],
"residences": [
{
"@id": "residence_id",
"@type": "residence",
"with_address": [
"borrower_address_id"
]
}
],
"roles": [
{
"@id": "role_id",
"@type": "role",
"with_appraiser": [
"appraiser_id"
]
}
],
"sales_contracts": [
{
"@id": "sales_contract_id",
"@type": "property_sales_contract",
"has_sales_contract_amount": {
"has_value": 123456
}
}
]
},
{
"addresses": [
{
"@id": "address_id",
"@type": "business_address",
"has_state_code": {
"has_value": "CA"
},
"has_city_name": {
"has_value": "Bankville"
},
"has_postal_code": {
"has_value": 2138
},
"has_address_line_1_text": {
"has_value": "123 Lending Lane"
}
},
{
"@id": "subject_property_address_id",
"@type": "subject_property_address",
"has_county_name": {
"has_value": "Pinellas"
},
"has_state_code": {
"has_value": "TX"
},
"has_city_name": {
"has_value": "Salem"
},
"has_postal_code": {
"has_value": "2138"
},
"has_address_line_1_text": {
"has_value": "456 Main Street"
}
},
{
"@id": "borrower_address_id",
"@type": "residential_address",
"has_state_code": {
"has_value": "TX"
},
"has_city_name": {
"has_value": "Salem"
},
"has_postal_code": {
"has_value": "2138"
},
"has_address_line_1_text": {
"has_value": "456 Main Street"
}
}
],
"documents": [
{
"@id": "document_id",
"@type": "document",
"has_staircase_blob_identifier": {
"has_value": "01G2YVWSGPQC9Y9A6AXTHYMDET"
}
}
],
"government_loans": [
{
"@id": "government_loan_id",
"@type": "government_loan",
"has_fha_case_number": {
"has_value": "FHA111111111"
}
}
],
"loans": [
{
"@id": "loan_id",
"@type": "loan",
"has_loan_identifier_value": {
"has_value": "01G313MDG9KVKW62YK8S1WNMWB"
},
"with_government_loan": [
"government_loan_id"
]
}
],
"loan_terms": [
{
"@id": "loan_term_id",
"@type": "loan_terms",
"has_loan_purpose_type": {
"has_value": "refinance"
}
}
],
"organizations": [
{
"@id": "organization_id",
"@type": "organization",
"has_organization_name": {
"has_value": "Liberty Lending"
},
"with_address": [
"address_id"
]
}
],
"people": [
{
"@id": "appraiser_id",
"@type": "appraiser",
"has_appraisal_sub_committee_appraiser_identifier": {
"has_value": "A12345"
},
"has_full_name": {
"has_value": "Alan Appraiser"
}
},
{
"@id": "borrower_id",
"@type": "borrower",
"has_full_name": {
"has_value": "Jane Doe"
},
"lives_at": [
"residence_id"
]
},
{
"@id": "co_borrower_id",
"@type": "borrower",
"has_full_name": {
"has_value": "John Doe"
}
}
],
"properties": [
{
"@id": "subject_property_id",
"@type": "subject_property",
"with_address": [
"subject_property_address_id"
],
"with_sales_contract": [
"sales_contract_id"
]
}
],
"property_valuations": [
{
"@id": "property_valution_id",
"@type": "property_valuation",
"has_property_inspection_type_other_description": {
"has_value": "1004"
}
}
],
"residences": [
{
"@id": "residence_id",
"@type": "residence",
"with_address": [
"borrower_address_id"
]
}
],
"roles": [
{
"@id": "role_id",
"@type": "role",
"with_appraiser": [
"appraiser_id"
]
}
],
"sales_contracts": [
{
"@id": "sales_contract_id",
"@type": "property_sales_contract",
"has_sales_contract_amount": {
"has_value": 123456
}
}
]
}
]
}
```
application/json Copy Error
```
{
"message": "Please provide one of valid return examples values:\ntrue, false"
}
```
text/html Copy Error
```
\r\n400 Bad Request\r\n\r\n400
Bad Request
\r\n\r\n\r\n
```
application/json Copy 403 invalid error
```
{
"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 Resource not found
```
{
"type": "string",
"description": "Error Message."
}
```
text/html Copy Resource not found
```
\r\n400 Bad Request\r\n\r\n400
Bad Request
\r\n\r\n\r\n
```
application/json Copy Internal server error
```
{
"message": "The product has encountered an internal server error. If you\nhave used a transaction_id to call our services, please submit it to\nStaircase support"
}
```
##### Parameters
2
| Parameter | Type | Description |
| --- | --- | --- |
| `x-api-key` required | `string` header | Environment API Key. |
| `return_examples` | `boolean` query | If included and set to `true`, returns one or more pre-filled examples that conform to the schema. Default to `false` |
##### Response `200``application/json`
2 fields
Request schema (possibly with examples) is successfully returned.
| Field | Type | Description |
| --- | --- | --- |
| `schema`required | `object` | Schema for the Request Collection |
| `examples` | `object` | Each item in the dictionary corresponds to the name of the example and dictionary content is the sample response. |
##### Response `400``application/json`
1 fields
Error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | 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` | Error Message. |
##### Response `500``application/json`
1 fields
Internal server error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message. |
`GET` `/products/collateral-underwriting/response-schema`
#### Retrieve Response Schema
`retrieveResponseSchema`
Retrieve Response Schema returns the JSON schema for the response collection, created by an invocation.
If you would like to retrieve examples along with the schema, you can provide `return_examples=True` query parameter.
##### Response
200 Schema200 Schema with Examples Response400 InvalidReturnExamplesValue400 text/html403404 GetProduct404 text/html500
application/json Copy Response schema (possibly with examples) is successfully returned.
```
{
"schema": {
"type": "object",
"required": [
"services",
"foreign_objects"
],
"properties": {
"services": {
"type": "array",
"items": {
"type": "object",
"required": [
"@id",
"@type",
"has_service_name",
"has_service_vendor_name",
"with_foreign_object"
],
"properties": {
"@id": {
"type": "string"
},
"@type": {
"type": "string"
},
"has_service_name": {
"type": "object",
"required": [
"has_value"
],
"properties": {
"has_value": {
"type": "string"
}
}
},
"has_service_vendor_name": {
"type": "object",
"required": [
"has_value"
],
"properties": {
"has_value": {
"type": "string"
}
}
},
"with_foreign_object": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"foreign_objects": {
"type": "array",
"items": {
"type": "object",
"required": [
"@id",
"@type",
"has_object_name"
],
"properties": {
"@id": {
"type": "string"
},
"@type": {
"type": "string"
},
"has_object_name": {
"type": "object",
"required": [
"has_value"
],
"properties": {
"has_value": {
"type": "string"
}
}
},
"has_object_url_value": {
"type": "object",
"required": [
"has_value"
],
"properties": {
"has_value": {
"type": "string"
}
}
}
}
}
}
}
}
}
```
application/json Copy Response schema (possibly with examples) is successfully returned.
```
{
"schema": {
"type": "object",
"required": [
"services",
"foreign_objects"
],
"properties": {
"services": {
"type": "array",
"items": {
"type": "object",
"required": [
"@id",
"@type",
"has_service_name",
"has_service_vendor_name",
"with_foreign_object"
],
"properties": {
"@id": {
"type": "string"
},
"@type": {
"type": "string"
},
"has_service_name": {
"type": "object",
"required": [
"has_value"
],
"properties": {
"has_value": {
"type": "string"
}
}
},
"has_service_vendor_name": {
"type": "object",
"required": [
"has_value"
],
"properties": {
"has_value": {
"type": "string"
}
}
},
"with_foreign_object": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"foreign_objects": {
"type": "array",
"items": {
"type": "object",
"required": [
"@id",
"@type",
"has_object_name"
],
"properties": {
"@id": {
"type": "string"
},
"@type": {
"type": "string"
},
"has_object_name": {
"type": "object",
"required": [
"has_value"
],
"properties": {
"has_value": {
"type": "string"
}
}
},
"has_object_url_value": {
"type": "object",
"required": [
"has_value"
],
"properties": {
"has_value": {
"type": "string"
}
}
}
}
}
}
}
},
"examples": [
{
"services": [
{
"@id": "service_id",
"@type": "service",
"has_service_name": {
"has_value": "Collateral Underwriting"
},
"has_service_vendor_name": {
"has_value": "homevision"
},
"with_foreign_object": [
"f1",
"f2",
"f3",
"f4"
]
}
],
"foreign_objects": [
{
"@id": "f1",
"@type": "foreign_object",
"has_object_name": {
"has_value": "internal_url"
},
"has_object_url_value": {
"has_value": "https://app.homevision.co/xmlqc/2394077"
}
},
{
"@id": "f2",
"@type": "foreign_object",
"has_object_name": {
"has_value": "pdf_url"
},
"has_object_url_value": {
"has_value": "https://app.homevision.co/123456/pdf.pdf"
}
},
{
"@id": "f3",
"@type": "foreign_object",
"has_object_name": {
"has_value": "xml_url"
},
"has_object_url_value": {
"has_value": "https://app.homevision.co/123456/xml.xml"
}
},
{
"@id": "f4",
"@type": "foreign_object",
"has_object_name": {
"has_value": "env_url"
},
"has_object_url_value": {
"has_value": "https://app.homevision.co/123456/env.env"
}
}
]
}
]
}
```
application/json Copy Error
```
{
"message": "Please provide one of valid return examples values:\ntrue, false"
}
```
text/html Copy Error
```
\r\n400 Bad Request\r\n\r\n400
Bad Request
\r\n\r\n\r\n
```
application/json Copy 403 invalid error
```
{
"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 Resource not found
```
{
"type": "string",
"description": "Error Message."
}
```
text/html Copy Resource not found
```
\r\n400 Bad Request\r\n\r\n400
Bad Request
\r\n\r\n\r\n
```
application/json Copy Internal server error
```
{
"message": "The product has encountered an internal server error. If you\nhave used a transaction_id to call our services, please submit it to\nStaircase support"
}
```
##### Parameters
2
| Parameter | Type | Description |
| --- | --- | --- |
| `x-api-key` required | `string` header | Environment API Key. |
| `return_examples` | `boolean` query | If included and set to `true`, returns one or more pre-filled examples that conform to the schema. Default to `false` |
##### Response `200``application/json`
2 fields
Response schema (possibly with examples) is successfully returned.
| Field | Type | Description |
| --- | --- | --- |
| `schema`required | `object` | JSON-Schema as a single object |
| `examples` | `object` | A key-value pair for the examples. Keys are the example names, while values correspond to the example values for the response collections you can retrieve. |
##### Response `400``application/json`
1 fields
Error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | 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` | Error Message. |
##### Response `500``application/json`
1 fields
Internal server error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message. |
### Platform
`POST` `/transactions`
#### Create Transaction
`createTransaction`
Create Transaction creates a transaction in Staircase. Transactions in Staircase are containers for all the data related to an instance of a transaction type. They enable you to correlate the output of various products to a single transaction type, where the transaction type depends on your line of business.
Transactions are identified by a unique key called `transaction_id`. As you use different Staircase products to gather the data needed for a specific instance of your transaction type, and receive different sets of output from each product, use the same transaction_id to correlate all the outputs to the same transaction. A `transaction_id`, when used properly, gives you a holistic view of the data related to the transaction you’ve assembled.
To access all collections associated with a given transaction_id, try out /transactions/{transaction_id}/collections
##### Response
201403500
application/json Copy Transaction created successfully
```
{
"transaction_id": "01F0KHK7DN3H5JZ4QJKMYAM6GB",
"created_at": "03/04/2021, 1:04:05 PM EST"
}
```
application/json Copy 403 invalid error
```
{
"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 Internal server error
```
{
"message": "The product has encountered an internal server error. If you\nhave used a transaction_id to call our services, please submit it to\nStaircase support"
}
```
##### Parameters
1
| Parameter | Type | Description |
| --- | --- | --- |
| `x-api-key` required | `string` header | Environment API Key. |
##### Response `201``application/json`
2 fields
Transaction created successfully
| Field | Type | Description |
| --- | --- | --- |
| `transaction_id` | `string (ulid)` | Staircase Transaction IdentifierExample `01F0KHK7DN3H5JZ4QJKMYAM6GB` |
| `created_at` | `string` | Staircase time string.Example `03/03/2021, 8:24:04 AM EST` |
##### Response `403``application/json`
2 fields
403 invalid error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message. |
| `url` | `string` | Error additional URL. |
##### Response `500``application/json`
1 fields
Internal server error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message. |
##### Other responses
`400`
`POST` `/transactions/{transaction_id}/collections`
#### Create Collection
`createCollection`
Create Collection creates a collection of data points required for product invocation. A collection contains a digital representation of the input or output data for the product and is identified by `collection_id`.
The Example below contains a sample collection that you can use to make the product invocation in /products/collateral-underwriting/invocations
##### Request
Conventional ExampleFha Example
application/json Copy
```
{
"data": {
"addresses": [
{
"@id": "address_id",
"@type": "business_address",
"has_state_code": {
"has_value": "CA"
},
"has_city_name": {
"has_value": "Bankville"
},
"has_postal_code": {
"has_value": 2138
},
"has_address_line_1_text": {
"has_value": "123 Lending Lane"
}
},
{
"@id": "subject_property_address_id",
"@type": "subject_property_address",
"has_county_name": {
"has_value": "Pinellas"
},
"has_state_code": {
"has_value": "TX"
},
"has_city_name": {
"has_value": "Salem"
},
"has_postal_code": {
"has_value": "2138"
},
"has_address_line_1_text": {
"has_value": "456 Main Street"
}
},
{
"@id": "borrower_address_id",
"@type": "residential_address",
"has_state_code": {
"has_value": "TX"
},
"has_city_name": {
"has_value": "Salem"
},
"has_postal_code": {
"has_value": "2138"
},
"has_address_line_1_text": {
"has_value": "456 Main Street"
}
}
],
"documents": [
{
"@id": "document_id",
"@type": "document",
"has_staircase_blob_identifier": {
"has_value": "01G2YVWSGPQC9Y9A6AXTHYMDET"
}
}
],
"loans": [
{
"@id": "loan_id",
"@type": "loan",
"has_loan_identifier_value": {
"has_value": "01G313MDG9KVKW62YK8S1WNMWB"
}
}
],
"loan_terms": [
{
"@id": "loan_term_id",
"@type": "loan_terms",
"has_loan_purpose_type": {
"has_value": "refinance"
}
}
],
"organizations": [
{
"@id": "organization_id",
"@type": "organization",
"has_organization_name": {
"has_value": "Liberty Lending"
},
"with_address": [
"address_id"
]
}
],
"people": [
{
"@id": "appraiser_id",
"@type": "appraiser",
"has_appraisal_sub_committee_appraiser_identifier": {
"has_value": "A12345"
},
"has_full_name": {
"has_value": "Alan Appraiser"
}
},
{
"@id": "borrower_id",
"@type": "borrower",
"has_full_name": {
"has_value": "Jane Doe"
},
"lives_at": [
"residence_id"
]
},
{
"@id": "co_borrower_id",
"@type": "borrower",
"has_full_name": {
"has_value": "John Doe"
}
}
],
"properties": [
{
"@id": "subject_property_id",
"@type": "subject_property",
"with_address": [
"subject_property_address_id"
],
"with_sales_contract": [
"sales_contract_id"
]
}
],
"property_valuations": [
{
"@id": "property_valution_id",
"@type": "property_valuation",
"has_property_inspection_type_other_description": {
"has_value": "1004"
}
}
],
"residences": [
{
"@id": "residence_id",
"@type": "residence",
"with_address": [
"borrower_address_id"
]
}
],
"roles": [
{
"@id": "role_id",
"@type": "role",
"with_appraiser": [
"appraiser_id"
]
}
],
"sales_contracts": [
{
"@id": "sales_contract_id",
"@type": "property_sales_contract",
"has_sales_contract_amount": {
"has_value": 123456
}
}
]
}
}
```
application/json Copy
```
{
"data": {
"addresses": [
{
"@id": "address_id",
"@type": "business_address",
"has_state_code": {
"has_value": "CA"
},
"has_city_name": {
"has_value": "Bankville"
},
"has_postal_code": {
"has_value": 2138
},
"has_address_line_1_text": {
"has_value": "123 Lending Lane"
}
},
{
"@id": "subject_property_address_id",
"@type": "subject_property_address",
"has_county_name": {
"has_value": "Pinellas"
},
"has_state_code": {
"has_value": "TX"
},
"has_city_name": {
"has_value": "Salem"
},
"has_postal_code": {
"has_value": "2138"
},
"has_address_line_1_text": {
"has_value": "456 Main Street"
}
},
{
"@id": "borrower_address_id",
"@type": "residential_address",
"has_state_code": {
"has_value": "TX"
},
"has_city_name": {
"has_value": "Salem"
},
"has_postal_code": {
"has_value": "2138"
},
"has_address_line_1_text": {
"has_value": "456 Main Street"
}
}
],
"documents": [
{
"@id": "document_id",
"@type": "document",
"has_staircase_blob_identifier": {
"has_value": "01G2YVWSGPQC9Y9A6AXTHYMDET"
}
}
],
"government_loans": [
{
"@id": "government_loan_id",
"@type": "government_loan",
"has_fha_case_number": {
"has_value": "FHA111111111"
}
}
],
"loans": [
{
"@id": "loan_id",
"@type": "loan",
"has_loan_identifier_value": {
"has_value": "01G313MDG9KVKW62YK8S1WNMWB"
},
"with_government_loan": [
"government_loan_id"
]
}
],
"loan_terms": [
{
"@id": "loan_term_id",
"@type": "loan_terms",
"has_loan_purpose_type": {
"has_value": "refinance"
}
}
],
"organizations": [
{
"@id": "organization_id",
"@type": "organization",
"has_organization_name": {
"has_value": "Liberty Lending"
},
"with_address": [
"address_id"
]
}
],
"people": [
{
"@id": "appraiser_id",
"@type": "appraiser",
"has_appraisal_sub_committee_appraiser_identifier": {
"has_value": "A12345"
},
"has_full_name": {
"has_value": "Alan Appraiser"
}
},
{
"@id": "borrower_id",
"@type": "borrower",
"has_full_name": {
"has_value": "Jane Doe"
},
"lives_at": [
"residence_id"
]
},
{
"@id": "co_borrower_id",
"@type": "borrower",
"has_full_name": {
"has_value": "John Doe"
}
}
],
"properties": [
{
"@id": "subject_property_id",
"@type": "subject_property",
"with_address": [
"subject_property_address_id"
],
"with_sales_contract": [
"sales_contract_id"
]
}
],
"property_valuations": [
{
"@id": "property_valution_id",
"@type": "property_valuation",
"has_property_inspection_type_other_description": {
"has_value": "1004"
}
}
],
"residences": [
{
"@id": "residence_id",
"@type": "residence",
"with_address": [
"borrower_address_id"
]
}
],
"roles": [
{
"@id": "role_id",
"@type": "role",
"with_appraiser": [
"appraiser_id"
]
}
],
"sales_contracts": [
{
"@id": "sales_contract_id",
"@type": "property_sales_contract",
"has_sales_contract_amount": {
"has_value": 123456
}
}
]
}
}
```
##### Response
201400 CreateCollectionError400 text/html403404 CreateCollectionError404 text/html500
application/json Copy Collection created successfully
```
{
"transaction_id": "01F0KHK7DN3H5JZ4QJKMYAM6GB",
"collection_id": "01F6QF1QJF20DMSXH4SYXKB1SN",
"metadata": {
"created_at": "2021-09-14T03:08:00.284090-04:00",
"validation": false
},
"data": {
"addresses": [
{
"@id": "address_id",
"@type": "business_address",
"has_state_code": {
"has_value": "CA"
},
"has_city_name": {
"has_value": "Bankville"
},
"has_postal_code": {
"has_value": 2138
},
"has_address_line_1_text": {
"has_value": "123 Lending Lane"
}
},
{
"@id": "subject_property_address_id",
"@type": "subject_property_address",
"has_county_name": {
"has_value": "Pinellas"
},
"has_state_code": {
"has_value": "TX"
},
"has_city_name": {
"has_value": "Salem"
},
"has_postal_code": {
"has_value": "2138"
},
"has_address_line_1_text": {
"has_value": "456 Main Street"
}
},
{
"@id": "borrower_address_id",
"@type": "residential_address",
"has_state_code": {
"has_value": "TX"
},
"has_city_name": {
"has_value": "Salem"
},
"has_postal_code": {
"has_value": "2138"
},
"has_address_line_1_text": {
"has_value": "456 Main Street"
}
}
],
"documents": [
{
"@id": "document_id",
"@type": "document",
"has_staircase_blob_identifier": {
"has_value": "01G2YVWSGPQC9Y9A6AXTHYMDET"
}
}
],
"loans": [
{
"@id": "loan_id",
"@type": "loan",
"has_loan_identifier_value": {
"has_value": "01G313MDG9KVKW62YK8S1WNMWB"
}
}
],
"loan_terms": [
{
"@id": "loan_term_id",
"@type": "loan_terms",
"has_loan_purpose_type": {
"has_value": "refinance"
}
}
],
"organizations": [
{
"@id": "organization_id",
"@type": "organization",
"has_organization_name": {
"has_value": "Liberty Lending"
},
"with_address": [
"address_id"
]
}
],
"people": [
{
"@id": "appraiser_id",
"@type": "appraiser",
"has_appraisal_sub_committee_appraiser_identifier": {
"has_value": "A12345"
},
"has_full_name": {
"has_value": "Alan Appraiser"
}
},
{
"@id": "borrower_id",
"@type": "borrower",
"has_full_name": {
"has_value": "Jane Doe"
},
"lives_at": [
"residence_id"
]
},
{
"@id": "co_borrower_id",
"@type": "borrower",
"has_full_name": {
"has_value": "John Doe"
}
}
],
"properties": [
{
"@id": "subject_property_id",
"@type": "subject_property",
"with_address": [
"subject_property_address_id"
],
"with_sales_contract": [
"sales_contract_id"
]
}
],
"property_valuations": [
{
"@id": "property_valution_id",
"@type": "property_valuation",
"has_property_inspection_type_other_description": {
"has_value": "1004"
}
}
],
"residences": [
{
"@id": "residence_id",
"@type": "residence",
"with_address": [
"borrower_address_id"
]
}
],
"roles": [
{
"@id": "role_id",
"@type": "role",
"with_appraiser": [
"appraiser_id"
]
}
],
"sales_contracts": [
{
"@id": "sales_contract_id",
"@type": "property_sales_contract",
"has_sales_contract_amount": {
"has_value": 123456
}
}
]
}
}
```
application/json Copy Error
```
{
"message": "Unable to create collection. Please check the collectionchr\ndata"
}
```
text/html Copy Error
```
\r\n400 Bad Request\r\n\r\n400
Bad Request
\r\n\r\n\r\n
```
application/json Copy 403 invalid error
```
{
"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 Resource not found
```
{
"message": "Unable to create collection. Please check the transaction\nID."
}
```
text/html Copy Resource not found
```
\r\n400 Bad Request\r\n\r\n400
Bad Request
\r\n\r\n\r\n
```
application/json Copy Internal server error
```
{
"message": "The product has encountered an internal server error. If you\nhave used a transaction_id to call our services, please submit it to\nStaircase support"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | — | Environment API Key. |
| `transaction_id` required | `string (ulid)` path | `01F0KHK7DN3H5JZ4QJKMYAM6GB` | Staircase Transaction Identifier |
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `data` | `object` | The data that is needed for invocation. It should follow the request schema |
| `addresses`required | `object[]` | — |
| `@id`required | `string` | — |
| `@type`required | `string` | — |
| `has_state_code`required | `object` | — |
| `has_value`required | `string` | — |
| `has_city_name`required | `object` | — |
| `has_value`required | `string` | — |
| `has_postal_code`required | `object` | — |
| `has_value`required | `string` | — |
| `has_address_line_1_text`required | `object` | — |
| `has_value`required | `string` | — |
| `has_county_name` | `object` | — |
| `has_value`required | `string` | — |
| `documents`required | `object[]` | — |
| `@id`required | `string` | — |
| `@type`required | `string` | — |
| `has_staircase_blob_identifier`required | `object` | — |
| `has_value`required | `string` | — |
| `loans`required | `object[]` | — |
| `@id`required | `string` | — |
| `@type`required | `string` | — |
| `with_government_loan` | `string[]` | — |
| `has_loan_identifier_value`required | `object` | — |
| `has_value`required | `string` | — |
| `government_loans` | `object[]` | — |
| `@id`required | `string` | — |
| `@type`required | `string` | — |
| `has_fha_case_number`required | `object` | — |
| `has_value`required | `string` | — |
| `loan_terms`required | `object[]` | — |
| `@id`required | `string` | — |
| `@type`required | `string` | — |
| `has_loan_purpose_type`required | `object` | — |
| `has_value`required | `string` | — |
| `organizations`required | `object[]` | — |
| `@id`required | `string` | — |
| `@type`required | `string` | — |
| `has_organization_name`required | `object` | — |
| `has_value`required | `string` | — |
| `with_address`required | `string[]` | — |
| `people`required | `object[]` | — |
| `@id`required | `string` | — |
| `@type`required | `string` | — |
| `has_appraisal_sub_committee_appraiser_identifier` | `object` | — |
| `has_value`required | `string` | — |
| `has_full_name`required | `object` | — |
| `has_value`required | `string` | — |
| `lives_at` | `string[]` | — |
| `properties`required | `object[]` | — |
| `@id`required | `string` | — |
| `@type`required | `string` | — |
| `with_address`required | `string[]` | — |
| `with_sales_contract`required | `string[]` | — |
| `property_valuations`required | `object[]` | — |
| `@id`required | `string` | — |
| `@type`required | `string` | — |
| `has_property_inspection_type_other_description`required | `object` | — |
| `has_value`required | `string` | — |
| `residences`required | `object[]` | — |
| `@id`required | `string` | — |
| `@type`required | `string` | — |
| `with_address`required | `string[]` | — |
| `roles`required | `object[]` | — |
| `@id`required | `string` | — |
| `@type`required | `string` | — |
| `with_appraiser`required | `string[]` | — |
| `sales_contracts`required | `object[]` | — |
| `@id`required | `string` | — |
| `@type`required | `string` | — |
| `has_sales_contract_amount`required | `object` | — |
| `has_value`required | `integer` | — |
##### Response `201``application/json`
4 fields
Collection created successfully
| Field | Type | Description |
| --- | --- | --- |
| `transaction_id` | `string (ulid)` | Transaction ID.Example `01EZQ32PJQGKRA6HR8D72Q9FFF` |
| `collection_id` | `string (ulid)` | Collection ID.Example `01EZQ32PJQGKRA6HR8D72Q9FFF` |
| `data` | `object` | Data in Staircase language schema. |
| `metadata` | `object` | Metadata about collection, f.e version of used Staircase schema. |
##### Response `400``application/json`
1 fields
Error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Either message object with more properties. |
##### 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 |
##### Response `500``application/json`
1 fields
Internal server error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message. |
##### Other responses
`405`
`GET` `/transactions/{transaction_id}/collections/{collection_id}`
#### Retrieve Collection
`retrieveCollection`
Retrieve Collection returns the content of a given `collection_id` associated with a `transaction_id`.
##### Response
403404 GetCollectionError404 GetCollectionsError500
application/json Copy 403 invalid error
```
{
"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 Resource not found
```
{
"message": "Unable to get collection. Please check the given ids"
}
```
application/json Copy Resource not found
```
{
"message": "Unable to get collections of given transaction. Please\ncheck the transaction id"
}
```
application/json Copy Internal server error
```
{
"message": "The product has encountered an internal server error. If you\nhave used a transaction_id to call our services, please submit it to\nStaircase support"
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | — | Environment API Key. |
| `transaction_id` required | `string (ulid)` path | `01F0KHK7DN3H5JZ4QJKMYAM6GB` | Staircase Transaction Identifier |
| `collection_id` required | `string (ulid)` path | `01F0KHKADN0HRFXMCQQXPA6AFZ` | Staircase collection_id |
##### Response `200``application/json`
4 fields
Successfully Retrieved Collection
| Field | Type | Description |
| --- | --- | --- |
| `transaction_id`required | `string` | — |
| `collection_id`required | `string` | — |
| `metadata`required | `object` | — |
| `created_at`required | `string` | — |
| `validation`required | `boolean` | — |
| `data`required | `object` | — |
##### 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 |
##### Response `500``application/json`
1 fields
Internal server error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message. |
##### Other responses
`400`
`GET` `/transactions/{transaction_id}/collections`
#### Retrieve Transaction Collections
`RetrieveTransactionCollections`
Retrieve Transaction Collections returns the content of a given `collection_id` associated with a specific `transaction_id`.
##### Response
200400403404500
application/json Copy Transaction collection retrieved successfully
```
{
"metadata": {
"created_at": "2021-09-14T03:08:00.284090-04:00",
"validation": false
},
"transaction_id": "01FFHJ2ZVS4P7N4AV5W0993QMD",
"collection_id": "01FFHJ4JCWGHV38SC1NJ8TVNFY",
"data": {}
}
```
text/html Copy Error
```
\r\n400 Bad Request\r\n\r\n400
Bad Request
\r\n\r\n\r\n
```
application/json Copy 403 invalid error
```
{
"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 Resource not found
```
{
"message": "Unable to get collections of given transaction. Please\ncheck the transaction id"
}
```
application/json Copy Internal server error
```
{
"message": "The product has encountered an internal server error. If you\nhave used a transaction_id to call our services, please submit it to\nStaircase support"
}
```
##### Parameters
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | — | Environment API Key. |
| `transaction_id` required | `string (ulid)` path | `01F0KHK7DN3H5JZ4QJKMYAM6GB` | Staircase Transaction Identifier |
##### Response `200``application/json`
4 fields
Transaction collection retrieved successfully
| Field | Type | Description |
| --- | --- | --- |
| `transaction_id` | `string (ulid)` | Transaction ID.Example `01EZQ32PJQGKRA6HR8D72Q9FFF` |
| `collection_id` | `string (ulid)` | Collection ID.Example `01EZQ32PJQGKRA6HR8D72Q9FFF` |
| `data` | `object` | Data in Staircase language schema. |
| `metadata` | `object` | Metadata about collection, f.e version of used Staircase schema. |
##### Response `400``application/json`
1 fields
Error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Either message object with more properties. |
##### 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 |
##### Response `500``application/json`
1 fields
Internal server error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message. |
`PUT` `/transactions/{transaction_id}/collections/{collection_id}`
#### Update Collection
`updateCollection`
Update Collection allows you to update the content of a given `collection_id` associated with a `transaction_id`.
##### Request
Conventional ExampleFha Example
application/json Copy
```
{
"data": {
"addresses": [
{
"@id": "address_id",
"@type": "business_address",
"has_state_code": {
"has_value": "CA"
},
"has_city_name": {
"has_value": "Bankville"
},
"has_postal_code": {
"has_value": 2138
},
"has_address_line_1_text": {
"has_value": "123 Lending Lane"
}
},
{
"@id": "subject_property_address_id",
"@type": "subject_property_address",
"has_county_name": {
"has_value": "Pinellas"
},
"has_state_code": {
"has_value": "TX"
},
"has_city_name": {
"has_value": "Salem"
},
"has_postal_code": {
"has_value": "2138"
},
"has_address_line_1_text": {
"has_value": "456 Main Street"
}
},
{
"@id": "borrower_address_id",
"@type": "residential_address",
"has_state_code": {
"has_value": "TX"
},
"has_city_name": {
"has_value": "Salem"
},
"has_postal_code": {
"has_value": "2138"
},
"has_address_line_1_text": {
"has_value": "456 Main Street"
}
}
],
"documents": [
{
"@id": "document_id",
"@type": "document",
"has_staircase_blob_identifier": {
"has_value": "01G2YVWSGPQC9Y9A6AXTHYMDET"
}
}
],
"loans": [
{
"@id": "loan_id",
"@type": "loan",
"has_loan_identifier_value": {
"has_value": "01G313MDG9KVKW62YK8S1WNMWB"
}
}
],
"loan_terms": [
{
"@id": "loan_term_id",
"@type": "loan_terms",
"has_loan_purpose_type": {
"has_value": "refinance"
}
}
],
"organizations": [
{
"@id": "organization_id",
"@type": "organization",
"has_organization_name": {
"has_value": "Liberty Lending"
},
"with_address": [
"address_id"
]
}
],
"people": [
{
"@id": "appraiser_id",
"@type": "appraiser",
"has_appraisal_sub_committee_appraiser_identifier": {
"has_value": "A12345"
},
"has_full_name": {
"has_value": "Alan Appraiser"
}
},
{
"@id": "borrower_id",
"@type": "borrower",
"has_full_name": {
"has_value": "Jane Doe"
},
"lives_at": [
"residence_id"
]
},
{
"@id": "co_borrower_id",
"@type": "borrower",
"has_full_name": {
"has_value": "John Doe"
}
}
],
"properties": [
{
"@id": "subject_property_id",
"@type": "subject_property",
"with_address": [
"subject_property_address_id"
],
"with_sales_contract": [
"sales_contract_id"
]
}
],
"property_valuations": [
{
"@id": "property_valution_id",
"@type": "property_valuation",
"has_property_inspection_type_other_description": {
"has_value": "1004"
}
}
],
"residences": [
{
"@id": "residence_id",
"@type": "residence",
"with_address": [
"borrower_address_id"
]
}
],
"roles": [
{
"@id": "role_id",
"@type": "role",
"with_appraiser": [
"appraiser_id"
]
}
],
"sales_contracts": [
{
"@id": "sales_contract_id",
"@type": "property_sales_contract",
"has_sales_contract_amount": {
"has_value": 123456
}
}
]
}
}
```
application/json Copy
```
{
"data": {
"addresses": [
{
"@id": "address_id",
"@type": "business_address",
"has_state_code": {
"has_value": "CA"
},
"has_city_name": {
"has_value": "Bankville"
},
"has_postal_code": {
"has_value": 2138
},
"has_address_line_1_text": {
"has_value": "123 Lending Lane"
}
},
{
"@id": "subject_property_address_id",
"@type": "subject_property_address",
"has_county_name": {
"has_value": "Pinellas"
},
"has_state_code": {
"has_value": "TX"
},
"has_city_name": {
"has_value": "Salem"
},
"has_postal_code": {
"has_value": "2138"
},
"has_address_line_1_text": {
"has_value": "456 Main Street"
}
},
{
"@id": "borrower_address_id",
"@type": "residential_address",
"has_state_code": {
"has_value": "TX"
},
"has_city_name": {
"has_value": "Salem"
},
"has_postal_code": {
"has_value": "2138"
},
"has_address_line_1_text": {
"has_value": "456 Main Street"
}
}
],
"documents": [
{
"@id": "document_id",
"@type": "document",
"has_staircase_blob_identifier": {
"has_value": "01G2YVWSGPQC9Y9A6AXTHYMDET"
}
}
],
"government_loans": [
{
"@id": "government_loan_id",
"@type": "government_loan",
"has_fha_case_number": {
"has_value": "FHA111111111"
}
}
],
"loans": [
{
"@id": "loan_id",
"@type": "loan",
"has_loan_identifier_value": {
"has_value": "01G313MDG9KVKW62YK8S1WNMWB"
},
"with_government_loan": [
"government_loan_id"
]
}
],
"loan_terms": [
{
"@id": "loan_term_id",
"@type": "loan_terms",
"has_loan_purpose_type": {
"has_value": "refinance"
}
}
],
"organizations": [
{
"@id": "organization_id",
"@type": "organization",
"has_organization_name": {
"has_value": "Liberty Lending"
},
"with_address": [
"address_id"
]
}
],
"people": [
{
"@id": "appraiser_id",
"@type": "appraiser",
"has_appraisal_sub_committee_appraiser_identifier": {
"has_value": "A12345"
},
"has_full_name": {
"has_value": "Alan Appraiser"
}
},
{
"@id": "borrower_id",
"@type": "borrower",
"has_full_name": {
"has_value": "Jane Doe"
},
"lives_at": [
"residence_id"
]
},
{
"@id": "co_borrower_id",
"@type": "borrower",
"has_full_name": {
"has_value": "John Doe"
}
}
],
"properties": [
{
"@id": "subject_property_id",
"@type": "subject_property",
"with_address": [
"subject_property_address_id"
],
"with_sales_contract": [
"sales_contract_id"
]
}
],
"property_valuations": [
{
"@id": "property_valution_id",
"@type": "property_valuation",
"has_property_inspection_type_other_description": {
"has_value": "1004"
}
}
],
"residences": [
{
"@id": "residence_id",
"@type": "residence",
"with_address": [
"borrower_address_id"
]
}
],
"roles": [
{
"@id": "role_id",
"@type": "role",
"with_appraiser": [
"appraiser_id"
]
}
],
"sales_contracts": [
{
"@id": "sales_contract_id",
"@type": "property_sales_contract",
"has_sales_contract_amount": {
"has_value": 123456
}
}
]
}
}
```
##### Response
200400 UpdateCollectionError400 text/html403404 UpdateCollectionError404 text/html500
application/json Copy Collection updated successfully
```
{
"transaction_id": "01F0KHK7DN3H5JZ4QJKMYAM6GB",
"collection_id": "01F6QF1QJF20DMSXH4SYXKB1SN",
"metadata": {
"created_at": "2021-09-14T03:08:00.284090-04:00",
"validation": false
},
"data": {
"addresses": [
{
"@id": "address_id",
"@type": "business_address",
"has_state_code": {
"has_value": "CA"
},
"has_city_name": {
"has_value": "Bankville"
},
"has_postal_code": {
"has_value": 2138
},
"has_address_line_1_text": {
"has_value": "123 Lending Lane"
}
},
{
"@id": "subject_property_address_id",
"@type": "subject_property_address",
"has_county_name": {
"has_value": "Pinellas"
},
"has_state_code": {
"has_value": "TX"
},
"has_city_name": {
"has_value": "Salem"
},
"has_postal_code": {
"has_value": "2138"
},
"has_address_line_1_text": {
"has_value": "456 Main Street"
}
},
{
"@id": "borrower_address_id",
"@type": "residential_address",
"has_state_code": {
"has_value": "TX"
},
"has_city_name": {
"has_value": "Salem"
},
"has_postal_code": {
"has_value": "2138"
},
"has_address_line_1_text": {
"has_value": "456 Main Street"
}
}
],
"documents": [
{
"@id": "document_id",
"@type": "document",
"has_staircase_blob_identifier": {
"has_value": "01G2YVWSGPQC9Y9A6AXTHYMDET"
}
}
],
"loans": [
{
"@id": "loan_id",
"@type": "loan",
"has_loan_identifier_value": {
"has_value": "01G313MDG9KVKW62YK8S1WNMWB"
}
}
],
"loan_terms": [
{
"@id": "loan_term_id",
"@type": "loan_terms",
"has_loan_purpose_type": {
"has_value": "refinance"
}
}
],
"organizations": [
{
"@id": "organization_id",
"@type": "organization",
"has_organization_name": {
"has_value": "Liberty Lending"
},
"with_address": [
"address_id"
]
}
],
"people": [
{
"@id": "appraiser_id",
"@type": "appraiser",
"has_appraisal_sub_committee_appraiser_identifier": {
"has_value": "A12345"
},
"has_full_name": {
"has_value": "Alan Appraiser"
}
},
{
"@id": "borrower_id",
"@type": "borrower",
"has_full_name": {
"has_value": "Jane Doe"
},
"lives_at": [
"residence_id"
]
},
{
"@id": "co_borrower_id",
"@type": "borrower",
"has_full_name": {
"has_value": "John Doe"
}
}
],
"properties": [
{
"@id": "subject_property_id",
"@type": "subject_property",
"with_address": [
"subject_property_address_id"
],
"with_sales_contract": [
"sales_contract_id"
]
}
],
"property_valuations": [
{
"@id": "property_valution_id",
"@type": "property_valuation",
"has_property_inspection_type_other_description": {
"has_value": "1004"
}
}
],
"residences": [
{
"@id": "residence_id",
"@type": "residence",
"with_address": [
"borrower_address_id"
]
}
],
"roles": [
{
"@id": "role_id",
"@type": "role",
"with_appraiser": [
"appraiser_id"
]
}
],
"sales_contracts": [
{
"@id": "sales_contract_id",
"@type": "property_sales_contract",
"has_sales_contract_amount": {
"has_value": 123456
}
}
]
}
}
```
application/json Copy Error
```
{
"description": "Error details.",
"message": "Unable to update collection. Please check the collection\ndata"
}
```
text/html Copy Error
```
\r\n400 Bad Request\r\n\r\n400
Bad Request
\r\n\r\n\r\n
```
application/json Copy 403 invalid error
```
{
"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 Resource not found
```
{
"message": "Unable to update collection. Please check the given ids"
}
```
text/html Copy Resource not found
```
\r\n400 Bad Request\r\n\r\n400
Bad Request
\r\n\r\n\r\n
```
application/json Copy Internal server error
```
{
"message": "The product has encountered an internal server error. If you\nhave used a transaction_id to call our services, please submit it to\nStaircase support"
}
```
##### Parameters
3
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `x-api-key` required | `string` header | — | Environment API Key. |
| `transaction_id` required | `string (ulid)` path | `01F0KHK7DN3H5JZ4QJKMYAM6GB` | Staircase Transaction Identifier |
| `collection_id` required | `string (ulid)` path | `01F0KHKADN0HRFXMCQQXPA6AFZ` | Staircase collection_id |
##### Request body`application/json`
1 fields
| Field | Type | Description |
| --- | --- | --- |
| `data` | `object` | The data that is needed for invocation. It should follow the request schema |
| `addresses`required | `object[]` | — |
| `@id`required | `string` | — |
| `@type`required | `string` | — |
| `has_state_code`required | `object` | — |
| `has_value`required | `string` | — |
| `has_city_name`required | `object` | — |
| `has_value`required | `string` | — |
| `has_postal_code`required | `object` | — |
| `has_value`required | `string` | — |
| `has_address_line_1_text`required | `object` | — |
| `has_value`required | `string` | — |
| `has_county_name` | `object` | — |
| `has_value`required | `string` | — |
| `documents`required | `object[]` | — |
| `@id`required | `string` | — |
| `@type`required | `string` | — |
| `has_staircase_blob_identifier`required | `object` | — |
| `has_value`required | `string` | — |
| `loans`required | `object[]` | — |
| `@id`required | `string` | — |
| `@type`required | `string` | — |
| `with_government_loan` | `string[]` | — |
| `has_loan_identifier_value`required | `object` | — |
| `has_value`required | `string` | — |
| `government_loans` | `object[]` | — |
| `@id`required | `string` | — |
| `@type`required | `string` | — |
| `has_fha_case_number`required | `object` | — |
| `has_value`required | `string` | — |
| `loan_terms`required | `object[]` | — |
| `@id`required | `string` | — |
| `@type`required | `string` | — |
| `has_loan_purpose_type`required | `object` | — |
| `has_value`required | `string` | — |
| `organizations`required | `object[]` | — |
| `@id`required | `string` | — |
| `@type`required | `string` | — |
| `has_organization_name`required | `object` | — |
| `has_value`required | `string` | — |
| `with_address`required | `string[]` | — |
| `people`required | `object[]` | — |
| `@id`required | `string` | — |
| `@type`required | `string` | — |
| `has_appraisal_sub_committee_appraiser_identifier` | `object` | — |
| `has_value`required | `string` | — |
| `has_full_name`required | `object` | — |
| `has_value`required | `string` | — |
| `lives_at` | `string[]` | — |
| `properties`required | `object[]` | — |
| `@id`required | `string` | — |
| `@type`required | `string` | — |
| `with_address`required | `string[]` | — |
| `with_sales_contract`required | `string[]` | — |
| `property_valuations`required | `object[]` | — |
| `@id`required | `string` | — |
| `@type`required | `string` | — |
| `has_property_inspection_type_other_description`required | `object` | — |
| `has_value`required | `string` | — |
| `residences`required | `object[]` | — |
| `@id`required | `string` | — |
| `@type`required | `string` | — |
| `with_address`required | `string[]` | — |
| `roles`required | `object[]` | — |
| `@id`required | `string` | — |
| `@type`required | `string` | — |
| `with_appraiser`required | `string[]` | — |
| `sales_contracts`required | `object[]` | — |
| `@id`required | `string` | — |
| `@type`required | `string` | — |
| `has_sales_contract_amount`required | `object` | — |
| `has_value`required | `integer` | — |
##### Response `200``application/json`
4 fields
Collection updated successfully
| Field | Type | Description |
| --- | --- | --- |
| `transaction_id` | `string (ulid)` | Transaction ID.Example `01EZQ32PJQGKRA6HR8D72Q9FFF` |
| `collection_id` | `string (ulid)` | Collection ID.Example `01EZQ32PJQGKRA6HR8D72Q9FFF` |
| `data` | `object` | Data in Staircase language schema. |
| `metadata` | `object` | Metadata about collection, f.e version of used Staircase schema. |
##### Response `400``application/json`
1 fields
Error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Either message object with more properties. |
##### 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 |
##### Response `500``application/json`
1 fields
Internal server error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message. |
##### Other responses
`405`
### Operations
`POST` `/appraisal`
#### Create Appraisal
`post-appraisal`
##### 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 Appraisal 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
Appraisal request created successfully.
| Field | Type | Description |
| --- | --- | --- |
| `collection_id` | `string` | Collection ID |
| `message` | `string` | Message |
`GET` `/appraisal/elements`
#### Retrieve Elements
`get-appraisal-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` `/appraisal/elements/complete`
#### Validate Collection
`post-appraisal-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` `/appraisal/status/{transaction_id}/{collection_id}`
#### Retrieve Status
`get-appraisal-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` `/appraisal/transactions`
#### Create Transaction
`post-appraisal-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` `/appraisal/transactions/{transaction_id}/collections`
#### Create Collection
`post-appraisal-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` `/appraisal/transactions/{transaction_id}/collections/{collection_id}`
#### Update Collection
`put-appraisal-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 |
## Errors
`400``403``404``405``500`
## More in Assessment
- Next product: Listing