Skip to content
Staircase

Valuation

A blended value opinion combining automated valuation, appraisal and listing signal into one number surfaced to pricing.

Three signals with different failure modes. An automated model is fast and uniform but blind to condition; an appraisal is condition-aware and slow; a listing shows what the market was asked to pay rather than what it paid. The product returns a blended opinion together with the components behind it.

The components are returned, not just the blend. A caller weighing collateral risk needs to know whether the number rests on a recent appraisal or on a model extrapolating from comparables.

Operations

Platform

GET /partners

Retrieve Partners

retrievePartners

Retrieve Partners retrieves an object containing all Partners active for the product and information about them. You can use the invoke_name variable to invoke the partner directly in the product invocation.

Response
application/json

Successfully returned the partner list

[
  {
    "company_name": "Partner 1",
    "invoke_name": "partner_1",
    "status": "active",
    "description": "Partner 1 does ...."
  },
  {
    "company_name": "Partner 2",
    "invoke_name": "partner_2",
    "status": "upcoming",
    "description": "Use Partner 2 if ...."
  }
]
Response 200application/json
4 fields

Successfully returned the partner list

FieldTypeDescription
company_namestringName of the partner
invoke_namestringThis string type object can be passed directly into the product invocation
statusstringDescribes whether the partner is available to useactivedeprecatedupcoming
descriptionstringFurther information on the partner
Response 403application/json
2 fields

Invalid key for service

FieldTypeDescription
messagestring
urlstring
GET /response-elements

Retrieve Response Elements

responseElements

Retrieve Response Elements provides a list of elements that will be returned by a partner providing an automated valuation model.

Response
application/json

Example for the Valuation Elements object

{
  "$.deal_sets.deal_set[0].deals.deal[0].collaterals.collateral[0].subject_property.property_valuations.property_valuation[0].avms.avm[0].date": "null,",
  "$.deal_sets.deal_set[0].deals.deal[0].collaterals.collateral[0].subject_property.property_valuations.property_valuation[0].avms.avm[0].high_value_range": "null,",
  "$.deal_sets.deal_set[0].deals.deal[0].collaterals.collateral[0].subject_property.property_valuations.property_valuation[0].avms.avm[0].low_value_range": "null,",
  "$.deal_sets.deal_set[0].deals.deal[0].collaterals.collateral[0].subject_property.property_valuations.property_valuation[0].avms.avm[0].value": null
}
Response 200application/json
2 fields

Elements retrieved successfully

FieldTypeDescription
pathstringContains the path in Staircase language
valuestringEnter your own values here
Response 403application/json
2 fields

Invalid key for service

FieldTypeDescription
messagestring
urlstring
Other responses

400404500

GET /schema/{data_object}

Retrieve Schema

retrieveSchema

Retrieve Schema retrieves a JSON schema for the request and the response returned by the product.

Response
application/json

