Skip to content
Staircase

Persistence

The graph store every product writes into: containers of linked-data items, immutable state, first-class blobs, and the transaction primitive.

Persistence holds the canonical record. Items are stored in containers keyed by class, each carrying a sortable identifier, and read back as linked data. Search runs over a separate index rather than over the graph itself, so a text query does not become a traversal.

Binary objects are first class. A response collection carries blob identifiers that resolve through a signed-URL call, which keeps documents out of payloads without making the caller manage storage.

How it works

State is immutable. Every change to an entity creates a new record with a new database-generated identifier, while a stable global identifier groups every state of the same real-world thing. Reading history is a query over that group rather than a separate audit table, and a correction never destroys what it corrected.

The transaction and collection primitives every product's API reuses are defined here. That is why a per-vendor attempt is inspectable on any product: the attempt was written as its own collection under the transaction, not folded into a final result.

Operations

Blobs

POST /blobs

Create Blob

create_blob

Create Blob creates a blob instance with specified extension and returns presigned url for content upload.

Note: This will NOT upload your file to the blob instance. To upload a document, you will need to issue a PUT request to the presigned URL returned by the response body. See example, code snippet below:

import requests

# Create Blob endpoint returns blob_id and upload presigned url
# For example, the presigned_url might look like this:
presigned_url = ""

# Set the path to the file you want to upload
filepath = "document.pdf"

# Set the headers appropriately
headers = {
'Content-Type': 'application/pdf'
}

# Read the file data and make the PUT request
with open(filepath, 'rb') as file:
 payload = file.read
 response = requests.put(url=upload_presigned_url, headers=headers, data=payload)
Request
application/json
{
  "extension": ".pdf",
  "presign_url_ttl": 30
}
Response
application/json

Blob has been created

{
  "blob_id": "8c561841-6671-412e-a356-523460ba0d8d",
  "extension": ".pdf",
  "presigned_urls": {
    "upload": {
      "url": "https://api-data-manager-blobs-bucket.s3.amazonaws.com/8c561841-6671-412e-a356-523460ba0d8d"
    }
  }
}
Request bodyapplication/json
3 fields
FieldTypeDescription
extensionrequiredstringExtension of file, that blob is persistingExample .pdf
presign_url_ttlintegerTTL of presigned url in seconds, default is 3600
blob_namestringName for blob
Response 201application/json
6 fields

Blob has been created

FieldTypeDescription
blob_idstring (ulid)Blob idExample 01EZQ32PJQGKRA6HR8D72Q9FFF
extensionstringExtension of file, that blob is persistingExample .pdf
presigned_urlsobjectPresigned urls for uploading or downloading file
uploadobjectPresigned url
urlstring (uri)Presigned urlExample https://api-data-manager-blobs-bucket.s3.amazonaws.com/00c8c9e5-dfdd-44c5-a57e-8de7a2672e2e
page_countintegerNumber of pages present, if the file persisted is a PDF.
content_lengthintegerSize of the file being persisted.
blob_namestringBlob name
Response 400application/json
1 fields

Request data failed validation

FieldTypeDescription
messageone ofMessage
Response 403application/json
1 fields

Missing API key

FieldTypeDescription
messagestringMessage
Response 429application/json
1 fields

The user has sent too many requests in a given amount of time ("rate limiting")

FieldTypeDescription
messagestringMessage
PUT /blobs/{blob_id}/presigned-urls/{action}

Create Blob Presigned URL

generate_presigned_url

Generate new presigned url

Request
application/json
{
  "presign_url_ttl": 3600
}
Response
application/json

New presigned url

{
  "url": "https://api-data-manager-blobs-bucket.s3.amazonaws.com/8c561841-6671-412e-a356-523460ba0d8d"
}
Parameters
3
ParameterTypeExampleDescription
blob_id required string (ulid) path 01EZQ32PJQGKRA6HR8D72Q9FFF Blob id
action required string path upload Action, one of one of ['upload', 'donwload']
x-sc-trace-id required string header 01FJCADX5QEXEDVRWNXAK206MA Trace ID of the transaction
Request bodyapplication/json
1 fields
FieldTypeDescription
presign_url_ttlintegerTTL of presigned url in seconds, default is 3600
Response 200application/json
1 fields

New presigned url

FieldTypeDescription
urlstring (uri)Presigned urlExample https://api-data-manager-blobs-bucket.s3.amazonaws.com/00c8c9e5-dfdd-44c5-a57e-8de7a2672e2e
Response 400application/json
1 fields

Request data failed validation

FieldTypeDescription
messageone ofMessage
Response 403application/json
1 fields

Missing API key

FieldTypeDescription
messagestringMessage
Response 404application/json
1 fields

Requested resource not found

FieldTypeDescription
messagestringMessage
Response 429application/json
1 fields

The user has sent too many requests in a given amount of time ("rate limiting")

FieldTypeDescription
messagestringMessage
GET /blobs/{blob_id}

Retrieve Blob

get_blob

Retrieve Blob instance: extension, last created presigned urls, page count and content length

Response
application/json

Blob instance with last created presigned urls

{
  "blob_id": "8c561841-6671-412e-a356-523460ba0d8d",
  "extension": ".pdf",
  "presigned_urls": {
    "download": {
      "url": "https://api-data-manager-blobs-bucket.s3.amazonaws.com/8c561841-6671-412e-a356-523460ba0d8d"
    },
    "upload": {
      "url": "https://api-data-manager-blobs-bucket.s3.amazonaws.com/8c561841-6671-412e-a356-523460ba0d8d"
    }
  },
  "page_count": 3,
  "content_length": 7478
}
Parameters
2
ParameterTypeExampleDescription
blob_id required string (ulid) path 01FJCA39TSCHS6Q8K69FEEMQZQ Blob id
x-sc-trace-id required string header 01FJCADX5QEXEDVRWNXAK206MA Trace ID of the transaction
Response 200application/json
4 fields

Blob instance with last created presigned urls

FieldTypeDescription
blob_idstring (ulid)Blob idExample 01EZQ32PJQGKRA6HR8D72Q9FFF
extensionstringExtension of file, that blob is persistingExample .pdf
presigned_urlsobjectPresigned urls for uploading or downloading file
downloadobjectPresigned url
urlstring (uri)Presigned urlExample https://api-data-manager-blobs-bucket.s3.amazonaws.com/00c8c9e5-dfdd-44c5-a57e-8de7a2672e2e
uploadobjectPresigned url
urlstring (uri)Presigned urlExample https://api-data-manager-blobs-bucket.s3.amazonaws.com/00c8c9e5-dfdd-44c5-a57e-8de7a2672e2e
blob_namestringBlob name
Response 400application/json
1 fields

Request data failed validation

FieldTypeDescription
messageone ofMessage
Response 403application/json
1 fields

Missing API key

FieldTypeDescription
messagestringMessage
Response 404application/json
1 fields

Requested resource not found

FieldTypeDescription
messagestringMessage
Response 429application/json
1 fields

The user has sent too many requests in a given amount of time ("rate limiting")

FieldTypeDescription
messagestringMessage
Other responses

422

GET /blobs/{blob_id}/presigned-urls

Retrieve Blob Presigned URLs

get_preassigned_urls

Response
application/json

Presigned urls

{
  "download": {
    "url": "https://api-data-manager-blobs-bucket.s3.amazonaws.com/8c561841-6671-412e-a356-523460ba0d8d"
  },
  "upload": {
    "url": "https://api-data-manager-blobs-bucket.s3.amazonaws.com/8c561841-6671-412e-a356-523460ba0d8d"
  }
}
Parameters
2
ParameterTypeExampleDescription
blob_id required string (ulid) path 01FJCA39TSCHS6Q8K69FEEMQZQ Blob id
x-sc-trace-id required string header 01FJCADX5QEXEDVRWNXAK206MA Trace ID of the transaction
Response 200application/json
2 fields

Presigned urls

FieldTypeDescription
downloadobjectPresigned url
urlstring (uri)Presigned urlExample https://api-data-manager-blobs-bucket.s3.amazonaws.com/00c8c9e5-dfdd-44c5-a57e-8de7a2672e2e
uploadobjectPresigned url
urlstring (uri)Presigned urlExample https://api-data-manager-blobs-bucket.s3.amazonaws.com/00c8c9e5-dfdd-44c5-a57e-8de7a2672e2e
Response 400application/json
1 fields

Request data failed validation

FieldTypeDescription
messageone ofMessage
Response 403application/json
1 fields

Missing API key

FieldTypeDescription
messagestringMessage
Response 404application/json
1 fields

Requested resource not found

FieldTypeDescription
messagestringMessage
Response 429application/json
1 fields

The user has sent too many requests in a given amount of time ("rate limiting")

FieldTypeDescription
messagestringMessage
GET /blobs/{blob_id}/presigned-urls/{action}

Retrieve Presigned URL for Action

get_presigned_url

Get presigned url

Response
application/json

Presigned url

{
  "url": "https://api-data-manager-blobs-bucket.s3.amazonaws.com/8c561841-6671-412e-a356-523460ba0d8d"
}
Parameters
3
ParameterTypeExampleDescription
blob_id required string (ulid) path 01EZQ32PJQGKRA6HR8D72Q9FFF Blob id
action required string path upload Action for url
x-sc-trace-id required string header 01FJCADX5QEXEDVRWNXAK206MA Trace ID of the transaction
Response 200application/json
1 fields

Presigned url

FieldTypeDescription
urlstring (uri)Presigned urlExample https://api-data-manager-blobs-bucket.s3.amazonaws.com/00c8c9e5-dfdd-44c5-a57e-8de7a2672e2e
Response 400application/json
1 fields

Request data failed validation

FieldTypeDescription
messageone ofMessage
Response 403application/json
1 fields

Missing API key

FieldTypeDescription
messagestringMessage
Response 404application/json
1 fields

Requested resource not found

FieldTypeDescription
messagestringMessage
Response 429application/json
1 fields

The user has sent too many requests in a given amount of time ("rate limiting")

FieldTypeDescription
messagestringMessage

Graph

POST /graph/merge

Execute Merge

execute_merge

Execute merge of collections stored in the Persistence Graph.

This API is only available when the Persistence Graph component is installed in the user's environment.

The request body must be in JSON format and contain the following properties:

transaction_id: ID of transaction to merge.

Also request body may contain one optional property:

collection_ids: A list of IDs of collections which should be merged.

Show the rest

The response is returned in JSON format and contains the results of the merge.

Example of merging process

In the transaction we have two collection that we want to merge. Entities will be merged if it matches by type, properties and values.

first collection:

 {
 "addresses": [
 {
 "@id": "01FD9XEX1KVQ182TXBN67YVJ04",
 "@type": "residential_address",
 "has_address_line_1_text": {
 "has_value": "535 30 RD"
 },
 "has_city_name": {
 "has_value": "GRAND JUNCTION"
 },
 "has_postal_code": {
 "has_value": "81504"
 },
 "has_state_code": {
 "has_value": "CO"
 }
 },
 {
 "@id": "01FD9XEX1KN579K22XEC9A6Q6C",
 "@type": "residential_address",
 "has_address_line_1_text": {
 "has_value": "312 OURAY AV"
 },
 "has_city_name": {
 "has_value": "GRAND JUNCTION"
 },
 "has_postal_code": {
 "has_value": "81501"
 },
 "has_state_code": {
 "has_value": "CO"
 }
 }
 ],
 "people": [
 {
 "@type": "borrower",
 "@id": "01GQHRJVS13E8S9T0RMZPXF02V",
 "has_first_name": {
 "has_value": "John"
 },
 "has_last_name": {
 "has_value": "Deere"
 },
 "has_birth_date": {
 "has_value": "01/01/1985"
 },
 "has_taxpayer_identifier_value": {
 "has_value": "999-00-0000"
 },
 "lives_at": [
 "01FD9XEX132KHJ64GEE6PYWE19",
 "01FD9XEX13TNAVJ0NJ23MYZMH2"
 ],
 "with_credit_information": [
 "01FD9XEWZYM5ZTNCGRRPND285X",
 "01GTM5V2BEWMFN1Q6E3675YVM1"
 ]
 }
 ],
 "residences": [
 {
 "@id": "01FD9XEX132KHJ64GEE6PYWE19",
 "@type": "residence",
 "has_borrower_residency_type": {
 "has_value": "current"
 },
 "with_address": [
 "01FD9XEX1KVQ182TXBN67YVJ04"
 ]
 },
 {
 "@id": "01FD9XEX13TNAVJ0NJ23MYZMH2",
 "@type": "residence",
 "has_borrower_residency_type": {
 "has_value": "prior"
 },
 "with_address": [
 "01FD9XEX1KN579K22XEC9A6Q6C"
 ]
 }
 ],
 "credit_information": [
 {
 "@id": "01FD9XEWZYM5ZTNCGRRPND285X",
 "@type": "credit_information",
 "has_credit_frozen_status_equifax_indicator": {
 "has_value": "false"
 },
 "has_credit_frozen_status_experian_indicator": {
 "has_value": "false"
 },
 "has_credit_frozen_status_trans_union_indicator": {
 "has_value": "false"
 },
 "has_credit_rating_code_type": {
 "has_value": "equifax"
 },
 "has_credit_report_first_issued_date": {
 "has_value": "2021-08-17"
 },
 "has_credit_report_identifier": {
 "has_value": "2-a7e4f473-18f0-4fc7-9"
 },
 "has_credit_report_merge_type": {
 "has_value": "list_and_stack"
 },
 "has_credit_repository_included_equifax_indicator": {
 "has_value": "false"
 },
 "has_credit_repository_included_experian_indicator": {
 "has_value": "false"
 },
 "has_credit_repository_included_trans_union_indicator": {
 "has_value": "true"
 },
 "has_credit_request_data_credit_repository_included_equifax_indicator": {
 "has_value": "false"
 },
 "has_credit_request_data_credit_repository_included_experian_indicator": {
 "has_value": "false"
 },
 "has_credit_request_data_credit_repository_included_trans_union_indicator": {
 "has_value": "false"
 },
 "has_data_version_credmo_identifier": {
 "has_value": "1.3"
 },
 "has_data_version_equifax_identifier": {
 "has_value": "4"
 }
 },
 {
 "@id": "01GTM5V2BEWMFN1Q6E3675YVM1",
 "@type": "credit_information",
 "has_credit_frozen_status_equifax_indicator": {
 "has_value": "false"
 },
 "has_credit_frozen_status_experian_indicator": {
 "has_value": "false"
 },
 "has_credit_frozen_status_trans_union_indicator": {
 "has_value": "false"
 },
 "has_credit_rating_code_type": {
 "has_value": "equifax"
 },
 "has_credit_report_first_issued_date": {
 "has_value": "2021-08-17"
 },
 "has_credit_report_identifier": {
 "has_value": "2-a7e4f473-18f0-4fc7-9"
 },
 "has_credit_report_merge_type": {
 "has_value": "list_and_stack"
 },
 "has_credit_repository_included_equifax_indicator": {
 "has_value": "false"
 },
 "has_credit_repository_included_experian_indicator": {
 "has_value": "false"
 },
 "has_credit_repository_included_trans_union_indicator": {
 "has_value": "true"
 },
 "has_credit_request_data_credit_repository_included_equifax_indicator": {
 "has_value": "false"
 },
 "has_credit_request_data_credit_repository_included_experian_indicator": {
 "has_value": "false"
 },
 "has_credit_request_data_credit_repository_included_trans_union_indicator": {
 "has_value": "false"
 },
 "has_data_version_credmo_identifier": {
 "has_value": "1.3"
 },
 "has_data_version_equifax_identifier": {
 "has_value": "4"
 }
 }
 ]
 }

second collection:

 {
 "people": [
 {
 "@type": "borrower",
 "@id": "01FDF04MYHEZ98AD7T8ZGY5CMB",
 "has_first_name": {
 "has_value": "John"
 },
 "has_last_name": {
 "has_value": "Deere"
 },
 "has_birth_date": {
 "has_value": "01/01/1985"
 },
 "has_taxpayer_identifier_value": {
 "has_value": "999-00-0000"
 },
 "contact_at": [
 "01FDF09BNQCT03DCAX7M5KM52T",
 "01GTM5XEKKJ23KC28QEA8TG971"
 ],
 "employed_as": [
 "01FDF0DFYAHBRJGFA5RS26HVP1"
 ]
 }
 ],
 "contact_information": [
 {
 "@type": "contact_information",
 "@id": "01FDF09BNQCT03DCAX7M5KM52T",
 "has_phone_number": {
 "has_value": "+1234567890"
 }
 },
 {
 "@type": "contact_information",
 "@id": "01GTM5XEKKJ23KC28QEA8TG971",
 "has_phone_number": {
 "has_value": "+1234567890"
 }
 }
 ],
 "employment": [
 {
 "@id": "01FDF0DFYAHBRJGFA5RS26HVP1",
 "@type": "employment",
 "has_employment_position_description": {
 "has_value": "Engineer"
 }
 }
 ]
 }

merged collection:

 {
 "addresses": [
 {
 "@id": "01FD9XEX1KVQ182TXBN67YVJ04",
 "@type": "residential_address",
 "has_address_line_1_text": {
 "has_value": "535 30 RD"
 },
 "has_city_name": {
 "has_value": "GRAND JUNCTION"
 },
 "has_postal_code": {
 "has_value": "81504"
 },
 "has_state_code": {
 "has_value": "CO"
 }
 },
 {
 "@id": "01FD9XEX1KN579K22XEC9A6Q6C",
 "@type": "residential_address",
 "has_address_line_1_text": {
 "has_value": "312 OURAY AV"
 },
 "has_city_name": {
 "has_value": "GRAND JUNCTION"
 },
 "has_postal_code": {
 "has_value": "81501"
 },
 "has_state_code": {
 "has_value": "CO"
 }
 }
 ],
 "contact_information": [
 {
 "@id": "01FDF09BNQCT03DCAX7M5KM52T",
 "@type": "contact_information",
 "has_phone_number": {
 "has_value": "+1234567890"
 }
 }
 ],
 "credit_information": [
 {
 "@id": "01FD9XEWZYM5ZTNCGRRPND285X",
 "@type": "credit_information",
 "has_credit_frozen_status_equifax_indicator": {
 "has_value": "false"
 },
 "has_credit_frozen_status_experian_indicator": {
 "has_value": "false"
 },
 "has_credit_frozen_status_trans_union_indicator": {
 "has_value": "false"
 },
 "has_credit_rating_code_type": {
 "has_value": "equifax"
 },
 "has_credit_report_first_issued_date": {
 "has_value": "2021-08-17"
 },
 "has_credit_report_identifier": {
 "has_value": "2-a7e4f473-18f0-4fc7-9"
 },
 "has_credit_report_merge_type": {
 "has_value": "list_and_stack"
 },
 "has_credit_repository_included_equifax_indicator": {
 "has_value": "false"
 },
 "has_credit_repository_included_experian_indicator": {
 "has_value": "false"
 },
 "has_credit_repository_included_trans_union_indicator": {
 "has_value": "true"
 },
 "has_credit_request_data_credit_repository_included_equifax_indicator": {
 "has_value": "false"
 },
 "has_credit_request_data_credit_repository_included_experian_indicator": {
 "has_value": "false"
 },
 "has_credit_request_data_credit_repository_included_trans_union_indicator": {
 "has_value": "false"
 },
 "has_data_version_credmo_identifier": {
 "has_value": "1.3"
 },
 "has_data_version_equifax_identifier": {
 "has_value": "4"
 }
 }
 ],
 "employment": [
 {
 "@id": "01FDF0DFYAHBRJGFA5RS26HVP1",
 "@type": "employment",
 "has_employment_position_description": {
 "has_value": "Engineer"
 }
 }
 ],
 "people": [
 {
 "@id": "01GQHRJVS13E8S9T0RMZPXF02V",
 "@type": "borrower",
 "contact_at": [
 "01FDF09BNQCT03DCAX7M5KM52T"
 ],
 "employed_as": [
 "01FDF0DFYAHBRJGFA5RS26HVP1"
 ],
 "has_birth_date": {
 "has_value": "01/01/1985"
 },
 "has_first_name": {
 "has_value": "John"
 },
 "has_last_name": {
 "has_value": "Deere"
 },
 "has_taxpayer_identifier_value": {
 "has_value": "999-00-0000"
 },
 "lives_at": [
 "01FD9XEX13TNAVJ0NJ23MYZMH2",
 "01FD9XEX132KHJ64GEE6PYWE19"
 ],
 "with_credit_information": [
 "01FD9XEWZYM5ZTNCGRRPND285X"
 ]
 }
 ],
 "residences": [
 {
 "@id": "01FD9XEX13TNAVJ0NJ23MYZMH2",
 "@type": "residence",
 "has_borrower_residency_type": {
 "has_value": "prior"
 },
 "with_address": [
 "01FD9XEX1KN579K22XEC9A6Q6C"
 ]
 },
 {
 "@id": "01FD9XEX132KHJ64GEE6PYWE19",
 "@type": "residence",
 "has_borrower_residency_type": {
 "has_value": "current"
 },
 "with_address": [
 "01FD9XEX1KVQ182TXBN67YVJ04"
 ]
 }
 ]
 }
