Skip to content
Staircase

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
application/json 
{
  "vendor_name": "homevision",
  "transaction_id": "01F6NAMXWN2XVBD1YJ92A6S6R4",
  "request_collection_id": "01F6QF1QJF20DMSXH4SYXKB1SN"
}
Response
application/json

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"
}
Parameters
1
ParameterTypeDescription
x-api-key required string header Environment API Key.
Response 201application/json
7 fields

Successfully started flow invocation.

FieldTypeDescription
invocation_idstringInvocation ID.
invocation_statusstringThe status of the invocation.STARTED
transaction_idstringTransaction ID.
product_flow_namestringProduct flow name.collateral-underwriting
metadataobjectThe metadata of the invoked product flow.
callback_urlstringCallback URL.
request_dataobjectThe data for the request collection.
Response 400application/json
1 fields

Request data failed validation

FieldTypeDescription
messagestringMessage
Response 403application/json
2 fields

403 invalid error

FieldTypeDescription
messagestringError message.
urlstringError additional URL.
Response 404application/json
1 fields

Resource not found

FieldTypeDescription
messagestringMessage
Response 500application/json
1 fields

Internal server error

FieldTypeDescription
messagestringError 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
application/json

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"
          }
        }
      ]
    }
  }
}
Parameters
2
ParameterTypeExampleDescription
x-api-key required string header — Environment API Key.
invocation_id required string (ulid) path 01F0KHKADN0HRFXMCQQXPA6AFZ Product flow invocation identifier
Response 200application/json
9 fields

Successfully returned status of the Product flow Invocation.

FieldTypeDescription
invocation_statusrequiredstringInvocation Status.ACTION_REQUIREDCOMPLETEDFAILEDRUNNINGSTARTED
transaction_idrequiredstringTransaction ID used for invocation.
request_collection_idstringRequest Collection ID.
request_collectionobjectCollection.
transaction_idstring (ulid)Transaction ID.Example 01EZQ32PJQGKRA6HR8D72Q9FFF
collection_idstring (ulid)Collection ID.Example 01EZQ32PJQGKRA6HR8D72Q9FFF
dataobjectData in Staircase language schema.
metadataobjectMetadata about collection, f.e version of used Staircase schema.
response_collection_idstringResponse Collection ID.
response_collectionobjectCollection.
transaction_idstring (ulid)Transaction ID.Example 01EZQ32PJQGKRA6HR8D72Q9FFF
collection_idstring (ulid)Collection ID.Example 01EZQ32PJQGKRA6HR8D72Q9FFF
dataobject—
servicesrequiredobject[]—
@idrequiredstring—
@typerequiredstring—
has_service_namerequiredobject—
has_service_vendor_namerequiredobject—
with_foreign_objectrequiredstring[]—
foreign_objectsrequiredobject[]—
@idrequiredstring—
@typerequiredstring—
has_object_namerequiredobject—
has_object_url_valueobject—
metadataobjectMetadata about collection, f.e version of used Staircase schema.
callback_urlstringURL that was specified in flow invocation and will be used to send the callback when flow invocation will be finished.
widget_urlstring (uri)URL of the widget.
metadataobjectResponse Collection ID.
Response 400application/json
1 fields

Request data failed validation

FieldTypeDescription
messagestringMessage
Response 403application/json
2 fields

403 invalid error

FieldTypeDescription
messagestringError message.
urlstringError additional URL.
Response 404application/json
1 fields

Resource not found

FieldTypeDescription
messagestringMessage
Response 500application/json
1 fields

Internal server error

FieldTypeDescription
messagestringError 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
application/json

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"
  }
}
Parameters
2
ParameterTypeDescription
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 200application/json
2 fields

Request schema (possibly with examples) is successfully returned.

FieldTypeDescription
schemarequiredobjectSchema for the Request Collection
examplesobjectEach item in the dictionary corresponds to the name of the example and dictionary content is the sample response.
Response 400application/json
1 fields

Error

FieldTypeDescription
messagestringMessage
Response 403application/json
2 fields

403 invalid error

FieldTypeDescription
messagestringError message.
urlstringError additional URL.
Response 404application/json
1 fields

Resource not found

FieldTypeDescription
messagestringError Message.
Response 500application/json
1 fields

