Document

A scorecard for document extraction: per-vendor accuracy and cost on real documents, exposed as endpoints rather than as a report.

Several extraction vendors are integrated for the same document types. This product measures them against ground truth and serves the result — accuracy per document type, per field, and the cost of each attempt.

Because it is an API rather than a dashboard, routing can consume it. A document type where one vendor is measurably better is a routing decision the pipeline can make rather than a preference someone remembers.

How it works

Ground truth comes from a labelling pipeline run over real documents rather than synthetic ones. Measuring extraction on generated documents produces a number that does not survive contact with a scanned fax.

Dual listing

Document is filed under two categories. The other listing is Document under Contract, and the recorded specifications resolve there — its 54 operations render on that page.

Operations

Documents

PUT /documents/{document_type}

Create or update document type

updateDocument

Create or update document type. Provided list of fields will be displayed to the labeller. Results will be translated to v2 and saved to response collection. Result with provided list of fields will be available via Retrieve Job endpoint.

Request

application/json

{
  "fields": [
    {
      "name": "document_date",
      "type": "date",
      "description": "Document date."
    },
    {
      "name": "document_signed_indicator",
      "type": "boolean",
      "description": "Identifies if document is signed"
    },
    {
      "name": "borrower_first_name",
      "type": "string",
      "description": "Borrower first name"
    }
  ],
  "language_name": "doc_v2_language"
}

Response

application/json

Document has been created/updated

{
  "document_type": "my_document_type",
  "fields": [
    {
      "name": "document_date",
      "type": "date",
      "description": "Document date."
    },
    {
      "name": "document_signed_indicator",
      "type": "boolean",
      "description": "Identifies if document is signed"
    },
    {
      "name": "borrower_first_name",
      "type": "string",
      "description": "Borrower first name"
    }
  ],
  "mapping_name": "doc_v2_mapping"
}

Parameters

Parameter	Type	Example	Description
`document_type` required	`string` path	`irs_w2`	Document type

Request body`application/json`

4 fields

Field	Type	Description
`fields`required	`object[]`	List of fields
`name`required	`string`	Field name
`type`required	`string`	Field datatype`booleandateintegernumberstring`
`description`	`string`	Field description.
`enum`	`string[]`	List of possible values
`mapping_name`	`string`	Name of mapping, created using staircase Translator product
`language_name`	`string`	Name of language, created using staircase Language product.
`soft_validation`	`boolean`	The flag that define if failed validation should fail creating/update of the document or just add validation errors as warnings to the document info.

Response `200application/json`

6 fields

Document has been created/updated

Field	Type	Description
`document_type`	`string`	Document type
`fields`	`object[]`	List of fields
`name`required	`string`	Field name
`type`required	`string`	Field datatype`booleandateintegernumberstring`
`description`	`string`	Field description.
`enum`	`string[]`	List of possible values
`mapping_name`	`string`	Name of mapping, created using staircase Translator product.
`language_name`	`string`	Name of language, created using staircase Language product.
`soft_validation`	`boolean`	The flag that define if failed validation should fail creating/update of the document or just add validation errors as warnings to the document info.
`validation_errors`	`object`	Validation information
`message`required	`string`	Validation general message
`error`	`object`	Validation error details

Response `400application/json`

1 fields

Request data failed validation

Field	Type	Description
`message`	`one of`	Message

Response `403application/json`

1 fields

Missing API key

Field	Type	Description
`message`	`string`	Message

Other responses

422

GET /documents/{document_type}

Retrieve document

retrieveDocument

Response

application/json

Document type

{
  "document_type": "my_document_type",
  "fields": [
    {
      "name": "document_date",
      "type": "date",
      "description": "Document date."
    },
    {
      "name": "document_signed_indicator",
      "type": "boolean",
      "description": "Identifies if document is signed"
    },
    {
      "name": "borrower_first_name",
      "type": "string",
      "description": "Borrower first name"
    }
  ],
  "mapping_name": "doc_v2_mapping"
}

Parameters

Parameter	Type	Example	Description
`document_type` required	`string` path	`irs_w2`	Document type

Response `200application/json`

6 fields

Document type

Field	Type	Description
`document_type`	`string`	Document type
`fields`	`object[]`	List of fields
`name`required	`string`	Field name
`type`required	`string`	Field datatype`booleandateintegernumberstring`
`description`	`string`	Field description.
`enum`	`string[]`	List of possible values
`mapping_name`	`string`	Name of mapping, created using staircase Translator product.
`language_name`	`string`	Name of language, created using staircase Language product.
`soft_validation`	`boolean`	The flag that define if failed validation should fail creating/update of the document or just add validation errors as warnings to the document info.
`validation_errors`	`object`	Validation information
`message`required	`string`	Validation general message
`error`	`object`	Validation error details

Response `400application/json`

1 fields

Request data failed validation

Field	Type	Description
`message`	`one of`	Message

Response `403application/json`

1 fields

Missing API key

Field	Type	Description
`message`	`string`	Message

Response `404application/json`

1 fields

Not Found

Field	Type	Description
`message`	`string`	Message

DELETE /documents/{document_type}

Delete document type

deleteDocument

Parameters

Parameter	Type	Example	Description
`document_type` required	`string` path	`irs_w2`	Document type

Response `200application/json`

1 fields

Document type has been deleted

Field	Type	Description
`message`	`string`	message

Response `400application/json`

1 fields

Request data failed validation

Field	Type	Description
`message`	`one of`	Message

Response `403application/json`

1 fields

Missing API key

Field	Type	Description
`message`	`string`	Message

Response `404application/json`