Request
application/json
{
  "transaction_id": "01GSWRGPWD2C5SYPAN8TS4ZADJ",
  "collection_ids": [
    "01GSWRQXKK7AHPH4XG4DRHYXSZ",
    "01GSWS0PY75NFRHBFA4ERTFMD8"
  ]
}
Response
application/json

Ok.

{
  "merge_result": {
    "contact_information": [
      {
        "@id": "01FDF09BNQCT03DCAX7M5KM52T",
        "@type": "contact_information",
        "has_phone_number": {
          "has_value": "+1234567890"
        }
      }
    ],
    "employment": [
      {
        "@id": "01FDF0DFYAHBRJGFA5RS26HVP1",
        "@type": "employment",
        "has_employment_position_description": {
          "has_value": "Engineer"
        }
      }
    ],
    "people": [
      {
        "@id": "01FDF04MYHEZ98AD7T8ZGY5CMB",
        "@type": "borrower",
        "contact_at": [
          "01FDF09BNQCT03DCAX7M5KM52T"
        ],
        "employed_as": [
          "01FDF0DFYAHBRJGFA5RS26HVP1"
        ],
        "has_birth_date": {
          "has_value": "01/01/1985"
        },
        "has_first_name": {
          "has_value": "John"
        },
        "has_last_name": {
          "has_value": "Deere"
        },
        "has_taxpayer_identifier_value": {
          "has_value": "999-00-0000"
        },
        "lives_at": [
          "01GS59J4PHKYRH3D9TPAV3FK40",
          "01FD9XEX13TNAVJ0NJ23MYZM10"
        ]
      }
    ]
  }
}
Request bodyapplication/json
2 fields
FieldTypeDescription
transaction_idrequiredstringID of transaction to merge.Example 01GSWRGPWD2C5SYPAN8TS4ZADJ
collection_idsstring[]Array of collection IDs to merge.
Response 200application/json
1 fields

Ok.

FieldTypeDescription
merge_resultrequiredobjectMerged collections
Response 400application/json
1 fields

Request data invalid

FieldTypeDescription
messagestringError message
POST /graph/query

Execute Query

execute_query