Internal server error

FieldTypeDescription
messagestringError 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
application/json

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"
                }
              }
            }
          }
        }
      }
    }
  }
}
Parameters
2
ParameterTypeDescription
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 200application/json
2 fields

Response schema (possibly with examples) is successfully returned.

FieldTypeDescription
schemarequiredobjectJSON-Schema as a single object
examplesobjectA 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 400application/json
1 fields

Error

FieldTypeDescription
messagestringMessage
Response 403application/json
2 fields

403 invalid error

FieldTypeDescription
messagestringError message.
urlstringError additional URL.
Response 404application/json
1 fields

Resource not found

FieldTypeDescription
messagestringError Message.
Response 500application/json
1 fields

Internal server error

FieldTypeDescription
messagestringError 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
application/json

Transaction created successfully

{
  "transaction_id": "01F0KHK7DN3H5JZ4QJKMYAM6GB",
  "created_at": "03/04/2021, 1:04:05 PM EST"
}
Parameters
1
ParameterTypeDescription
x-api-key required string header Environment API Key.
Response 201application/json
2 fields

Transaction created successfully

FieldTypeDescription
transaction_idstring (ulid)Staircase Transaction IdentifierExample 01F0KHK7DN3H5JZ4QJKMYAM6GB
created_atstringStaircase time string.Example 03/03/2021, 8:24:04 AM EST
Response 403application/json
2 fields

403 invalid error

FieldTypeDescription
messagestringError message.
urlstringError additional URL.
Response 500application/json
1 fields

Internal server error

FieldTypeDescription
messagestringError 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
application/json 
{
  "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
application/json

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
        }
      }
    ]
  }
}
Parameters
2
ParameterTypeExampleDescription
x-api-key required string header — Environment API Key.
transaction_id required string (ulid) path 01F0KHK7DN3H5JZ4QJKMYAM6GB Staircase Transaction Identifier
Request bodyapplication/json
1 fields
FieldTypeDescription
dataobjectThe data that is needed for invocation. It should follow the request schema
addressesrequiredobject[]—
@idrequiredstring—
@typerequiredstring—
has_state_coderequiredobject—
has_valuerequiredstring—
has_city_namerequiredobject—
has_valuerequiredstring—
has_postal_coderequiredobject—
has_valuerequiredstring—
has_address_line_1_textrequiredobject—
has_valuerequiredstring—
has_county_nameobject—
has_valuerequiredstring—
documentsrequiredobject[]—
@idrequiredstring—
@typerequiredstring—
has_staircase_blob_identifierrequiredobject—
has_valuerequiredstring—
loansrequiredobject[]—
@idrequiredstring—
@typerequiredstring—
with_government_loanstring[]—
has_loan_identifier_valuerequiredobject—
has_valuerequiredstring—
government_loansobject[]—
@idrequiredstring—
@typerequiredstring—
has_fha_case_numberrequiredobject—
has_valuerequiredstring—
loan_termsrequiredobject[]—
@idrequiredstring—
@typerequiredstring—
has_loan_purpose_typerequiredobject—
has_valuerequiredstring—
organizationsrequiredobject[]—
@idrequiredstring—
@typerequiredstring—
has_organization_namerequiredobject—
has_valuerequiredstring—
with_addressrequiredstring[]—
peoplerequiredobject[]—
@idrequiredstring—
@typerequiredstring—
has_appraisal_sub_committee_appraiser_identifierobject—
has_valuerequiredstring—
has_full_namerequiredobject—
has_valuerequiredstring—
lives_atstring[]—
propertiesrequiredobject[]—
@idrequiredstring—
@typerequiredstring—
with_addressrequiredstring[]—
with_sales_contractrequiredstring[]—
property_valuationsrequiredobject[]—
@idrequiredstring—
@typerequiredstring—
has_property_inspection_type_other_descriptionrequiredobject—
has_valuerequiredstring—
residencesrequiredobject[]—
@idrequiredstring—
@typerequiredstring—
with_addressrequiredstring[]—
rolesrequiredobject[]—
@idrequiredstring—
@typerequiredstring—
with_appraiserrequiredstring[]—
sales_contractsrequiredobject[]—
@idrequiredstring—
@typerequiredstring—
has_sales_contract_amountrequiredobject—
has_valuerequiredinteger—
Response 201application/json
4 fields