1 fields

Not Found

Field	Type	Description
`message`	`string`	Message

POST /documents/{document_type}/samples

Create Sample

createSample

Create sample

Request

application/json

{
  "blob_id": "01G9300Q4KT3FHP61ANG2R66SY",
  "name": "FILLED_CLOSING_DISCLOSURE"
}

Parameters

Parameter	Type	Example	Description
`document_type` required	`string` path	`irs_w2`	Document type

Request body`application/json`

2 fields

Field	Type	Description
`blob_id`required	`string (ulid)`	Blob ID
`name`	`string`	Sample alias

Response `201application/json`

3 fields

Sample has been created

Field	Type	Description
`sample_id`required	`string (ulid)`	Sample ID
`blob_id`required	`string (ulid)`	Blob ID
`name`	`string`	Sample alias

Response `400application/json`

1 fields

Request data failed validation

Field	Type	Description
`message`	`one of`	Message

Response `403application/json`

1 fields

Missing API key

Field	Type	Description
`message`	`string`	Message

Response `404application/json`

1 fields

Not Found

Field	Type	Description
`message`	`string`	Message

Other responses

422

GET /documents/{document_type}/samples

Retrieve Samples

retrieveSamples

Retrieve samples

Parameters

Parameter	Type	Example	Description
`document_type` required	`string` path	`irs_w2`	Document type

Response `200application/json`

2 fields

Document samples

Field	Type	Description
`count`	`integer`	Samples count
`samples`	`array`	Samples

Response `400application/json`

1 fields

Request data failed validation

Field	Type	Description
`message`	`one of`	Message

Response `403application/json`

1 fields

Missing API key

Field	Type	Description
`message`	`string`	Message

Response `404application/json`

1 fields

Not Found

Field	Type	Description
`message`	`string`	Message

GET /documents/hint

Get Classification Hint

getClassificationHint

Provides the URL to the classification hint page.

Response `200application/json`

1 fields

Documents hint

Field	Type	Description
`hint_page_url`required	`string`	URL to the hint page

Response `403application/json`

1 fields

Missing API key

Field	Type	Description
`message`	`string`	Message

DELETE /documents/{document_type}/samples/{sample_id}

Delete Sample

deleteSample

Delete sample

Parameters

Parameter	Type	Example	Description
`document_type` required	`string` path	`irs_w2`	Document type
`sample_id` required	`string` path	`12345`	Sample ID

Response `200application/json`

3 fields

Document type has been deleted

Field	Type	Description
`sample_id`required	`string (ulid)`	Sample ID
`blob_id`required	`string (ulid)`	Blob ID
`name`	`string`	Sample alias

Response `400application/json`

1 fields

Request data failed validation

Field	Type	Description
`message`	`one of`	Message

Response `403application/json`

1 fields

Missing API key

Field	Type	Description
`message`	`string`	Message

Response `404application/json`

1 fields

Not Found

Field	Type	Description
`message`	`string`	Message

Workflow

POST /transactions

Create Transaction

createTransaction

Create empty transaction You can subscribe to every 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 ```json json_schema
{
"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

Request

application/json

{
  "label": "first_transaction",
  "callback_url": "https://webhook.site/0c1c4e00-79d9-490b-a0f3-bab8b12a61d5"
}

Response

application/json

Transaction created successfully

{
  "transaction_id": "01F0KHK7DN3H5JZ4QJKMYAM6GB",
  "created_at": "03/04/2021, 1:04:05 PM EST"
}

application/json

403 invalid error

{
  "message": "Please check the key you used to call this service",
  "url": "https://api.staircase.co/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}

application/json

Internal server error

{
  "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support"
}

Parameters

Parameter	Type	Example	Description
`x-api-key` required	`string` header	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`	Environment API Key.

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 `201application/json`

2 fields

Transaction created successfully

Field	Type	Description
`transaction_id`	`string (ulid)`	Staircase Transaction IdentifierExample `01F0KHK7DN3H5JZ4QJKMYAM6GB`
`created_at`	`string`	Staircase time string.Example `03/03/2021, 8:24:04 AM EST`

Response `403application/json`

2 fields

403 invalid error

Field	Type	Description
`message`	`string`	Error message.
`url`	`string`	Error additional URL.

Response `500application/json`

1 fields

Internal server error

Field	Type	Description
`message`	`string`	Error message.

Other responses

400

POST /transactions/{transaction_id}/collections

Create Collection

createCollection

Create Collection creates a collection of data points required for product invocation. A collection contains a digital representation of the input or output data for the product and is identified by collection_id.

The Example below contains a sample collection that you can use to make the product invocation in /get-collection

Request

application/json

{}

Response

application/json

Collection created successfully

{}

application/json

403 invalid error