Successfully returned the list of elements needed for AUS.

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "deal_sets": {
      "type": "object",
      "properties": {
        "deal_set": {
          "type": "array",
          "items": [
            {
              "type": "object",
              "properties": {
                "deals": {
                  "type": "object",
                  "properties": {
                    "deal": {
                      "type": "array",
                      "items": [
                        {
                          "type": "object",
                          "properties": {
                            "collaterals": {
                              "type": "object",
                              "properties": {
                                "collateral": {
                                  "type": "array",
                                  "items": [
                                    {
                                      "type": "object",
                                      "properties": {
                                        "subject_property": {
                                          "type": "object",
                                          "properties": {
                                            "address": {
                                              "type": "object",
                                              "properties": {
                                                "line_text": {
                                                  "type": "string"
                                                },
                                                "city": {
                                                  "type": "string"
                                                },
                                                "state_code": {
                                                  "type": "string"
                                                },
                                                "postal_code": {
                                                  "type": "string"
                                                }
                                              },
                                              "required": [
                                                "line_text",
                                                "postal_code"
                                              ]
                                            }
                                          },
                                          "required": [
                                            "address"
                                          ]
                                        }
                                      },
                                      "required": [
                                        "subject_property"
                                      ]
                                    }
                                  ]
                                }
                              },
                              "required": [
                                "collateral"
                              ]
                            }
                          },
                          "required": [
                            "collaterals"
                          ]
                        }
                      ]
                    }
                  },
                  "required": [
                    "deal"
                  ]
                }
              },
              "required": [
                "deals"
              ]
            }
          ]
        }
      },
      "required": [
        "deal_set"
      ]
    }
  },
  "required": [
    "deal_sets"
  ]
}
Parameters
3
ParameterTypeDescription
data_object required string path Describes the particular data object you are getting a schema for.
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`
version required string query Defines the version of the Staircase language you want the JSON to return in.
Response 200application/json
1 fields

Successfully returned the list of elements needed for AUS.

FieldTypeDescription
schemaobject
Response 400application/json
1 fields

Error

FieldTypeDescription
messagestringMessage
Response 403application/json
2 fields

Invalid key for service

FieldTypeDescription
messagestring
urlstring
GET /transactions/{transaction_id}/collections

Retrieve Transaction Collections

retrieveCollections

Retrieve Transaction Collections returns all collections that associated with a transaction_id.

Response
application/json

Successfully Retrieved Collection

[
  {
    "metadata": {
      "created_at": "03/02/2021, 3:19:37 AM EST",
      "last_updated_at": "03/02/2021, 6:06:56 AM EST",
      "validation": false
    },
    "collection_id": "01EZZEJ3W6MHW9W75CYHEC9PAZ",
    "transaction_id": "01EZZEHJY0J6Y2C6R2C26C1V2F",
    "data": {
      "deal_sets": {
        "deal_set": [
          {
            "deals": {
              "deal": [
                {
                  "collaterals": {
                    "collateral": [
                      {
                        "subject_property": {
                          "address": {
                            "city": "Lafayette",
                            "line_text": 1,
                            "postal_code": "705061",
                            "state_code": "LA"
                          }
                        }
                      }
                    ]
                  }
                }
              ]
            }
          }
        ]
      }
    }
  },
  {
    "metadata": {
      "created_at": "03/02/2021, 5:19:37 AM EST",
      "last_updated_at": "03/02/2021, 7:06:56 AM EST",
      "validation": false
    },
    "collection_id": "01EZZEJ3W6MHW9W75CYHEC9PAZ",
    "transaction_id": "01EZZEHJY0J6Y2C6R2C26C1V2F",
    "data": {
      "deal_sets": {
        "deal_set": [
          {
            "deals": {
              "deal": [
                {
                  "collaterals": {
                    "collateral": [
                      {
                        "subject_property": {
                          "address": {
                            "city": "Lafayette",
                            "line_text": 1,
                            "postal_code": "70506",
                            "state_code": "LA"
                          }
                        }
                      }
                    ]
                  }
                }
              ]
            }
          }
        ]
      }
    }
  }
]
Parameters
1
ParameterTypeExampleDescription
transaction_id required string (ulid) path 01EZZEHJY0J6Y2C6R2C26C1V2F Staircase Transaction Identifier
Response 200application/json
4 fields

Successfully Retrieved Collection

FieldTypeDescription
dataobjectCustomer Input Data
metadataobjectStaircase metadata
transaction_idstring (ulid)Staircase Transaction IdentifierExample 01EZZEHJY0J6Y2C6R2C26C1V2F
collection_idstring (ulid)Staircase Collection IdentifierExample 01EZZEJ3W6MHW9W75CYHEC9PAZ
Response 403application/json
2 fields

Invalid key for service

FieldTypeDescription
messagestring
urlstring
Response 404application/json
1 fields

Resource not found

FieldTypeDescription
messagestringMessage
Other responses

400

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.

Response
application/json

Error

{
  "message": "Unable to update collection. Please check the collection data"
}
Parameters
2
ParameterTypeExampleDescription
transaction_id required string (ulid) path 01EZZEHJY0J6Y2C6R2C26C1V2F Staircase Transaction Identifier
collection_id required string (ulid) path 01EZZEJ3W6MHW9W75CYHEC9PAZ Staircase collection_id
Response 400application/json
1 fields

Error

FieldTypeDescription
messageone of
Response 403application/json
2 fields

Invalid key for service

FieldTypeDescription
messagestring
urlstring
Response 404application/json
1 fields

Resource not found

FieldTypeDescription
messagestringMessage
Other responses

200

POST /request-elements/complete

Validate Collection

validateCollection

Validate Collection allows you to validate an input collection prior to submitting to our partners. This service will return messages with all the corrections you need to make to your collection in order for it to be accepted by our partner call.

Request
application/json
{
  "data": {
    "deal_sets": {
      "deal_set": [
        {
          "deals": {
            "deal": [
              {
                "collaterals": {
                  "collateral": [
                    {
                      "subject_property": {
                        "address": {
                          "line_text": "110 Ocean Park Blvd Unit 205",
                          "city": "Santa Monica",
                          "postal_code": "90405",
                          "state_code": "CA"
                        }
                      }
                    }
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  },
  "metadata": {}
}
Response
application/json

Collection is valid

{
  "message": "Collection is valid."
}
Request bodyapplication/json
4 fields
FieldTypeDescription
dataobjectCustomer Input Data
metadataobjectStaircase metadata
transaction_idstring (ulid)Staircase Transaction IdentifierExample 01EZZEHJY0J6Y2C6R2C26C1V2F
collection_idstring (ulid)Staircase Collection IdentifierExample 01EZZEJ3W6MHW9W75CYHEC9PAZ
Response 200application/json
1 fields

Collection is valid

FieldTypeDescription
messagestringMessage
Response 400application/json
1 fields

Validation Error

FieldTypeDescription
messagestringMessage
Response 403application/json
2 fields

Invalid key for service

FieldTypeDescription
messagestring
urlstring
Other responses

500

Workflow

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.

Response
application/json

Transaction created successfully

{
  "transaction_id": {
    "$ref": "#/components/schemas/TransactionId/example"
  }
}
Response 201application/json
1 fields

Transaction created successfully

FieldTypeDescription
transaction_idstring (ulid)Staircase Transaction IdentifierExample 01EZZEHJY0J6Y2C6R2C26C1V2F
Response 400application/json
2 fields

Transaction creation unsuccessfully

FieldTypeDescription
errorstring
error_codeinteger
Response 403application/json
2 fields

Invalid key for service

FieldTypeDescription
messagestring
urlstring
GET /request-elements

Retrieve Request Elements

requestElements

Retrieve Request Elements retrieves a list of elements needed to invoke a partner for valuation.

Response
application/json

Example for the Valuation Request Elements object

{
  "$.deal_sets.deal_set[0].deals.deal[0].collaterals.collateral[0].subject_property.address.line_text": null,
  "$.deal_sets.deal_set[0].deals.deal[0].collaterals.collateral[0].subject_property.address.city": null,
  "$.deal_sets.deal_set[0].deals.deal[0].collaterals.collateral[0].subject_property.address.postal_code": null,
  "$.deal_sets.deal_set[0].deals.deal[0].collaterals.collateral[0].subject_property.address.state_code": null
}
Response 200application/json
2 fields

Elements retrieved successfully

FieldTypeDescription
pathstringContains the path in Staircase language
valuestringEnter your own values here
Response 403application/json
2 fields

Invalid key for service

FieldTypeDescription
messagestring
urlstring
Other responses

400500

POST /build-payload

Build JSON Payload

retrieveExampleJSON

Build JSON Payload helps you build a JSON payload using the JSON paths from Retrieve Request Elements/requestElements) or Retrieve Response Elements/responseElements). You can use this payload to either:

  • submit a request to valuate collateral.
  • simulate a response containing collateral valuation details. Simply add key/value pairs of path/desired output and POST to /build-payload. It will then build a nested JSON. You can find examples below.
Request
application/json
{
  "$.deal_sets.deal_set[0].deals.deal[0].collaterals.collateral[0].subject_property.address.line_text": "112 Southfield Pkwy",
  "$.deal_sets.deal_set[0].deals.deal[0].collaterals.collateral[0].subject_property.address.city": "Lafayette",
  "$.deal_sets.deal_set[0].deals.deal[0].collaterals.collateral[0].subject_property.address.postal_code": "LA",
  "$.deal_sets.deal_set[0].deals.deal[0].collaterals.collateral[0].subject_property.address.state_code": "70506"
}
Response
application/json

Valuation Payload.

{
  "deal_sets": {
    "deal_set": [
      {
        "deals": {
          "deal": [
            {
              "collaterals": {
                "collateral": [
                  {
                    "subject_property": {
                      "address": {
                        "line_text": "110 Ocean Park Blvd Unit 205",
                        "city": "Santa Monica",
                        "postal_code": "90405",
                        "state_code": "CA"
                      }
                    }
                  }
                ]
              }
            }
          ]
        }
      }
    ]
  }
}
Request bodyapplication/json
2 fields
FieldTypeDescription
pathstringContains the path in Staircase language
valuestringEnter your own values here
Response 200application/json
1 fields

Valuation Payload.

FieldTypeDescription
deal_setsobject
deal_setobject[]
dealsobject
dealobject[]
Response 403application/json
2 fields

Invalid key for service

FieldTypeDescription
messagestring
urlstring
Other responses

400404500

POST /transactions/{transaction_id}/collections

Create Collection

createCollection

Create Collection creates a collection of elements required for valuation. A collection contains a digital representation of the borrower and is identified by collection_id. A collection_id is passed to the partner when requesting valuation.

Request
application/json
{
  "data": {
    "deal_sets": {
      "deal_set": [
        {
          "deals": {
            "deal": [
              {
                "collaterals": {
                  "collateral": [
                    {
                      "subject_property": {
                        "address": {
                          "line_text": "110 Ocean Park Blvd Unit 205",
                          "city": "Santa Monica",
                          "postal_code": "90405",
                          "state_code": "CA"
                        }
                      }
                    }
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  },
  "metadata": {}
}
Response
application/json

Collection created successfully

{
  "data": {
    "deal_sets": {
      "deal_set": [
        {
          "deals": {
            "deal": [
              {
                "collaterals": {
                  "collateral": [
                    {
                      "subject_property": {
                        "address": {
                          "line_text": "110 Ocean Park Blvd Unit 205",
                          "city": "Santa Monica",
                          "postal_code": "90405",
                          "state_code": "CA"
                        }
                      }
                    }
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  },
  "metadata": {},
  "collection_id": "01EZZEJ3W6MHW9W75CYHEC9PAZ",
  "transaction_id": "01EZZEHJY0J6Y2C6R2C26C1V2F"
}
Parameters
1
ParameterTypeExampleDescription
transaction_id required string (ulid) path 01EZZEHJY0J6Y2C6R2C26C1V2F Staircase Transaction Identifier
Request bodyapplication/json
2 fields
FieldTypeDescription
dataobject
deal_setsobject
deal_setobject[]
dealsobject
metadataobjectStaircase metadata
Response 201application/json
1 fields

Collection created successfully

FieldTypeDescription
collection_idstring (ulid)Staircase Collection IdentifierExample 01EZZEJ3W6MHW9W75CYHEC9PAZ
Response 400application/json
1 fields

Error

FieldTypeDescription
messageone of
Response 403application/json
2 fields

Invalid key for service

FieldTypeDescription
messagestring
urlstring
Response 404application/json
1 fields

Resource not found

FieldTypeDescription
messagestringMessage
POST /valuation

Valuate Collateral

valuation

Valuate Collateral invokes a partner to provide automated valuation modeling for a property. To invoke Valuate Collateral, you will need:

  • a transaction_id/createTransaction), and
  • a collection_id/createCollection).

Once you have a transaction_id and collection_id, you can send them, along with your Authorization Key (api_key), to as many partners as you want.

Simply invoke Valuate Collateral with the same transaction_id and collection_id, but with different partner names. The partner_name parameter is optional. You can retrieve partner_name information by querying the /partners endpoint. Doing so enables you to get automated valuation modeling results from multiple partners, and to see which one provides the optimal response.

Valuate Collateral returns, as a synchronous acknowledgement, a new collection_id. The new collection_id represents an empty container which will hold the partner's response once processing has completed.

Response
application/json

Request for valuation successfully.

{
  "transaction_id": "01EZZEHJY0J6Y2C6R2C26C1V2F",
  "collection_id": "01EZZEJ3W6MHW9W75CYHEC9PAZ"
}
Request bodyapplication/json
3 fields
FieldTypeDescription
transaction_idrequiredstring (ulid)Staircase Transaction IdentifierExample 01EZZEHJY0J6Y2C6R2C26C1V2F
collection_idrequiredstring (ulid)Staircase Collection IdentifierExample 01EZZEJ3W6MHW9W75CYHEC9PAZ
partner_namestringTo get available partners, you can use /partners endpoint
Response 201application/json
2 fields

Request for valuation successfully.

FieldTypeDescription
transaction_idstring (ulid)Staircase Transaction IdentifierExample 01EZZEHJY0J6Y2C6R2C26C1V2F
collection_idstring (ulid)Staircase Collection IdentifierExample 01EZZEJ3W6MHW9W75CYHEC9PAZ
Response 400application/json
1 fields

General error

FieldTypeDescription
messagestringMessage
Response 403application/json
2 fields

Invalid key for service

FieldTypeDescription
messagestring
urlstring
Response 404application/json
1 fields

Resource not found

FieldTypeDescription
messagestringMessage
Response 422application/json
1 fields

Unprocessable Entity

FieldTypeDescription
messagestringMessage
GET /status/{transaction_id}/{collection_id}

Retrieve Status

retrieveStatus

Retrieve Status determines if a partner has completed valuation.

Response
application/json

Error

{
  "message": "transaction_id value is missing"
}
Parameters
2
ParameterTypeExampleDescription
transaction_id required string (ulid) path 01EZZEHJY0J6Y2C6R2C26C1V2F Staircase Transaction Identifier
collection_id required string (ulid) path 01EZZEJ3W6MHW9W75CYHEC9PAZ Staircase collection_id
Response 200application/json
1 fields

Request for getting AVM request status.

FieldTypeDescription
statusstringPotential status responses: 'IN_PROGRESS', 'WAITING_FOR_RESPONSE', 'COMPLETED', 'ERROR'
Response 400application/json
1 fields

Error

FieldTypeDescription
messagestringMessage
Response 403application/json
2 fields

Invalid key for service

FieldTypeDescription
messagestring
urlstring
Response 404application/json
1 fields

Resource not found

FieldTypeDescription
messagestringMessage
Other responses

500

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

Successfully Retrieved Collection

{
  "metadata": {
    "created_at": "03/02/2021, 6:20:55 AM EST",
    "last_updated_at": "03/02/2021, 6:21:12 AM EST",
    "partner_name": "estated",
    "validation": false
  },
  "collection_id": "01EZZEJ3W6MHW9W75CYHEC9PAZ",
  "transaction_id": "01EZZEHJY0J6Y2C6R2C26C1V2F",
  "data": {
    "deal_sets": {
      "deal_set": [
        {
          "deals": {
            "deal": [
              {
                "collaterals": {
                  "collateral": [
                    {
                      "subject_property": {
                        "property_valuations": {
                          "property_valuation": [
                            {
                              "avms": {
                                "avm": [
                                  {
                                    "date": "2020-01-30",
                                    "high_value_range": 118650,
                                    "low_value_range": 91350,
                                    "value": 105000
                                  }
                                ]
                              }
                            }
                          ]
                        }
                      }
                    }
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  }
}
Parameters
2
ParameterTypeExampleDescription
transaction_id required string (ulid) path 01EZZEHJY0J6Y2C6R2C26C1V2F Staircase Transaction Identifier
collection_id required string (ulid) path 01EZZEJ3W6MHW9W75CYHEC9PAZ Staircase collection_id
Response 200application/json
4 fields

Successfully Retrieved Collection

FieldTypeDescription
dataobjectCustomer Input Data
metadataobjectStaircase metadata
transaction_idstring (ulid)Staircase Transaction IdentifierExample 01EZZEHJY0J6Y2C6R2C26C1V2F
collection_idstring (ulid)Staircase Collection IdentifierExample 01EZZEJ3W6MHW9W75CYHEC9PAZ
Response 400application/json
1 fields

Error

FieldTypeDescription
messagestringMessage
Response 403application/json
2 fields

Invalid key for service

FieldTypeDescription
messagestring
urlstring
Response 404application/json
1 fields

Resource not found

FieldTypeDescription
messagestringMessage

Operations

POST /avm

Create AVM

post-avm

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

AVM 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

AVM request created successfully.

FieldTypeDescription
collection_idstringCollection ID
messagestringMessage
GET /avm/elements

Retrieve Elements

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

Validate Collection

post-avm-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 /avm/status/{transaction_id}/{collection_id}

Retrieve Status

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

Create Transaction

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

Create Collection

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

Update Collection

put-avm-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
GET /info

Info endpoint

Placeholder endpoint. As this is a language repo, it must be used in conjunction with the Translator Service.

Other responses

200

POST /inspection

Create Inspection

post-inspection

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

Inspection 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

Inspection request created successfully.

FieldTypeDescription
collection_idstringCollection ID
messagestringMessage
GET /inspection/elements

Retrieve Elements

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

Validate Collection

post-inspection-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 /inspection/status/{transaction_id}/{collection_id}

Retrieve Status

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

Create Transaction

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

Create Collection

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

Update Collection

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

400403404422500

Type to search.