Collection created successfully

FieldTypeDescription
transaction_idstring (ulid)Transaction ID.Example 01EZQ32PJQGKRA6HR8D72Q9FFF
collection_idstring (ulid)Collection ID.Example 01EZQ32PJQGKRA6HR8D72Q9FFF
dataobjectData in Staircase language schema.
metadataobjectMetadata about collection, f.e version of used Staircase schema.
Response 400application/json
1 fields

Error

FieldTypeDescription
messageone ofEither message object with more properties.
Response 403application/json
2 fields

403 invalid error

FieldTypeDescription
messagestringError message.
urlstringError additional URL.
Response 404application/json
1 fields

Resource not found

FieldTypeDescription
messagestringMessage
Response 500application/json
1 fields

Internal server error

FieldTypeDescription
messagestringError 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
application/json

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"
}
Parameters
3
ParameterTypeExampleDescription
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 200application/json
4 fields

Successfully Retrieved Collection

FieldTypeDescription
transaction_idrequiredstring—
collection_idrequiredstring—
metadatarequiredobject—
created_atrequiredstring—
validationrequiredboolean—
datarequiredobject—
Response 403application/json
2 fields

403 invalid error

FieldTypeDescription
messagestringError message.
urlstringError additional URL.
Response 404application/json
1 fields

Resource not found

FieldTypeDescription
messagestringMessage
Response 500application/json
1 fields

Internal server error

FieldTypeDescription
messagestringError 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
application/json

Transaction collection retrieved successfully

{
  "metadata": {
    "created_at": "2021-09-14T03:08:00.284090-04:00",
    "validation": false
  },
  "transaction_id": "01FFHJ2ZVS4P7N4AV5W0993QMD",
  "collection_id": "01FFHJ4JCWGHV38SC1NJ8TVNFY",
  "data": {}
}
Parameters
2
ParameterTypeExampleDescription
x-api-key required string header — Environment API Key.
transaction_id required string (ulid) path 01F0KHK7DN3H5JZ4QJKMYAM6GB Staircase Transaction Identifier
Response 200application/json
4 fields

Transaction collection retrieved successfully

FieldTypeDescription
transaction_idstring (ulid)Transaction ID.Example 01EZQ32PJQGKRA6HR8D72Q9FFF
collection_idstring (ulid)Collection ID.Example 01EZQ32PJQGKRA6HR8D72Q9FFF
dataobjectData in Staircase language schema.
metadataobjectMetadata about collection, f.e version of used Staircase schema.
Response 400application/json
1 fields

Error

FieldTypeDescription
messageone ofEither message object with more properties.
Response 403application/json
2 fields

403 invalid error

FieldTypeDescription
messagestringError message.
urlstringError additional URL.
Response 404application/json
1 fields

Resource not found

FieldTypeDescription
messagestringMessage
Response 500application/json
1 fields

Internal server error

FieldTypeDescription
messagestringError 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
application/json 
{
  "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
application/json

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
        }
      }
    ]
  }
}
Parameters
3
ParameterTypeExampleDescription
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 bodyapplication/json
1 fields
FieldTypeDescription
dataobjectThe data that is needed for invocation. It should follow the request schema
addressesrequiredobject[]—
@idrequiredstring—
@typerequiredstring—
has_state_coderequiredobject—
has_valuerequiredstring—
has_city_namerequiredobject—
has_valuerequiredstring—
has_postal_coderequiredobject—
has_valuerequiredstring—
has_address_line_1_textrequiredobject—
has_valuerequiredstring—
has_county_nameobject—
has_valuerequiredstring—
documentsrequiredobject[]—
@idrequiredstring—
@typerequiredstring—
has_staircase_blob_identifierrequiredobject—
has_valuerequiredstring—
loansrequiredobject[]—
@idrequiredstring—
@typerequiredstring—
with_government_loanstring[]—
has_loan_identifier_valuerequiredobject—
has_valuerequiredstring—
government_loansobject[]—
@idrequiredstring—
@typerequiredstring—
has_fha_case_numberrequiredobject—
has_valuerequiredstring—
loan_termsrequiredobject[]—
@idrequiredstring—
@typerequiredstring—
has_loan_purpose_typerequiredobject—
has_valuerequiredstring—
organizationsrequiredobject[]—
@idrequiredstring—
@typerequiredstring—
has_organization_namerequiredobject—
has_valuerequiredstring—
with_addressrequiredstring[]—
peoplerequiredobject[]—
@idrequiredstring—
@typerequiredstring—
has_appraisal_sub_committee_appraiser_identifierobject—
has_valuerequiredstring—
has_full_namerequiredobject—
has_valuerequiredstring—
lives_atstring[]—
propertiesrequiredobject[]—
@idrequiredstring—
@typerequiredstring—
with_addressrequiredstring[]—
with_sales_contractrequiredstring[]—
property_valuationsrequiredobject[]—
@idrequiredstring—
@typerequiredstring—
has_property_inspection_type_other_descriptionrequiredobject—
has_valuerequiredstring—
residencesrequiredobject[]—
@idrequiredstring—
@typerequiredstring—
with_addressrequiredstring[]—
rolesrequiredobject[]—
@idrequiredstring—
@typerequiredstring—
with_appraiserrequiredstring[]—
sales_contractsrequiredobject[]—
@idrequiredstring—
@typerequiredstring—
has_sales_contract_amountrequiredobject—
has_valuerequiredinteger—
Response 200application/json
4 fields