{
  "message": "Please check the key you used to call this service",
  "url": "https://api.staircase.co/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}

application/json

Internal server error

{
  "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support"
}

Parameters

Parameter	Type	Example	Description
`x-api-key` required	`string` header	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`	Environment API Key.
`transaction_id` required	`string (ulid)` path	`01F0KHK7DN3H5JZ4QJKMYAM6GB`	Staircase Transaction Identifier

Response `400application/json`

1 fields

Error

Field	Type	Description
`message`	`one of`	Either message object with more properties.

Response `403application/json`

2 fields

403 invalid error

Field	Type	Description
`message`	`string`	Error message.
`url`	`string`	Error additional URL.

Response `404application/json`

1 fields

Resource not found

Field	Type	Description
`message`	`string`	Message

Response `500application/json`

1 fields

Internal server error

Field	Type	Description
`message`	`string`	Error message.

Other responses

201405

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

Retrieve Collection

retrieveCollection

Retrieve Collection returns the content of a given collection_id associated with a transaction_id.

Response

application/json

Successfully Retrieved Collection

{}

application/json

403 invalid error

{
  "message": "Please check the key you used to call this service",
  "url": "https://api.staircase.co/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}

application/json

Internal server error

{
  "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support"
}

Parameters

Parameter	Type	Example	Description
`x-api-key` required	`string` header	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`	Environment API Key.
`transaction_id` required	`string (ulid)` path	`01F0KHK7DN3H5JZ4QJKMYAM6GB`	Staircase Transaction Identifier
`collection_id` required	`string (ulid)` path	`01F0KHKADN0HRFXMCQQXPA6AFZ`	Staircase collection_id

Response `403application/json`

2 fields

403 invalid error

Field	Type	Description
`message`	`string`	Error message.
`url`	`string`	Error additional URL.

Response `404application/json`

1 fields

Resource not found

Field	Type	Description
`message`	`string`	Message

Response `500application/json`

1 fields

Internal server error

Field	Type	Description
`message`	`string`	Error message.

Other responses

200400

POST /classify

Classification

invokeProductFlow

Invoke Product

Invoke Specific Product Flow helps you to invoke specific product flow, this endpoint shall:

Validate the input transaction_id, request_collection_id, response_collection_id if provided;
Create transaction if the transaction_id was not provided;
Create input collection with the request_data provided if the request_collection_id was not provided;
Create empty output collection if the response_collection_id was not provided;
Validate the provided product name and the product flow name;
Retrieve the product flow information associated to the provided Product Flow Name;

Show the rest

Run the connector flow associated to the Product Flow Name;

Translate the input collection from Vendor language to Staircase language if output_translation_language was configured for the product flow;

Set the status, invocation_id and output_translation_language that will be used to translate the results from Vendor Language to Staircase language if output_translation_language was configured for the product flow.

Request

application/json

{
  "product_flow_name": "documentai",
  "transaction_id": "01F6NAMXWN2XVBD1YJ92A6S6R4",
  "response_collection_id": "01F6NAQ4894HPMCBGB4P0G95XK",
  "request_collection_id": "01F6QF1QJF20DMSXH4SYXKB1SN",
  "callback_url": "https://webhook.site/3706b519-9426-4533-9868-14a7dec4fd97",
  "request_data": {}
}

application/json

{
  "transaction_id": "01F6NAMXWN2XVBD1YJ92A6S6R4",
  "response_collection_id": "01F6NAQ4894HPMCBGB4P0G95XK",
  "request_collection_id": "01F6QF1QJF20DMSXH4SYXKB1SN",
  "callback_url": "https://webhook.site/3706b519-9426-4533-9868-14a7dec4fd97",
  "tags": [
    "manual_verification"
  ]
}

application/json

{
  "product_flow_name": "get-document-from-byte",
  "transaction_id": "01F6NAMXWN2XVBD1YJ92A6S6R4",
  "response_collection_id": "01F6NAQ4894HPMCBGB4P0G95XK",
  "callback_url": "https://webhook.site/3706b519-9426-4533-9868-14a7dec4fd97",
  "request_data": {
    "deal_sets": {
      "deal_set": [
        {
          "deals": {
            "deal": [
              {
                "parties": {
                  "party": [
                    {
                      "individual": {
                        "name": {
                          "first": "Thomas",
                          "last": "Alex"
                        }
                      },
                      "taxpayer_identifiers": {
                        "taxpayer_identifier": [
                          {
                            "value": "12345"
                          }
                        ]
                      },
                      "roles": {
                        "role": [
                          {
                            "borrower": {
                              "residences": {
                                "residence": [
                                  {
                                    "address": {
                                      "line_text": "street 101",
                                      "city": "example city",
                                      "state": "state",
                                      "postal_code": "1234",
                                      "street_name": "street 23"
                                    }
                                  }
                                ]
                              }
                            }
                          }
                        ]
                      }
                    }
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  }
}

application/json

{
  "transaction_id": "01F6NAMXWN2XVBD1YJ92A6S6R4",
  "response_collection_id": "01F6NAQ4894HPMCBGB4P0G95XK",
  "request_collection_id": "01F6QF1QJF20DMSXH4SYXKB1SN",
  "callback_url": "https://webhook.site/3706b519-9426-4533-9868-14a7dec4fd97",
  "tags": [
    "manual_verification"
  ],
  "options": {
    "option1": "test_option"
  }
}

application/json

{
  "transaction_id": "01F6NAMXWN2XVBD1YJ92A6S6R4",
  "response_collection_id": "01F6NAQ4894HPMCBGB4P0G95XK",
  "callback_url": "https://webhook.site/3706b519-9426-4533-9868-14a7dec4fd97",
  "request_data": {
    "deal_sets": {
      "deal_set": [
        {
          "deals": {
            "deal": [
              {
                "parties": {
                  "party": [
                    {
                      "individual": {
                        "name": {
                          "first": "Thomas",
                          "last": "Alex"
                        }
                      },
                      "taxpayer_identifiers": {
                        "taxpayer_identifier": [
                          {
                            "value": "12345"
                          }
                        ]
                      },
                      "roles": {
                        "role": [
                          {
                            "borrower": {
                              "residences": {
                                "residence": [
                                  {
                                    "address": {
                                      "line_text": "street 101",
                                      "city": "example city",
                                      "state": "state",
                                      "postal_code": "1234",
                                      "street_name": "street 23"
                                    }
                                  }
                                ]
                              }
                            }
                          }
                        ]
                      }
                    }
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  },
  "tags": [
    "manual_verification"
  ],
  "options": {
    "option1": "test_option"
  }
}

application/json

{
  "product_flow_name": "get-document-from-byte",
  "transaction_id": "01F6NAMXWN2XVBD1YJ92A6S6R4",
  "request_collection_id": "01F6QF1QJF20DMSXH4SYXKB1SN",
  "response_collection_id": "01F6NAQ4894HPMCBGB4P0G95XK",
  "callback_url": "https://webhook.site/3706b519-9426-4533-9868-14a7dec4fd97",
  "options": {
    "option1": "test_option"
  }
}

application/json

{
  "vendor_name": "Vendor_name_example",
  "transaction_id": "01F6NAMXWN2XVBD1YJ92A6S6R4",
  "request_collection_id": "01F6QF1QJF20DMSXH4SYXKB1SN",
  "response_collection_id": "01F6NAQ4894HPMCBGB4P0G95XK",
  "callback_url": "https://webhook.site/3706b519-9426-4533-9868-14a7dec4fd97",
  "options": {
    "option1": "test_option"
  }
}

application/json

{
  "transaction_id": "01F6NAMXWN2XVBD1YJ92A6S6R4",
  "request_collection_id": "01F6QF1QJF20DMSXH4SYXKB1SN",
  "response_collection_id": "01F6NAQ4894HPMCBGB4P0G95XK",
  "callback_url": "https://webhook.site/3706b519-9426-4533-9868-14a7dec4fd97",
  "invocation_mode": "waterfall"
}

Response

application/json

Successfully started flow invocation.

{
  "invocation_id": "9aefb465-90fb-4d50-8ae6-2df2b58373f4",
  "invocation_status": "STARTED",
  "product_flow_name": "product_flow_name_example",
  "transaction_id": "01F6NAMXWN2XVBD1YJ92A6S6R4",
  "request_collection_id": "01F6NAQ4894HPMCBGB4P0G95XK",
  "response_collection_id": "01F6NAQ4894HPMCBGB4P0G78HG",
  "options": {
    "dry_run": false
  },
  "tags": [
    "manual verification"
  ],
  "widget_url": "https://product-dev-productsbucket-1j472c4onqkxw.s3.amazonaws.com/widgets/063f5f"
}

application/json

403 invalid error

{
  "message": "Please check the key you used to call this service",
  "url": "https://api.staircase.co/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}

application/json

Unprocessable entity error

{
  "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support"
}

application/json

Internal server error

{
  "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support"
}

Parameters

Parameter	Type	Example	Description
`x-api-key` required	`string` header	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`	Environment API Key.

Request body`application/json`

10 fields

Field	Type	Description
`product_flow_name`	`string`	Product flow name. If it is not specified, the default product flow will be invoked. If the product has no default product flow, the first created flow will be invoked. Cannot be specified together with vendor_name.
`vendor_name`	`string`	Vendor name. Cannot be specified together with product_flow_name.
`transaction_id`	`string`	Transaction ID used for invocation.
`request_collection_id`	`string`	Request Collection ID.
`response_collection_id`	`string`	Response Collection ID.
`callback_url`	`string (uri)`	Callback URL.
`request_data`	`object`	Request JSON body.
`tags`	`string[]`	List of tags.
`options`	`object`	Additional information that should be passed to the connector but not be added to the request collection.
`invocation_mode`	`string`	The invocation mode of a product flow single_flow or waterfall, default value single_flow

Response `201application/json`

12 fields

Successfully started flow invocation.

Field	Type	Description
`invocation_id`required	`string`	Invocation ID.
`invocation_status`required	`string`	The status of the invocation.`STARTED`
`transaction_id`required	`string`	Transaction ID.
`request_collection_id`required	`string`	Request collection ID.
`response_collection_id`required	`string`	Response collection ID.
`product_flow_name`	`string`	Product flow name.
`metadata`	`object`	The metadata of the invoked product flow.
`callback_url`	`string`	Callback URL.
`request_data`	`object`	The data for the request collection.
`tags`	`string[]`	List of tags.
`options`	`object`	Additional information that should be passed to the connector but not be added to the request collection.
`widget_url`	`string`	Product widget_url listening on the connector widget_url

Response `400application/json`

1 fields

Request data failed validation

Field	Type	Description
`message`	`one of`	Message

Response `403application/json`

2 fields

403 invalid error

Field	Type	Description
`message`	`string`	Error message.
`url`	`string`	Error additional URL.

Response `404application/json`

1 fields

Resource not found

Field	Type	Description
`message`	`string`	Message

Response `422application/json`

1 fields

Unprocessable entity error

Field	Type	Description
`message`	`string`	Error Message.

Response `500application/json`

1 fields

Internal server error

Field	Type	Description
`message`	`string`	Error message.

Platform

GET /transactions/{transaction_id}/collections

Retrieve Transaction Collections

RetrieveTransactionCollections

Retrieve Transaction Collections. Collections can be filtered by collection_id or created_at fields. Supported operations per fields:

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

Response

application/json

Transaction collection retrieved successfully

{}

application/json

403 invalid error

{
  "message": "Please check the key you used to call this service",
  "url": "https://api.staircase.co/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}

application/json

Internal server error

{
  "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support"
}

Parameters

Parameter	Type	Example	Description
`x-api-key` required	`string` header	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`	Environment API Key.
`transaction_id` required	`string (ulid)` path	`01F0KHK7DN3H5JZ4QJKMYAM6GB`	Staircase Transaction Identifier

Response `400application/json`

1 fields

Error

Field	Type	Description
`message`	`one of`	Either message object with more properties.

Response `403application/json`

2 fields

403 invalid error

Field	Type	Description
`message`	`string`	Error message.
`url`	`string`	Error additional URL.

Response `404application/json`

1 fields

Resource not found

Field	Type	Description
`message`	`string`	Message

Response `500application/json`

1 fields

Internal server error

Field	Type	Description
`message`	`string`	Error message.

Other responses

200

GET /partners

Retrieve Partners

getVendors

Retrieve Product Partners

Retrieve Partners retrieves: -All the Partners (vendors) configured in the Product Flows configurations. -The Order of the partner in the Product Waterfall Settings or default order in Product Flows if Product Waterfall was not configured. -The status of the partners as active/upcoming according to the configurations of the product flows of these partners (partner will be active if at least one flow is active).

Response

application/json

Successfully retrieved product partners.

[
  {
    "Partner": "partner_name",
    "order": 1,
    "active": true,
    "status": "active",
    "verification_type": "borrower",
    "byoc": true
  }
]

application/json

Successfully retrieved product partners.

[
  {
    "Partner": "partner_name",
    "order": 1,
    "active": false,
    "status": "upcoming",
    "verification_type": "borrower",
    "byoc": true
  }
]

application/json

Validation Error

{
  "message": "3 is not of type ```string```. Failed validating ```type``` in schema[\"properties\"][\"deal_sets\"][\"items\"][0][\"properties\"][\"parties\"][\"items\"][0][\"properties\"][\"customer_transaction_ID\"]:"
}

application/json

403 invalid error

{
  "message": "Please check the key you used to call this service",
  "url": "https://api.staircase.co/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}

application/json

Internal server error

{
  "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support"
}

Parameters

Parameter	Type	Example	Description
`x-api-key` required	`string` header	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`	Environment API Key.
`active`	`boolean` query	`false`	Include vendors with active product flows

Response `200application/json`

6 fields

Successfully retrieved product partners.

Field	Type	Description
`partner`	`string`	Partner name
`order`	`number`	Order of the product flows associated with this partner
`active`	`boolean`	Partner has active flows
`status`	`string`	Status of the partner
`verification_type`	`string`	Type of verification
`byoc`	`boolean`	Specify whether customer should add its own partner credentials or not

Response `400application/json`

1 fields

Validation Error

Field	Type	Description
`message`	`one of`	Message

Response `403application/json`

2 fields

403 invalid error

Field	Type	Description
`message`	`string`	Error message.
`url`	`string`	Error additional URL.

Response `404application/json`

1 fields

Resource not found

Field	Type	Description
`message`	`string`	Error Message.

Response `500application/json`

1 fields

Internal server error

Field	Type	Description
`message`	`string`	Error message.

GET /products/{product_name}/custom_endpoint/document_language

Get Document Language

getDocumentLanguage

Get document language

Retrieves a document language using the provided name.

Response

application/json

Validation Error

{
  "message": "3 is not of type ```string```. Failed validating ```type``` in schema[\"properties\"][\"deal_sets\"][\"items\"][0][\"properties\"][\"parties\"][\"items\"][0][\"properties\"][\"customer_transaction_ID\"]:"
}

application/json

403 invalid error

{
  "message": "Please check the key you used to call this service",
  "url": "https://api.staircase.co/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}

application/json

Internal server error

{
  "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support"
}

Parameters

Parameter	Type	Example	Description
`product_name` required	`string` path	`Document`	product name
`language_name` required	`string` query	`train-documents-irsw2`	language name

Response `200application/json`

11 fields

Successfully retrieved document language.

Field	Type	Description
`product_name`	`string`	—
`updated_at`	`string`	—
`company_name`	`string`	—
`format`	`string`	Can be JSON or TTL
`type`	`string`	—
`original_data`	`object`	—
`graph_data_ttl`	`string`	—
`example`	`object`	—
`jsonld_settings`	`object`	—
`jsonschema`	`object`	—
`language_name`	`string`	—

Response `400application/json`

1 fields

Validation Error

Field	Type	Description
`message`	`one of`	Message

Response `403application/json`

2 fields

403 invalid error

Field	Type	Description
`message`	`string`	Error message.
`url`	`string`	Error additional URL.

Response `500application/json`

1 fields

Internal server error

Field	Type	Description
`message`	`string`	Error message.

GET /products/{product_name}/custom_endpoint/document_language_search

Search Document Language

searchDocumentLanguage

Get element of document language

Retrieves an element of a document language using the provided query

Response

application/json

Validation Error

{
  "message": "3 is not of type ```string```. Failed validating ```type``` in schema[\"properties\"][\"deal_sets\"][\"items\"][0][\"properties\"][\"parties\"][\"items\"][0][\"properties\"][\"customer_transaction_ID\"]:"
}

application/json

403 invalid error

{
  "message": "Please check the key you used to call this service",
  "url": "https://api.staircase.co/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}

application/json

Internal server error

{
  "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support"
}

Parameters

Parameter	Type	Example	Description
`product_name` required	`string` path	`Document`	product name
`language_name` required	`string` query	`train-documents-irsw2`	language name
`query` required	`string` query	`extracted_data`	query

Response `400application/json`

1 fields

Validation Error

Field	Type	Description
`message`	`one of`	Message

Response `403application/json`

2 fields

403 invalid error

Field	Type	Description
`message`	`string`	Error message.
`url`	`string`	Error additional URL.

Response `500application/json`

1 fields

Internal server error

Field	Type	Description
`message`	`string`	Error message.

Other responses

200

GET /schema/{data_object}

Retrieve Example Schema

retrieveProductSchema

Retrieve Product Schema

Retrieve Product Schema retrieves a JSON that provides schema and examples of the configured product. With Product Schema it is possible to have multiple examples and request, response and merged.

Response

application/json

Successfully returned the object requested

{}

application/json

403 invalid error

{
  "message": "Please check the key you used to call this service",
  "url": "https://api.staircase.co/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}

application/json

Internal server error

{
  "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support"
}

Parameters

Parameter	Type	Example	Description
`x-api-key` required	`string` header	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`	Environment API Key.
`data_object` required	`string` path	`request`	Data Object
`version`	`string` query	`v2`	If included restrict retrieval to the version specified
`return_examples`	`boolean` query	`false`	If included and set to `true`, returns one or more examples. Default to `false`

Response `400application/json`

1 fields

Error

Field	Type	Description
`message`	`string`	Message

Response `403application/json`

2 fields

403 invalid error

Field	Type	Description
`message`	`string`	Error message.
`url`	`string`	Error additional URL.

Response `404application/json`

1 fields

Resource not found

Field	Type	Description
`message`	`string`	Error Message.

Response `500application/json`

1 fields

Internal server error

Field	Type	Description
`message`	`string`	Error message.

Other responses

200

Product Invocation

GET /products/{product_name}/invocations/{invocation_id}

Retrieve Product Flow Invocation Status

RetrieveProductFlowInvocationStatus

Retrieves the status of running Product flow invocation or Waterfall invocation. Product flow invocation statuses:

STARTED: The product flow invocation has been started.
RUNNING: The product flow invocation is running and the status of the running products can be found in service_invocation.
ACTION_REQUIRED: Action is required from the customer and widget_url will be filled to guide the user for the next step.
COMPLETED: The product flow invocation is completed successfully.
FAILED: The product flow invocation failed and the reason of failure can be found in failure_reason.

Response

application/json

Successfully returned status of the Product flow Invocation.

{
  "invocation_id": "9aefb465-90fb-4d50-8ae6-2df2b58373f4",
  "invocation_status": "COMPLETED",
  "product_flow_name": "product_flow_name_example",
  "service_invocation": {
    "Connector": {
      "connector_flow_name": "demo_flow",
      "invocation_id": "e75e8566-976d-4a15-b801-1e2301646f4e",
      "status": "COMPLETED"
    },
    "Translator": {
      "output": {
        "translation_id": "ad985392-1255-4dc0-8a26-bc166744c60c",
        "language_name": "output_language_example",
        "status": "COMPLETED"
      },
      "convert_output": {
        "translation_id": "5382d495-9ec9-4619-8e46-299879c1e92e",
        "language_name": "output_language_example",
        "status": "COMPLETED"
      },
      "input": {
        "translation_id": "0742bc3d-07ca-45fb-a4b7-e9bf627108d0",
        "language_name": "input_language_example",
        "status": "COMPLETED"
      },
      "convert_input": {
        "translation_id": "57082d7c-9964-49b6-945c-7c655768e56a",
        "language_name": "input_language_example",
        "status": "COMPLETED"
      }
    }
  },
  "transaction_id": "01F6NAMXWN2XVBD1YJ92A6S6R4",
  "request_collection_id": "01F6NAQ4894HPMCBGB4P0G95XK",
  "convert_request_collection_id": "01F6NAQ4894HPMCBGB4P0G9KX5",
  "response_collection_id": "01F6QF1QJF20DMSXH4SYXKB1SN",
  "convert_response_collection_id": "01F6QF1QJF20DMSXH4SYXKBNS1",
  "connector_job_id": "3706b519-9426-4533-9868-14a7dec4fd97",
  "request_collection": {
    "collection_id": "01FCWSAQD3QDKEW91K7CPXN4Y2",
    "transaction_id": "01FCWSAH1RVMC0DH6GRQ9JSAE7",
    "data": {},
    "metadata": {
      "created_at": "2021-08-12T04:58:15.331517-04:00",
      "validation": false
    }
  },
  "response_collection": {
    "collection_id": "01FCWSAQD3QDKEW91K7CPXN4Y2",
    "transaction_id": "01FCWSAH1RVMC0DH6GRQ9JSAE7",
    "data": {},
    "metadata": {
      "created_at": "2021-08-12T04:58:15.331517-04:00",
      "validation": false,
      "partner_name": "test_partner",
      "report_download_urls": {
        "voe_template": {
          "download_url": "https://dev-data-manager-blobs-bucket-us-east-1-873429376159.s3.amazonaws.com/01FJYAHNJR",
          "blob_id": "01FCWSAQD3QDKEW91K7CPXN4Y2",
          "status": "Succeeded"
        }
      },
      "service_invocation": {
        "Connector": {
          "connector_flow_name": "demo_flow",
          "invocation_id": "e75e8566-976d-4a15-b801-1e2301646f4e",
          "status": "COMPLETED"
        },
        "Translator": {
          "output": {
            "translation_id": "ad985392-1255-4dc0-8a26-bc166744c60c",
            "language_name": "output_language_example",
            "status": "COMPLETED"
          },
          "convert_output": {
            "translation_id": "5382d495-9ec9-4619-8e46-299879c1e92e",
            "language_name": "output_language_example",
            "status": "COMPLETED"
          },
          "input": {
            "translation_id": "0742bc3d-07ca-45fb-a4b7-e9bf627108d0",
            "language_name": "input_language_example",
            "status": "COMPLETED"
          },
          "convert_input": {
            "translation_id": "57082d7c-9964-49b6-945c-7c655768e56a",
            "language_name": "input_language_example",
            "status": "COMPLETED"
          }
        }
      }
    }
  },
  "options": {
    "dry_run": false
  },
  "tags": [
    "manual verification"
  ]
}

application/json

Successfully returned status of the Product flow Invocation.

{
  "invocation_id": "fbc19f9b-1d37-4ced-9f1d-d2769b018b0a",
  "invocation_status": "COMPLETED",
  "request_collection_id": "01FCWK741N7GWYBVG4Z3N74V16",
  "callback_url": "https://webhook.site/68a4aa6a-bf18-4f7d-be7d-bc26503adeb2",
  "transaction_id": "01FCWK72GC1MFM5003SXJHMWNG",
  "request_collection": {
    "data": {
      "foo": "bar",
      "biz": "baz"
    },
    "metadata": {
      "created_at": "2021-08-12T03:11:25.749933-04:00",
      "validation": false
    },
    "transaction_id": "01FCWK72GC1MFM5003SXJHMWNG",
    "collection_id": "01FCWK741N7GWYBVG4Z3N74V16"
  },
  "response_collection": {
    "data": {},
    "collection_id": "01FCWSMVWW7192SZXR9MP52B4A",
    "transaction_id": "01FCWSMNZM271WVQY6FDS2CB6M",
    "metadata": {
      "created_at": "2021-08-12T05:03:47.612771-04:00",
      "validation": false,
      "partner_name": "test_partner",
      "report_download_urls": {
        "voe_template": {
          "download_url": "https://dev-data-manager-blobs-bucket-us-east-1-873429376159.s3.amazonaws.com/01FJYAHNJR",
          "blob_id": "01FCWSAQD3QDKEW91K7CPXN4Y2",
          "status": "Succeeded"
        }
      }
    }
  },
  "flows_responses": {
    "flow1": {
      "response_collection_id": "01FCWSAQD3QDKEW91K7CPXN4Y2",
      "invocation_id": "7a8980a1-73ac-4313-ada5-e0e976c38ebb",
      "invocation_status": "FAILED",
      "transaction_id": "01FCWSAH1RVMC0DH6GRQ9JSAE7",
      "product_flow_name": "demo_product_flow_422",
      "failure_reason": "Service Connector failed. Connector flow failed. Response payload: {\"Error\": \"CallVendorError\", \"Cause\": {\"errorMessage\": \"\", \"errorType\": \"CallVendorError\"}}",
      "response_collection": {
        "collection_id": "01FCWSAQD3QDKEW91K7CPXN4Y2",
        "data": {},
        "transaction_id": "01FCWSAH1RVMC0DH6GRQ9JSAE7",
        "metadata": {
          "created_at": "2021-08-12T04:58:15.331517-04:00",
          "validation": false
        }
      }
    },
    "flow2": {
      "response_collection_id": "01FCWSMVWW7192SZXR9MP52B4A",
      "invocation_id": "c861def5-5e5d-4690-9313-2f25427029a8",
      "invocation_status": "COMPLETED",
      "transaction_id": "01FCWSMNZM271WVQY6FDS2CB6M",
      "product_flow_name": "demo_product_flow"
    },
    "metadata": {
      "actual_flow_name": "flow2",
      "response_collection_id": "01FCWSMVWW7192SZXR9MP52B4A"
    }
  }
}

application/json

Successfully returned status of the Product flow Invocation.

{
  "invocation_id": "fbc19f9b-1d37-4ced-9f1d-d2769b018b0a",
  "invocation_status": "FAILED",
  "request_collection_id": "01FCWK741N7GWYBVG4Z3N74V16",
  "callback_url": "https://webhook.site/68a4aa6a-bf18-4f7d-be7d-bc26503adeb2",
  "transaction_id": "01FCWK72GC1MFM5003SXJHMWNG",
  "failure_reason": "All product flows were failed.",
  "request_collection": {
    "data": {
      "foo": "bar",
      "biz": "baz"
    },
    "metadata": {
      "created_at": "2021-08-12T03:11:25.749933-04:00",
      "validation": false
    },
    "transaction_id": "01FCWK72GC1MFM5003SXJHMWNG",
    "collection_id": "01FCWK741N7GWYBVG4Z3N74V16"
  },
  "response_collection": {
    "collection_id": "01FCWSAQD3QDKEW91K7CPXN4Y2",
    "data": {},
    "transaction_id": "01FCWSAH1RVMC0DH6GRQ9JSAE7",
    "metadata": {
      "partner_name": "test_partner",
      "created_at": "2021-08-12T04:58:15.331517-04:00",
      "validation": false
    }
  },
  "flows_responses": {
    "flow1": {
      "response_collection_id": "01FCWSAQD3QDKEW91K7CPXN4Y2",
      "invocation_id": "7a8980a1-73ac-4313-ada5-e0e976c38ebb",
      "invocation_status": "FAILED",
      "transaction_id": "01FCWSAH1RVMC0DH6GRQ9JSAE7",
      "product_flow_name": "demo_product_flow_422",
      "failure_reason": "Service Connector failed. Connector flow failed. Response payload: {\"Error\": \"CallVendorError\", \"Cause\": {\"errorMessage\": \"\", \"errorType\": \"CallVendorError\"}}"
    }
  },
  "metadata": {
    "actual_flow_name": "flow1"
  }
}

application/json

403 invalid error

{
  "message": "Please check the key you used to call this service",
  "url": "https://api.staircase.co/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}

application/json

Internal server error

{
  "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support"
}

Parameters

Parameter	Type	Example	Description
`x-api-key` required	`string` header	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`	Environment API Key.
`product_name` required	`string` path	`demo_product_product`	Product Name
`invocation_id` required	`string (ulid)` path	`d7ccedb8-8889-4657-add4-bc1s4xs97637`	Product flow invocation identifier

Response `200application/json`

13 fields

Successfully returned status of the Product flow Invocation.

Field	Type	Description
`invocation_id`required	`string`	Invocation ID.
`invocation_status`required	`string`	Invocation Status.`ACTION_REQUIREDCOMPLETEDFAILEDRUNNINGSTARTED`
`transaction_id`required	`string`	Transaction ID used for invocation.
`request_collection_id`	`string`	Request Collection ID.
`request_collection`	`object`	Collection.
`transaction_id`	`string (ulid)`	Transaction ID.Example `01EZQ32PJQGKRA6HR8D72Q9FFF`
`collection_id`	`string (ulid)`	Collection ID.Example `01EZQ32PJQGKRA6HR8D72Q9FFF`
`data`	`object`	Data in Staircase language schema.
`metadata`	`object`	Metadata about collection, f.e version of used Staircase schema.
`response_collection_id`	`string`	Response Collection ID.
`response_collection`	`object`	Collection.
`transaction_id`	`string (ulid)`	Transaction ID.Example `01EZQ32PJQGKRA6HR8D72Q9FFF`
`collection_id`	`string (ulid)`	Collection ID.Example `01EZQ32PJQGKRA6HR8D72Q9FFF`
`data`	`object`	Data in Staircase language schema.
`metadata`	`object`	Metadata about collection, f.e version of used Staircase schema.
`report_download_urls`required	`object`	Information about each generated report identified by template name.
`callback_url`	`string`	URL that was specified in flow invocation and will be used to send the callback when flow invocation will be finished.
`widget_url`	`string (uri)`	URL of the widget.
`metadata`	`object`	Response Collection ID.
`options`	`—`	Options that were passed to the flow invocation.
`connector_job_id`	`string`	Connector job ID.
`service_invocation`required	`one of`	Includes underlying services invocation.

Response `400application/json`

1 fields

Request data failed validation

Field	Type	Description
`message`	`one of`	Message

Response `403application/json`

2 fields

403 invalid error

Field	Type	Description
`message`	`string`	Error message.
`url`	`string`	Error additional URL.

Response `404application/json`

1 fields

Resource not found

Field	Type	Description
`message`	`string`	Message

Response `500application/json`

1 fields

Internal server error

Field	Type	Description
`message`	`string`	Error message.

Providers

Errors

400403404405422500

How it works

Dual listing

Operations

Documents

Create or update document type

Request

Response

Parameters

Request bodyapplication/json

Response 200application/json

Response 400application/json

Response 403application/json

Other responses

Retrieve document

Response

Parameters

Response 200application/json

Response 400application/json

Response 403application/json

Response 404application/json

Delete document type

Parameters

Response 200application/json

Response 400application/json

Response 403application/json

Response 404application/json

Create Sample

Request

Parameters

Request bodyapplication/json

Response 201application/json

Response 400application/json

Response 403application/json

Response 404application/json

Other responses

Retrieve Samples

Parameters

Response 200application/json

Response 400application/json

Response 403application/json

Response 404application/json

Get Classification Hint

Response 200application/json

Response 403application/json

Delete Sample

Parameters

Response 200application/json

Response 400application/json

Response 403application/json

Response 404application/json

Workflow

Create Transaction

Request

Response

Parameters

Request bodyapplication/json

Response 201application/json

Response 403application/json

Response 500application/json

Other responses

Create Collection

Request

Response

Parameters

Response 400application/json

Response 403application/json

Response 404application/json

Response 500application/json

Other responses

Retrieve Collection

Response

Parameters

Response 403application/json

Response 404application/json

Response 500application/json

Other responses

Classification

Request

Response

Parameters

Request body`application/json`

Response `200application/json`

Response `400application/json`

Response `403application/json`

Response `200application/json`

Response `400application/json`

Response `403application/json`

Response `404application/json`

Response `200application/json`

Response `400application/json`

Response `403application/json`

Response `404application/json`

Request body`application/json`

Response `201application/json`

Response `400application/json`

Response `403application/json`

Response `404application/json`

Response `200application/json`

Response `400application/json`

Response `403application/json`

Response `404application/json`

Response `200application/json`

Response `403application/json`

Response `200application/json`

Response `400application/json`

Response `403application/json`

Response `404application/json`

Request body`application/json`

Response `201application/json`

Response `403application/json`

Response `500application/json`

Response `400application/json`

Response `403application/json`

Response `404application/json`

Response `500application/json`

Response `403application/json`

Response `404application/json`

Response `500application/json`

Request body`application/json`

Response `201application/json`

Response `400application/json`

Response `403application/json`

Response `404application/json`

Response `422application/json`

Response `500application/json`

Response `400application/json`

Response `403application/json`

Response `404application/json`

Response `500application/json`

Response `200application/json`

Response `400application/json`

Response `403application/json`

Response `404application/json`

Response `500application/json`

Response `200application/json`

Response `400application/json`

Response `403application/json`

Response `500application/json`

Response `400application/json`

Response `403application/json`

Response `500application/json`

Response `400application/json`

Response `403application/json`

Response `404application/json`

Response `500application/json`

Response `200application/json`

Response `400application/json`

Response `403application/json`

Response `404application/json`

Response `500application/json`