# Persistence # 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 Pdf file uploadJpg file upload application/json Copy ``` { "extension": ".pdf", "presign_url_ttl": 30 } ``` application/json Copy ``` { "extension": ".jpg", "blob_name": "image.jpg" } ``` ##### Response 201400 application/json Copy 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" } } } ``` application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` ##### Request body`application/json` 3 fields | Field | Type | Description | | --- | --- | --- | | `extension`required | `string` | Extension of file, that blob is persistingExample `.pdf` | | `presign_url_ttl` | `integer` | TTL of presigned url in seconds, default is 3600 | | `blob_name` | `string` | Name for blob | ##### Response `201``application/json` 6 fields Blob has been created | Field | Type | Description | | --- | --- | --- | | `blob_id` | `string (ulid)` | Blob idExample `01EZQ32PJQGKRA6HR8D72Q9FFF` | | `extension` | `string` | Extension of file, that blob is persistingExample `.pdf` | | `presigned_urls` | `object` | Presigned urls for uploading or downloading file | | `upload` | `object` | Presigned url | | `url` | `string (uri)` | Presigned urlExample `https://api-data-manager-blobs-bucket.s3.amazonaws.com/00c8c9e5-dfdd-44c5-a57e-8de7a2672e2e` | | `page_count` | `integer` | Number of pages present, if the file persisted is a PDF. | | `content_length` | `integer` | Size of the file being persisted. | | `blob_name` | `string` | Blob name | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `one of` | Message | ##### Response `403``application/json` 1 fields Missing API key | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `429``application/json` 1 fields The user has sent too many requests in a given amount of time ("rate limiting") | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | `PUT` `/blobs/{blob_id}/presigned-urls/{action}` #### Create Blob Presigned URL `generate_presigned_url` Generate new presigned url ##### Request application/json Copy ``` { "presign_url_ttl": 3600 } ``` ##### Response 200400404 application/json Copy New presigned url ``` { "url": "https://api-data-manager-blobs-bucket.s3.amazonaws.com/8c561841-6671-412e-a356-523460ba0d8d" } ``` application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy Requested resource not found ``` { "message": "Collection not found" } ``` ##### Parameters 3 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `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 body`application/json` 1 fields | Field | Type | Description | | --- | --- | --- | | `presign_url_ttl` | `integer` | TTL of presigned url in seconds, default is 3600 | ##### Response `200``application/json` 1 fields New presigned url | Field | Type | Description | | --- | --- | --- | | `url` | `string (uri)` | Presigned urlExample `https://api-data-manager-blobs-bucket.s3.amazonaws.com/00c8c9e5-dfdd-44c5-a57e-8de7a2672e2e` | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `one of` | Message | ##### Response `403``application/json` 1 fields Missing API key | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `404``application/json` 1 fields Requested resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `429``application/json` 1 fields The user has sent too many requests in a given amount of time ("rate limiting") | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | `GET` `/blobs/{blob_id}` #### Retrieve Blob `get_blob` Retrieve Blob instance: extension, last created presigned urls, page count and content length ##### Response 200400404 application/json Copy 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 } ``` application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy Requested resource not found ``` { "message": "Collection not found" } ``` ##### Parameters 2 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `blob_id` required | `string (ulid)` path | `01FJCA39TSCHS6Q8K69FEEMQZQ` | Blob id | | `x-sc-trace-id` required | `string` header | `01FJCADX5QEXEDVRWNXAK206MA` | Trace ID of the transaction | ##### Response `200``application/json` 4 fields Blob instance with last created presigned urls | Field | Type | Description | | --- | --- | --- | | `blob_id` | `string (ulid)` | Blob idExample `01EZQ32PJQGKRA6HR8D72Q9FFF` | | `extension` | `string` | Extension of file, that blob is persistingExample `.pdf` | | `presigned_urls` | `object` | Presigned urls for uploading or downloading file | | `download` | `object` | Presigned url | | `url` | `string (uri)` | Presigned urlExample `https://api-data-manager-blobs-bucket.s3.amazonaws.com/00c8c9e5-dfdd-44c5-a57e-8de7a2672e2e` | | `upload` | `object` | Presigned url | | `url` | `string (uri)` | Presigned urlExample `https://api-data-manager-blobs-bucket.s3.amazonaws.com/00c8c9e5-dfdd-44c5-a57e-8de7a2672e2e` | | `blob_name` | `string` | Blob name | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `one of` | Message | ##### Response `403``application/json` 1 fields Missing API key | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `404``application/json` 1 fields Requested resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `429``application/json` 1 fields The user has sent too many requests in a given amount of time ("rate limiting") | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Other responses `422` `GET` `/blobs/{blob_id}/presigned-urls` #### Retrieve Blob Presigned URLs `get_preassigned_urls` ##### Response 200400404 application/json Copy 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" } } ``` application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy Requested resource not found ``` { "message": "Collection not found" } ``` ##### Parameters 2 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `blob_id` required | `string (ulid)` path | `01FJCA39TSCHS6Q8K69FEEMQZQ` | Blob id | | `x-sc-trace-id` required | `string` header | `01FJCADX5QEXEDVRWNXAK206MA` | Trace ID of the transaction | ##### Response `200``application/json` 2 fields Presigned urls | Field | Type | Description | | --- | --- | --- | | `download` | `object` | Presigned url | | `url` | `string (uri)` | Presigned urlExample `https://api-data-manager-blobs-bucket.s3.amazonaws.com/00c8c9e5-dfdd-44c5-a57e-8de7a2672e2e` | | `upload` | `object` | Presigned url | | `url` | `string (uri)` | Presigned urlExample `https://api-data-manager-blobs-bucket.s3.amazonaws.com/00c8c9e5-dfdd-44c5-a57e-8de7a2672e2e` | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `one of` | Message | ##### Response `403``application/json` 1 fields Missing API key | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `404``application/json` 1 fields Requested resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `429``application/json` 1 fields The user has sent too many requests in a given amount of time ("rate limiting") | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | `GET` `/blobs/{blob_id}/presigned-urls/{action}` #### Retrieve Presigned URL for Action `get_presigned_url` Get presigned url ##### Response 200400404 application/json Copy Presigned url ``` { "url": "https://api-data-manager-blobs-bucket.s3.amazonaws.com/8c561841-6671-412e-a356-523460ba0d8d" } ``` application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy Requested resource not found ``` { "message": "Collection not found" } ``` ##### Parameters 3 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `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 `200``application/json` 1 fields Presigned url | Field | Type | Description | | --- | --- | --- | | `url` | `string (uri)` | Presigned urlExample `https://api-data-manager-blobs-bucket.s3.amazonaws.com/00c8c9e5-dfdd-44c5-a57e-8de7a2672e2e` | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `one of` | Message | ##### Response `403``application/json` 1 fields Missing API key | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `404``application/json` 1 fields Requested resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `429``application/json` 1 fields The user has sent too many requests in a given amount of time ("rate limiting") | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ### 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 Merge selected collections in transactionMerge all collections in transaction application/json Copy ``` { "transaction_id": "01GSWRGPWD2C5SYPAN8TS4ZADJ", "collection_ids": [ "01GSWRQXKK7AHPH4XG4DRHYXSZ", "01GSWS0PY75NFRHBFA4ERTFMD8" ] } ``` application/json Copy ``` { "transaction_id": "01GSWRGPWD2C5SYPAN8TS4ZADJ" } ``` ##### Response 200400 application/json Copy 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" ] } ] } } ``` application/json Copy Request data invalid ``` { "message": "Request body is not valid JSON." } ``` ##### Request body`application/json` 2 fields | Field | Type | Description | | --- | --- | --- | | `transaction_id`required | `string` | ID of transaction to merge.Example `01GSWRGPWD2C5SYPAN8TS4ZADJ` | | `collection_ids` | `string[]` | Array of collection IDs to merge. | ##### Response `200``application/json` 1 fields Ok. | Field | Type | Description | | --- | --- | --- | | `merge_result`required | `object` | Merged collections | ##### Response `400``application/json` 1 fields Request data invalid | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error 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_only`flag. 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 over`latest_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. 1. Pipe Expressions for JMESPATH not available. 1. No multiple logical conditions for JMESPATH. 1. No functions for JMESPATH. If you need this feature, please open Customer Request to us. ##### Request First person in people array with has_first_name equals VladFirst person in people array with has_first_name equals Vlad Only latest collectionsFirst person in people array with has_first_name equals Vlad Second PageFirst person in people array with has_first_name equals Vlad inside transactions labeled as prodFirst person in people array with has_first_name equals Vlad jmespathAll people with has_credit_score between 400 and 500All people with first name Vlad and last name KNested filters, find peoples with name Vlad that lives in New York city NY statestartswithcontainsnegtgteltlteandand_orCombine JSONPATH and JMESPATHPaginated requestlimittotal_count application/json Copy ``` { "query": { "path": { "path": "$.people[0].has_first_name.has_value", "format": "jsonpath" }, "operation": "eq", "value": "Vlad" } } ``` application/json Copy ``` { "query": { "path": { "path": "$.people[0].has_first_name.has_value", "format": "jsonpath" }, "operation": "eq", "value": "Vlad" }, "latest_collections_only": true } ``` application/json Copy ``` { "query": { "path": { "path": "$.people[0].has_first_name.has_value", "format": "jsonpath" }, "operation": "eq", "value": "Vlad" }, "page": 1, "next_token": "7b22637265617465645f6174223a2022323032332d30322d32325431383a31333a32352e3834373236372b30323a3030222c20226f6666736574223a20313030307d" } ``` application/json Copy ``` { "query": { "path": { "path": "$.people[0].has_first_name.has_value", "format": "jsonpath" }, "operation": "eq", "value": "Vlad" }, "transaction_label": "prod" } ``` application/json Copy ``` { "query": { "path": { "path": "people[0].has_first_name.has_value", "format": "jmespath" }, "operation": "eq", "value": "Vlad" } } ``` application/json Copy ``` { "query": { "path": { "path": "$.people[*].has_credit_score.has_value", "format": "jsonpath" }, "operation": "between", "value": [ 400, 500 ] } } ``` application/json Copy ``` { "query": { "path": { "path": "$.people[?(@.has_first_name.has_value = 'Vlad')].has_last_name.has_value", "format": "jsonpath" }, "operation": "eq", "value": "K" } } ``` application/json Copy ``` { "query": { "path": { "path": "$.people[?(@.has_first_name.has_value = 'Vlad')].with_addresses[?(@.has_city_name.has_value = 'New York')].has_state_name.has_value", "format": "jsonpath" }, "operation": "eq", "value": "NY" } } ``` application/json Copy ``` { "query": { "path": { "path": "$.people[*].with_addresses[*].has_state_name.has_value", "format": "jsonpath" }, "operation": "startswith", "value": "N" } } ``` application/json Copy ``` { "query": { "path": { "path": "$.people[*].has_last_name.has_value", "format": "jsonpath" }, "operation": "contains", "value": "mik" } } ``` application/json Copy ``` { "query": { "path": { "path": "$.people[*].has_credit_score.has_value", "format": "jsonpath" }, "operation": "ne", "value": 200 } } ``` application/json Copy ``` { "query": { "path": { "path": "$.people[*].has_credit_score.has_value", "format": "jsonpath" }, "operation": "gt", "value": 200 } } ``` application/json Copy ``` { "query": { "path": { "path": "$.people[*].has_credit_score.has_value", "format": "jsonpath" }, "operation": "gte", "value": 200 } } ``` application/json Copy ``` { "query": { "path": { "path": "$.people[*].has_credit_score.has_value", "format": "jsonpath" }, "operation": "lt", "value": 200 } } ``` application/json Copy ``` { "query": { "path": { "path": "$.people[*].has_credit_score.has_value", "format": "jsonpath" }, "operation": "lte", "value": 200 } } ``` application/json Copy ``` { "query": { "and": [ { "path": { "path": "$.people[*].has_credit_score.has_value", "format": "jsonpath" }, "operation": "eq", "value": 200 }, { "and": [ { "path": { "path": "$.people[*].has_first_name.has_value", "format": "jsonpath" }, "operation": "eq", "value": "Bob" }, { "path": { "path": "$.people[*].has_last_name.has_value", "format": "jsonpath" }, "operation": "eq", "value": "Odenkirk" } ] } ] } } ``` application/json Copy ``` { "query": { "or": [ { "path": { "path": "$.people[*].has_credit_score.has_value", "format": "jsonpath" }, "operation": "eq", "value": 200 }, { "and": [ { "path": { "path": "$.people[*].has_first_name.has_value", "format": "jsonpath" }, "operation": "eq", "value": "Bob" }, { "path": { "path": "$.people[*].has_last_name.has_value", "format": "jsonpath" }, "operation": "eq", "value": "Odenkirk" } ] } ] } } ``` application/json Copy ``` { "query": { "and": [ { "or": [ { "path": { "path": "people[*].has_credit_score.has_value", "format": "jmespath" }, "operation": "eq", "value": 200 }, { "path": { "path": "$.people[*].has_last_name.has_value", "format": "jsonpath" }, "operation": "eq", "value": "K" } ] }, { "and": [ { "path": { "path": "$.people[*].has_first_name.has_value", "format": "jsonpath" }, "operation": "eq", "value": "Bob" }, { "path": { "path": "$.people[*].has_last_name.has_value", "format": "jsonpath" }, "operation": "eq", "value": "Odenkirk" } ] } ] } } ``` application/json Copy ``` { "query": { "path": { "path": "$.people[0].has_first_name.has_value", "format": "jsonpath" }, "operation": "eq", "value": "Vlad" }, "next_token": "7b22637265617465645f6174223a2022323032332d30322d32325431383a31333a32352e3834373236372b30323a3030222c20226f6666736574223a20313030307d" } ``` application/json Copy ``` { "query": { "path": { "path": "$.people[0].has_first_name.has_value", "format": "jsonpath" }, "operation": "eq", "value": "Vlad" }, "limit": 150 } ``` application/json Copy ``` { "query": { "path": { "path": "$.people[0].has_first_name.has_value", "format": "jsonpath" }, "operation": "eq", "value": "Vlad" }, "include_total_count": true } ``` ##### Response 200400 application/json Copy Ok. ``` { "query_result": [ { "transaction_id": "01GSD62EEBT4YD1Y0W6GFVA4EB", "collection_id": "01GSD68Z48JRJK8MM4YYRCTH3D" }, { "transaction_id": "01GSD62EEBT4YD1Y0W6GFVA4EB", "collection_id": "01GSD6AC2XH7QW4N8RE67QB0Z9" } ], "next_token": "7b22637265617465645f6174223a2022323032332d30322d32325431383a31333a32352e3834373236372b30323a3030222c20226f6666736574223a20313030307d", "total_count": 42 } ``` application/json Copy Request data invalid ``` { "message": "Invalid path. Reason: Invalid JSONPATH." } ``` ##### Request body`application/json` 11 fields | Field | Type | Description | | --- | --- | --- | | `query`required | `object` | JSONPath query | | `path`required | `object` | The location of data for query | | `path`required | `string` | The query path. Must be valid JSONPATH or JMESPATH. | | `format`required | `string` | The query format in use`JMESPATH``JSONPATH` | | `operation`required | `string` | Operation`BETWEEN``CONTAINS``EQ``GT``GTE``LT``LTE``NE``STARTSWITH` | | `value`required | `string` | What value to query against. | | `next_token` | `string` | Next token from the response body.Example `7b22637265617465645f6174223a2022323032332d30322d32325431383a31333a32352e3834373236372b30323a3030222c20226f6666736574223a20313030307d` | | `limit` | `integer` | Limits how many results should be in the response.Example `100` | | `transaction_label` | `string` | If provided, include only the transactions with the provided 'transaction_label'.Example `my_label` | | `transaction_ids` | `string[]` | If provided, include only the transactions with the provided 'transaction_ids'. | | `echo` | `boolean` | If provided, response will include `raw_query` key.Example `true` | | `sort` | `string` | If provided, response will be sorted asc or desc.`ASC``DESC`Example `DESC` | | `include_total_count` | `boolean` | 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. | | `page` | `integer` | Optional parameter to specify the page of data to retrieve. Must be used with the "next_token" parameter. | | `latest_collections_only` | `boolean` | If true, only return the latest collection from each transaction.Example `true` | | `use_sug` | `boolean` | If true, collections are searched in SUG.Example `true` | ##### Response `200``application/json` 3 fields Ok. | Field | Type | Description | | --- | --- | --- | | `query_result`required | `object[]` | Array of transaction and collection IDs pair | | `transaction_id`required | `string` | Transaction IDExample `01GSD62EEBT4YD1Y0W6GFVA4EB` | | `collection_id`required | `string` | Collection IDExample `01GSD6AC2XH7QW4N8RE67QB0Z9` | | `next_token`required | `string` | Next 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_query` | `string` | The raw SPARQL Query that was executed. Useful for debug. Only available if request body parameter echo is true.Example `PREFIX sci: PREFIX sc: PREFIX rdf: PREFIX xsd: 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 `400``application/json` 1 fields Request data invalid | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error 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 Copy Request data failed validation ``` { "detailedMessage": "Malformed query", "code": "MalformedQueryException" } ``` ##### Parameters 3 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `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 `200``application/sparql-results+json` 3 fields queried | Field | Type | Description | | --- | --- | --- | | `head` | `object` | The head of the result set. | | `vars` | `string[]` | The variables in the result set. | | `results` | `object` | The results of the query. | | `bindings` | `object[]` | The bindings of the results. | | `boolean` | `boolean` | The boolean result of the query. Used in ASK query | ##### Response `400``application/json` 2 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `detailedMessage` | `string` | Message | | `code` | `string` | Exception Code in Neptune format | ##### Response `403``application/json` 1 fields Missing API key | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Other responses `406``422``500` ### Typesense `GET` `/health` #### Health check `health_check` ##### Response application/json Copy OK response ``` { "ok": true } ``` ##### Response `200``application/json` 1 fields OK response | Field | Type | Description | | --- | --- | --- | | `ok` | `boolean` | Health 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 Copy ``` { "name": "borrower_ssn", "path": { "path": "$.people[?(@['@type'] == 'borrower')].has_taxpayer_identifier_value.has_value", "format": "jsonpath" } } ``` ##### Response application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` ##### Request body`application/json` 4 fields | Field | Type | Description | | --- | --- | --- | | `name`required | `string` | Name of the Index | | `many` | `boolean` | Flag 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. | | `path`required | `object` | The location of data to be indexed | | `path`required | `string` | The query path | | `format`required | `string` | The query format in use`jmespath``jsonpath` | | `transaction_labels` | `string[]` | The list of transaction labels, which collections need to be captured in the index | ##### Response `201``application/json` 3 fields created | Field | Type | Description | | --- | --- | --- | | `name`required | `string` | Name of the Index | | `many` | `boolean` | Flag 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. | | `path`required | `object` | The location of data to be indexed | | `path`required | `string` | The query path | | `format`required | `string` | The query format in use`jmespath``jsonpath` | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `one of` | Message | ##### Response `403``application/json` 1 fields Missing API key | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### 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 400404 application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy Requested resource not found ``` { "message": "Collection not found" } ``` ##### Parameters 1 | Parameter | Type | Description | | --- | --- | --- | | `filter` | `string` query | Filter by one of the index_name or created_at fields. | ##### Response `200``application/json` 3 fields Index | Field | Type | Description | | --- | --- | --- | | `indexes` | `array` | List of indexes | | `_links` | `object` | Links to next page of results | | `next` | `string` | Link to next page of results | | `next_token` | `string` | Pagination token for next page | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `one of` | Message | ##### Response `403``application/json` 1 fields Missing API key | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `404``application/json` 1 fields Requested resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Other responses `422` `DELETE` `/indexes/{index_name}` #### Delete Index `delete_index` Delete an index ##### Response 200404 application/json Copy Index ``` { "message": "Index deleted" } ``` application/json Copy Requested resource not found ``` { "message": "Collection not found" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `index_name` required | `string` path | `my_index` | The name of the index | ##### Response `200``application/json` 1 fields Index | Field | Type | Description | | --- | --- | --- | | `message` | `string` | MessageExample `Index deleted` | ##### Response `404``application/json` 1 fields Requested resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | `GET` `/indexes/{index_name}` #### Retrieve Index `get_index` Retrieve an index ##### Response 200400404 application/json Copy Index ``` { "name": "borrower_ssn", "path": { "path": "$.people[@['@type'] == 'borrower'].has_taxpayer_identifier_value.has_value", "format": "jsonpath" } } ``` application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy Requested resource not found ``` { "message": "Collection not found" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `index_name` required | `string` path | `my_index` | The name of the index | ##### Response `200``application/json` 6 fields Index | Field | Type | Description | | --- | --- | --- | | `name`required | `string` | The name of the index | | `path`required | `object` | The query location of the indexed data | | `path`required | `string` | Value of the path | | `format`required | `string` | The query format in use`jmespath``jsonpath` | | `created_at` | `string (date-time)` | Date time when index was created. | | `status` | `string` | Status of the index`AVAILABLE``REINDEXING``REINDEXING_FAILED` | | `reindexing_failure_reason` | `string` | Provided if status is "REINDEXING_FAILED". | | `_links` | `object` | Links | | `items` | `string (uri)` | Link to index items | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `one of` | Message | ##### Response `403``application/json` 1 fields Missing API key | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `404``application/json` 1 fields Requested resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | `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 400404 application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy Requested resource not found ``` { "message": "Collection not found" } ``` ##### Parameters 5 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `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 `200``application/json` 3 fields Indexed data | Field | Type | Description | | --- | --- | --- | | `items` | `array` | Items matching the query | | `_links` | `object` | Links to next page of results | | `next` | `string` | Link to next page of results | | `next_token` | `string` | Pagination token for next page | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `one of` | Message | ##### Response `403``application/json` 1 fields Missing API key | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `404``application/json` 1 fields Requested resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### 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 Specific list of transactionsSpecific transaction label application/json Copy ``` { "transaction_ids": [ "01EZQ32NEN5VDHE288WN4TV2D3", "01EZQ32NEN5VDHE288WN4TV2D4" ] } ``` application/json Copy ``` { "transaction_label": "my_transaction_label" } ``` ##### Response 400404409 application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy Requested resource not found ``` { "message": "Collection not found" } ``` application/json Copy Conflict ``` { "message": "Index name 'x' already exists" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `index_name` required | `string` path | `my_index` | The name of the index | ##### Request body`application/json` 2 fields | Field | Type | Description | | --- | --- | --- | | `transaction_ids` | `string[]` | List of transaction ID's which collections will be re-indexed. | | `transaction_label` | `string` | Transaction label, which collections will be re-indexed. | ##### Response `200``application/json` 1 fields created | Field | Type | Description | | --- | --- | --- | | `status` | `string` | New status of the index`REINDEXING` | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `one of` | Message | ##### Response `403``application/json` 1 fields Missing API key | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `404``application/json` 1 fields Requested resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `409``application/json` 1 fields Conflict | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### 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 Complex querySimple query application/json Copy ``` { "or": [ { "and": [ { "index_name": "foo", "operation": "eq", "value": 23 }, { "index_name": "bar", "operation": "startswith", "value": "grate" } ] }, { "index_name": "baz", "operation": "between", "value": [ 20, 35 ] } ] } ``` application/json Copy ``` { "index_name": "foo", "operation": "eq", "value": 23 } ``` ##### Response `200``application/json` 1 fields Successfully queried indexes | Field | Type | Description | | --- | --- | --- | | `results` | `object[]` | List of collections that match the query | | `transaction_id` | `string` | Transaction ID of the collection | | `collection_id` | `string` | Collection ID of the collection | ##### Other responses `422` ### Lexicon `PUT` `/lexicon` #### Import Lexicon `PutLexicon` ##### Request application/json Copy ``` { "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 body`application/json` 1 fields | Field | Type | Description | | --- | --- | --- | | `classes`required | `object[]` | List of classes | | `type`required | `string` | Type of class | | `container_name`required | `string` | Container name | | `is_deprecated`required | `boolean` | Is deprecated | | `deprecated_properties`required | `string[]` | Deprecated properties | | `properties`required | `object` | Properties | | `relationships` | `object` | Relationships | ##### Response `201``application/json` 1 fields Lexicon have been accepted to import | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Lexicon have been accepted to import | ##### Response `400``application/json` 1 fields Lexicon did not passed validation | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error 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 400404 application/json Copy Request data failed validation ``` { "detailedMessage": "Bad request exception" } ``` application/json Copy Requested resource not found ``` { "message": "Configuration not found" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `configuration` required | `string` query | `https://hooks.slack.com/services/ABCZXC/B00000000/ABCZXCJWKM` | The configuration identifier to delete. | ##### Response `400``application/json` 2 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `detailedMessage` | `string` | Message | | `code` | `string` | Code | ##### Response `404``application/json` 1 fields Requested resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Other responses `204` `GET` `/notifications/configurations` #### Configure channel webhook `list_configurations` List Configurations Retrieve a list of notification configurations. ##### Response 200404 application/json Copy List of configurations ``` { "configurations": [ { "slack_webhook_url": "https://hooks.slack.com/services/ABCZXC/B00000000/ABCZXCJWKM" } ] } ``` application/json Copy Requested resource not found ``` { "message": "Configuration not found" } ``` ##### Response `200``application/json` 1 fields List of configurations | Field | Type | Description | | --- | --- | --- | | `configurations` | `object[]` | List of configurations | | `slack_webhook_url` | `string` | Slack webhook URL | ##### Response `404``application/json` 1 fields Requested resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | `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 Copy ``` { "slack_webhook_url": "https://hooks.slack.com/services/ABCZXC/B00000000/ABCZXCJWKM" } ``` ##### Response 201400 application/json Copy Configuration created ``` { "slack_webhook_url": "https://hooks.slack.com/services/ABCZXC/B00000000/ABCZXCJWKM" } ``` application/json Copy Request data failed validation ``` { "detailedMessage": "Bad request exception" } ``` ##### Request body`application/json` 1 fields | Field | Type | Description | | --- | --- | --- | | `slack_webhook_url` | `string (uri)` | Slack webhook URL | ##### Response `201``application/json` 1 fields Configuration created | Field | Type | Description | | --- | --- | --- | | `slack_webhook_url` | `string (uri)` | Slack webhook URL | ##### Response `400``application/json` 2 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `detailedMessage` | `string` | Message | | `code` | `string` | Code | ##### Response `403``application/json` 1 fields Missing API key | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Other responses `422``500` ### 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 Copy ``` { "transaction_id": "01G92FSH5FYKQE6X22FECB95V2", "collection_id": "01G92FSX8A9YXPAMT6V97TH0VZ" } ``` ##### Response 202400 application/json Copy Accepted. ``` { "collection_id": "01G92FWG135BTEMQC3SSMA8Q7A" } ``` application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` ##### Request body`application/json` 3 fields | Field | Type | Description | | --- | --- | --- | | `transaction_id`required | `string` | Transaction ID | | `collection_id`required | `string` | Collection ID | | `options` | `object` | Options | | `callback_url` | `string (url)` | Callback URL | ##### Response `202``application/json` 1 fields Accepted. | Field | Type | Description | | --- | --- | --- | | `collection_id` | `string` | Response collection ID. | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `one of` | Message | ##### Response `403``application/json` 1 fields Missing API key | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Other responses `422` `GET` `/pdf-splitter/invocations` #### List PDF Splitting jobs `list_pdf_splitting_job` Provides the list of splitting jobs. ##### Response 200400 application/json Copy OK. ``` { "invocations": [ { "invocation_id": "01G92FWG135BTEMQC3SSMA8Q7A" }, { "invocation_id": "01G92FWG135BTEMQC3SSMA8Q7B" }, { "invocation_id": "01G92FWG135BTEMQC3SSMA8Q7C" } ] } ``` application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` ##### Response `200``application/json` 2 fields OK. | Field | Type | Description | | --- | --- | --- | | `invocations`required | `object[]` | Invocations list. | | `invocation_id` | `string` | Invocation ID. | | `next_token` | `string` | Token to paginate | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `one of` | Message | ##### Response `403``application/json` 1 fields Missing API key | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | `GET` `/pdf-splitter/invocations/{invocation_id}` #### Get PDF Splitting job `get_pdf_splitting_job` Provides the splitting job information. ##### Response 200404 application/json Copy OK. ``` { "invocations": [ { "invocation_id": "01G92FWG135BTEMQC3SSMA8Q7A" }, { "invocation_id": "01G92FWG135BTEMQC3SSMA8Q7B" }, { "invocation_id": "01G92FWG135BTEMQC3SSMA8Q7C" } ] } ``` application/json Copy Requested resource not found ``` { "message": "Collection not found" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `invocation_id` required | `string` path | `12345` | Invocation ID | ##### Response `200``application/json` 5 fields OK. | Field | Type | Description | | --- | --- | --- | | `status`required | `string` | Job status`ABORTED``FAILED``RUNNING``SUCCEEDED``TIMED_OUT` | | `input`required | `object` | Job input. | | `documents` | `object[]` | Input documents | | `blob_id` | `string` | Blob ID | | `callback_url` | `string (url)` | Callback URL | | `transaction_id`required | `string` | Transaction ID | | `collection_id`required | `string` | Collection ID | | `started_at`required | `string (date-time)` | Datetime when job was started in iso-format. | ##### Response `403``application/json` 1 fields Missing API key | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `404``application/json` 1 fields Requested resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ### 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 200400404 application/json Copy 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 } } ] ``` application/json Copy Request data failed validation ``` { "detailedMessage": "Malformed query", "code": "MalformedQueryException" } ``` application/json Copy Requested resource not found ``` { "message": "Collection not found" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `index_name` | `string` query | `name` | Name of the index | ##### Response `400``application/json` 2 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `detailedMessage` | `string` | Message | | `code` | `string` | Exception Code | ##### Response `403``application/json` 1 fields Missing API key | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `404``application/json` 1 fields Requested resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Other responses `200``422``500` `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 Copy ``` { "index_name": "addresses/has_state_code/has_value" } ``` ##### Response 200400409 application/json Copy queried ``` { "IndexField": { "Status": { "CreationDate": "2023-04-03T01:02:06.541Z", "UpdateDate": "2023-04-03T01:02:06.541Z", "State": "Active" } } } ``` application/json Copy Request data failed validation ``` { "detailedMessage": "Malformed query", "code": "MalformedQueryException" } ``` application/json Copy Conflict ``` { "message": "Index name 'x' already exists" } ``` ##### Request body`application/json` 1 fields | Field | Type | Description | | --- | --- | --- | | `index_name`required | `string` | Name of the indexExample `name` | ##### Response `200``application/json` 1 fields queried | Field | Type | Description | | --- | --- | --- | | `IndexField` | `object` | Index field | | `Status` | `object` | Status | | `CreationDate` | `string` | Creation dateExample `2023-04-03T01:02:06.541Z` | | `UpdateDate` | `string` | Update dateExample `2023-04-03T01:02:06.541Z` | | `State` | `string` | State`Active``FailedToValidate``Processing``RequiresIndexDocuments`Example `Active` | ##### Response `400``application/json` 2 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `detailedMessage` | `string` | Message | | `code` | `string` | Exception Code | ##### Response `403``application/json` 1 fields Missing API key | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `409``application/json` 1 fields Conflict | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Other responses `422``500` `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 SimpleExamplelatest_transaction_collectiontransaction_label application/json Copy ``` { "fields": [ { "field": "addresses/has_state_name/has_value", "value": "CA", "distance": 10, "weight": 0.5 } ] } ``` application/json Copy ``` { "fields": [ { "field": "addresses/has_state_name/has_value", "value": "CA", "distance": 10, "weight": 0.5 } ], "latest_transaction_collection": true } ``` application/json Copy ``` { "fields": [ { "field": "addresses/has_state_name/has_value", "value": "CA", "distance": 10, "weight": 0.5 } ], "transaction_label": "01GZNQYD9H0J2Z57F4JJJTKQ1Q" } ``` ##### Response 200400 application/json Copy Queried response ``` [ { "transaction_id": "01GV5S3SYTEX8QSVEWSPVQHNQS", "score": 0.95, "collection_id": "01GV5S40XNZ47YYASFRE78GXW1" } ] ``` application/json Copy Request data failed validation ``` { "detailedMessage": "Malformed query", "code": "MalformedQueryException" } ``` ##### Request body`application/json` 3 fields | Field | Type | Description | | --- | --- | --- | | `fields`required | `object[]` | List of fields to query | | `field` | `string` | Field to queryExample `addresses/has_state_code/has_value` | | `value` | `string` | Value to queryExample `CA` | | `distance` | `number` | Distance to queryExample `10` | | `weight` | `number` | Weight to queryExample `0.5` | | `latest_transaction_collection` | `boolean` | Whether 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_label` | `string` | When this parameter is set, the search results will only include transactions that have the specified transaction label.Example `my_label` | ##### Response `200``application/json` 3 fields Queried response | Field | Type | Description | | --- | --- | --- | | `transaction_id` | `string` | Transaction_id of the resultExample `01GV5S3SYTEX8QSVEWSPVQHNQS` | | `score` | `number` | Score of the resultExample `0.95` | | `collection_id` | `string` | Collection_id of the resultExample `01GV5S40XNZ47YYASFRE78GXW1` | ##### Response `400``application/json` 2 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `detailedMessage` | `string` | Message | | `code` | `string` | Exception Code | ##### Response `403``application/json` 1 fields Missing API key | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Other responses `422``500` ### 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 Copy ``` { "item": { "@type": "Address", "street": "123 Main St", "city": "Anytown", "state": "CA", "zip": 12345 } } ``` ##### Response 201400404409 application/json Copy Created item successfully ``` { "item": { "@id": "1234567890", "@type": "Address", "street": "123 Main St", "city": "Anytown", "state": "CA", "zip": 12345 } } ``` application/json Copy Request data failed validation ``` { "detailedMessage": "Bad request exception" } ``` application/json Copy Requested resource not found ``` { "message": "Container not found" } ``` application/json Copy Conflict ``` { "message": "Item with @id 'x' already exists" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `container_name` required | `string` path | `addresses` | Name of the container where the item will be added | ##### Request body`application/json` 1 fields | Field | Type | Description | | --- | --- | --- | | `item` | `object` | Item that was created | | `@id` | `string` | ID of the created item | | `@type` | `string` | Type of the created item | ##### Response `201``application/json` 1 fields Created item successfully | Field | Type | Description | | --- | --- | --- | | `item`required | `object` | Item that was created | | `@id` | `string` | ID of the created item | | `@type` | `string` | Type of the created item | ##### Response `400``application/json` 2 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `detailedMessage` | `string` | Message | | `code` | `string` | Code | ##### Response `403``application/json` 1 fields Missing API key | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `404``application/json` 1 fields Requested resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `409``application/json` 1 fields Conflict | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Other responses `422``500` `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 200400404 application/json Copy Get item successfully ``` { "item": { "@id": "1234567890", "@type": "Address", "street": "123 Main St", "city": "Anytown", "state": "CA", "zip": 12345 }, "container_name": "addresses" } ``` application/json Copy Request data failed validation ``` { "detailedMessage": "Bad request exception" } ``` application/json Copy Requested resource not found ``` { "message": "Container not found" } ``` ##### Parameters 2 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `id` required | `string` path | `AJXZ159292` | Id of the item to get | | `id` required | `string` path | `AJXZ159292` | Id of the item to get | ##### Response `200``application/json` 2 fields Get item successfully | Field | Type | Description | | --- | --- | --- | | `item`required | `object` | Item that was created | | `@id` | `string` | ID of the created item | | `@type` | `string` | Type of the created item | | `container_name` | `string` | Name of the containerExample `container_name` | ##### Response `400``application/json` 2 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `detailedMessage` | `string` | Message | | `code` | `string` | Code | ##### Response `403``application/json` 1 fields Missing API key | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `404``application/json` 1 fields Requested resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Other responses `422``500` `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 Copy ``` { "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 202400404409 application/json Copy Created item successfully ``` { "upload_id": "1234567890" } ``` application/json Copy Request data failed validation ``` { "detailedMessage": "Bad request exception" } ``` application/json Copy Requested resource not found ``` { "message": "Container not found" } ``` application/json Copy Conflict ``` { "message": "Item with @id 'x' already exists" } ``` ##### Request body`application/json` 2 fields | Field | Type | Description | | --- | --- | --- | | `items`required | `array` | Array of items to be uploaded | | `reassigned_ids` | `boolean` | Flag to reassign ids for items with existing ids. USE ONLY IF NEEDED. | ##### Response `202``application/json` 1 fields Created item successfully | Field | Type | Description | | --- | --- | --- | | `upload_id` | `string` | Id of the upload | ##### Response `400``application/json` 2 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `detailedMessage` | `string` | Message | | `code` | `string` | Code | ##### Response `403``application/json` 1 fields Missing API key | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `404``application/json` 1 fields Requested resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `409``application/json` 1 fields Conflict | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Other responses `422``500` `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 200400404409 application/json Copy Created item successfully ``` { "upload_id": "1234567890", "status": "COMPLETED" } ``` application/json Copy Request data failed validation ``` { "detailedMessage": "Bad request exception" } ``` application/json Copy Requested resource not found ``` { "message": "Container not found" } ``` application/json Copy Conflict ``` { "message": "Item with @id 'x' already exists" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `upload_id` required | `string` path | `1234567890` | Id of the upload | ##### Response `200``application/json` 2 fields Created item successfully | Field | Type | Description | | --- | --- | --- | | `upload_id` | `string` | Id of the upload | | `status` | `string` | Status of the upload`COMPLETED``FAILED``IN_PROGRESS` | ##### Response `400``application/json` 2 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `detailedMessage` | `string` | Message | | `code` | `string` | Code | ##### Response `403``application/json` 1 fields Missing API key | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `404``application/json` 1 fields Requested resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `409``application/json` 1 fields Conflict | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Other responses `422``500` `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 BasicPersonInfoFilterByNameWithRelationsGroupByAgeIncludeAllPropertiesAggregationExampleOptionalPropertiesAllFieldsExample application/json Copy ``` { "type": "person", "properties": [ "first_name", "last_name" ] } ``` application/json Copy ``` { "type": "person", "properties": [ "first_name", "last_name" ], "conditions": { "first_name": { "condition": "eq", "value": "John" } } } ``` application/json Copy ``` { "type": "person", "properties": [ "first_name", "last_name" ], "relations": [ { "relationship": "earns", "type": "income", "properties": [ "annual_income" ], "conditions": { "annual_income": { "condition": "gt", "value": 50000 } }, "required": true } ] } ``` application/json Copy ``` { "type": "person", "properties": [ "age" ], "group_by": "age" } ``` application/json Copy ``` { "type": "person", "properties": [ "*" ] } ``` application/json Copy ``` { "type": "person", "properties": [ "last_name", "first_name" ], "aggregate": { "function": "max", "attribute": "last_name" }, "group_by": "first_name" } ``` application/json Copy ``` { "type": "person", "properties": [ "first_name", "last_name", "email" ], "optional_properties": [ "email" ] } ``` application/json Copy ``` { "type": "person", "properties": [ "first_name", "last_name", "email" ], "optional_properties": [ "email" ], "relations": [ { "relationship": "earns", "type": "income", "properties": [ "annual_income" ], "conditions": { "annual_income": { "condition": "gt", "value": 50000 } }, "required": true } ], "group_by": "first_name", "aggregate": { "function": "max", "attribute": "last_name" }, "pagination": { "limit": 10 }, "echo": true } ``` ##### Response 200400404409 application/json Copy 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" } } ``` application/json Copy Request data failed validation ``` { "detailedMessage": "Bad request exception" } ``` application/json Copy Requested resource not found ``` { "message": "Container not found" } ``` application/json Copy Conflict ``` { "message": "Item with @id 'x' already exists" } ``` ##### Request body`application/json` 9 fields | Field | Type | Description | | --- | --- | --- | | `type` | `string` | Type of the main object you're constructing.Example `person` | | `properties` | `string[]` | Properties to include for each main object. Use * to include all properties. | | `optional_properties` | `string[]` | Optional properties to include for each main object. You can add property from properties parameter here to mark it as optional. | | `conditions` | `object` | Conditions for filtering the main objects. Key-value pairs define the attribute and its condition. | | `relations` | `object[]` | Array of relation objects to include related items in the output. | | `group_by` | `string` | Attribute to group the results by.Example `first_name` | | `aggregate` | `object` | Aggregation function to apply on the grouped results. | | `pagination` | `object` | Pagination options, including limit for paginated responses. | | `echo` | `boolean` | Echo the SPARQL query used for the data fetch. | ##### Response `200``application/json` 3 fields Succeeded | Field | Type | Description | | --- | --- | --- | | `items` | `object[]` | An array of item objects along with their relationship data. | | `@id` | `string` | The unique identifier of item. | | `pagination` | `object` | Pagination metadata for the list of items. | | `limit` | `integer` | The number of items returned per page. | | `next_token` | `integer` | Token to get the next set of items. | | `query` | `string` | The SPARQL query used for the data fetch. | ##### Response `400``application/json` 2 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `detailedMessage` | `string` | Message | | `code` | `string` | Code | ##### Response `403``application/json` 1 fields Missing API key | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `404``application/json` 1 fields Requested resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `409``application/json` 1 fields Conflict | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Other responses `422``500` `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 200400404 application/json Copy Succeeded ``` { "item": { "@id": "1234567890", "@type": "Address", "street": "123 Main St", "city": "Anytown", "state": "CA", "zip": 12345 }, "version": 1 } ``` application/json Copy Request data failed validation ``` { "detailedMessage": "Bad request exception" } ``` application/json Copy Requested resource not found ``` { "message": "Container not found" } ``` ##### Parameters 6 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `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 `200``application/json` 3 fields Succeeded | Field | Type | Description | | --- | --- | --- | | `items`required | `array` | Requested items | | `_links`required | `object` | Links to other resources | | `next` | `string` | Link to next page of resultsExample `https://api.staircaseapi.com/persistence/sug/addresses?filter=first_name+eq+John&next_token=123456789` | | `previous` | `string` | Link to previous page of resultsExample `https://api.staircaseapi.com/persistence/sug/addresses?filter=first_name+eq+John&next_token=123456789` | | `next_token` | `string` | Token to retrieve next page of resultsExample `123456789` | ##### Response `400``application/json` 2 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `detailedMessage` | `string` | Message | | `code` | `string` | Code | ##### Response `403``application/json` 1 fields Missing API key | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `404``application/json` 1 fields Requested resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | `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 Copy ``` { "item": { "street": "123 Main St", "city": "Anytown", "state": "CA", "zip": 12345 } } ``` ##### Response 200400404 application/json Copy 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 } } ``` application/json Copy Request data failed validation ``` { "detailedMessage": "Bad request exception" } ``` application/json Copy Requested resource not found ``` { "message": "Container not found" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `id` required | `string` path | `AJXZ159292` | Id of the item to get | ##### Request body`application/json` 1 fields | Field | Type | Description | | --- | --- | --- | | `item` | `object` | Item data to update | ##### Response `200``application/json` 4 fields Created item successfully | Field | Type | Description | | --- | --- | --- | | `status` | `string` | Status of the updateExample `success` | | `message` | `string` | MessageExample `Item updated successfully and previous version created.` | | `updated_item` | `object` | Item that was created | | `@id` | `string` | ID of the created item | | `@type` | `string` | Type of the created item | | `versioned_item` | `object` | Item that was created | | `@id` | `string` | ID of the created item | | `@type` | `string` | Type of the created item | ##### Response `400``application/json` 2 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `detailedMessage` | `string` | Message | | `code` | `string` | Code | ##### Response `403``application/json` 1 fields Missing API key | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `404``application/json` 1 fields Requested resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Other responses `422``500` ### 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 Copy ``` { "label": "first_transaction" } ``` ##### Response 201400 application/json Copy Transaction have been created ``` { "transaction_id": "01EZQ32PJQGKRA6HR8D72Q9FFF", "created_at": "2024-03-29T05:32:11.731227-04:00" } ``` application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` ##### Parameters 2 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `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 body`application/json` 2 fields | Field | Type | Description | | --- | --- | --- | | `callback_url` | `string (url)` | URL for receiving events about changes inside transaction | | `label` | `string` | Transaction label | ##### Response `201``application/json` 5 fields Transaction have been created | Field | Type | Description | | --- | --- | --- | | `transaction_id` | `string (ulid)` | Transaction idExample `01EZQ32PJQGKRA6HR8D72Q9FFF` | | `created_at` | `string` | Datetime, when transaction was created | | `callback_url` | `string` | Callback url | | `label` | `string` | Transaction label | | `_links` | `object` | Links | | `collections` | `string (url)` | Link to transaction collections | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `one of` | Message | ##### Response `403``application/json` 1 fields Missing API key | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `429``application/json` 1 fields The user has sent too many requests in a given amount of time ("rate limiting") | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | `GET` `/transactions/{transaction_id}` #### Retrieve Transaction `get_transaction` Retrieve transaction ##### Response 200400404 application/json Copy Transaction ``` { "transaction_id": "01EZQ32PJQGKRA6HR8D72Q9FFF", "created_at": "2024-03-29T05:32:11.731227-04:00" } ``` application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy Requested resource not found ``` { "message": "Collection not found" } ``` ##### Parameters 2 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `transaction_id` required | `string (ulid)` path | `01FJCADX5QEXEDVRWNXAK206MA` | Transaction ID | | `x-sc-trace-id` required | `string` header | `01FJCADX5QEXEDVRWNXAK206MA` | Trace ID of the transaction | ##### Response `200``application/json` 5 fields Transaction | Field | Type | Description | | --- | --- | --- | | `transaction_id` | `string (ulid)` | Transaction idExample `01EZQ32PJQGKRA6HR8D72Q9FFF` | | `created_at` | `string` | Datetime, when transaction was created | | `callback_url` | `string` | Callback url | | `label` | `string` | Transaction label | | `_links` | `object` | Links | | `collections` | `string (url)` | Link to transaction collections | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `one of` | Message | ##### Response `403``application/json` 1 fields Missing API key | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `404``application/json` 1 fields Requested resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `429``application/json` 1 fields The user has sent too many requests in a given amount of time ("rate limiting") | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | `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 400404 application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy Requested resource not found ``` { "message": "Collection not found" } ``` ##### Parameters 6 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `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 `200``application/json` 4 fields Transaction Data | Field | Type | Description | | --- | --- | --- | | `transaction_id` | `string (ulid)` | Transaction idExample `01EZQ32PJQGKRA6HR8D72Q9FFF` | | `collection_id` | `string (ulid)` | Collection idExample `01EZQ32PJQGKRA6HR8D72Q9FFF` | | `data` | `object` | Data in Staircase language schema | | `metadata` | `object` | Metadata about collection, f.e version of used Staircase schema. Maximum allowable length of the dumped json object - 400 000 symbols. | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `one of` | Message | ##### Response `403``application/json` 1 fields Missing API key | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `404``application/json` 1 fields Requested resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `429``application/json` 1 fields The user has sent too many requests in a given amount of time ("rate limiting") | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### 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 400404 application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy Requested resource not found ``` { "message": "Collection not found" } ``` ##### Parameters 3 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `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 `200``application/json` 5 fields Merge status | Field | Type | Description | | --- | --- | --- | | `merge_id` | `string` | Merge ID | | `status` | `string` | Merge status | | `transaction_id` | `string` | Transaction ID | | `error` | `string` | Error message if present | | `response_collection_id` | `string` | Collection ID of merged data | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `one of` | Message | ##### Response `403``application/json` 1 fields Missing API key | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `404``application/json` 1 fields Requested resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `429``application/json` 1 fields The user has sent too many requests in a given amount of time ("rate limiting") | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### 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 400404 application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy Requested resource not found ``` { "message": "Collection not found" } ``` ##### Parameters 6 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `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 `200``application/json` 1 fields List of transactions | Field | Type | Description | | --- | --- | --- | | `transactions` | `object[]` | List of transactions | | `transaction_id` | `string` | Transaction id | | `created_at` | `string` | Datetime, when transaction was created | | `collections` | `array` | List of collections created inside transaction | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `one of` | Message | ##### Response `403``application/json` 1 fields Missing API key | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `404``application/json` 1 fields Requested resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `429``application/json` 1 fields The user has sent too many requests in a given amount of time ("rate limiting") | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | `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 Copy ``` { "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 400404 application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy Requested resource not found ``` { "message": "Collection not found" } ``` ##### Parameters 2 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `transaction_id` required | `string (ulid)` path | `01FJCADX5QEXEDVRWNXAK206MA` | Transaction ID | | `x-sc-trace-id` required | `string` header | `01FJCADX5QEXEDVRWNXAK206MA` | Trace ID of the transaction | ##### Request body`application/json` 7 fields | Field | Type | Description | | --- | --- | --- | | `raw_collections` | `array` | List of collections created inside transaction | | `collection_ids` | `string[]` | List of Collection IDs to be merged | | `types_to_merge` | `string[]` | List of Types to be merged | | `staircase_version` | `integer` | Version of Staircase language for collections to be merged. Collections, that are not of this version will be filtered out | | `merge_transaction_collections` | `boolean` | If `true`, existing transaction collections will be included in merge | | `async` | `boolean` | If `true`, merge will be performed asynchronously | | `callback_url` | `string (uri)` | URL to which the callback will be sent if `async` is `true` | ##### Response `201``application/json` 4 fields Transaction Data | Field | Type | Description | | --- | --- | --- | | `transaction_id` | `string (ulid)` | Transaction idExample `01EZQ32PJQGKRA6HR8D72Q9FFF` | | `collection_id` | `string (ulid)` | Collection idExample `01EZQ32PJQGKRA6HR8D72Q9FFF` | | `data` | `object` | Data in Staircase language schema | | `metadata` | `object` | Metadata about collection, f.e version of used Staircase schema. Maximum allowable length of the dumped json object - 400 000 symbols. | ##### Response `202``application/json` 2 fields Merge transaction collections request accepted | Field | Type | Description | | --- | --- | --- | | `merge_id` | `string` | Merge ID | | `status` | `string` | Merge status | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `one of` | Message | ##### Response `403``application/json` 1 fields Missing API key | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `404``application/json` 1 fields Requested resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `429``application/json` 1 fields The user has sent too many requests in a given amount of time ("rate limiting") | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### 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 merge_with_transactionsmerge_with_collections application/json Copy ``` { "transaction_ids": [ "01FJCADX5QEXEDVRWNXAK206MA", "01FJCAQW7EYJAA6FY05WRKRM3T" ] } ``` application/json Copy ``` { "collections": [ { "transaction_id": "01FJCADX5QEXEDVRWNXAK206MA", "collection_id": "01FJCAQW7EYJAA6FY05WRKRM3T" } ] } ``` ##### Response 200 application/json200 application/json400404 application/json Copy 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" } } ``` application/json Copy New merged transaction ``` { "transaction_id": "01EZQ32PJQGKRA6HR8D72Q9FFF", "created_at": "2024-03-29T05:32:11.731227-04:00" } ``` application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy Requested resource not found ``` { "message": "Collection not found" } ``` ##### Request body`application/json` 2 fields | Field | Type | Description | | --- | --- | --- | | `transaction_ids`required | `string[]` | Transaction ids | | `collections` | `object[]` | Collections to merge into one transaction | | `transaction_id` | `string (ulid)` | Transaction id | | `collection_id` | `string (ulid)` | Collection id | ##### Response `200``application/json` 5 fields New merged transaction | Field | Type | Description | | --- | --- | --- | | `transaction_id` | `string (ulid)` | Transaction idExample `01EZQ32PJQGKRA6HR8D72Q9FFF` | | `created_at` | `string` | Datetime, when transaction was created | | `callback_url` | `string` | Callback url | | `label` | `string` | Transaction label | | `_links` | `object` | Links | | `collections` | `string (url)` | Link to transaction collections | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `one of` | Message | ##### Response `403``application/json` 1 fields Missing API key | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `404``application/json` 1 fields Requested resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `429``application/json` 1 fields The user has sent too many requests in a given amount of time ("rate limiting") | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### 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 Copy ``` { "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 201400404 application/json Copy 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" } } ] } } ``` application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy Requested resource not found ``` { "message": "Collection not found" } ``` ##### Parameters 2 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `transaction_id` required | `string (ulid)` path | `01FJCADX5QEXEDVRWNXAK206MA` | Transaction ID | | `x-sc-trace-id` required | `string` header | `01FJCADX5QEXEDVRWNXAK206MA` | Trace ID of the transaction | ##### Request body`application/json` 2 fields | Field | Type | Description | | --- | --- | --- | | `data`required | `object` | Collection data | | `metadata` | `object` | Collection metadata. Maximum allowable length of the dumped json object - 400 000 symbols. | | `version` | `integer` | Version of staircase language with what collection has been created.`0``2``3` | | `validation` | `boolean` | Flag that enables validation | | `linked_collections` | `object[]` | List of linked collections | | `collection_id` | `string (ulid)` | Collection ID of linked collection | | `label` | `string` | Label of linked collection | | `serialise_to_graph` | `boolean` | Flag that enables collection serialization to persistence graph | | `fuzzy_searchable` | `boolean` | Flag that enables fuzzy search for collection | ##### Response `201``application/json` 4 fields 201 response | Field | Type | Description | | --- | --- | --- | | `transaction_id` | `string (ulid)` | Transaction idExample `01EZQ32PJQGKRA6HR8D72Q9FFF` | | `collection_id` | `string (ulid)` | Collection idExample `01EZQ32PJQGKRA6HR8D72Q9FFF` | | `data` | `object` | Data in Staircase language schema | | `metadata` | `object` | Metadata about collection, f.e version of used Staircase schema. Maximum allowable length of the dumped json object - 400 000 symbols. | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `one of` | Message | ##### Response `403``application/json` 1 fields Missing API key | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `404``application/json` 1 fields Requested resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `429``application/json` 1 fields The user has sent too many requests in a given amount of time ("rate limiting") | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Other responses `413` `GET` `/transactions/{transaction_id}/collections/{collection_id}` #### Retrieve Collection `get_collection` ##### Response 200400404 application/json Copy 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" } } ] } } ``` application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy Requested resource not found ``` { "message": "Collection not found" } ``` ##### Parameters 5 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `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 `200``application/json` 4 fields 200 response | Field | Type | Description | | --- | --- | --- | | `transaction_id` | `string (ulid)` | Transaction idExample `01EZQ32PJQGKRA6HR8D72Q9FFF` | | `collection_id` | `string (ulid)` | Collection idExample `01EZQ32PJQGKRA6HR8D72Q9FFF` | | `data` | `object` | Data in Staircase language schema | | `metadata` | `object` | Metadata about collection, f.e version of used Staircase schema. Maximum allowable length of the dumped json object - 400 000 symbols. | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `one of` | Message | ##### Response `403``application/json` 1 fields Missing API key | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `404``application/json` 1 fields Requested resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `429``application/json` 1 fields The user has sent too many requests in a given amount of time ("rate limiting") | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### 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 Copy ``` { "people": { "has_first_name": {}, "earns": { "has_federal_tax_withheld_amount": {}, "has_dependent_care_benefits_amount": {} } } } ``` ##### Response 200400404 application/json Copy 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" } } ] } ``` application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy Requested resource not found ``` { "message": "Collection not found" } ``` ##### Parameters 3 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `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 `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `one of` | Message | ##### Response `403``application/json` 1 fields Missing API key | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `404``application/json` 1 fields Requested resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `429``application/json` 1 fields The user has sent too many requests in a given amount of time ("rate limiting") | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### 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 jsonpathjmespath application/json Copy JSONPath query ``` { "format": "jsonpath", "query": "$.people[?(@['@type'] = 'borrower')].with_address[?(@['@type'] = 'mailing_address')].has_city_name.has_value" } ``` application/json Copy JMESPath query ``` { "format": "jmespath", "query": "people[?\"@type\" == 'borrower'].with_address[] | [?\"@type\" == 'mailing_address'].{city: has_city_name.has_value, state_code: has_state_code.has_value}" } ``` ##### Response 400404 application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy Requested resource not found ``` { "message": "Collection not found" } ``` ##### Parameters 3 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `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 body`application/json` 2 fields | Field | Type | Description | | --- | --- | --- | | `format`required | `string` | Query format.`jmespath``jsonpath` | | `query`required | `string` | Query. | ##### Response `200``application/json` 1 fields Query results. | Field | Type | Description | | --- | --- | --- | | `result` | `one of` | Query results. | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `one of` | Message | ##### Response `403``application/json` 1 fields Missing API key | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `404``application/json` 1 fields Requested resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `429``application/json` 1 fields The user has sent too many requests in a given amount of time ("rate limiting") | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | `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 400404 application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy Requested resource not found ``` { "message": "Collection not found" } ``` ##### Parameters 7 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `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 `200``application/json` 4 fields 200 response | Field | Type | Description | | --- | --- | --- | | `transaction_id` | `string (ulid)` | Transaction idExample `01EZQ32PJQGKRA6HR8D72Q9FFF` | | `collection_id` | `string (ulid)` | Collection idExample `01EZQ32PJQGKRA6HR8D72Q9FFF` | | `data` | `object` | Data in Staircase language schema | | `metadata` | `object` | Metadata about collection, f.e version of used Staircase schema. Maximum allowable length of the dumped json object - 400 000 symbols. | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `one of` | Message | ##### Response `404``application/json` 1 fields Requested resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `422``application/json` 2 fields Unprocessable Entity | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | | `collections` | `object[]` | List of collections without 'data' field and with links to retrieve single collections. | | `transaction_id` | `string (ulid)` | Transaction id | | `collection_id` | `string (ulid)` | Collection id | | `metadata` | `object` | Metadata about collection, f.e version of used Staircase schema Maximum allowable length of the dumped json object - 400 000 symbols. | | `_links` | `object` | Links | | `collection` | `string (url)` | Link to retrieve full collection. | ##### Response `429``application/json` 1 fields The user has sent too many requests in a given amount of time ("rate limiting") | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | `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 Copy ``` { "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": "false", "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": "2250", "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 200400404 application/json Copy 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": "false", "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": "2250", "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" } } ] } ] } } ``` application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy Requested resource not found ``` { "message": "Collection not found" } ``` ##### Parameters 3 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `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 body`application/json` 2 fields | Field | Type | Description | | --- | --- | --- | | `data`required | `object` | Data for updating | | `metadata` | `object` | Metadata for updating. Maximum allowable length of the dumped json object - 400 000 symbols. | ##### Response `200``application/json` 4 fields 200 response | Field | Type | Description | | --- | --- | --- | | `transaction_id` | `string (ulid)` | Transaction idExample `01EZQ32PJQGKRA6HR8D72Q9FFF` | | `collection_id` | `string (ulid)` | Collection idExample `01EZQ32PJQGKRA6HR8D72Q9FFF` | | `data` | `object` | Data in Staircase language schema | | `metadata` | `object` | Metadata about collection, f.e version of used Staircase schema. Maximum allowable length of the dumped json object - 400 000 symbols. | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `one of` | Message | ##### Response `403``application/json` 1 fields Missing API key | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `404``application/json` 1 fields Requested resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `429``application/json` 1 fields The user has sent too many requests in a given amount of time ("rate limiting") | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Other responses `413``422` `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 Copy ``` { "data": { "liabilities": [ { "@type": "liability", "liability_account_identifier": "12340002", "has_liability_timeline": { "@type": "liability_timeline", "liability_unpaid_balance_amount": 2000 } } ] } } ``` ##### Response 200400404 application/json Copy 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 } ] } } ``` application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy Requested resource not found ``` { "message": "Collection not found" } ``` ##### Request body`application/json` 1 fields | Field | Type | Description | | --- | --- | --- | | `data` | `object` | Data | ##### Response `200``application/json` 1 fields New flattened data | Field | Type | Description | | --- | --- | --- | | `data` | `object` | Data | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `one of` | Message | ##### Response `403``application/json` 1 fields Missing API key | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `404``application/json` 1 fields Requested resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `429``application/json` 1 fields The user has sent too many requests in a given amount of time ("rate limiting") | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | `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 Copy Simple request ``` { "element_id": "01F6N4YSTM8EWPM80PFYJA15JP", "op": "remove" } ``` ##### Response 200400404 application/json Copy 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" } } ] } } ``` application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy Requested resource not found ``` { "message": "Collection not found" } ``` ##### Parameters 3 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `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 body`application/json` 4 fields | Field | Type | Description | | --- | --- | --- | | `op` | `string` | Remove`remove` | | `element_id` | `string` | Element ID | | `exclude_relationships` | `string[]` | Relationships to exclude | | `query` | `object` | query | | `format` | `string` | Query format.`jmespath``jsonpath` | | `query` | `string` | Query. | ##### Response `200``application/json` 4 fields New collection | Field | Type | Description | | --- | --- | --- | | `transaction_id` | `string (ulid)` | Transaction idExample `01EZQ32PJQGKRA6HR8D72Q9FFF` | | `collection_id` | `string (ulid)` | Collection idExample `01EZQ32PJQGKRA6HR8D72Q9FFF` | | `data` | `object` | Data in Staircase language schema | | `metadata` | `object` | Metadata about collection, f.e version of used Staircase schema. Maximum allowable length of the dumped json object - 400 000 symbols. | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `one of` | Message | ##### Response `403``application/json` 1 fields Missing API key | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `404``application/json` 1 fields Requested resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `429``application/json` 1 fields The user has sent too many requests in a given amount of time ("rate limiting") | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ### 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 Copy ``` { "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 201400409 application/json Copy 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 } ``` application/json Copy Request data failed validation ``` { "detailedMessage": "Bad request exception" } ``` application/json Copy Conflict ``` { "message": "Trigger name 'x' already exists" } ``` ##### Request body`application/json` 5 fields | Field | Type | Description | | --- | --- | --- | | `trigger_name`required | `string` | Name of the triggerExample `name` | | `condition`required | `string` | Condition as jmespath query that returns a boolean responseExample `contains(locations[].name, 'Some name')` | | `webhook_url`required | `string (uri)` | Webhook URLExample `https://webhook.site/5f9b1b1f-1b1f-5f9b-1b1f-5f9b1b1f5f9b` | | `transaction_label` | `string` | Transaction label to filter transactions with labelExample `optional_label` | | `valid_collections_only` | `boolean` | Flag defining if the trigger is triggered only for collections with `"validation": true` in the `metadata`.Example `true` | ##### Response `201``application/json` 6 fields Trigger created | Field | Type | Description | | --- | --- | --- | | `trigger_name`required | `string` | Name of the triggerExample `name` | | `condition`required | `string` | Condition as jmespath query that returns a boolean responseExample `contains(locations[].name, 'Some name')` | | `webhook_url`required | `string (uri)` | Webhook URLExample `https://webhook.site/5f9b1b1f-1b1f-5f9b-1b1f-5f9b1b1f5f9b` | | `transaction_label` | `string` | Transaction label to filter transactions with labelExample `optional_label` | | `valid_collections_only` | `boolean` | Flag defining if the trigger is triggered only for collections with `"validation": true` in the `metadata`.Example `true` | | `trigger_id`required | `string` | ID of the triggerExample `5f9b1b1f-1b1f-5f9b-1b1f-5f9b1b1f5f9b` | ##### Response `400``application/json` 2 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `detailedMessage` | `string` | Message | | `code` | `string` | Code | ##### Response `403``application/json` 1 fields Missing API key | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `409``application/json` 1 fields Conflict | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Other responses `422``500` `DELETE` `/triggers/{trigger_id}` #### Delete Trigger `delete_trigger` Delete trigger ##### Response 400404 application/json Copy Request data failed validation ``` { "detailedMessage": "Bad request exception" } ``` application/json Copy Requested resource not found ``` { "message": "Trigger not found" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `trigger_id` required | `string` path | `52341234-1234-1234-1234-123412341234` | Trigger ID | ##### Response `400``application/json` 2 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `detailedMessage` | `string` | Message | | `code` | `string` | Code | ##### Response `403``application/json` 1 fields Missing API key | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `404``application/json` 1 fields Requested resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Other responses `204``422``500` `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 Copy ``` [ { "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 200400404 application/json Copy 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" } ``` application/json Copy Request data failed validation ``` { "detailedMessage": "Bad request exception" } ``` application/json Copy Requested resource not found ``` { "message": "Trigger not found" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `trigger_id` required | `string` path | `52341234-1234-1234-1234-123412341234` | Trigger ID | ##### Response `200``application/json` 6 fields Patched trigger object | Field | Type | Description | | --- | --- | --- | | `trigger_name`required | `string` | Name of the triggerExample `name` | | `condition`required | `string` | Condition as jmespath query that returns a boolean responseExample `contains(locations[].name, 'Some name')` | | `webhook_url`required | `string (uri)` | Webhook URLExample `https://webhook.site/5f9b1b1f-1b1f-5f9b-1b1f-5f9b1b1f5f9b` | | `transaction_label` | `string` | Transaction label to filter transactions with labelExample `optional_label` | | `valid_collections_only` | `boolean` | Flag defining if the trigger is triggered only for collections with `"validation": true` in the `metadata`.Example `true` | | `trigger_id`required | `string` | ID of the triggerExample `5f9b1b1f-1b1f-5f9b-1b1f-5f9b1b1f5f9b` | ##### Response `400``application/json` 2 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `detailedMessage` | `string` | Message | | `code` | `string` | Code | ##### Response `403``application/json` 1 fields Missing API key | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `404``application/json` 1 fields Requested resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Other responses `422``500` `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 200400404 application/json Copy 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" } ] ``` application/json Copy Request data failed validation ``` { "detailedMessage": "Bad request exception" } ``` application/json Copy Requested resource not found ``` { "message": "Trigger not found" } ``` ##### Parameters 2 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `trigger_id` | `string` query | `52341234-1234-1234-1234-123412341234` | Trigger id | | `trigger_name` | `string` query | `example_trigger` | Trigger name | ##### Response `400``application/json` 2 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `detailedMessage` | `string` | Message | | `code` | `string` | Code | ##### Response `403``application/json` 1 fields Missing API key | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `404``application/json` 1 fields Requested resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Other responses `200``422``500` ### Operations `GET` `/data-share/public-key` ##### Response `200``application/json` 1 fields OK Response | Field | Type | Description | | --- | --- | --- | | `public_key` | `string` | — | `POST` `/data-share/share` ##### Request body`application/json` 3 fields | Field | Type | Description | | --- | --- | --- | | `transaction_id`required | `string` | — | | `collection_id`required | `string` | — | | `to_public_key`required | `string` | — | ##### Response `200``application/json` 1 fields OK response | Field | Type | Description | | --- | --- | --- | | `share_id` | `string` | — | `GET` `/data-share/shared` #### List of colelctions, that was sahred with you ##### Response `200``application/json` 1 fields OK response | Field | Type | Description | | --- | --- | --- | | `collections` | `object[]` | — | | `transaction_id` | `string` | — | | `collection_id` | `string` | — | | `share_id` | `string` | — | ## Errors `400``403``404``406``409``413``422``429``500` ## More in Data - Previous product: ML - Next product: Rule