Collection updated successfully

FieldTypeDescription
transaction_idstring (ulid)Transaction ID.Example 01EZQ32PJQGKRA6HR8D72Q9FFF
collection_idstring (ulid)Collection ID.Example 01EZQ32PJQGKRA6HR8D72Q9FFF
dataobjectData in Staircase language schema.
metadataobjectMetadata about collection, f.e version of used Staircase schema.
Response 400application/json
1 fields

Error

FieldTypeDescription
messageone ofEither message object with more properties.
Response 403application/json
2 fields

403 invalid error

FieldTypeDescription
messagestringError message.
urlstringError additional URL.
Response 404application/json
1 fields

Resource not found

FieldTypeDescription
messagestringMessage
Response 500application/json
1 fields

Internal server error

FieldTypeDescription
messagestringError message.
Other responses

405

Operations

POST /appraisal

Create Appraisal

post-appraisal

Request
application/json 
{
  "transaction_id": "uhz6t54e-9d74-g17e-99ca-a36b30vdfd35",
  "collection_id": "hg62e49f-9d74-g17e-99ca-a36b30vdfd35",
  "partner_name": "PartnerName"
}
Response
application/json

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
ParameterTypeExampleDescription
x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Authorization key
Request bodyapplication/json
3 fields
FieldTypeDescription
transaction_idrequiredstringTransaction ID
collection_idrequiredstringCollection ID
partner_namerequiredstring—
Response 200application/json
2 fields

Appraisal request created successfully.

FieldTypeDescription
collection_idstringCollection ID
messagestringMessage
GET /appraisal/elements

Retrieve Elements

get-appraisal-elements

Retrieve Elements provides a list of the elements needed to invoke a partner product.

Parameters
1
ParameterTypeExampleDescription
x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Authorization key
Response 200application/json
1 fields

Elements needed for request.

FieldTypeDescription
elementsobjectList 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
ParameterTypeExampleDescription
x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Authorization key
Request bodyapplication/json
1 fields
FieldTypeDescription
collectionrequiredobject—
Response 400application/json
2 fields

Collection is invalid.

FieldTypeDescription
messagestringError message
errorsobjectList 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
application/json

Statuses include: * REQUEST_MADE<p> * REQUEST_ACCEPTED<p> * WAITING_FOR_RESPONSE<p> * COMPLETED

{
  "status": "COMPLETED"
}
Parameters
3
ParameterTypeExampleDescription
transaction_id required string path 9u8z7t65-cb71-4f20-8e40-7a829b52e91e Transaction ID
collection_id required string path e4502ed2-8df8-4b8f-84bd-a1097e999a77 Collection ID
x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Authorization key
Response 200application/json
1 fields

Statuses include: * REQUEST_MADE<p> * REQUEST_ACCEPTED<p> * WAITING_FOR_RESPONSE<p> * COMPLETED

FieldTypeDescription
statusobjectCurrent execution status
Response 400application/json
1 fields

Status is unavailable