Execute query against data stored in the Persistence Graph. This API endpoint /graph/query allows users to execute a query against the data stored in the Persistence Graph. This API is only available when the Persistence Graph component is installed in the user's environment. The HTTP method used to execute a query is POST. The request body must be in JSON format and contain the following properties: query: A JSONPATH or JMESPATH query object containing the path of the data to query, the operation to perform, and the value to query against. The query object has the following properties: path: An object containing the query path and format. The format property must be set to JSONPATH or JMESPATH. operation: The operation to perform, such as BETWEEN, CONTAINS, EQ, GT, GTE, LT, LTE, NE, or STARTSWITH. value: The value to query against. echo: Boolean flag, if true, the raw SPARQL Query will be present in the response. include_total_count: An optional boolean value that determines whether the response should include a field called "total_count" with the total number of items returned by the query. The default value is false. sort: Optional flag. If ASC, response will be sorted from small to greater. If DESC, response will be sorted from greater to lesser. By default, ASC sort is applied. transaction_ids: Optional field. If provided, response will include only collections from the transactions_ids provided. If omitted, will return data in all transactions. page parameter is specified with the next_token parameter. The page parameter is a number with a value more than 0. latest_collections_only Boolean flag. If true, only return the latest collection from each transaction. Default is false. use_sug Boolean flag. If true, collections are searched in SUG. Default is false. 'latest_collection_only_tr: Boolean flag, new version of latest_collections_onlyflag. Uses different method to make queries to SPARQL, optimized for large amount of collections in transaction, but works only with collections created after 18.01.2024. Has priority overlatest_collection_only` The request body examples show how to use the API to perform different types of queries. For example, finding the first person in the people array with a has_first_name property equal to Vlad, or finding all people with a has_credit_score property between 400 and 500. The response is returned in JSON format and contains the results of the query. If query_result array of the response body is empty, it means no new data is available for this query.

Show the rest
Known limitations 1. No slices are supported.
  1. No multiselect for JMESPATH (for example 'people[?age > 20].[name, age]') is not supported.

  2. Pipe Expressions for JMESPATH not available.

  3. No multiple logical conditions for JMESPATH.

  4. No functions for JMESPATH.

If you need this feature, please open Customer Request to us.

Request
application/json
{
  "query": {
    "path": {
      "path": "$.people[0].has_first_name.has_value",
      "format": "jsonpath"
    },
    "operation": "eq",
    "value": "Vlad"
  }
}
Response
application/json

Ok.

{
  "query_result": [
    {
      "transaction_id": "01GSD62EEBT4YD1Y0W6GFVA4EB",
      "collection_id": "01GSD68Z48JRJK8MM4YYRCTH3D"
    },
    {
      "transaction_id": "01GSD62EEBT4YD1Y0W6GFVA4EB",
      "collection_id": "01GSD6AC2XH7QW4N8RE67QB0Z9"
    }
  ],
  "next_token": "7b22637265617465645f6174223a2022323032332d30322d32325431383a31333a32352e3834373236372b30323a3030222c20226f6666736574223a20313030307d",
  "total_count": 42
}
Request bodyapplication/json
11 fields
FieldTypeDescription
queryrequiredobjectJSONPath query
pathrequiredobjectThe location of data for query
pathrequiredstringThe query path. Must be valid JSONPATH or JMESPATH.
formatrequiredstringThe query format in useJMESPATHJSONPATH
operationrequiredstringOperationBETWEENCONTAINSEQGTGTELTLTENESTARTSWITH
valuerequiredstringWhat value to query against.
next_tokenstringNext token from the response body.Example 7b22637265617465645f6174223a2022323032332d30322d32325431383a31333a32352e3834373236372b30323a3030222c20226f6666736574223a20313030307d
limitintegerLimits how many results should be in the response.Example 100
transaction_labelstringIf provided, include only the transactions with the provided 'transaction_label'.Example my_label
transaction_idsstring[]If provided, include only the transactions with the provided 'transaction_ids'.
echobooleanIf provided, response will include `raw_query` key.Example true
sortstringIf provided, response will be sorted asc or desc.ASCDESCExample DESC
include_total_countbooleanAn optional boolean value that determines whether the response should include a field called "total_count" with the total number of items returned by the query. The default value is false.
pageintegerOptional parameter to specify the page of data to retrieve. Must be used with the "next_token" parameter.
latest_collections_onlybooleanIf true, only return the latest collection from each transaction.Example true
use_sugbooleanIf true, collections are searched in SUG.Example true
Response 200application/json
3 fields

Ok.

FieldTypeDescription
query_resultrequiredobject[]Array of transaction and collection IDs pair
transaction_idrequiredstringTransaction IDExample 01GSD62EEBT4YD1Y0W6GFVA4EB
collection_idrequiredstringCollection IDExample 01GSD6AC2XH7QW4N8RE67QB0Z9
next_tokenrequiredstringNext token of the query. Pass it to request body to get next 1000 results of the query. If null, no next results available.Example 7b22637265617465645f6174223a2022323032332d30322d32325431383a31333a32352e3834373236372b30323a3030222c20226f6666736574223a20313030307d
raw_querystringThe raw SPARQL Query that was executed. Useful for debug. Only available if request body parameter echo is true.Example PREFIX sci: <https://staircase.co/> PREFIX sc: <https://www.staircase.co/ontology/> PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> PREFIX xsd: <http://www.w3.org/2001/XMLSchema#> SELECT DISTINCT ?transaction_id ?collection_id { {?data sc:communications/rdf:rest*/rdf:first ?x_1 . ?x_1 rdf:type ?x_2 . ?x_1 sc:has_communication_source_username/sc:has_value ?x_3 FILTER (?x_2 = sc:email) . FILTER (?x_3 = "nivanjeet.singh@staircase.co")}{?data sc:communications/rdf:rest*/rdf:first ?x_4 . ?x_4 rdf:type ?x_5 . ?x_4 sc:with_sender/rdf:first/sc:contact_at/rdf:first/sc:has_email_address/sc:has_value ?x_6 FILTER (?x_5 = sc:email) . FILTER (?x_6 = "blah@blah.com")} GRAPH ?transaction_id { ?collection_id sci:data ?data } ?collection_id sci:metadata/sci:created_at ?created_at . FILTER (xsd:dateTime(?created_at) <= "2023-03-06T16:24:11.362539+00:00"^^xsd:dateTime) } ORDER BY ?transaction_id ?collection_id LIMIT 10 OFFSET 0
Response 400application/json
1 fields

Request data invalid

FieldTypeDescription
messagestringError message
GET /graph/sparql

Query Graph

query_graph

Query Graph as SPARQL HTTP JSON query endpoint so that customer can use it with any SPARQL wrapper, f.e.: Endpoint is fully compatible with SPARQL 1.1 Protocol. Supports SELECT, ASK, CONSTRUCT, and DESCRIBE queries. The default return format is JSON-LD, customizable with an Accept header. Persistence Graph service is installed as a separate component from the marketplace and requires an installed Persistence product. Persistence Graph costs 300 USD per month.

Show the rest

To include the collection in the graph, you should set the serialise_to_graph parameter in metadata to true. The collection is stored as a named graph with transaction_id as graph URI in the format: ``.

Example of Collection in TriG format:

 @prefix sci: .
 @prefix sc: .
 @prefix xsd: .
 sci:01GPG88H8ZYDDTXE9M6DYCF7WN {
 sci:01GPG88H8ZYDDTXE9M6DYCF7WN sci:transaction_label "some_label"
 sci:01GPG89C7FRM7F5STXMW59TBPQ sci:data [ sc:addresses sci:01GPG9FP9CM7SN1AF1NP3Z0B5K,
 sci:01GPGBQNZ5YHEWTKN43B8CPWHW ;
 sc:people sci:01GPG8ZHGNWH85DYPZQ7CEVTRZ ] ;
 sci:metadata [ sci:active true ;
 sci:created_at "2023-01-11T13:56:48.485729" ;
 sci:last_updated_at "2023-01-11T13:57:48.485729" ] .
 sci:01GPG8ZHGNWH85DYPZQ7CEVTRZ a sc:borrower ;
 sc:has_first_name [ sc:has_value "Bob" ] ;
 sc:with_addresses sci:01GPG9FP9CM7SN1AF1NP3Z0B5K,
 sci:01GPGBQNZ5YHEWTKN43B8CPWHW .
 sci:01GPG9FP9CM7SN1AF1NP3Z0B5K a sc:mailing_address ;
 sc:has_city_name [ sc:has_value "New York" ] .
 sci:01GPGBQNZ5YHEWTKN43B8CPWHW a sc:mailing_address ;
 sc:has_city_name [ sc:has_value "Chicago" ] .
 }
Response
application/json

Request data failed validation

{
  "detailedMessage": "Malformed query",
  "code": "MalformedQueryException"
}
Parameters
3
ParameterTypeExampleDescription
query required string query SELECT%20%2A%20WHERE%20%7B%20%3Fs%20%3Fp%20%3Fo%20%7D%20LIMIT%2010 Your SPARQL query in URL-encoded format
Accept string header application/sparql-results+json Accept header is used to specify the format of the response. If not specified, the default is application/sparql-results+json. Supported formats: application/nquads, application/n-triples, application/rdf+xml, application/ld+json, application/trig, application/trix, text/turtle, text/x-nquads, text/n3, application/sparql-results+json, application/x-binary-rdf, */*
explain string query static Explain parameter could be passed to retrieve information about how your SPARQL query will be executed in the neptune. Currently supports explain only in SPARQL SELECT queries.
Response 200application/sparql-results+json
3 fields

queried

FieldTypeDescription
headobjectThe head of the result set.
varsstring[]The variables in the result set.
resultsobjectThe results of the query.
bindingsobject[]The bindings of the results.
booleanbooleanThe boolean result of the query. Used in ASK query
Response 400application/json
2 fields

Request data failed validation

FieldTypeDescription
detailedMessagestringMessage
codestringException Code in Neptune format
Response 403application/json
1 fields

Missing API key

FieldTypeDescription
messagestringMessage
Other responses

406422500

Typesense

GET /health

Health check

health_check

Response
application/json

OK response

{
  "ok": true
}
Response 200application/json
1 fields

OK response

FieldTypeDescription
okbooleanHealth check status.

Indexes

POST /indexes

Create Index

create_index

Creates an index. Persistence indexes support 2 type of JSON query languages: JSONPath and JMESPath. Both of them work with graph v2 collections like in Query on Collection Level endpoint. After index is created all collections will be indexed against it. You can list indexed items using List index items endpoint.

Request
application/json
{
  "name": "borrower_ssn",
  "path": {
    "path": "$.people[?(@['@type'] == 'borrower')].has_taxpayer_identifier_value.has_value",
    "format": "jsonpath"
  }
}
Response
application/json

Request data failed validation

{
  "message": "{'data': ['Missing data for required field.']}"
}
Request bodyapplication/json
4 fields
FieldTypeDescription
namerequiredstringName of the Index
manybooleanFlag that defines the separating of values in the query to different items. If `many` == true, and query by index found more than 2 values, they will be put to different items. Otherwise, to the same item.
pathrequiredobjectThe location of data to be indexed
pathrequiredstringThe query path
formatrequiredstringThe query format in usejmespathjsonpath
transaction_labelsstring[]The list of transaction labels, which collections need to be captured in the index
Response 201application/json
3 fields

created

FieldTypeDescription
namerequiredstringName of the Index
manybooleanFlag that defines the separating of values in the query to different items. If `many` == true, and query by index found more than 2 values, they will be put to different items. Otherwise, to the same item.
pathrequiredobjectThe location of data to be indexed
pathrequiredstringThe query path
formatrequiredstringThe query format in usejmespathjsonpath
Response 400application/json
1 fields

Request data failed validation

FieldTypeDescription
messageone ofMessage
Response 403application/json
1 fields

Missing API key

FieldTypeDescription
messagestringMessage
Other responses

422

GET /indexes

List Indexes

list_indexes

List indexes

List indexes. You can specify additional filters using the index_name or created_at parameters, with available operators: gt, lt, startswith.

Response
application/json

Request data failed validation

{
  "message": "{'data': ['Missing data for required field.']}"
}
Parameters
1
ParameterTypeDescription
filter string query Filter by one of the index_name or created_at fields.
Response 200application/json
3 fields

Index

FieldTypeDescription
indexesarrayList of indexes
_linksobjectLinks to next page of results
nextstringLink to next page of results
next_tokenstringPagination token for next page
Response 400application/json
1 fields

Request data failed validation

FieldTypeDescription
messageone ofMessage
Response 403application/json
1 fields

Missing API key

FieldTypeDescription
messagestringMessage
Response 404application/json
1 fields

Requested resource not found

FieldTypeDescription
messagestringMessage
Other responses

422

DELETE /indexes/{index_name}

Delete Index

delete_index

Delete an index

Response
application/json

Index

{
  "message": "Index deleted"
}
Parameters
1
ParameterTypeExampleDescription
index_name required string path my_index The name of the index
Response 200application/json
1 fields

Index

FieldTypeDescription
messagestringMessageExample Index deleted
Response 404application/json
1 fields

Requested resource not found

FieldTypeDescription
messagestringMessage
GET /indexes/{index_name}

Retrieve Index

get_index

Retrieve an index

Response
application/json

Index

{
  "name": "borrower_ssn",
  "path": {
    "path": "$.people[@['@type'] == 'borrower'].has_taxpayer_identifier_value.has_value",
    "format": "jsonpath"
  }
}
Parameters
1
ParameterTypeExampleDescription
index_name required string path my_index The name of the index
Response 200application/json
6 fields

Index

FieldTypeDescription
namerequiredstringThe name of the index
pathrequiredobjectThe query location of the indexed data
pathrequiredstringValue of the path
formatrequiredstringThe query format in usejmespathjsonpath
created_atstring (date-time)Date time when index was created.
statusstringStatus of the indexAVAILABLEREINDEXINGREINDEXING_FAILED
reindexing_failure_reasonstringProvided if status is "REINDEXING_FAILED".
_linksobjectLinks
itemsstring (uri)Link to index items
Response 400application/json
1 fields

Request data failed validation

FieldTypeDescription
messageone ofMessage
Response 403application/json
1 fields

Missing API key

FieldTypeDescription
messagestringMessage
Response 404application/json
1 fields

Requested resource not found

FieldTypeDescription
messagestringMessage
GET /indexes/{index_name}/items

Get items in index

list_items

List index items

List index items. Index items contain transaction and collection IDs of collections with its values. Items can be filtered by value and by creation date, by providing them in query parameters. Items are sorted by creation date. Filtering by created_at:

  • gt:
  • description: Get items, that were created after specified datetime in ISO format
  • example: created_at+gt+2021-03-30T04:27:15.372006-04:00
  • lt:
  • description: Get items, that were created before specified datetime in ISO format
  • example: created_at+lt+2021-03-30T04:27:15.372006-04:00
Response
application/json

Request data failed validation

{
  "message": "{'data': ['Missing data for required field.']}"
}
Parameters
5
ParameterTypeExampleDescription
index_name required string path my_index The name of the index
value string query Filter by value of the indexed data
sort string query Sorting direction.
filter string query Filter by created_at field.
limit integer query Limit the number of items returned.
Response 200application/json
3 fields

Indexed data

FieldTypeDescription
itemsarrayItems matching the query
_linksobjectLinks to next page of results
nextstringLink to next page of results
next_tokenstringPagination token for next page
Response 400application/json
1 fields

Request data failed validation

FieldTypeDescription
messageone ofMessage
Response 403application/json
1 fields

Missing API key

FieldTypeDescription
messagestringMessage
Response 404application/json
1 fields

Requested resource not found

FieldTypeDescription
messagestringMessage
Other responses

422

POST /indexes/{index_name}/reindex

Re-index collections

reindex_collections

Re-indexes specific v2 collections on the environment that were created before the index was created. You must specify specific transactions to be re-indexed with body parameters: transaction_ids or transaction_label. Reindexing of all collections on the environment is not supported since cost of reindexing all collections is too high.

Request
application/json
{
  "transaction_ids": [
    "01EZQ32NEN5VDHE288WN4TV2D3",
    "01EZQ32NEN5VDHE288WN4TV2D4"
  ]
}
Response
application/json

Request data failed validation

{
  "message": "{'data': ['Missing data for required field.']}"
}
Parameters
1
ParameterTypeExampleDescription
index_name required string path my_index The name of the index
Request bodyapplication/json
2 fields
FieldTypeDescription
transaction_idsstring[]List of transaction ID's which collections will be re-indexed.
transaction_labelstringTransaction label, which collections will be re-indexed.
Response 200application/json
1 fields

created

FieldTypeDescription
statusstringNew status of the indexREINDEXING
Response 400application/json
1 fields

Request data failed validation

FieldTypeDescription
messageone ofMessage
Response 403application/json
1 fields

Missing API key

FieldTypeDescription
messagestringMessage
Response 404application/json
1 fields

Requested resource not found

FieldTypeDescription
messagestringMessage
Response 409application/json
1 fields

Conflict

FieldTypeDescription
messagestringMessage
Other responses

422

POST /indexes/query

Query Indexes

query_indexes

Query on Indexes

Query on multiple Indexes at the same time to find specific collections. You can query on indexes values with operations: between, contains, eq, gt, gte, lt, lte, ne, startswith. And then you can combine them with logical operators: and, or, xor, diff; such as on the example below.

Request
application/json
{
  "or": [
    {
      "and": [
        {
          "index_name": "foo",
          "operation": "eq",
          "value": 23
        },
        {
          "index_name": "bar",
          "operation": "startswith",
          "value": "grate"
        }
      ]
    },
    {
      "index_name": "baz",
      "operation": "between",
      "value": [
        20,
        35
      ]
    }
  ]
}
Response 200application/json
1 fields

Successfully queried indexes

FieldTypeDescription
resultsobject[]List of collections that match the query
transaction_idstringTransaction ID of the collection
collection_idstringCollection ID of the collection
Other responses

422

Lexicon

PUT /lexicon

Import Lexicon

PutLexicon

Request
application/json
{
  "classes": [
    {
      "type": "person",
      "container_name": "people",
      "is_deprecated": false,
      "deprecated_properties": [],
      "properties": {
        "first_name": {
          "type": "boolean"
        }
      }
    },
    {
      "type": "address",
      "container_name": "addresses",
      "is_deprecated": false,
      "deprecated_properties": [
        "address_line_deprecated"
      ],
      "properties": {
        "address_type": {
          "type": "string",
          "enum": [
            "Mailing",
            "Current"
          ]
        },
        "address_line_1": {
          "type": "string"
        },
        "address_line_deprecated": {
          "type": "string"
        }
      }
    },
    {
      "type": "credit",
      "container_name": "credits",
      "is_deprecated": false,
      "deprecated_properties": [],
      "properties": {
        "credit_identifier": {
          "type": "string"
        }
      },
      "relationships": {
        "owed_to": {
          "targets": [
            "person"
          ]
        }
      }
    },
    {
      "type": "finance_relation",
      "container_name": "relationships",
      "relationships": {
        "has_person": {
          "targets": [
            "person"
          ]
        }
      }
    },
    {
      "type": "contact_relation",
      "container_name": "relationships",
      "relationships": {
        "my_id": {
          "targets": [
            "person"
          ]
        }
      }
    }
  ]
}
Request bodyapplication/json
1 fields
FieldTypeDescription
classesrequiredobject[]List of classes
typerequiredstringType of class
container_namerequiredstringContainer name
is_deprecatedrequiredbooleanIs deprecated
deprecated_propertiesrequiredstring[]Deprecated properties
propertiesrequiredobjectProperties
relationshipsobjectRelationships
Response 201application/json
1 fields

Lexicon have been accepted to import

FieldTypeDescription
messagestringLexicon have been accepted to import
Response 400application/json
1 fields

Lexicon did not passed validation

FieldTypeDescription
messagestringError message

Embeddings

GET /lexicon/embeddings/smoke

Smoke

smoke

Hello World

Dummy hello world endpoint

Other responses

200

Notifications

DELETE /notifications/configurations

Configure channel webhook

delete_configuration

Delete Configuration

Delete a notification configuration.

Response
application/json

Request data failed validation

{
  "detailedMessage": "Bad request exception"
}
Parameters
1
ParameterTypeExampleDescription
configuration required string query https://hooks.slack.com/services/ABCZXC/B00000000/ABCZXCJWKM The configuration identifier to delete.
Response 400application/json
2 fields

Request data failed validation

FieldTypeDescription
detailedMessagestringMessage
codestringCode
Response 404application/json
1 fields

Requested resource not found

FieldTypeDescription
messagestringMessage
Other responses

204

GET /notifications/configurations

Configure channel webhook

list_configurations

List Configurations

Retrieve a list of notification configurations.

Response
application/json

List of configurations

{
  "configurations": [
    {
      "slack_webhook_url": "https://hooks.slack.com/services/ABCZXC/B00000000/ABCZXCJWKM"
    }
  ]
}
Response 200application/json
1 fields

List of configurations

FieldTypeDescription
configurationsobject[]List of configurations
slack_webhook_urlstringSlack webhook URL
Response 404application/json
1 fields

Requested resource not found

FieldTypeDescription
messagestringMessage
POST /notifications/configurations

Configure channel webhook

create_configuration

Create configuration

Create a new configuration for notifications. Use slack webhook url from to your channel, to use it for getting notifications about deprecated collections in persistence on daily basis.

Request
application/json
{
  "slack_webhook_url": "https://hooks.slack.com/services/ABCZXC/B00000000/ABCZXCJWKM"
}
Response
application/json

Configuration created

{
  "slack_webhook_url": "https://hooks.slack.com/services/ABCZXC/B00000000/ABCZXCJWKM"
}
Request bodyapplication/json
1 fields
FieldTypeDescription
slack_webhook_urlstring (uri)Slack webhook URL
Response 201application/json
1 fields

Configuration created

FieldTypeDescription
slack_webhook_urlstring (uri)Slack webhook URL
Response 400application/json
2 fields

Request data failed validation

FieldTypeDescription
detailedMessagestringMessage
codestringCode
Response 403application/json
1 fields

Missing API key

FieldTypeDescription
messagestringMessage
Other responses

422500

PDFs

POST /pdf-splitter/invocations

Split PDF

split_pdf

Start PDF splitting process. If callback_url was provided in body, this url will be called with POST request, with your x-api-key in headers. If response for this call has non 2XX status code or doesn't respond within 6 sec, requests will be retried during 5 minutes every 2 seconds, You can indicate if you already processed that event, but for some reasons respond with non 2XX code by id parameter. type parameter indicates type of the event.

Show the rest
Event type Description
co.staircase.pdf_split PDF splitting is finished successfully
co.staircase.pdf_split_failed PDF splitting is failed

Event structure is cloudevents, so you can use any tools that supports it or SDK

 {
 "type": "object",
 "$schema": "",
 "properties": {
 "specversion": {
 "type": "string",
 "description": "Version of cloudevents event structure"
 },
 "id": {
 "type": "string",
 "description": "Unique identifier of the event, for retired requests will always be the same"
 },
 "source": {
 "type": "string",
 "description": "Source of the event, for Persistence it will always be co.staircase.persistence",
 "const": "persistence"
 },
 "type": {
 "type": "string",
 "description": "Name of the event, that indicates, what happened",
 "enum": [
 "co.staircase.persistence.pdf_split",
 "co.staircase.persistence.pdf_split_failed"
 ]
 },
 "time": {
 "type": "string",
 "format": "date-time",
 "description": "Timestamp of when the occurrence happened."
 },
 "data": {
 "type": "object",
 "properties": {
 "transaction_id": {
 "type": "string",
 "format": "ulid",
 "description": "Transaction id"
 },
 "response_collection_id": {
 "type": "string",
 "format": "ulid",
 "description": "Collection id"
 },
 "reason": {
 "type": "string",
 "description": "Failure reason"
 }
 }
 }
 }
 }
Request
application/json
{
  "transaction_id": "01G92FSH5FYKQE6X22FECB95V2",
  "collection_id": "01G92FSX8A9YXPAMT6V97TH0VZ"
}
Response
application/json

Accepted.

{
  "collection_id": "01G92FWG135BTEMQC3SSMA8Q7A"
}
Request bodyapplication/json
3 fields
FieldTypeDescription
transaction_idrequiredstringTransaction ID
collection_idrequiredstringCollection ID
optionsobjectOptions
callback_urlstring (url)Callback URL
Response 202application/json
1 fields

Accepted.

FieldTypeDescription
collection_idstringResponse collection ID.
Response 400application/json
1 fields

Request data failed validation

FieldTypeDescription
messageone ofMessage
Response 403application/json
1 fields

Missing API key

FieldTypeDescription
messagestringMessage
Other responses

422

GET /pdf-splitter/invocations

List PDF Splitting jobs

list_pdf_splitting_job

Provides the list of splitting jobs.

Response
application/json

OK.

{
  "invocations": [
    {
      "invocation_id": "01G92FWG135BTEMQC3SSMA8Q7A"
    },
    {
      "invocation_id": "01G92FWG135BTEMQC3SSMA8Q7B"
    },
    {
      "invocation_id": "01G92FWG135BTEMQC3SSMA8Q7C"
    }
  ]
}
Response 200application/json
2 fields

OK.

FieldTypeDescription
invocationsrequiredobject[]Invocations list.
invocation_idstringInvocation ID.
next_tokenstringToken to paginate
Response 400application/json
1 fields

Request data failed validation

FieldTypeDescription
messageone ofMessage
Response 403application/json
1 fields

Missing API key

FieldTypeDescription
messagestringMessage
GET /pdf-splitter/invocations/{invocation_id}

Get PDF Splitting job

get_pdf_splitting_job

Provides the splitting job information.

Response
application/json

OK.

{
  "invocations": [
    {
      "invocation_id": "01G92FWG135BTEMQC3SSMA8Q7A"
    },
    {
      "invocation_id": "01G92FWG135BTEMQC3SSMA8Q7B"
    },
    {
      "invocation_id": "01G92FWG135BTEMQC3SSMA8Q7C"
    }
  ]
}
Parameters
1
ParameterTypeExampleDescription
invocation_id required string path 12345 Invocation ID
Response 200application/json
5 fields

OK.

FieldTypeDescription
statusrequiredstringJob statusABORTEDFAILEDRUNNINGSUCCEEDEDTIMED_OUT
inputrequiredobjectJob input.
documentsobject[]Input documents
blob_idstringBlob ID
callback_urlstring (url)Callback URL
transaction_idrequiredstringTransaction ID
collection_idrequiredstringCollection ID
started_atrequiredstring (date-time)Datetime when job was started in iso-format.
Response 403application/json
1 fields

Missing API key

FieldTypeDescription
messagestringMessage
Response 404application/json
1 fields

Requested resource not found

FieldTypeDescription
messagestringMessage

Search

GET /search/indexes

Get Search Indexes

get_search_indexes

Get indexes

This function retrieves list of indexes and their statuses. You can specify index_name parameter in query parameters and retrieve the status of particular index, indicating whether it is currently active and available for querying.

Response
application/json

queried

[
  {
    "Options": {
      "IndexFieldName": "name",
      "IndexFieldType": "text-array"
    },
    "Status": {
      "CreationDate": "2023-04-03T01:02:06.541Z",
      "UpdateDate": "2023-04-03T01:02:06.541Z",
      "UpdateVersion": 1,
      "State": "Active",
      "PendingDeletion": false
    }
  }
]
Parameters
1
ParameterTypeExampleDescription
index_name string query name Name of the index
Response 400application/json
2 fields

Request data failed validation

FieldTypeDescription
detailedMessagestringMessage
codestringException Code
Response 403application/json
1 fields

Missing API key

FieldTypeDescription
messagestringMessage
Response 404application/json
1 fields

Requested resource not found

FieldTypeDescription
messagestringMessage
Other responses

200422500

POST /search/indexes

Create Search Index

create_search_index

Create index

To create an index with text fields for indexing, you need to provide a request body in JSON format with the specified index_name. After creating the index, the status will initially be Processing. Only when the status changes to Active, the newly added field will be available for querying and uploading new documents. However, please note that the new field will not be indexed for previously added documents. It's also important to note that there is a quota of 200 indexing fields.

Request
application/json
{
  "index_name": "addresses/has_state_code/has_value"
}
Response
application/json

queried

{
  "IndexField": {
    "Status": {
      "CreationDate": "2023-04-03T01:02:06.541Z",
      "UpdateDate": "2023-04-03T01:02:06.541Z",
      "State": "Active"
    }
  }
}
Request bodyapplication/json
1 fields
FieldTypeDescription
index_namerequiredstringName of the indexExample name
Response 200application/json
1 fields

queried

FieldTypeDescription
IndexFieldobjectIndex field
StatusobjectStatus
CreationDatestringCreation dateExample 2023-04-03T01:02:06.541Z
UpdateDatestringUpdate dateExample 2023-04-03T01:02:06.541Z
StatestringStateActiveFailedToValidateProcessingRequiresIndexDocumentsExample Active
Response 400application/json
2 fields

Request data failed validation

FieldTypeDescription
detailedMessagestringMessage
codestringException Code
Response 403application/json
1 fields

Missing API key

FieldTypeDescription
messagestringMessage
Response 409application/json
1 fields

Conflict

FieldTypeDescription
messagestringMessage
Other responses

422500

POST /search/query

Query

perform_search_query

To search for a value in a field using fuzzy search, follow these guidelines:

  • If the value you provide contains a single word, fuzzy search will be performed based on the Levenshtein Distance with this word. This means that the search will return results that contains the word you provided, but with minor spelling variations due to insertions, deletions, or substitutions of characters.
  • If the value you provide is a phrase, separated with spaces, proximity search will be performed. This means that the search will return results that contain the words in your phrase in proximity to each other. The proximity between words is defined by a maximum number of words that can occur between them in the searched field. Optionally, you can also specify a latest_transaction_collection flag, which will return only the latest transaction collection for each result. This is useful when you want to get the latest transaction collection for each result, but don't want to perform a separate query for each result.
Request
application/json
{
  "fields": [
    {
      "field": "addresses/has_state_name/has_value",
      "value": "CA",
      "distance": 10,
      "weight": 0.5
    }
  ]
}
Response
application/json

Queried response

[
  {
    "transaction_id": "01GV5S3SYTEX8QSVEWSPVQHNQS",
    "score": 0.95,
    "collection_id": "01GV5S40XNZ47YYASFRE78GXW1"
  }
]
Request bodyapplication/json
3 fields
FieldTypeDescription
fieldsrequiredobject[]List of fields to query
fieldstringField to queryExample addresses/has_state_code/has_value
valuestringValue to queryExample CA
distancenumberDistance to queryExample 10
weightnumberWeight to queryExample 0.5
latest_transaction_collectionbooleanWhether to query the latest transaction collection. If true, results will only contain transaction/collection ID pairs where the collection is the latest in its transaction. Default is false.Example true
transaction_labelstringWhen this parameter is set, the search results will only include transactions that have the specified transaction label.Example my_label
Response 200application/json
3 fields

Queried response

FieldTypeDescription
transaction_idstringTransaction_id of the resultExample 01GV5S3SYTEX8QSVEWSPVQHNQS
scorenumberScore of the resultExample 0.95
collection_idstringCollection_id of the resultExample 01GV5S40XNZ47YYASFRE78GXW1
Response 400application/json
2 fields

Request data failed validation

FieldTypeDescription
detailedMessagestringMessage
codestringException Code
Response 403application/json
1 fields

Missing API key

FieldTypeDescription
messagestringMessage
Other responses

422500

SUG

POST /sug/{container_name}

Create Item

create_item

Add item to specified container

Endpoint to add an item to a specified container in the Staircase Universal Graph. The 'item' object in request must include the '@type' property and may also include the '@id' property. If the '@id' property is not provided, it will be generated automatically. The 'item' object may also include any additional properties, which will be added to the item. A successful request will return a JSON object containing the 'item' object with '@id', '@type', and any additional properties of the created item.

Request
application/json
{
  "item": {
    "@type": "Address",
    "street": "123 Main St",
    "city": "Anytown",
    "state": "CA",
    "zip": 12345
  }
}
Response
application/json

Created item successfully

{
  "item": {
    "@id": "1234567890",
    "@type": "Address",
    "street": "123 Main St",
    "city": "Anytown",
    "state": "CA",
    "zip": 12345
  }
}
Parameters
1
ParameterTypeExampleDescription
container_name required string path addresses Name of the container where the item will be added
Request bodyapplication/json
1 fields
FieldTypeDescription
itemobjectItem that was created
@idstringID of the created item
@typestringType of the created item
Response 201application/json
1 fields

Created item successfully

FieldTypeDescription
itemrequiredobjectItem that was created
@idstringID of the created item
@typestringType of the created item
Response 400application/json
2 fields

Request data failed validation

FieldTypeDescription
detailedMessagestringMessage
codestringCode
Response 403application/json
1 fields

Missing API key

FieldTypeDescription
messagestringMessage
Response 404application/json
1 fields

Requested resource not found

FieldTypeDescription
messagestringMessage
Response 409application/json
1 fields

Conflict

FieldTypeDescription
messagestringMessage
Other responses

422500

GET /sug/items/{id}

Get Item

get_item

Get item in Staircase Universal Graph

Endpoint to get an item in the Staircase Universal Graph. A successful request will return a JSON object containing the 'item' object with '@id', '@type', and properties of the item

Response
application/json

Get item successfully

{
  "item": {
    "@id": "1234567890",
    "@type": "Address",
    "street": "123 Main St",
    "city": "Anytown",
    "state": "CA",
    "zip": 12345
  },
  "container_name": "addresses"
}
Parameters
2
ParameterTypeExampleDescription
id required string path AJXZ159292 Id of the item to get
id required string path AJXZ159292 Id of the item to get
Response 200application/json
2 fields

Get item successfully

FieldTypeDescription
itemrequiredobjectItem that was created
@idstringID of the created item
@typestringType of the created item
container_namestringName of the containerExample container_name
Response 400application/json
2 fields

Request data failed validation

FieldTypeDescription
detailedMessagestringMessage
codestringCode
Response 403application/json
1 fields

Missing API key

FieldTypeDescription
messagestringMessage
Response 404application/json
1 fields

Requested resource not found

FieldTypeDescription
messagestringMessage
Other responses

422500

POST /sug/bulk-upload

Bulk Upload

bulk_upload

Bulk Upload items in Staircase Universal Graph

Endpoint to bulk upload items to the Staircase Universal Graph.

The 'items' object in request must include the '@type' property and may also include the '@id' property.

For all the items - if the @id property is not provided, it will be generated and set. Otherwise, if the item's @type is neither transaction or collection, the @id will be replaced with a newly generated one with keeping all the relationships in other items.

If some property of the item is a relationship and it contains the value which is not an @id of any item in the same request, this values will not be changed because it is considered as an @id of the existing item in the graph.

The 'items' object may also include any additional properties, which will be added to the item.

A successful request will return a JSON object containing:

  • the upload_id which could be used to check the status of the upload.
  • the items array of completed items.
Request
application/json
{
  "items": [
    {
      "@type": "person",
      "@id": "01GYSJNDZMZB37TNTWY8KVVSSC",
      "first_name": "John",
      "last_name": "Doe"
    },
    {
      "@type": "address",
      "@id": "01GYSVT1BCQHEFDY86FKGGX8PD",
      "city": "LA"
    },
    {
      "@type": "person_address_relation",
      "@id": "01GYSW9BAD87KKQM7F0GYK1AG3",
      "has_address": "01GYSVT1BCQHEFDY86FKGGX8PD",
      "has_person": "01GYSJNDZMZB37TNTWY8KVVSSC"
    }
  ]
}
Response
application/json

Created item successfully

{
  "upload_id": "1234567890"
}
Request bodyapplication/json
2 fields
FieldTypeDescription
itemsrequiredarrayArray of items to be uploaded
reassigned_idsbooleanFlag to reassign ids for items with existing ids. USE ONLY IF NEEDED.
Response 202application/json
1 fields

Created item successfully

FieldTypeDescription
upload_idstringId of the upload
Response 400application/json
2 fields

Request data failed validation

FieldTypeDescription
detailedMessagestringMessage
codestringCode
Response 403application/json
1 fields

Missing API key

FieldTypeDescription
messagestringMessage
Response 404application/json
1 fields

Requested resource not found

FieldTypeDescription
messagestringMessage
Response 409application/json
1 fields

Conflict

FieldTypeDescription
messagestringMessage
Other responses

422500

GET /sug/bulk-upload/{upload_id}

Check Bulk Upload

get_bulk_upload

Check Bulk Upload Status

Endpoint to check the status of a bulk upload to the Staircase Universal Graph. A successful request will return a JSON object containing the upload_id and status of the upload.

Response
application/json

Created item successfully

{
  "upload_id": "1234567890",
  "status": "COMPLETED"
}
Parameters
1
ParameterTypeExampleDescription
upload_id required string path 1234567890 Id of the upload
Response 200application/json
2 fields

Created item successfully

FieldTypeDescription
upload_idstringId of the upload
statusstringStatus of the uploadCOMPLETEDFAILEDIN_PROGRESS
Response 400application/json
2 fields

Request data failed validation

FieldTypeDescription
detailedMessagestringMessage
codestringCode
Response 403application/json
1 fields

Missing API key

FieldTypeDescription
messagestringMessage
Response 404application/json
1 fields

Requested resource not found

FieldTypeDescription
messagestringMessage
Response 409application/json
1 fields

Conflict

FieldTypeDescription
messagestringMessage
Other responses

422500

POST /sug/construct

Construct data query

construct_data_query

This endpoint provides an advanced items data querying mechanism that supports filtering conditions, nested relationships, aggregation, and pagination. It generates SPARQL query language to fetch data from a persistence graph database. You can specify types, properties, optional properties, and conditions along with optional fields like relations, aggregate functions, and grouping. You can specify item properties as ["*"] to include all properties. Supported conditions functions are: eq, in, ne, gt, lt, gte, lte, contains. Relationships are defined in a list of dictionaries, each containing the type, name, properties, conditions, and any nested relations. Aggregation supports simple functions like 'max', 'min', "count", etc. on specific attributes. In addition to this, you can opt for echo functionality which would return the SPARQL query used for the data fetch.

Request
application/json
{
  "type": "person",
  "properties": [
    "first_name",
    "last_name"
  ]
}
Response
application/json

Succeeded

{
  "items": [
    {
      "@id": "01H7AAJJP33QV8V7EAG26MYZP1",
      "@type": "person",
      "first_name": "Leo",
      "last_name": "Messi",
      "person_identifier": "5ba3cf68-0eba-4011-a70b-a47899c2f986",
      "email": "messi@domain.com",
      "earns": {
        "@id": "01H7AAMTBJHDS4CB38PVZ62VCW",
        "@type": "income",
        "annual_income": 50001,
        "bonus_income_amount": 200,
        "income_identifier": "3b317e55-3614-4e97-b2df-e117b8834197"
      }
    }
  ],
  "pagination": {
    "limit": 10,
    "next_token": "39373833613763612d363461662d346231342d383035372d393535346138323363646337"
  }
}
Request bodyapplication/json
9 fields
FieldTypeDescription
typestringType of the main object you're constructing.Example person
propertiesstring[]Properties to include for each main object. Use * to include all properties.
optional_propertiesstring[]Optional properties to include for each main object. You can add property from properties parameter here to mark it as optional.
conditionsobjectConditions for filtering the main objects. Key-value pairs define the attribute and its condition.
relationsobject[]Array of relation objects to include related items in the output.
group_bystringAttribute to group the results by.Example first_name
aggregateobjectAggregation function to apply on the grouped results.
paginationobjectPagination options, including limit for paginated responses.
echobooleanEcho the SPARQL query used for the data fetch.
Response 200application/json
3 fields

Succeeded

FieldTypeDescription
itemsobject[]An array of item objects along with their relationship data.
@idstringThe unique identifier of item.
paginationobjectPagination metadata for the list of items.
limitintegerThe number of items returned per page.
next_tokenintegerToken to get the next set of items.
querystringThe SPARQL query used for the data fetch.
Response 400application/json
2 fields

Request data failed validation

FieldTypeDescription
detailedMessagestringMessage
codestringCode
Response 403application/json
1 fields

Missing API key

FieldTypeDescription
messagestringMessage
Response 404application/json
1 fields

Requested resource not found

FieldTypeDescription
messagestringMessage
Response 409application/json
1 fields

Conflict

FieldTypeDescription
messagestringMessage
Other responses

422500

GET /sug/{container_name}

List Items

List Items

List items of specified container

Endpoint to list items of a specified container in the Staircase Universal Graph. A successful request will return an array of objects containing the property 'item' with an object with '@id', '@type', and any additional properties of item.

Response
application/json

Succeeded

{
  "item": {
    "@id": "1234567890",
    "@type": "Address",
    "street": "123 Main St",
    "city": "Anytown",
    "state": "CA",
    "zip": 12345
  },
  "version": 1
}
Parameters
6
ParameterTypeExampleDescription
container_name required string path addresses Container name
filter string query first_name+eq+John Filter to query items in container to be returned. Supported operations - eq, ne, gt, lt, gte, lte, startswith, endswith, contains.
group_by string query person_identifier Property to group items by for aggregation. Should be a property name, valid for this container or @type or @id.
agg_func string query max+@id Aggregation for group_by property. Should be in format `{func}+{field}`. Available functions are: min, max, sample.
limit string query 123456789 Number of items to return. Default is 100.
sort string query asc Direction of sorting by '@id'. Default is 'desc'.
Response 200application/json
3 fields

Succeeded

FieldTypeDescription
itemsrequiredarrayRequested items
_linksrequiredobjectLinks to other resources
nextstringLink to next page of resultsExample https://api.staircaseapi.com/persistence/sug/addresses?filter=first_name+eq+John&next_token=123456789
previousstringLink to previous page of resultsExample https://api.staircaseapi.com/persistence/sug/addresses?filter=first_name+eq+John&next_token=123456789
next_tokenstringToken to retrieve next page of resultsExample 123456789
Response 400application/json
2 fields

Request data failed validation

FieldTypeDescription
detailedMessagestringMessage
codestringCode
Response 403application/json
1 fields

Missing API key

FieldTypeDescription
messagestringMessage
Response 404application/json
1 fields

Requested resource not found

FieldTypeDescription
messagestringMessage
PATCH /sug/items/{id}

Update Item

update_itemNew

Update item in Staircase Universal Graph

The API will create RDF triples with the predicate sc:has_data pointing to the new properties of the updated item. The API will create RDF triples with the predicate sc:has_target pointing to the new item representing the previous version. Consistency is ensured by making sure the RDF triples for sc:has_data and sc:has_target accurately reflect the versions, ensuring the current item points to the updated properties and the new versioned item represents the previous state. Item @id or @type can not be updated. If value of a field is null, the field will be removed from the item.

Request
application/json
{
  "item": {
    "street": "123 Main St",
    "city": "Anytown",
    "state": "CA",
    "zip": 12345
  }
}
Response
application/json

Created item successfully

{
  "status": "success",
  "message": "Item updated successfully and previous version created.",
  "updated_item": {
    "@id": "AJXZ159292",
    "@type": "Address",
    "street": "123 Main St",
    "city": "Anytown",
    "state": "CA",
    "zip": 12345
  },
  "versioned_item": {
    "@id": "AJXZ159292_v1",
    "@type": "Address",
    "street": "456 Old St",
    "city": "Oldtown",
    "state": "CA",
    "zip": 67890,
    "sc:version": 1
  }
}
Parameters
1
ParameterTypeExampleDescription
id required string path AJXZ159292 Id of the item to get
Request bodyapplication/json
1 fields
FieldTypeDescription
itemobjectItem data to update
Response 200application/json
4 fields

Created item successfully

FieldTypeDescription
statusstringStatus of the updateExample success
messagestringMessageExample Item updated successfully and previous version created.
updated_itemobjectItem that was created
@idstringID of the created item
@typestringType of the created item
versioned_itemobjectItem that was created
@idstringID of the created item
@typestringType of the created item
Response 400application/json
2 fields

Request data failed validation

FieldTypeDescription
detailedMessagestringMessage
codestringCode
Response 403application/json
1 fields

Missing API key

FieldTypeDescription
messagestringMessage
Response 404application/json
1 fields

Requested resource not found

FieldTypeDescription
messagestringMessage
Other responses

422500

Transactions

POST /transactions

Create Transaction

create_transaction

Create empty transaction You can subscribe to all changes inside transaction by providing callback_url in body, and you will receive POST request to this url, with your x-api-key in headers. If you respond with a non 2XX status code or not within 6 sec, requests will be retried during 5 minutes every 2 seconds, you can indicate if you already processed that event, but for some reasons respond with non 2XX code by id parameter. type parameter indicates type of the event.

Show the rest
Event type Description
co.staircase.persistence.collection_created New collection was created
co.staircase.persistence.collection_data_inserted Data was added to collection
co.staircase.persistence.collection_metadata_updated Metadata of collection was updated
co.staircase.persistence.collection_updated Both metadata and data of collection was updated

Event structure is cloudevents, so you can use any tools that supports it or SDK

 {
 "type": "object",
 "$schema": "",
 "properties": {
 "specversion": {
 "type": "string",
 "description": "Version of cloudevents event structure"
 },
 "id": {
 "type": "string",
 "description": "Unique identifier of the event, for retired requests will always be the same"
 },
 "source": {
 "type": "string",
 "description": "Source of the event, for Persistence it will always be co.staircase.persistence",
 "const": "persistence"
 },
 "type": {
 "type": "string",
 "description": "Name of the event, that indicates, what happened",
 "enum": [
 "co.staircase.persistence.collection_created",
 "co.staircase.persistence.collection_data_inserted",
 "co.staircase.persistence.collection_metadata_updated",
 "co.staircase.persistence.collection_updated"
 ]
 },
 "time": {
 "type": "string",
 "format": "date-time",
 "description": "Timestamp of when the occurrence happened."
 },
 "data": {
 "type": "object",
 "properties": {
 "transaction_id": {
 "type": "string",
 "format": "ulid",
 "description": "Transaction id"
 },
 "collection_id": {
 "type": "string",
 "format": "ulid",
 "description": "Collection id"
 },
 "collection": {
 "type": "object",
 "description": "Collection itself"
 }
 }
 }
 }
 }

You can assign label to transaction by providing label field. To search for transaction using label you should use Retrieve List of Transactions endpoint You can provide an trace ID to the transaction by providing x-sc-trace-id header or query parameter. If trace ID is not provided, it will be generated automatically. Created transaction guarantees that trace ID will be present in the response header named x-sc-trace-id.

Request
application/json
{
  "label": "first_transaction"
}
Response
application/json

Transaction have been created

{
  "transaction_id": "01EZQ32PJQGKRA6HR8D72Q9FFF",
  "created_at": "2024-03-29T05:32:11.731227-04:00"
}
Parameters
2
ParameterTypeExampleDescription
x-sc-trace-id string query 01FJCADX5QEXEDVRWNXAK206MA Trace ID of the transaction
x-sc-trace-id required string header 01FJCADX5QEXEDVRWNXAK206MA Trace ID of the transaction
Request bodyapplication/json
2 fields
FieldTypeDescription
callback_urlstring (url)URL for receiving events about changes inside transaction
labelstringTransaction label
Response 201application/json
5 fields

Transaction have been created

FieldTypeDescription
transaction_idstring (ulid)Transaction idExample 01EZQ32PJQGKRA6HR8D72Q9FFF
created_atstringDatetime, when transaction was created
callback_urlstringCallback url
labelstringTransaction label
_linksobjectLinks
collectionsstring (url)Link to transaction collections
Response 400application/json
1 fields

Request data failed validation

FieldTypeDescription
messageone ofMessage
Response 403application/json
1 fields

Missing API key

FieldTypeDescription
messagestringMessage
Response 429application/json
1 fields

The user has sent too many requests in a given amount of time ("rate limiting")

FieldTypeDescription
messagestringMessage
GET /transactions/{transaction_id}

Retrieve Transaction

get_transaction

Retrieve transaction

Response
application/json

Transaction

{
  "transaction_id": "01EZQ32PJQGKRA6HR8D72Q9FFF",
  "created_at": "2024-03-29T05:32:11.731227-04:00"
}
Parameters
2
ParameterTypeExampleDescription
transaction_id required string (ulid) path 01FJCADX5QEXEDVRWNXAK206MA Transaction ID
x-sc-trace-id required string header 01FJCADX5QEXEDVRWNXAK206MA Trace ID of the transaction
Response 200application/json
5 fields

Transaction

FieldTypeDescription
transaction_idstring (ulid)Transaction idExample 01EZQ32PJQGKRA6HR8D72Q9FFF
created_atstringDatetime, when transaction was created
callback_urlstringCallback url
labelstringTransaction label
_linksobjectLinks
collectionsstring (url)Link to transaction collections
Response 400application/json
1 fields

Request data failed validation

FieldTypeDescription
messageone ofMessage
Response 403application/json
1 fields

Missing API key

FieldTypeDescription
messagestringMessage
Response 404application/json
1 fields

Requested resource not found

FieldTypeDescription
messagestringMessage
Response 429application/json
1 fields

The user has sent too many requests in a given amount of time ("rate limiting")

FieldTypeDescription
messagestringMessage
GET /transactions/{transaction_id}/data

Retrieve Transaction Data

get_transaction_data

Retrieve transaction data

Merge data from all collections of transaction. Data will be merged, assuming, that borrower from every collection is the same borrower

Response
application/json

Request data failed validation

{
  "message": "{'data': ['Missing data for required field.']}"
}
Parameters
6
ParameterTypeExampleDescription
transaction_id required string (ulid) path 01FJCADX5QEXEDVRWNXAK206MA Transaction ID
collection_ids string query 01FEP1VDZE6BQ1Q4X52JNPE2X4,01FEP1VPG7WJVQ3F8B3Y9J2NX8 List of collection ids, that you want to be merged.
types_to_merge string query borrower,loan Types for merge
save_to_collection boolean query false Indicates if output should be saved to collection
staircase_version integer query 3 Version of Staircase language for collections to be merged. Collections, that are not of this version will be filtered out
x-sc-trace-id required string header 01FJCADX5QEXEDVRWNXAK206MA Trace ID of the transaction
Response 200application/json
4 fields

Transaction Data

FieldTypeDescription
transaction_idstring (ulid)Transaction idExample 01EZQ32PJQGKRA6HR8D72Q9FFF
collection_idstring (ulid)Collection idExample 01EZQ32PJQGKRA6HR8D72Q9FFF
dataobjectData in Staircase language schema
metadataobjectMetadata about collection, f.e version of used Staircase schema. Maximum allowable length of the dumped json object - 400 000 symbols.
Response 400application/json
1 fields

Request data failed validation

FieldTypeDescription
messageone ofMessage
Response 403application/json
1 fields

Missing API key

FieldTypeDescription
messagestringMessage
Response 404application/json
1 fields

Requested resource not found

FieldTypeDescription
messagestringMessage
Response 429application/json
1 fields

The user has sent too many requests in a given amount of time ("rate limiting")

FieldTypeDescription
messagestringMessage
Other responses

422

GET /transactions/{transaction_id}/data/{merge_id}

Retrieve Merge

retrieve_merge

Retrieve merge status

Retrieve status of async merge transaction operation for a given merge ID.

Response
application/json

Request data failed validation

{
  "message": "{'data': ['Missing data for required field.']}"
}
Parameters
3
ParameterTypeExampleDescription
transaction_id required string (ulid) path 01FJCADX5QEXEDVRWNXAK206MA Transaction ID
merge_id required string (ulid) path 01FJCADX5QEXEDVRDX5QEXEDVR Merge ID
x-sc-trace-id required string header 01FJCADX5QEXEDVRWNXAK206MA Trace ID of the transaction
Response 200application/json
5 fields

Merge status

FieldTypeDescription
merge_idstringMerge ID
statusstringMerge status
transaction_idstringTransaction ID
errorstringError message if present
response_collection_idstringCollection ID of merged data
Response 400application/json
1 fields

Request data failed validation

FieldTypeDescription
messageone ofMessage
Response 403application/json
1 fields

Missing API key

FieldTypeDescription
messagestringMessage
Response 404application/json
1 fields

Requested resource not found

FieldTypeDescription
messagestringMessage
Response 429application/json
1 fields

The user has sent too many requests in a given amount of time ("rate limiting")

FieldTypeDescription
messagestringMessage
Other responses

422

GET /transactions

Retrieve List of Transactions

retrieve_transactions

Retrieve transactions

Retrieve list of transactions. Transactions can be filtered by transaction_id or created_at fields. Supported operations per fields:

  • transaction_id:
  • in:
  • description: Get only transactions with specified ids
  • example: transaction_id+in+01EZQ32PJQGKRA6HR8D72Q9FFF,01EZQ32NZ34WACWSAF54WGEM51
  • created_at:
  • gt:
  • description: Get transactions, that was created after specified datetime in ISO format
  • example: created_at+gt+2021-03-30T04:27:15.372006-04:00
  • lt:
  • description: Get transactions, that was created before specified datetime in ISO format
  • example: created_at+lt+2021-03-30T04:27:15.372006-04:00
  • label:
  • eq:
  • description: Get transactions where label equals provided value
  • example: label+eq+byte-efb91c0c-e8d7-4bd5-a25c-07bdf58f3182
Response
application/json

Request data failed validation

{
  "message": "{'data': ['Missing data for required field.']}"
}
Parameters
6
ParameterTypeExampleDescription
filter string query transaction_id+in+01EZQ32PJQGKRA6HR8D72Q9FFF,01EZQ32NZ34WACWSAF54WGEM51 Filter expression in format {field_name}+{operation}+{value}
sort string query asc Order of sorting
limit number query 5 Amount of items to show
after_id string query 01EZQ32PJQGKRA6HR8D72Q9FFF id of last evaluated transaction
include_collections boolean query false If true, transaction collections will be included to the response body.
x-sc-trace-id required string header 01FJCADX5QEXEDVRWNXAK206MA Trace ID of the transaction
Response 200application/json
1 fields

List of transactions

FieldTypeDescription
transactionsobject[]List of transactions
transaction_idstringTransaction id
created_atstringDatetime, when transaction was created
collectionsarrayList of collections created inside transaction
Response 400application/json
1 fields

Request data failed validation

FieldTypeDescription
messageone ofMessage
Response 403application/json
1 fields

Missing API key

FieldTypeDescription
messagestringMessage
Response 404application/json
1 fields

Requested resource not found

FieldTypeDescription
messagestringMessage
Response 429application/json
1 fields

The user has sent too many requests in a given amount of time ("rate limiting")

FieldTypeDescription
messagestringMessage
POST /transactions/{transaction_id}/data

Merge transaction

post_transaction_data

Retrieve transaction data

Merge data from all collections of the transaction as well as collections data provided in the body. Data will be merged, assuming that every collection borrower is the same. Merging works only with collections with "version": 2 in metadata, else it skips the collection without this parameter. You can specify async parameter to run the merge in asynchronous way and specify callback_url to receive the result in cloudevents format.

Request
application/json
{
  "merge_transaction_collections": false,
  "collection_ids": [
    "01FDF10040SA2VTETKJQXJ3MQZ",
    "01FJCADX5QEXEDVRWNXAK206MA"
  ],
  "staircase_version": 3,
  "types_to_merge": [
    "borrower",
    "address"
  ],
  "raw_collections": [
    {
      "metadata": {
        "version": 2,
        "validation": true
      },
      "data": {
        "people": [
          {
            "@type": "borrower",
            "@id": "01FDF04MYHEZ98AD7T8ZGY5CMB",
            "has_first_name": {
              "has_value": "John"
            },
            "has_last_name": {
              "has_value": "Deere"
            },
            "has_birth_date": {
              "has_value": "1985-01-01"
            },
            "has_taxpayer_identifier_value": {
              "has_value": "999-00-0000"
            },
            "contact_at": [
              "01FDF09BNQCT03DCAX7M5KM52T"
            ],
            "employed_as": [
              "01FDF0DFYAHBRJGFA5RS26HVP1"
            ]
          }
        ],
        "addresses": [
          {
            "@id": "01FDF077N6V7R2RNC64DGT31DY",
            "@type": "business_address",
            "has_address_line_1_text": {
              "has_value": "33 IRVING PLACE",
              "data_sourced_from": [
                "01FDF10040SA2VTETKJQXJ3MQZ"
              ]
            },
            "has_address_line_2_text": {
              "has_value": "additional_line_text",
              "data_sourced_from": [
                "01FDF10040SA2VTETKJQXJ3MQZ"
              ]
            },
            "has_city_name": {
              "has_value": "NEW YORK",
              "data_sourced_from": [
                "01FDF10040SA2VTETKJQXJ3MQZ"
              ]
            },
            "has_postal_code": {
              "has_value": "10003",
              "data_sourced_from": [
                "01FDF10040SA2VTETKJQXJ3MQZ"
              ]
            },
            "has_country_name": {
              "has_value": "US",
              "data_sourced_from": [
                "01FDF10040SA2VTETKJQXJ3MQZ"
              ]
            }
          }
        ],
        "contact_information": [
          {
            "@type": "contact_information",
            "@id": "01FDF09BNQCT03DCAX7M5KM52T",
            "has_phone_number": {
              "has_value": "+1234567890"
            }
          }
        ],
        "employment": [
          {
            "@type": "employment",
            "@id": "01FDF0DFYAHBRJGFA5RS26HVP1",
            "has_employment_position_description": {
              "has_value": "Engineer",
              "data_sourced_from": [
                "01FDF10040SA2VTETKJQXJ3MQZ"
              ]
            },
            "provided_by": [
              "01FDF0G4BP9AE6B7FT5VDEWK5F"
            ]
          }
        ],
        "organizations": [
          {
            "@type": "organization",
            "@id": "01FDF0G4BP9AE6B7FT5VDEWK5F",
            "has_organization_name": {
              "has_value": "GRAIN PROCESSING COR",
              "data_sourced_from": [
                "01FDF10040SA2VTETKJQXJ3MQZ"
              ]
            },
            "with_address": [
              "01FDF077N6V7R2RNC64DGT31DY"
            ]
          }
        ],
        "mortgage_products": [
          {
            "@type": "employment",
            "@id": "01FDF10040SA2VTETKJQXJ3MQZ",
            "has_data_source_date": {
              "has_value": "1972-01-01"
            },
            "has_purpose_of_verification_description": {
              "has_value": "risk-assessment"
            }
          }
        ],
        "documents": [
          {
            "@type": "irs_w2",
            "@id": "01FS9VK2BVSBZYN0MMYQQ73KAZ",
            "has_staircase_document_category_type": {
              "has_value": "sc_core"
            },
            "has_document_description": {
              "has_value": "Employment Verification Report prepared by Staircase"
            },
            "has_document_mime_type": {
              "has_value": "application/pdf"
            },
            "has_document_name": {
              "has_value": "01FD9X8V5N804Y0CFWY7F72ZCD.pdf"
            }
          }
        ]
      }
    }
  ]
}
Response
application/json

Request data failed validation

{
  "message": "{'data': ['Missing data for required field.']}"
}
Parameters
2
ParameterTypeExampleDescription
transaction_id required string (ulid) path 01FJCADX5QEXEDVRWNXAK206MA Transaction ID
x-sc-trace-id required string header 01FJCADX5QEXEDVRWNXAK206MA Trace ID of the transaction
Request bodyapplication/json
7 fields
FieldTypeDescription
raw_collectionsarrayList of collections created inside transaction
collection_idsstring[]List of Collection IDs to be merged
types_to_mergestring[]List of Types to be merged
staircase_versionintegerVersion of Staircase language for collections to be merged. Collections, that are not of this version will be filtered out
merge_transaction_collectionsbooleanIf `true`, existing transaction collections will be included in merge
asyncbooleanIf `true`, merge will be performed asynchronously
callback_urlstring (uri)URL to which the callback will be sent if `async` is `true`
Response 201application/json
4 fields

Transaction Data

FieldTypeDescription
transaction_idstring (ulid)Transaction idExample 01EZQ32PJQGKRA6HR8D72Q9FFF
collection_idstring (ulid)Collection idExample 01EZQ32PJQGKRA6HR8D72Q9FFF
dataobjectData in Staircase language schema
metadataobjectMetadata about collection, f.e version of used Staircase schema. Maximum allowable length of the dumped json object - 400 000 symbols.
Response 202application/json
2 fields

Merge transaction collections request accepted

FieldTypeDescription
merge_idstringMerge ID
statusstringMerge status
Response 400application/json
1 fields

Request data failed validation

FieldTypeDescription
messageone ofMessage
Response 403application/json
1 fields

Missing API key

FieldTypeDescription
messagestringMessage
Response 404application/json
1 fields

Requested resource not found

FieldTypeDescription
messagestringMessage
Response 429application/json
1 fields

The user has sent too many requests in a given amount of time ("rate limiting")

FieldTypeDescription
messagestringMessage
Other responses

422

POST /transactions/merge

Merge Transactions

merge_transactions

Merge transactions into one transaction. This endpoint will merge all transactions into one transaction. All collections from transactions will be moved to new transaction. If you want to merge specific collections, you can use collections field. Only collections, that has version 3 and are validated using metadata.validation = true, can be merged. This API can merge up to 1000 collections.

Request
application/json
{
  "transaction_ids": [
    "01FJCADX5QEXEDVRWNXAK206MA",
    "01FJCAQW7EYJAA6FY05WRKRM3T"
  ]
}
Response
application/json

New merged transaction

{
  "transaction_id": "01FJCADX5QEXEDVRWNXAK206MA",
  "created_at": "2024-03-29T05:32:11.731227-04:00",
  "label": null,
  "callback_url": null,
  "_links": {
    "collections": "https://documentation.straircaseapi.com/transactions/01FJCADX5QEXEDVRWNXAK206MA/collections"
  }
}
Request bodyapplication/json
2 fields
FieldTypeDescription
transaction_idsrequiredstring[]Transaction ids
collectionsobject[]Collections to merge into one transaction
transaction_idstring (ulid)Transaction id
collection_idstring (ulid)Collection id
Response 200application/json
5 fields

New merged transaction

FieldTypeDescription
transaction_idstring (ulid)Transaction idExample 01EZQ32PJQGKRA6HR8D72Q9FFF
created_atstringDatetime, when transaction was created
callback_urlstringCallback url
labelstringTransaction label
_linksobjectLinks
collectionsstring (url)Link to transaction collections
Response 400application/json
1 fields

Request data failed validation

FieldTypeDescription
messageone ofMessage
Response 403application/json
1 fields

Missing API key

FieldTypeDescription
messagestringMessage
Response 404application/json
1 fields

Requested resource not found

FieldTypeDescription
messagestringMessage
Response 429application/json
1 fields

The user has sent too many requests in a given amount of time ("rate limiting")

FieldTypeDescription
messagestringMessage
Other responses

422

Collections

POST /transactions/{transaction_id}/collections

Create Collection

create_collection

Create Collection. Collection data can be validated by setting validation flag to true and version in metadata. To validate version 2 Language is required to be installed on the environment. To validate version 3 Persistence Graph is required to be installed on the environment. Collections by default are saved to Persistence Graph. Collections created with version 2 or 3 of Staircase lexicon are dumped according to the version of Staircase lexicon. Collections created with version 0 of Staircase lexicon are dumped with prefix ``"

Request
application/json
{
  "metadata": {
    "version": 2,
    "validation": true,
    "linked_collections": [
      {
        "collection_id": "01EZQ32PJQGKRA6HR8D72Q9FFF",
        "label": "Employment Verification Report"
      }
    ]
  },
  "data": {
    "people": [
      {
        "@type": "borrower",
        "@id": "01FDF04MYHEZ98AD7T8ZGY5CMB",
        "has_first_name": {
          "has_value": "John"
        },
        "has_last_name": {
          "has_value": "Deere"
        },
        "has_birth_date": {
          "has_value": "1985-01-01"
        },
        "has_taxpayer_identifier_value": {
          "has_value": "999-00-0000"
        },
        "contact_at": [
          "01FDF09BNQCT03DCAX7M5KM52T"
        ],
        "employed_as": [
          "01FDF0DFYAHBRJGFA5RS26HVP1"
        ]
      }
    ],
    "addresses": [
      {
        "@id": "01FDF077N6V7R2RNC64DGT31DY",
        "@type": "business_address",
        "has_address_line_1_text": {
          "has_value": "33 IRVING PLACE",
          "data_sourced_from": [
            "01FDF10040SA2VTETKJQXJ3MQZ"
          ]
        },
        "has_address_line_2_text": {
          "has_value": "additional_line_text",
          "data_sourced_from": [
            "01FDF10040SA2VTETKJQXJ3MQZ"
          ]
        },
        "has_city_name": {
          "has_value": "NEW YORK",
          "data_sourced_from": [
            "01FDF10040SA2VTETKJQXJ3MQZ"
          ]
        },
        "has_postal_code": {
          "has_value": "10003",
          "data_sourced_from": [
            "01FDF10040SA2VTETKJQXJ3MQZ"
          ]
        },
        "has_country_name": {
          "has_value": "US",
          "data_sourced_from": [
            "01FDF10040SA2VTETKJQXJ3MQZ"
          ]
        }
      }
    ],
    "contact_information": [
      {
        "@type": "contact_information",
        "@id": "01FDF09BNQCT03DCAX7M5KM52T",
        "has_phone_number": {
          "has_value": "+1234567890"
        }
      }
    ],
    "employment": [
      {
        "@type": "employment",
        "@id": "01FDF0DFYAHBRJGFA5RS26HVP1",
        "has_employment_position_description": {
          "has_value": "Engineer",
          "data_sourced_from": [
            "01FDF10040SA2VTETKJQXJ3MQZ"
          ]
        },
        "provided_by": [
          "01FDF0G4BP9AE6B7FT5VDEWK5F"
        ]
      }
    ],
    "organizations": [
      {
        "@type": "organization",
        "@id": "01FDF0G4BP9AE6B7FT5VDEWK5F",
        "has_organization_name": {
          "has_value": "GRAIN PROCESSING COR",
          "data_sourced_from": [
            "01FDF10040SA2VTETKJQXJ3MQZ"
          ]
        },
        "with_address": [
          "01FDF077N6V7R2RNC64DGT31DY"
        ]
      }
    ],
    "mortgage_products": [
      {
        "@type": "employment",
        "@id": "01FDF10040SA2VTETKJQXJ3MQZ",
        "has_data_source_date": {
          "has_value": "1972-01-01"
        },
        "has_purpose_of_verification_description": {
          "has_value": "risk-assessment"
        }
      }
    ],
    "documents": [
      {
        "@type": "irs_w2",
        "@id": "01FS9VK2BVSBZYN0MMYQQ73KAZ",
        "has_document_description": {
          "has_value": "Employment Verification Report prepared by Staircase"
        },
        "has_document_mime_type": {
          "has_value": "application/pdf"
        },
        "has_document_name": {
          "has_value": "01FD9X8V5N804Y0CFWY7F72ZCD.pdf"
        }
      }
    ]
  }
}
Response
application/json

201 response

{
  "transaction_id": "01FJCADX5QEXEDVRWNXAK206MA",
  "collection_id": "01FJCAQW7EYJAA6FY05WRKRM3T",
  "metadata": {
    "version": 2
  },
  "data": {
    "people": [
      {
        "@type": "borrower",
        "@id": "01FDF04MYHEZ98AD7T8ZGY5CMB",
        "has_first_name": {
          "has_value": "John"
        },
        "has_last_name": {
          "has_value": "Deere"
        },
        "has_birth_date": {
          "has_value": "01/01/1985"
        },
        "has_taxpayer_identifier_value": {
          "has_value": "999-00-0000"
        },
        "contact_at": [
          "01FDF09BNQCT03DCAX7M5KM52T"
        ],
        "employed_as": [
          "01FDF0DFYAHBRJGFA5RS26HVP1"
        ]
      }
    ],
    "addresses": [
      {
        "@id": "01FDF077N6V7R2RNC64DGT31DY",
        "@type": "business_address",
        "has_address_line_1_text": {
          "has_value": "33 IRVING PLACE",
          "data_sourced_from": [
            "01FDF10040SA2VTETKJQXJ3MQZ"
          ]
        },
        "has_address_line_2_text": {
          "has_value": "additional_line_text",
          "data_sourced_from": [
            "01FDF10040SA2VTETKJQXJ3MQZ"
          ]
        },
        "has_city_name": {
          "has_value": "NEW YORK",
          "data_sourced_from": [
            "01FDF10040SA2VTETKJQXJ3MQZ"
          ]
        },
        "has_postal_code": {
          "has_value": "10003",
          "data_sourced_from": [
            "01FDF10040SA2VTETKJQXJ3MQZ"
          ]
        },
        "has_country_name": {
          "has_value": "US",
          "data_sourced_from": [
            "01FDF10040SA2VTETKJQXJ3MQZ"
          ]
        }
      }
    ],
    "contact_information": [
      {
        "@type": "contact_information",
        "@id": "01FDF09BNQCT03DCAX7M5KM52T",
        "has_phone_number": {
          "has_value": "+1234567890"
        }
      }
    ],
    "employment": [
      {
        "@type": "employment",
        "@id": "01FDF0DFYAHBRJGFA5RS26HVP1",
        "has_employment_position_description": {
          "has_value": "Engineer",
          "data_sourced_from": [
            "01FDF10040SA2VTETKJQXJ3MQZ"
          ]
        },
        "provided_by": [
          "01FDF0G4BP9AE6B7FT5VDEWK5F"
        ]
      }
    ],
    "organizations": [
      {
        "@type": "organization",
        "@id": "01FDF0G4BP9AE6B7FT5VDEWK5F",
        "has_organization_name": {
          "has_value": "GRAIN PROCESSING COR",
          "data_sourced_from": [
            "01FDF10040SA2VTETKJQXJ3MQZ"
          ]
        },
        "has_transaction_identifier": {
          "has_value": "e171ec31-75b4-4fd6-ada1",
          "data_sourced_from": [
            "01FDF10040SA2VTETKJQXJ3MQZ"
          ]
        },
        "with_address": [
          "01FDF077N6V7R2RNC64DGT31DY"
        ]
      }
    ],
    "mortgage_products": [
      {
        "@type": "employment",
        "@id": "01FDF10040SA2VTETKJQXJ3MQZ",
        "has_data_source_date": {
          "has_value": "01/01/1972"
        },
        "has_purpose_of_verification_description": {
          "has_value": "risk-assessment"
        }
      }
    ],
    "documents": [
      {
        "@type": "irs_w2",
        "has_staircase_document_category_type": {
          "has_value": "staircase"
        },
        "has_document_description": {
          "has_value": "Employment Verification Report prepared by Staircase"
        },
        "has_document_mime_type": {
          "has_value": "application/pdf"
        },
        "has_document_name": {
          "has_value": "01FD9X8V5N804Y0CFWY7F72ZCD.pdf"
        }
      }
    ]
  }
}
Parameters
2
ParameterTypeExampleDescription
transaction_id required string (ulid) path 01FJCADX5QEXEDVRWNXAK206MA Transaction ID
x-sc-trace-id required string header 01FJCADX5QEXEDVRWNXAK206MA Trace ID of the transaction
Request bodyapplication/json
2 fields
FieldTypeDescription
datarequiredobjectCollection data
metadataobjectCollection metadata. Maximum allowable length of the dumped json object - 400 000 symbols.
versionintegerVersion of staircase language with what collection has been created.023
validationbooleanFlag that enables validation
linked_collectionsobject[]List of linked collections
collection_idstring (ulid)Collection ID of linked collection
labelstringLabel of linked collection
serialise_to_graphbooleanFlag that enables collection serialization to persistence graph
fuzzy_searchablebooleanFlag that enables fuzzy search for collection
Response 201application/json
4 fields

201 response

FieldTypeDescription
transaction_idstring (ulid)Transaction idExample 01EZQ32PJQGKRA6HR8D72Q9FFF
collection_idstring (ulid)Collection idExample 01EZQ32PJQGKRA6HR8D72Q9FFF
dataobjectData in Staircase language schema
metadataobjectMetadata about collection, f.e version of used Staircase schema. Maximum allowable length of the dumped json object - 400 000 symbols.
Response 400application/json
1 fields

Request data failed validation

FieldTypeDescription
messageone ofMessage
Response 403application/json
1 fields

Missing API key

FieldTypeDescription
messagestringMessage
Response 404application/json
1 fields

Requested resource not found

FieldTypeDescription
messagestringMessage
Response 429application/json
1 fields

The user has sent too many requests in a given amount of time ("rate limiting")

FieldTypeDescription
messagestringMessage
Other responses

413

GET /transactions/{transaction_id}/collections/{collection_id}

Retrieve Collection

get_collection

Response
application/json

200 response

{
  "transaction_id": "01FJCADX5QEXEDVRWNXAK206MA",
  "collection_id": "01FJCAQW7EYJAA6FY05WRKRM3T",
  "metadata": {
    "version": 2
  },
  "data": {
    "people": [
      {
        "@type": "borrower",
        "@id": "01FDF04MYHEZ98AD7T8ZGY5CMB",
        "has_first_name": {
          "has_value": "John"
        },
        "has_last_name": {
          "has_value": "Deere"
        },
        "has_birth_date": {
          "has_value": "01/01/1985"
        },
        "has_taxpayer_identifier_value": {
          "has_value": "999-00-0000"
        },
        "contact_at": [
          "01FDF09BNQCT03DCAX7M5KM52T"
        ],
        "employed_as": [
          "01FDF0DFYAHBRJGFA5RS26HVP1"
        ]
      }
    ],
    "addresses": [
      {
        "@id": "01FDF077N6V7R2RNC64DGT31DY",
        "@type": "business_address",
        "has_address_line_1_text": {
          "has_value": "33 IRVING PLACE",
          "data_sourced_from": [
            "01FDF10040SA2VTETKJQXJ3MQZ"
          ]
        },
        "has_address_line_2_text": {
          "has_value": "additional_line_text",
          "data_sourced_from": [
            "01FDF10040SA2VTETKJQXJ3MQZ"
          ]
        },
        "has_city_name": {
          "has_value": "NEW YORK",
          "data_sourced_from": [
            "01FDF10040SA2VTETKJQXJ3MQZ"
          ]
        },
        "has_postal_code": {
          "has_value": "10003",
          "data_sourced_from": [
            "01FDF10040SA2VTETKJQXJ3MQZ"
          ]
        },
        "has_country_name": {
          "has_value": "US",
          "data_sourced_from": [
            "01FDF10040SA2VTETKJQXJ3MQZ"
          ]
        }
      }
    ],
    "contact_information": [
      {
        "@type": "contact_information",
        "@id": "01FDF09BNQCT03DCAX7M5KM52T",
        "has_phone_number": {
          "has_value": "+1234567890"
        }
      }
    ],
    "employment": [
      {
        "@type": "employment",
        "@id": "01FDF0DFYAHBRJGFA5RS26HVP1",
        "has_employment_position_description": {
          "has_value": "Engineer",
          "data_sourced_from": [
            "01FDF10040SA2VTETKJQXJ3MQZ"
          ]
        },
        "provided_by": [
          "01FDF0G4BP9AE6B7FT5VDEWK5F"
        ]
      }
    ],
    "organizations": [
      {
        "@type": "organization",
        "@id": "01FDF0G4BP9AE6B7FT5VDEWK5F",
        "has_organization_name": {
          "has_value": "GRAIN PROCESSING COR",
          "data_sourced_from": [
            "01FDF10040SA2VTETKJQXJ3MQZ"
          ]
        },
        "has_transaction_identifier": {
          "has_value": "e171ec31-75b4-4fd6-ada1",
          "data_sourced_from": [
            "01FDF10040SA2VTETKJQXJ3MQZ"
          ]
        },
        "with_address": [
          "01FDF077N6V7R2RNC64DGT31DY"
        ]
      }
    ],
    "mortgage_products": [
      {
        "@type": "employment",
        "@id": "01FDF10040SA2VTETKJQXJ3MQZ",
        "has_data_source_date": {
          "has_value": "01/01/1972"
        },
        "has_purpose_of_verification_description": {
          "has_value": "risk-assessment"
        }
      }
    ],
    "documents": [
      {
        "@type": "irs_w2",
        "has_staircase_document_category_type": {
          "has_value": "staircase"
        },
        "has_document_description": {
          "has_value": "Employment Verification Report prepared by Staircase"
        },
        "has_document_mime_type": {
          "has_value": "application/pdf"
        },
        "has_document_name": {
          "has_value": "01FD9X8V5N804Y0CFWY7F72ZCD.pdf"
        }
      }
    ]
  }
}
Parameters
5
ParameterTypeExampleDescription
transaction_id required string (ulid) path 01FJCADX5QEXEDVRWNXAK206MA Transaction ID
collection_id required string (ulid) path 01FJCAQW7EYJAA6FY05WRKRM3T Collection ID
refs boolean query true If `true`, refs will not be resolved
flatten boolean query true If `true`, the collection will be flattened
x-sc-trace-id required string header 01FJCADX5QEXEDVRWNXAK206MA Trace ID of the transaction
Response 200application/json
4 fields

200 response

FieldTypeDescription
transaction_idstring (ulid)Transaction idExample 01EZQ32PJQGKRA6HR8D72Q9FFF
collection_idstring (ulid)Collection idExample 01EZQ32PJQGKRA6HR8D72Q9FFF
dataobjectData in Staircase language schema
metadataobjectMetadata about collection, f.e version of used Staircase schema. Maximum allowable length of the dumped json object - 400 000 symbols.
Response 400application/json
1 fields

Request data failed validation

FieldTypeDescription
messageone ofMessage
Response 403application/json
1 fields

Missing API key

FieldTypeDescription
messagestringMessage
Response 404application/json
1 fields

Requested resource not found

FieldTypeDescription
messagestringMessage
Response 429application/json
1 fields

The user has sent too many requests in a given amount of time ("rate limiting")

FieldTypeDescription
messagestringMessage
Other responses

422

POST /transactions/{transaction_id}/collections/{collection_id}/graph

Perform Graph Query on Collection Level

collection_graph

Perform graph query on collection level

This feature is experimental Collections created using v2 Staircase language represents data linked with @id, so it can be presented like graph F.e in collection below

 {
 "metadata": {
 "version": 2
 },
 "data": {
 "addresses": [
 {
 "@id": "01F6N4YSSFY8EB5RAY0XNCQ7XD",
 "@type": "address",
 "has_address_line_1_text": {
 "has_value": "1234 MAIN STREET"
 },
 "has_address_line_2_text": {
 "has_value": "SUITE 30"
 },
 "has_city_name": {
 "has_value": "LOS ANGELES"
 },
 "has_full_address_text": {
 "has_value": "1234 Main St, Suite 30, Los Angeles, CA 90210"
 },
 "has_postal_code": {
 "has_value": "90210"
 },
 "has_state_code": {
 "has_value": "CA"
 }
 },
 {
 "@id": "01F6N4YSTP8PRC75SBT40JH0CM",
 "@type": "address",
 "has_address_line_1_text": {
 "has_value": "410 TERRY AVE. NORTH"
 },
 "has_address_line_2_text": {
 "has_value": ""
 },
 "has_city_name": {
 "has_value": "SEATTLE"
 },
 "has_full_address_text": {
 "has_value": "None"
 },
 "has_postal_code": {
 "has_value": "98109"
 },
 "has_state_code": {
 "has_value": "WA"
 }
 }
 ],
 "people": [
 {
 "@id": "01F6N4YSSNTBT17Q5BXDD7R19Q",
 "@type": "borrower",
 "earns": [
 "01F6N4YSTNWAVCPDK0GTA32B9Z"
 ],
 "has_first_name": {
 "has_value": "JOHN"
 },
 "has_full_name": {
 "has_value": "JOHN DOE"
 },
 "has_last_name": {
 "has_value": "DOE"
 },
 "has_social_security_number": {
 "has_value": "999-00-0000"
 },
 "with_address": [
 "01F6N4YSSFY8EB5RAY0XNCQ7XD"
 ],
 "works_for": [
 "01F6N4YSTM8EWPM80PFYJA15JP"
 ]
 }
 ]
 }
 }

As we can see, there is one borrower, and property with_address links us to address in LOS ANGELES. To query borrower information with his address info embed into it, we should construct shape query, where we will specify list of all properties, that we want to retrieve

Show the rest
{
 "people": {
 "has_first_name": {},
 "has_last_name": {},
 "with_address": {
 "has_address_line_1_text": {},
 "has_address_line_2_text": {},
 "has_city_name": {},
 "has_full_address_text": {},
 "has_postal_code": {},
 "has_state_code": {}
 }
 }
}

As a result we will have

{
 "people": [
 {
 "@id": "01F6N4YSSNTBT17Q5BXDD7R19Q",
 "@type": "borrower",
 "has_first_name": {
 "has_value": "JOHN"
 },
 "has_last_name": {
 "has_value": "DOE"
 },
 "with_address": [
 {
 "@id": "01F6N4YSSFY8EB5RAY0XNCQ7XD",
 "@type": "address",
 "has_address_line_1_text": {
 "has_value": "1234 MAIN STREET"
 },
 "has_address_line_2_text": {
 "has_value": "SUITE 30"
 },
 "has_city_name": {
 "has_value": "LOS ANGELES"
 },
 "has_full_address_text": {
 "has_value": "1234 Main St, Suite 30, Los Angeles, CA 90210"
 },
 "has_postal_code": {
 "has_value": "90210"
 },
 "has_state_code": {
 "has_value": "CA"
 }
 }
 ]
 }
 ]
}

So, for retrieving data you should specify the structure, that you want it to have, you will get only property, that you specified as keys and {} as a value. For referencable properties, there is no need to specify has_value property.

Request
application/json
{
  "people": {
    "has_first_name": {},
    "earns": {
      "has_federal_tax_withheld_amount": {},
      "has_dependent_care_benefits_amount": {}
    }
  }
}
Response
application/json

Resolved graph query

{
  "people": [
    {
      "@id": "01F6N4YSSNTBT17Q5BXDD7R19Q",
      "@type": "borrower",
      "earns": [
        {
          "@id": "01F6N4YSTNWAVCPDK0GTA32B9Z",
          "@type": "employment_income",
          "has_dependent_care_benefits_amount": {
            "has_value": "1000.00"
          },
          "has_federal_tax_withheld_amount": {
            "has_value": "6835.00"
          }
        }
      ],
      "has_first_name": {
        "has_value": "JOHN"
      }
    }
  ]
}
Parameters
3
ParameterTypeExampleDescription
transaction_id required string (ulid) path 01FJCADX5QEXEDVRWNXAK206MA Transaction ID
collection_id required string (ulid) path 01FJCAQW7EYJAA6FY05WRKRM3T Collection ID
x-sc-trace-id required string header 01FJCADX5QEXEDVRWNXAK206MA Trace ID of the transaction
Response 400application/json
1 fields

Request data failed validation

FieldTypeDescription
messageone ofMessage
Response 403application/json
1 fields

Missing API key

FieldTypeDescription
messagestringMessage
Response 404application/json
1 fields

Requested resource not found

FieldTypeDescription
messagestringMessage
Response 429application/json
1 fields

The user has sent too many requests in a given amount of time ("rate limiting")

FieldTypeDescription
messagestringMessage
Other responses

200

POST /transactions/{transaction_id}/collections/{collection_id}/query

Query on Collection Level

query_collection

This endpoint provides query capabilities on collection level. You can write query in one of two formats:

  • JSONPath
  • JMESPath

You can write queries, that will follow links in your collection to get results. For example, we have this collection:

{
 "addresses": [
 {
 "@id": "01F6N4YSSFY8EB5RAY0XNCQ7XD",
 "@type": "mailing_address",
 "has_city_name": {
 "has_value": "LOS ANGELES"
 },
 "has_state_code": {
 "has_value": "CA"
 }
 },
 {
 "@id": "01FFFRTHRP2FPT481FVT1R1Z0Q",
 "@type": "mailing_address",
 "has_city_name": {
 "has_value": "SAN FRANCISCO"
 },
 "has_state_code": {
 "has_value": "CA"
 }
 },
 {
 "@id": "01F6N4YSTP8PRC75SBT40JH0CM",
 "@type": "residential_address",
 "has_city_name": {
 "has_value": "SEATTLE"
 },
 "has_state_code": {
 "has_value": "WA"
 }
 },
 {
 "@id": "01FFFR2XWQTBGNNXN68X32QS8Y",
 "@type": "mailing_address",
 "has_city_name": {
 "has_value": "NEW YORK"
 },
 "has_state_code": {
 "has_value": "CA"
 }
 }
 ],
 "people": [
 {
 "@id": "01F6N4YSSNTBT17Q5BXDD7R19Q",
 "@type": "borrower",
 "has_first_name": {
 "has_value": "JOHN"
 },
 "has_full_name": {
 "has_value": "JOHN DOE"
 },
 "has_last_name": {
 "has_value": "DOE"
 },
 "with_address": [
 "01F6N4YSSFY8EB5RAY0XNCQ7XD",
 "01F6N4YSTP8PRC75SBT40JH0CM",
 "01FFFR2XWQTBGNNXN68X32QS8Y"
 ]
 },
 {
 "@id": "01FFFQSWKY384GKNQFMET31HTX",
 "@type": "co_borrower",
 "has_first_name": {
 "has_value": "Rakhim"
 },
 "has_full_name": {
 "has_value": "Rakhim Sterling"
 },
 "has_last_name": {
 "has_value": "Sterling"
 },
 "with_address": [
 "01FFFQZ4BE5NRJDGP7FJ20XA0H"
 ]
 }
 ]
}

As you see here we have two people, one borrower and one co-borrower. Three addresses is associated to borrower, two mailing and one residential. One mailing address is associated to co-borrower. Let's build query to retrieve city name of borrower mailing address. To do this, we need to get people, where type equals borrower and addresses, where type equals mailing address. JSONPath query:

Show the rest
{
 "format": "jsonpath",
 "query": "$.people[?(@['@type'] = 'borrower')].with_address[?(@['@type'] = 'mailing_address')].has_city_name.has_value"
}

Result:

{
 "result": ["LOS ANGELES", "NEW YORK"]
}

Same query using JMESPath, but with grabing state code and reformatting output:

{
 "format": "jmespath",
 "query": "people[?\"@type\" == 'borrower'].with_address[] | [?\"@type\" == 'mailing_address'].{city: has_city_name.has_value, state_code: has_state_code.has_value}"
}

Result:

{
 "result": [
 {
 "city": "LOS ANGELES",
 "state_code": "CA"
 },
 {
 "city": "NEW YORK",
 "state_code": "CA"
 }
 ]
}
Request
application/json

JSONPath query

{
  "format": "jsonpath",
  "query": "$.people[?(@['@type'] = 'borrower')].with_address[?(@['@type'] = 'mailing_address')].has_city_name.has_value"
}
Response
application/json

Request data failed validation

{
  "message": "{'data': ['Missing data for required field.']}"
}
Parameters
3
ParameterTypeExampleDescription
transaction_id required string (ulid) path 01FJCADX5QEXEDVRWNXAK206MA Transaction ID
collection_id required string (ulid) path 01FJCAQW7EYJAA6FY05WRKRM3T Collection ID
x-sc-trace-id required string header 01FJCADX5QEXEDVRWNXAK206MA Trace ID of the transaction
Request bodyapplication/json
2 fields
FieldTypeDescription
formatrequiredstringQuery format.jmespathjsonpath
queryrequiredstringQuery.
Response 200application/json
1 fields

Query results.

FieldTypeDescription
resultone ofQuery results.
Response 400application/json
1 fields

Request data failed validation

FieldTypeDescription
messageone ofMessage
Response 403application/json
1 fields

Missing API key

FieldTypeDescription
messagestringMessage
Response 404application/json
1 fields

Requested resource not found

FieldTypeDescription
messagestringMessage
Response 429application/json
1 fields

The user has sent too many requests in a given amount of time ("rate limiting")

FieldTypeDescription
messagestringMessage
GET /transactions/{transaction_id}/collections

Retrieve Transaction Collections

get_collections

Retrieve Transaction Collections. If transaction was replaced by the new one, it will return collections from the new transaction. This behavior can be changed by providing ignore_replacement query parameter. Collections can be filtered by collection_id or created_at fields. Supported operations per fields:

  • collection_id:
  • in:
  • description: Get only collections with specified ids
  • example: collection_id+in+01EZQ32PJQGKRA6HR8D72Q9FFF,01EZQ32NZ34WACWSAF54WGEM51
  • created_at:
  • gt:
  • description: Get collections that were created after specified datetime in ISO format
  • example: created_at+gt+2021-03-30T04:27:15.372006-04:00
  • lt:
  • description: Get collections that were created before specified datetime in ISO format
  • example: created_at+lt+2021-03-30T04:27:15.372006-04:00
Response
application/json

Request data failed validation

{
  "message": "{'data': ['Missing data for required field.']}"
}
Parameters
7
ParameterTypeExampleDescription
transaction_id required string (ulid) path 01FJCADX5QEXEDVRWNXAK206MA Transaction ID
filter string query collection_id+in+01EZQ32PJQGKRA6HR8D72Q9FFF,01EZQ32NZ34WACWSAF54WGEM51 Filter expression in format {field_name}+{operation}+{value}
ignore_replacement boolean query true Ignores replacement for the transaction.
sort string query asc Order of sorting
limit number query 5 Amount of items to show
after_id string query 01EZQ32PJQGKRA6HR8D72Q9FFF id of last evaluated collection
x-sc-trace-id required string header 01FJCADX5QEXEDVRWNXAK206MA Trace ID of the transaction
Response 200application/json
4 fields

200 response

FieldTypeDescription
transaction_idstring (ulid)Transaction idExample 01EZQ32PJQGKRA6HR8D72Q9FFF
collection_idstring (ulid)Collection idExample 01EZQ32PJQGKRA6HR8D72Q9FFF
dataobjectData in Staircase language schema
metadataobjectMetadata about collection, f.e version of used Staircase schema. Maximum allowable length of the dumped json object - 400 000 symbols.
Response 400application/json
1 fields

Request data failed validation

FieldTypeDescription
messageone ofMessage
Response 404application/json
1 fields

Requested resource not found

FieldTypeDescription
messagestringMessage
Response 422application/json
2 fields

Unprocessable Entity

FieldTypeDescription
messagestringMessage
collectionsobject[]List of collections without 'data' field and with links to retrieve single collections.
transaction_idstring (ulid)Transaction id
collection_idstring (ulid)Collection id
metadataobjectMetadata about collection, f.e version of used Staircase schema Maximum allowable length of the dumped json object - 400 000 symbols.
_linksobjectLinks
collectionstring (url)Link to retrieve full collection.
Response 429application/json
1 fields

The user has sent too many requests in a given amount of time ("rate limiting")

FieldTypeDescription
messagestringMessage
PUT /transactions/{transaction_id}/collections/{collection_id}

Update Collection

update_collection

Update Collection. Collection data can not be updated, but it can be inserted, if previously it was an empty object.

Request
application/json
{
  "data": {
    "deal_sets": [
      {
        "assets": [
          {
            "account_identifier": "1523421245",
            "cash_or_market_value": 45000,
            "holder_name": "BankA",
            "type": "SavingsAccount"
          }
        ],
        "collaterals": [
          {
            "address": {
              "city": "Winston Salem",
              "line_text": "1234 Main St",
              "postal_code": "27104",
              "state_code": "NC"
            },
            "property_detail": {
              "attachment_type": "Detached",
              "construction_method_type": "SiteBuilt",
              "estate_type": "FeeSimple",
              "estimated_value": 225000,
              "financed_unit_count": 1,
              "is_existing_clean_energy_lien": false,
              "is_in_project": false,
              "is_mixed_usage": false,
              "is_pud": false,
              "usage_type": "PrimaryResidence"
            },
            "property_valuations": {
              "property_valuation": [
                {
                  "property_valuation_detail": {
                    "amount": 225000,
                    "appraisal_identifier": "1100AA1111"
                  }
                }
              ]
            },
            "sales_contracts": {
              "sales_contract": [
                {
                  "sales_contract_detail": {
                    "amount": 225000
                  }
                }
              ]
            }
          }
        ],
        "expenses": [
          {
            "EXTENSION": "<EXTENSION xmlns:lpa=\"http://www.datamodelextension.org/Schema/LPA\" xmlns=\"http://www.mismo.org/residential/2009/schemas\" xmlns:lparqst=\"http://www.freddiemac.com/lpa/LPALoanAssessmentService/schemas\" xmlns:ulad=\"http://www.datamodelextension.org/Schema/ULAD\" xmlns:xlink=\"http://www.w3.org/1999/xlink\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"><OTHER><EXPENSE_EXTENSION><ExpenseExclusionIndicator>false</ExpenseExclusionIndicator></EXPENSE_EXTENSION></OTHER></EXTENSION>",
            "monthly_payment": 127,
            "type": "JobRelatedExpenses"
          }
        ],
        "liabilities": [
          {
            "account_identifier": "913432",
            "holder_name": "Toyota Credit",
            "is_exclusion": false,
            "is_payoff_status": false,
            "monthly_payment": 500,
            "type": "Installment",
            "unpaid_balance": 15838
          }
        ],
        "loans": [
          {
            "amortization": {
              "loan_period_count": 360,
              "loan_period_type": "Month",
              "type": "Fixed"
            },
            "application_received_date": "2019-03-21",
            "cash_out_determination_type": null,
            "document_specific_data_sets": [
              {
                "EXTENSION": "<EXTENSION xmlns:lpa=\"http://www.datamodelextension.org/Schema/LPA\" xmlns=\"http://www.mismo.org/residential/2009/schemas\" xmlns:lparqst=\"http://www.freddiemac.com/lpa/LPALoanAssessmentService/schemas\" xmlns:ulad=\"http://www.datamodelextension.org/Schema/ULAD\" xmlns:xlink=\"http://www.w3.org/1999/xlink\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"><OTHER><URLA_TOTAL_EXTENSION><URLATotalSellerCreditsAmount>2250</URLATotalSellerCreditsAmount></URLA_TOTAL_EXTENSION></OTHER></EXTENSION>",
                "estimated_closing_costs": 6750,
                "mi_and_funding_fee_financed": 0,
                "prepaid_items_estimated": 2300
              }
            ],
            "housing_expenses": [
              {
                "payment": 506.69,
                "timing_type": "Proposed",
                "type": "FirstMortgagePrincipalAndInterest"
              },
              {
                "payment": 153,
                "timing_type": "Proposed",
                "type": "HomeownersInsurance"
              },
              {
                "payment": 188,
                "timing_type": "Proposed",
                "type": "RealEstateTax"
              },
              {
                "payment": 123,
                "timing_type": "Proposed",
                "type": "Other",
                "type_other": "WaterSewerAssessment"
              }
            ],
            "is_balloon": false,
            "is_buydown_temporary_subsidy_funding": false,
            "is_construction": false,
            "is_interest_only": false,
            "is_prepayment_penalty": false,
            "loan_identifiers": [
              {
                "identifier": "1122334455",
                "type": "LenderLoan"
              },
              {
                "identifier": "111198756421356000",
                "type": "MERS_MIN"
              },
              {
                "identifier": "1234567890",
                "type": "UniversalLoan"
              }
            ],
            "loan_product": {
              "description": "30YrFixed",
              "discount_points_total": 2100
            },
            "loan_statuses": [
              {
                "identifier": "Underwriting"
              }
            ],
            "origination_systems": [
              {
                "loan_vendor_identifier": "000000",
                "loan_version_identifier": "2.7"
              }
            ],
            "projected_reserves": 100000,
            "purchase_credits": [
              {
                "amount": 1000,
                "source_type": "BorrowerPaidOutsideClosing",
                "type": "EarnestMoney"
              },
              {
                "amount": 750,
                "source_type": "Lender",
                "type": "Other",
                "type_other": "ClosingCosts"
              }
            ],
            "qualifying_rate_percent": null,
            "terms_of_loan": {
              "base": 100000,
              "lien_priority_type": "FirstLien",
              "mortgage_type": "Conventional",
              "note_rate_percent": 4.5,
              "purpose_type": "Purchase"
            }
          }
        ]
      }
    ]
  }
}
Response
application/json

200 response

{
  "transaction_id": "dfa22839-8ecd-40c0-9bcb-b70f78002cdb",
  "collection_id": "104592a7-fcbe-4fa3-92e9-90e2b648a0a4",
  "metadata": {},
  "data": {
    "deal_sets": [
      {
        "assets": [
          {
            "account_identifier": "1523421245",
            "cash_or_market_value": 45000,
            "holder_name": "BankA",
            "type": "SavingsAccount"
          }
        ],
        "collaterals": [
          {
            "address": {
              "city": "Winston Salem",
              "line_text": "1234 Main St",
              "postal_code": "27104",
              "state_code": "NC"
            },
            "property_detail": {
              "attachment_type": "Detached",
              "construction_method_type": "SiteBuilt",
              "estate_type": "FeeSimple",
              "estimated_value": 225000,
              "financed_unit_count": 1,
              "is_existing_clean_energy_lien": false,
              "is_in_project": false,
              "is_mixed_usage": false,
              "is_pud": false,
              "usage_type": "PrimaryResidence"
            },
            "property_valuations": {
              "property_valuation": [
                {
                  "property_valuation_detail": {
                    "amount": 225000,
                    "appraisal_identifier": "1100AA1111"
                  }
                }
              ]
            },
            "sales_contracts": {
              "sales_contract": [
                {
                  "sales_contract_detail": {
                    "amount": 225000
                  }
                }
              ]
            }
          }
        ],
        "expenses": [
          {
            "EXTENSION": "<EXTENSION xmlns:lpa=\"http://www.datamodelextension.org/Schema/LPA\" xmlns=\"http://www.mismo.org/residential/2009/schemas\" xmlns:lparqst=\"http://www.freddiemac.com/lpa/LPALoanAssessmentService/schemas\" xmlns:ulad=\"http://www.datamodelextension.org/Schema/ULAD\" xmlns:xlink=\"http://www.w3.org/1999/xlink\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"><OTHER><EXPENSE_EXTENSION><ExpenseExclusionIndicator>false</ExpenseExclusionIndicator></EXPENSE_EXTENSION></OTHER></EXTENSION>",
            "monthly_payment": 127,
            "type": "JobRelatedExpenses"
          }
        ],
        "liabilities": [
          {
            "account_identifier": "913432",
            "holder_name": "Toyota Credit",
            "is_exclusion": false,
            "is_payoff_status": false,
            "monthly_payment": 500,
            "type": "Installment",
            "unpaid_balance": 15838
          }
        ],
        "loans": [
          {
            "amortization": {
              "loan_period_count": 360,
              "loan_period_type": "Month",
              "type": "Fixed"
            },
            "application_received_date": "2019-03-21",
            "cash_out_determination_type": null,
            "document_specific_data_sets": [
              {
                "EXTENSION": "<EXTENSION xmlns:lpa=\"http://www.datamodelextension.org/Schema/LPA\" xmlns=\"http://www.mismo.org/residential/2009/schemas\" xmlns:lparqst=\"http://www.freddiemac.com/lpa/LPALoanAssessmentService/schemas\" xmlns:ulad=\"http://www.datamodelextension.org/Schema/ULAD\" xmlns:xlink=\"http://www.w3.org/1999/xlink\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"><OTHER><URLA_TOTAL_EXTENSION><URLATotalSellerCreditsAmount>2250</URLATotalSellerCreditsAmount></URLA_TOTAL_EXTENSION></OTHER></EXTENSION>",
                "estimated_closing_costs": 6750,
                "mi_and_funding_fee_financed": 0,
                "prepaid_items_estimated": 2300
              }
            ],
            "housing_expenses": [
              {
                "payment": 506.69,
                "timing_type": "Proposed",
                "type": "FirstMortgagePrincipalAndInterest"
              },
              {
                "payment": 153,
                "timing_type": "Proposed",
                "type": "HomeownersInsurance"
              },
              {
                "payment": 188,
                "timing_type": "Proposed",
                "type": "RealEstateTax"
              },
              {
                "payment": 123,
                "timing_type": "Proposed",
                "type": "Other",
                "type_other": "WaterSewerAssessment"
              }
            ],
            "is_balloon": false,
            "is_buydown_temporary_subsidy_funding": false,
            "is_construction": false,
            "is_interest_only": false,
            "is_prepayment_penalty": false,
            "loan_identifiers": [
              {
                "identifier": "1122334455",
                "type": "LenderLoan"
              },
              {
                "identifier": "111198756421356000",
                "type": "MERS_MIN"
              },
              {
                "identifier": "1234567890",
                "type": "UniversalLoan"
              }
            ],
            "loan_product": {
              "description": "30YrFixed",
              "discount_points_total": 2100
            },
            "loan_statuses": [
              {
                "identifier": "Underwriting"
              }
            ],
            "origination_systems": [
              {
                "loan_vendor_identifier": "000000",
                "loan_version_identifier": "2.7"
              }
            ],
            "projected_reserves": 100000,
            "purchase_credits": [
              {
                "amount": 1000,
                "source_type": "BorrowerPaidOutsideClosing",
                "type": "EarnestMoney"
              },
              {
                "amount": 750,
                "source_type": "Lender",
                "type": "Other",
                "type_other": "ClosingCosts"
              }
            ],
            "qualifying_rate_percent": null,
            "terms_of_loan": {
              "base": 100000,
              "lien_priority_type": "FirstLien",
              "mortgage_type": "Conventional",
              "note_rate_percent": 4.5,
              "purpose_type": "Purchase"
            }
          }
        ]
      }
    ]
  }
}
Parameters
3
ParameterTypeExampleDescription
transaction_id required string (ulid) path 01FJCADX5QEXEDVRWNXAK206MA Transaction ID
collection_id required string (ulid) path 01FJCAQW7EYJAA6FY05WRKRM3T Collection ID
x-sc-trace-id required string header 01FJCADX5QEXEDVRWNXAK206MA Trace ID of the transaction
Request bodyapplication/json
2 fields
FieldTypeDescription
datarequiredobjectData for updating
metadataobjectMetadata for updating. Maximum allowable length of the dumped json object - 400 000 symbols.
Response 200application/json
4 fields

200 response

FieldTypeDescription
transaction_idstring (ulid)Transaction idExample 01EZQ32PJQGKRA6HR8D72Q9FFF
collection_idstring (ulid)Collection idExample 01EZQ32PJQGKRA6HR8D72Q9FFF
dataobjectData in Staircase language schema
metadataobjectMetadata about collection, f.e version of used Staircase schema. Maximum allowable length of the dumped json object - 400 000 symbols.
Response 400application/json
1 fields

Request data failed validation

FieldTypeDescription
messageone ofMessage
Response 403application/json
1 fields

Missing API key

FieldTypeDescription
messagestringMessage
Response 404application/json
1 fields

Requested resource not found

FieldTypeDescription
messagestringMessage
Response 429application/json
1 fields

The user has sent too many requests in a given amount of time ("rate limiting")

FieldTypeDescription
messagestringMessage
Other responses

413422

POST /models/convert

Convert Nested Model

convert_nested_model

Convert nested models into flat Staircase collections

This endpoint allows you to convert data structures with nested elements into a more manageable, flat format. It requires data field in it's body, and will flatten data according to V3 Lexicon

Request
application/json
{
  "data": {
    "liabilities": [
      {
        "@type": "liability",
        "liability_account_identifier": "12340002",
        "has_liability_timeline": {
          "@type": "liability_timeline",
          "liability_unpaid_balance_amount": 2000
        }
      }
    ]
  }
}
Response
application/json

New flattened data

{
  "data": {
    "liabilities": [
      {
        "@id": "01HHEEBDS82E4FXB7XKB2EFN54",
        "@type": "liability",
        "has_liability_timeline": "01HHKJY1QNZ5MFPEAHS4KSRNCW",
        "liability_account_identifier": "12340002"
      }
    ],
    "liability_timelines": [
      {
        "@id": "01HHKJY1QNZ5MFPEAHS4KSRNCW",
        "@type": "liability_timeline",
        "liability_unpaid_balance_amount": 2000
      }
    ]
  }
}
Request bodyapplication/json
1 fields
FieldTypeDescription
dataobjectData
Response 200application/json
1 fields

New flattened data

FieldTypeDescription
dataobjectData
Response 400application/json
1 fields

Request data failed validation

FieldTypeDescription
messageone ofMessage
Response 403application/json
1 fields

Missing API key

FieldTypeDescription
messagestringMessage
Response 404application/json
1 fields

Requested resource not found

FieldTypeDescription
messagestringMessage
Response 429application/json
1 fields

The user has sent too many requests in a given amount of time ("rate limiting")

FieldTypeDescription
messagestringMessage
PATCH /transactions/{transaction_id}/collections/{collection_id}

Patch Collection

patch_collection

Patch collection

This endpoint provides ability to patch collection. Collections are immutable, so as a result you will have new collection created for you with applied changes.

Operations

Remove

This operation gives you the ability to remove elements and/or properties from your collection along with its relationships. You can explicitly specify the element ID you want to remove or apply the query. Read more about queries by the link. You can also specify depth for graph traversing and relationships, you don't want to remove. For examples, we use this collection

Show the rest
{
 "metadata": {
 "version": 2
 },
 "data": {
 "addresses": [
 {
 "@id": "01F6N4YSSFY8EB5RAY0XNCQ7XD",
 "@type": "address",
 "has_address_line_1_text": {
 "has_value": "1234 MAIN STREET"
 },
 "has_address_line_2_text": {
 "has_value": "SUITE 30"
 },
 "has_city_name": {
 "has_value": "LOS ANGELES"
 },
 "has_full_address_text": {
 "has_value": "1234 Main St, Suite 30, Los Angeles, CA 90210"
 },
 "has_postal_code": {
 "has_value": "90210"
 },
 "has_state_code": {
 "has_value": "CA"
 }
 },
 {
 "@id": "01F6N4YSTP8PRC75SBT40JH0CM",
 "@type": "address",
 "has_address_line_1_text": {
 "has_value": "410 TERRY AVE. NORTH"
 },
 "has_address_line_2_text": {
 "has_value": ""
 },
 "has_city_name": {
 "has_value": "SEATTLE"
 },
 "has_full_address_text": {
 "has_value": "None"
 },
 "has_postal_code": {
 "has_value": "98109"
 },
 "has_state_code": {
 "has_value": "WA"
 }
 }
 ],
 "documents": [
 {
 "@id": "01F6N4YSRAQVA8FA1F5MKBYR55",
 "@type": "irs_w2",
 "has_data_owner_document_identifer": {
 "has_value": "None"
 },
 "has_document_data_extraction_confidence_score": {
 "has_value": 72.453
 },
 "has_document_identifier": {
 "has_value": "z354-43431"
 },
 "has_instance_identifier": {
 "has_value": "z354-43431"
 }
 }
 ],
 "employment": [
 {
 "@id": "01F6N4YSXSGAGJ0BKKMB7606V0",
 "@type": "employment",
 "has_retirement_plan_participant_indicator": {
 "has_value": "true"
 },
 "has_statutory_employee_indicator": {
 "has_value": "false"
 }
 }
 ],
 "income": [
 {
 "@id": "01F6N4YSTNWAVCPDK0GTA32B9Z",
 "@type": "employment_income",
 "earned_from": [
 "01F6N4YSXSGAGJ0BKKMB7606V0"
 ],
 "has_allocated_tips_amount": {
 "has_value": ""
 },
 "has_dependent_care_benefits_amount": {
 "has_value": "1000.00"
 },
 "has_federal_tax_withheld_amount": {
 "has_value": "6835.00"
 },
 "has_gross_income_amount": {
 "data_sourced_from": [
 "01F6N4YSRAQVA8FA1F5MKBYR55"
 ],
 "has_data_extraction_confidence_score": 32.38,
 "has_value": "48500.00"
 },
 "has_income_paid_by_third_parties_indicator": {
 "has_value": "false"
 },
 "has_local_1_income_amount": {
 "has_value": "50000.00"
 },
 "has_local_1_tax_withheld_amount": {
 "has_value": "750.00"
 },
 "has_local_2_income_amount": {
 "has_value": ""
 },
 "has_local_2_tax_withheld_amount": {
 "has_value": ""
 },
 "has_locality_1_name": {
 "has_value": "MU"
 },
 "has_locality_2_name": {
 "has_value": ""
 },
 "has_medicare_income_amount": {
 "has_value": "50000.00"
 },
 "has_medicare_tax_withheld_amount": {
 "has_value": "725.00"
 },
 "has_nonqualified_retirement_plan_distribution_amount": {
 "has_value": ""
 },
 "has_social_security_income_amount": {
 "has_value": "50000.00"
 },
 "has_social_security_tax_withheld_amount": {
 "has_value": "3100.00"
 },
 "has_social_security_tips_amount": {
 "has_value": "600.00"
 },
 "has_state_1_income_amount": {
 "data_owned_by": [
 "01F6N4YSTM8EWPM80PFYJA15JP"
 ],
 "data_sourced_from": [
 "01F6N4YSRAQVA8FA1F5MKBYR55"
 ],
 "has_data_extraction_confidence_score": 76.68,
 "has_value": "50000.00"
 },
 "has_state_1_tax_withheld_amount": {
 "has_value": "1535.00"
 },
 "has_state_2_income_amount": {
 "has_value": ""
 },
 "has_state_2_tax_withheld_amount": {
 "has_value": ""
 }
 }
 ],
 "mortgage_products": [
 {
 "@id": "01F6N4YSXSN7Y010QW2AG4M70W",
 "@type": "data_extraction",
 "product_used_for": [
 "01F6N4YSRAQVA8FA1F5MKBYR55"
 ]
 }
 ],
 "organizations": [
 {
 "@id": "01F6N4YSTM8EWPM80PFYJA15JP",
 "@type": "organization",
 "has_organization_identifier": "23-5247235",
 "has_organization_name": {
 "has_value": "AMAZON , INC."
 },
 "with_address": [
 "01F6N4YSTP8PRC75SBT40JH0CM"
 ]
 }
 ],
 "people": [
 {
 "@id": "01F6N4YSSNTBT17Q5BXDD7R19Q",
 "@type": "borrower",
 "earns": [
 "01F6N4YSTNWAVCPDK0GTA32B9Z"
 ],
 "has_first_name": {
 "has_value": "JOHN"
 },
 "has_full_name": {
 "has_value": "JOHN DOE"
 },
 "has_last_name": {
 "has_value": "DOE"
 },
 "has_social_security_number": {
 "has_value": "999-00-0000"
 },
 "with_address": [
 "01F6N4YSSFY8EB5RAY0XNCQ7XD"
 ],
 "works_for": [
 "01F6N4YSTM8EWPM80PFYJA15JP"
 ]
 }
 ]
 }
}
Remove element by @id

To remove element and all connected elements we just need to specify @id of it. Let's remove the only organization we have in our collection.

{
 "element_id": "01F6N4YSTM8EWPM80PFYJA15JP",
 "op": "remove"
}

As a result we have collection without organization and its address

{
 "metadata": {
 "version": 2
 },
 "data": {
 "addresses": [
 {
 "@id": "01F6N4YSSFY8EB5RAY0XNCQ7XD",
 "@type": "address",
 "has_address_line_1_text": {
 "has_value": "1234 MAIN STREET"
 },
 "has_address_line_2_text": {
 "has_value": "SUITE 30"
 },
 "has_city_name": {
 "has_value": "LOS ANGELES"
 },
 "has_full_address_text": {
 "has_value": "1234 Main St, Suite 30, Los Angeles, CA 90210"
 },
 "has_postal_code": {
 "has_value": "90210"
 },
 "has_state_code": {
 "has_value": "CA"
 }
 }
 ],
 "documents": [
 {
 "@id": "01F6N4YSRAQVA8FA1F5MKBYR55",
 "@type": "irs_w2",
 "has_data_owner_document_identifer": {
 "has_value": "None"
 },
 "has_document_data_extraction_confidence_score": {
 "has_value": 72.453
 },
 "has_document_identifier": {
 "has_value": "z354-43431"
 },
 "has_instance_identifier": {
 "has_value": "z354-43431"
 }
 }
 ],
 "employment": [
 {
 "@id": "01F6N4YSXSGAGJ0BKKMB7606V0",
 "@type": "employment",
 "has_retirement_plan_participant_indicator": {
 "has_value": "true"
 },
 "has_statutory_employee_indicator": {
 "has_value": "false"
 }
 }
 ],
 "income": [
 {
 "@id": "01F6N4YSTNWAVCPDK0GTA32B9Z",
 "@type": "employment_income",
 "earned_from": [
 "01F6N4YSXSGAGJ0BKKMB7606V0"
 ],
 "has_allocated_tips_amount": {
 "has_value": ""
 },
 "has_dependent_care_benefits_amount": {
 "has_value": "1000.00"
 },
 "has_federal_tax_withheld_amount": {
 "has_value": "6835.00"
 },
 "has_gross_income_amount": {
 "data_sourced_from": [
 "01F6N4YSRAQVA8FA1F5MKBYR55"
 ],
 "has_data_extraction_confidence_score": 32.38,
 "has_value": "48500.00"
 },
 "has_income_paid_by_third_parties_indicator": {
 "has_value": "false"
 },
 "has_local_1_income_amount": {
 "has_value": "50000.00"
 },
 "has_local_1_tax_withheld_amount": {
 "has_value": "750.00"
 },
 "has_local_2_income_amount": {
 "has_value": ""
 },
 "has_local_2_tax_withheld_amount": {
 "has_value": ""
 },
 "has_locality_1_name": {
 "has_value": "MU"
 },
 "has_locality_2_name": {
 "has_value": ""
 },
 "has_medicare_income_amount": {
 "has_value": "50000.00"
 },
 "has_medicare_tax_withheld_amount": {
 "has_value": "725.00"
 },
 "has_nonqualified_retirement_plan_distribution_amount": {
 "has_value": ""
 },
 "has_social_security_income_amount": {
 "has_value": "50000.00"
 },
 "has_social_security_tax_withheld_amount": {
 "has_value": "3100.00"
 },
 "has_social_security_tips_amount": {
 "has_value": "600.00"
 },
 "has_state_1_income_amount": {
 "data_sourced_from": [
 "01F6N4YSRAQVA8FA1F5MKBYR55"
 ],
 "has_data_extraction_confidence_score": 76.68,
 "has_value": "50000.00"
 },
 "has_state_1_tax_withheld_amount": {
 "has_value": "1535.00"
 },
 "has_state_2_income_amount": {
 "has_value": ""
 },
 "has_state_2_tax_withheld_amount": {
 "has_value": ""
 }
 }
 ],
 "mortgage_products": [
 {
 "@id": "01F6N4YSXSN7Y010QW2AG4M70W",
 "@type": "data_extraction",
 "product_used_for": [
 "01F6N4YSRAQVA8FA1F5MKBYR55"
 ]
 }
 ],
 "people": [
 {
 "@id": "01F6N4YSSNTBT17Q5BXDD7R19Q",
 "@type": "borrower",
 "earns": [
 "01F6N4YSTNWAVCPDK0GTA32B9Z"
 ],
 "has_first_name": {
 "has_value": "JOHN"
 },
 "has_full_name": {
 "has_value": "JOHN DOE"
 },
 "has_last_name": {
 "has_value": "DOE"
 },
 "has_social_security_number": {
 "has_value": "999-00-0000"
 },
 "with_address": [
 "01F6N4YSSFY8EB5RAY0XNCQ7XD"
 ]
 }
 ]
 }
}
Use depth

Let's remove borrower, but keep all elements, connected with it in collection. To do it, we need to specify borrower ID and depth = 1.

{
 "op": "remove",
 "element_id": "01F6N4YSSNTBT17Q5BXDD7R19Q",
 "depth": 1
}

As a result we have same collection, just without borrower element

{
 "metadata": {
 "version": 2
 },
 "data": {
 "addresses": [
 {
 "@id": "01F6N4YSSFY8EB5RAY0XNCQ7XD",
 "@type": "address",
 "has_address_line_1_text": {
 "has_value": "1234 MAIN STREET"
 },
 "has_address_line_2_text": {
 "has_value": "SUITE 30"
 },
 "has_city_name": {
 "has_value": "LOS ANGELES"
 },
 "has_full_address_text": {
 "has_value": "1234 Main St, Suite 30, Los Angeles, CA 90210"
 },
 "has_postal_code": {
 "has_value": "90210"
 },
 "has_state_code": {
 "has_value": "CA"
 }
 },
 {
 "@id": "01F6N4YSTP8PRC75SBT40JH0CM",
 "@type": "address",
 "has_address_line_1_text": {
 "has_value": "410 TERRY AVE. NORTH"
 },
 "has_address_line_2_text": {
 "has_value": ""
 },
 "has_city_name": {
 "has_value": "SEATTLE"
 },
 "has_full_address_text": {
 "has_value": "None"
 },
 "has_postal_code": {
 "has_value": "98109"
 },
 "has_state_code": {
 "has_value": "WA"
 }
 }
 ],
 "documents": [
 {
 "@id": "01F6N4YSRAQVA8FA1F5MKBYR55",
 "@type": "irs_w2",
 "has_data_owner_document_identifer": {
 "has_value": "None"
 },
 "has_document_data_extraction_confidence_score": {
 "has_value": 72.453
 },
 "has_document_identifier": {
 "has_value": "z354-43431"
 },
 "has_instance_identifier": {
 "has_value": "z354-43431"
 }
 }
 ],
 "employment": [
 {
 "@id": "01F6N4YSXSGAGJ0BKKMB7606V0",
 "@type": "employment",
 "has_retirement_plan_participant_indicator": {
 "has_value": "true"
 },
 "has_statutory_employee_indicator": {
 "has_value": "false"
 }
 }
 ],
 "income": [
 {
 "@id": "01F6N4YSTNWAVCPDK0GTA32B9Z",
 "@type": "employment_income",
 "earned_from": [
 "01F6N4YSXSGAGJ0BKKMB7606V0"
 ],
 "has_allocated_tips_amount": {
 "has_value": ""
 },
 "has_dependent_care_benefits_amount": {
 "has_value": "1000.00"
 },
 "has_federal_tax_withheld_amount": {
 "has_value": "6835.00"
 },
 "has_gross_income_amount": {
 "data_sourced_from": [
 "01F6N4YSRAQVA8FA1F5MKBYR55"
 ],
 "has_data_extraction_confidence_score": 32.38,
 "has_value": "48500.00"
 },
 "has_income_paid_by_third_parties_indicator": {
 "has_value": "false"
 },
 "has_local_1_income_amount": {
 "has_value": "50000.00"
 },
 "has_local_1_tax_withheld_amount": {
 "has_value": "750.00"
 },
 "has_local_2_income_amount": {
 "has_value": ""
 },
 "has_local_2_tax_withheld_amount": {
 "has_value": ""
 },
 "has_locality_1_name": {
 "has_value": "MU"
 },
 "has_locality_2_name": {
 "has_value": ""
 },
 "has_medicare_income_amount": {
 "has_value": "50000.00"
 },
 "has_medicare_tax_withheld_amount": {
 "has_value": "725.00"
 },
 "has_nonqualified_retirement_plan_distribution_amount": {
 "has_value": ""
 },
 "has_social_security_income_amount": {
 "has_value": "50000.00"
 },
 "has_social_security_tax_withheld_amount": {
 "has_value": "3100.00"
 },
 "has_social_security_tips_amount": {
 "has_value": "600.00"
 },
 "has_state_1_income_amount": {
 "data_sourced_from": [
 "01F6N4YSRAQVA8FA1F5MKBYR55"
 ],
 "has_data_extraction_confidence_score": 76.68,
 "has_value": "50000.00"
 },
 "has_state_1_tax_withheld_amount": {
 "has_value": "1535.00"
 },
 "has_state_2_income_amount": {
 "has_value": ""
 },
 "has_state_2_tax_withheld_amount": {
 "has_value": ""
 }
 }
 ],
 "mortgage_products": [
 {
 "@id": "01F6N4YSXSN7Y010QW2AG4M70W",
 "@type": "data_extraction",
 "product_used_for": [
 "01F6N4YSRAQVA8FA1F5MKBYR55"
 ]
 }
 ],
 "organizations": [
 {
 "@id": "01F6N4YSTM8EWPM80PFYJA15JP",
 "@type": "organization",
 "has_organization_identifier": "23-5247235",
 "has_organization_name": {
 "has_value": "AMAZON , INC."
 },
 "with_address": [
 "01F6N4YSTP8PRC75SBT40JH0CM"
 ]
 }
 ]
 }
}
Exclude relationships

Let's remove borrower and everything connected, except his adress. To do this, we need to specify with_address relationship in exclude_relationships field

{
 "op": "remove",
 "element_id": "01F6N4YSSNTBT17Q5BXDD7R19Q",
 "exclude_relationships": [
 "with_address"
 ]
}

Output:

{
 "metadata": {
 "version": 2
 },
 "data": {
 "addresses": [
 {
 "@id": "01F6N4YSSFY8EB5RAY0XNCQ7XD",
 "@type": "address",
 "has_address_line_1_text": {
 "has_value": "1234 MAIN STREET"
 },
 "has_address_line_2_text": {
 "has_value": "SUITE 30"
 },
 "has_city_name": {
 "has_value": "LOS ANGELES"
 },
 "has_full_address_text": {
 "has_value": "1234 Main St, Suite 30, Los Angeles, CA 90210"
 },
 "has_postal_code": {
 "has_value": "90210"
 },
 "has_state_code": {
 "has_value": "CA"
 }
 },
 {
 "@id": "01F6N4YSTP8PRC75SBT40JH0CM",
 "@type": "address",
 "has_address_line_1_text": {
 "has_value": "410 TERRY AVE. NORTH"
 },
 "has_address_line_2_text": {
 "has_value": ""
 },
 "has_city_name": {
 "has_value": "SEATTLE"
 },
 "has_full_address_text": {
 "has_value": "None"
 },
 "has_postal_code": {
 "has_value": "98109"
 },
 "has_state_code": {
 "has_value": "WA"
 }
 }
 ],
 "documents": [
 {
 "@id": "01F6N4YSRAQVA8FA1F5MKBYR55",
 "@type": "irs_w2",
 "has_data_owner_document_identifer": {
 "has_value": "None"
 },
 "has_document_data_extraction_confidence_score": {
 "has_value": 72.453
 },
 "has_document_identifier": {
 "has_value": "z354-43431"
 },
 "has_instance_identifier": {
 "has_value": "z354-43431"
 }
 }
 ],
 "mortgage_products": [
 {
 "@id": "01F6N4YSXSN7Y010QW2AG4M70W",
 "@type": "data_extraction",
 "product_used_for": [
 "01F6N4YSRAQVA8FA1F5MKBYR55"
 ]
 }
 ]
 }
}
Query

All capabilities mentioned eariler can be used with query mechanism. Instead of element_id you just need to provide query in the same format as in Query on Collection Level endpoint. With qeury you can remove either elements or proeprties.

Elements example:

{
 "op": "remove",
 "query": {
 "format": "jmespath",
 "query": "people[?\"@type\" == 'borrower'].with_address[] | [?\"@type\" == 'mailing_address']"
 }
}

Properties example:

{
 "op": "remove",
 "query": {
 "format": "jsonpath",
 "query": "$.people[?(@['@type'] = 'borrower')].with_address[?(@['@type'] = 'mailing_address')].has_city_name"
 }
}
Request
application/json

Simple request

{
  "element_id": "01F6N4YSTM8EWPM80PFYJA15JP",
  "op": "remove"
}
Response
application/json

New collection

{
  "transaction_id": "01FJCADX5QEXEDVRWNXAK206MA",
  "collection_id": "01FJCAQW7EYJAA6FY05WRKRM3T",
  "metadata": {
    "version": 2
  },
  "data": {
    "people": [
      {
        "@type": "borrower",
        "@id": "01FDF04MYHEZ98AD7T8ZGY5CMB",
        "has_first_name": {
          "has_value": "John"
        },
        "has_last_name": {
          "has_value": "Deere"
        },
        "has_birth_date": {
          "has_value": "01/01/1985"
        },
        "has_taxpayer_identifier_value": {
          "has_value": "999-00-0000"
        },
        "contact_at": [
          "01FDF09BNQCT03DCAX7M5KM52T"
        ],
        "employed_as": [
          "01FDF0DFYAHBRJGFA5RS26HVP1"
        ]
      }
    ],
    "addresses": [
      {
        "@id": "01FDF077N6V7R2RNC64DGT31DY",
        "@type": "business_address",
        "has_address_line_1_text": {
          "has_value": "33 IRVING PLACE",
          "data_sourced_from": [
            "01FDF10040SA2VTETKJQXJ3MQZ"
          ]
        },
        "has_address_line_2_text": {
          "has_value": "additional_line_text",
          "data_sourced_from": [
            "01FDF10040SA2VTETKJQXJ3MQZ"
          ]
        },
        "has_city_name": {
          "has_value": "NEW YORK",
          "data_sourced_from": [
            "01FDF10040SA2VTETKJQXJ3MQZ"
          ]
        },
        "has_postal_code": {
          "has_value": "10003",
          "data_sourced_from": [
            "01FDF10040SA2VTETKJQXJ3MQZ"
          ]
        },
        "has_country_name": {
          "has_value": "US",
          "data_sourced_from": [
            "01FDF10040SA2VTETKJQXJ3MQZ"
          ]
        }
      }
    ],
    "contact_information": [
      {
        "@type": "contact_information",
        "@id": "01FDF09BNQCT03DCAX7M5KM52T",
        "has_phone_number": {
          "has_value": "+1234567890"
        }
      }
    ],
    "employment": [
      {
        "@type": "employment",
        "@id": "01FDF0DFYAHBRJGFA5RS26HVP1",
        "has_employment_position_description": {
          "has_value": "Engineer",
          "data_sourced_from": [
            "01FDF10040SA2VTETKJQXJ3MQZ"
          ]
        },
        "provided_by": [
          "01FDF0G4BP9AE6B7FT5VDEWK5F"
        ]
      }
    ],
    "organizations": [
      {
        "@type": "organization",
        "@id": "01FDF0G4BP9AE6B7FT5VDEWK5F",
        "has_organization_name": {
          "has_value": "GRAIN PROCESSING COR",
          "data_sourced_from": [
            "01FDF10040SA2VTETKJQXJ3MQZ"
          ]
        },
        "has_transaction_identifier": {
          "has_value": "e171ec31-75b4-4fd6-ada1",
          "data_sourced_from": [
            "01FDF10040SA2VTETKJQXJ3MQZ"
          ]
        },
        "with_address": [
          "01FDF077N6V7R2RNC64DGT31DY"
        ]
      }
    ],
    "mortgage_products": [
      {
        "@type": "employment",
        "@id": "01FDF10040SA2VTETKJQXJ3MQZ",
        "has_data_source_date": {
          "has_value": "01/01/1972"
        },
        "has_purpose_of_verification_description": {
          "has_value": "risk-assessment"
        }
      }
    ],
    "documents": [
      {
        "@type": "irs_w2",
        "has_staircase_document_category_type": {
          "has_value": "staircase"
        },
        "has_document_description": {
          "has_value": "Employment Verification Report prepared by Staircase"
        },
        "has_document_mime_type": {
          "has_value": "application/pdf"
        },
        "has_document_name": {
          "has_value": "01FD9X8V5N804Y0CFWY7F72ZCD.pdf"
        }
      }
    ]
  }
}
Parameters
3
ParameterTypeExampleDescription
transaction_id required string (ulid) path 01FJCADX5QEXEDVRWNXAK206MA Transaction ID
collection_id required string (ulid) path 01FJCAQW7EYJAA6FY05WRKRM3T Collection ID
x-sc-trace-id required string header 01FJCADX5QEXEDVRWNXAK206MA Trace ID of the transaction
Request bodyapplication/json
4 fields
FieldTypeDescription
opstringRemoveremove
element_idstringElement ID
exclude_relationshipsstring[]Relationships to exclude
queryobjectquery
formatstringQuery format.jmespathjsonpath
querystringQuery.
Response 200application/json
4 fields

New collection

FieldTypeDescription
transaction_idstring (ulid)Transaction idExample 01EZQ32PJQGKRA6HR8D72Q9FFF
collection_idstring (ulid)Collection idExample 01EZQ32PJQGKRA6HR8D72Q9FFF
dataobjectData in Staircase language schema
metadataobjectMetadata about collection, f.e version of used Staircase schema. Maximum allowable length of the dumped json object - 400 000 symbols.
Response 400application/json
1 fields

Request data failed validation

FieldTypeDescription
messageone ofMessage
Response 403application/json
1 fields

Missing API key

FieldTypeDescription
messagestringMessage
Response 404application/json
1 fields

Requested resource not found

FieldTypeDescription
messagestringMessage
Response 429application/json
1 fields

The user has sent too many requests in a given amount of time ("rate limiting")

FieldTypeDescription
messagestringMessage

Triggers

POST /triggers

Create Trigger

create_trigger

Create trigger

Create a trigger with specific condition as a JMESPath expression. The condition is evaluated on every create/update action with the collections. If the condition is true, the webhook is triggered. The webhook request is sent in Cloudevents format and request contains x-api-key header with the api key of the environment, with collection_id, transaction_id, trigger and transaction label in data. Trigger might be configured to work for validated collections only by setting "valid_collections_only": true. In this case, the trigger is triggered only if collection has "validation": true in the metadata.

Request
application/json
{
  "trigger_name": "example_trigger",
  "condition": "contains(locations[].name, 'Some name')",
  "webhook_url": "https://example.com/webhook",
  "transaction_label": "example_transaction",
  "valid_collections_only": true
}
Response
application/json

Trigger created

{
  "trigger_id": 52341234,
  "trigger_name": "example_trigger",
  "condition": "contains(locations[].name, 'Some name')",
  "webhook_url": "https://example.com/webhook",
  "transaction_label": "example_transaction",
  "valid_collections_only": true
}
Request bodyapplication/json
5 fields
FieldTypeDescription
trigger_namerequiredstringName of the triggerExample name
conditionrequiredstringCondition as jmespath query that returns a boolean responseExample contains(locations[].name, 'Some name')
webhook_urlrequiredstring (uri)Webhook URLExample https://webhook.site/5f9b1b1f-1b1f-5f9b-1b1f-5f9b1b1f5f9b
transaction_labelstringTransaction label to filter transactions with labelExample optional_label
valid_collections_onlybooleanFlag defining if the trigger is triggered only for collections with `"validation": true` in the `metadata`.Example true
Response 201application/json
6 fields

Trigger created

FieldTypeDescription
trigger_namerequiredstringName of the triggerExample name
conditionrequiredstringCondition as jmespath query that returns a boolean responseExample contains(locations[].name, 'Some name')
webhook_urlrequiredstring (uri)Webhook URLExample https://webhook.site/5f9b1b1f-1b1f-5f9b-1b1f-5f9b1b1f5f9b
transaction_labelstringTransaction label to filter transactions with labelExample optional_label
valid_collections_onlybooleanFlag defining if the trigger is triggered only for collections with `"validation": true` in the `metadata`.Example true
trigger_idrequiredstringID of the triggerExample 5f9b1b1f-1b1f-5f9b-1b1f-5f9b1b1f5f9b
Response 400application/json
2 fields

Request data failed validation

FieldTypeDescription
detailedMessagestringMessage
codestringCode
Response 403application/json
1 fields

Missing API key

FieldTypeDescription
messagestringMessage
Response 409application/json
1 fields

Conflict

FieldTypeDescription
messagestringMessage
Other responses

422500

DELETE /triggers/{trigger_id}

Delete Trigger

delete_trigger

Delete trigger

Response
application/json

Request data failed validation

{
  "detailedMessage": "Bad request exception"
}
Parameters
1
ParameterTypeExampleDescription
trigger_id required string path 52341234-1234-1234-1234-123412341234 Trigger ID
Response 400application/json
2 fields

Request data failed validation

FieldTypeDescription
detailedMessagestringMessage
codestringCode
Response 403application/json
1 fields

Missing API key

FieldTypeDescription
messagestringMessage
Response 404application/json
1 fields

Requested resource not found

FieldTypeDescription
messagestringMessage
Other responses

204422500

PATCH /triggers/{trigger_id}

Patch Trigger

patch_trigger

Patch trigger

Patch trigger with an JSON Patch format object. Remove operation limitations:

  • Supported only for transaction_label field.
Request
application/json
[
  {
    "op": "replace",
    "path": "trigger_name",
    "value": "example_trigger"
  },
  {
    "op": "replace",
    "path": "condition",
    "value": "contains(locations[].name, 'Some name')"
  },
  {
    "op": "replace",
    "path": "webhook_url",
    "value": "https://example.com/webhook"
  },
  {
    "op": "remove",
    "path": "transaction_label"
  }
]
Response
application/json

Patched trigger object

{
  "trigger_id": 52341234,
  "trigger_name": "example_trigger",
  "condition": "contains(locations[].name, 'Some name')",
  "webhook_url": "https://example.com/webhook",
  "transaction_label": "example_transaction"
}
Parameters
1
ParameterTypeExampleDescription
trigger_id required string path 52341234-1234-1234-1234-123412341234 Trigger ID
Response 200application/json
6 fields

Patched trigger object

FieldTypeDescription
trigger_namerequiredstringName of the triggerExample name
conditionrequiredstringCondition as jmespath query that returns a boolean responseExample contains(locations[].name, 'Some name')
webhook_urlrequiredstring (uri)Webhook URLExample https://webhook.site/5f9b1b1f-1b1f-5f9b-1b1f-5f9b1b1f5f9b
transaction_labelstringTransaction label to filter transactions with labelExample optional_label
valid_collections_onlybooleanFlag defining if the trigger is triggered only for collections with `"validation": true` in the `metadata`.Example true
trigger_idrequiredstringID of the triggerExample 5f9b1b1f-1b1f-5f9b-1b1f-5f9b1b1f5f9b
Response 400application/json
2 fields

Request data failed validation

FieldTypeDescription
detailedMessagestringMessage
codestringCode
Response 403application/json
1 fields

Missing API key

FieldTypeDescription
messagestringMessage
Response 404application/json
1 fields

Requested resource not found

FieldTypeDescription
messagestringMessage
Other responses

422500

GET /triggers

List Triggers

list_triggers

List triggers

List triggers and query specific filter with a trigger_id or trigger_name parameter in query string. Filtering with trigger_name return all triggers that match trigger_name, else an empty array. Querying with trigger_id returns Not Found if trigger with specific id does not exist.

Response
application/json

Triggers listed

[
  {
    "trigger_id": 52341234,
    "trigger_name": "example_trigger",
    "condition": "contains(locations[].name, 'Some name')",
    "webhook_url": "https://example.com/webhook",
    "transaction_label": "example_transaction"
  }
]
Parameters
2
ParameterTypeExampleDescription
trigger_id string query 52341234-1234-1234-1234-123412341234 Trigger id
trigger_name string query example_trigger Trigger name
Response 400application/json
2 fields

Request data failed validation

FieldTypeDescription
detailedMessagestringMessage
codestringCode
Response 403application/json
1 fields

Missing API key

FieldTypeDescription
messagestringMessage
Response 404application/json
1 fields

Requested resource not found

FieldTypeDescription
messagestringMessage
Other responses

200422500

Operations

GET /data-share/public-key
Response 200application/json
1 fields

OK Response

FieldTypeDescription
public_keystring
POST /data-share/share
Request bodyapplication/json
3 fields
FieldTypeDescription
transaction_idrequiredstring
collection_idrequiredstring
to_public_keyrequiredstring
Response 200application/json
1 fields

OK response

FieldTypeDescription
share_idstring
GET /data-share/shared

List of colelctions, that was sahred with you

Response 200application/json
1 fields

OK response

FieldTypeDescription
collectionsobject[]
transaction_idstring
collection_idstring
share_idstring

Errors

400403404406409413422429500

Type to search.