FieldTypeDescription
errorstringError 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

Transaction successfully created.

{
  "transaction_id": "a34c40a6-3c02-44f9-a696-cd7388f506d3"
}
Parameters
1
ParameterTypeExampleDescription
x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Authorization key
Response 200application/json
1 fields

Transaction successfully created.

FieldTypeDescription
transaction_idstringTransaction 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 
{
  "sets": {
    "set": [
      {
        "elements": {
          "element": [
            {
              "property_entry": {
                "property_entries": {
                  "datetime": "2020-08-25",
                  "description": "Description of property",
                  "event_type": "TestType"
                }
              },
              "property_class": {
                "property_clases": {
                  "type": "STATEMENT"
                },
                "name": "Test",
                "period_start_date": "2020-07-01",
                "period_end_date": "2020-07-31"
              },
              "content": {
                "foreign_object": "7e62ce76-d93d-4f31-92d3-45c2cb8255ea"
              }
            }
          ]
        }
      }
    ]
  }
}
Response
application/json

Collection successfully created.

{
  "collection_id": "hg62e49f-9d74-g17e-99ca-a36b30vdfd35",
  "data": {
    "sets": {
      "set": [
        {
          "elements": {
            "element": [
              {
                "property_entry": {
                  "property_entries": {
                    "datetime": "2020-08-25",
                    "description": "Description of property",
                    "event_type": "TestType"
                  }
                },
                "property_class": {
                  "property_clases": {
                    "type": "STATEMENT"
                  },
                  "name": "Test",
                  "period_start_date": "2020-07-01",
                  "period_end_date": "2020-07-31"
                },
                "content": {
                  "foreign_object": "7e62ce76-d93d-4f31-92d3-45c2cb8255ea"
                }
              }
            ]
          }
        }
      ]
    }
  },
  "metadata": {},
  "transaction_id": "6t5r4wq1-9d74-g17e-99ca-a36b30vdfd35"
}
Parameters
2
ParameterTypeExampleDescription
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 bodyapplication/json
2 fields
FieldTypeDescription
datarequiredobject—
metadataobject—
Response 200application/json
4 fields

Collection successfully created.

FieldTypeDescription
transaction_idobjectTransaction ID
collection_idobjectCollection ID
dataobjectData object
metadataobjectMetadata 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 
{
  "sets": {
    "set": [
      {
        "properties": {
          "property": [
            {
              "propety_entry": {
                "propety_entries": {
                  "datetime": "2020-05-05",
                  "description": "Test Description",
                  "event_type": "TestType"
                }
              },
              "propety_class": {
                "propety_classes": {
                  "type": "TestType"
                },
                "name": "TestName",
                "period_start_date": "2019-01-01",
                "period_end_date": "2019-12-31"
              },
              "content": {
                "foreign_object": "7z6t5r4e-d93d-4f31-92d3-45c2cb8255ea"
              }
            }
          ]
        }
      }
    ]
  }
}
Response
application/json

Collection successfully updated

{
  "collection_id": "hg62e49f-9d74-g17e-99ca-a36b30vdfd35",
  "data": {
    "sets": {
      "set": [
        {
          "properties": {
            "property": [
              {
                "property_data": {
                  "property_class": {
                    "datetime": "2020-05-05",
                    "description": "Info",
                    "event_type": "TestEvent"
                  }
                },
                "document_classification": {
                  "document_classes": {
                    "type": "TestType"
                  },
                  "name": "TestName",
                  "period_start_date": "2019-01-01",
                  "period_end_date": "2019-12-31"
                },
                "content": {
                  "foreign_object": "7z6t5r4e-d93d-4f31-92d3-45c2cb8255ea"
                }
              }
            ]
          }
        }
      ]
    }
  },
  "metadata": {},
  "transaction_id": "6t5r4wq1-9d74-g17e-99ca-a36b30vdfd35"
}
Parameters
3
ParameterTypeExampleDescription
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 bodyapplication/json
2 fields
FieldTypeDescription
datarequiredobject—
metadataobject—
Response 200application/json
4 fields

Collection successfully updated

FieldTypeDescription
transaction_idobjectTransaction ID
collection_idobjectCollection ID
dataobjectData object
metadataobjectMetadata object

Errors

400403404405500

Type to search.