# Document
# 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 Copy
```
{
"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 Copy 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
1
| 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`boolean``date``integer``number``string` |
| `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 `200``application/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`boolean``date``integer``number``string` |
| `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 `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` `/documents/{document_type}`
#### Retrieve document
`retrieveDocument`
##### Response
application/json Copy 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
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `document_type` required | `string` path | `irs_w2` | Document type |
##### Response `200``application/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`boolean``date``integer``number``string` |
| `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 `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
Not Found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
`DELETE` `/documents/{document_type}`
#### Delete document type
`deleteDocument`
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `document_type` required | `string` path | `irs_w2` | Document type |
##### Response `200``application/json`
1 fields
Document type has been deleted
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | message |
##### 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
Not Found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
`POST` `/documents/{document_type}/samples`
#### Create Sample
`createSample`
Create sample
##### Request
application/json Copy
```
{
"blob_id": "01G9300Q4KT3FHP61ANG2R66SY",
"name": "FILLED_CLOSING_DISCLOSURE"
}
```
##### Parameters
1
| 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 `201``application/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 `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
Not Found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Other responses
`422`
`GET` `/documents/{document_type}/samples`
#### Retrieve Samples
`retrieveSamples`
Retrieve samples
##### Parameters
1
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `document_type` required | `string` path | `irs_w2` | Document type |
##### Response `200``application/json`
2 fields
Document samples
| Field | Type | Description |
| --- | --- | --- |
| `count` | `integer` | Samples count |
| `samples` | `array` | Samples |
##### 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
Not Found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
`GET` `/documents/hint`
#### Get Classification Hint
`getClassificationHint`
Provides the URL to the classification hint page.
##### Response `200``application/json`
1 fields
Documents hint
| Field | Type | Description |
| --- | --- | --- |
| `hint_page_url`required | `string` | URL to the hint page |
##### Response `403``application/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
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `document_type` required | `string` path | `irs_w2` | Document type |
| `sample_id` required | `string` path | `12345` | Sample ID |
##### Response `200``application/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 `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
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 Copy
```
{
"label": "first_transaction",
"callback_url": "https://webhook.site/0c1c4e00-79d9-490b-a0f3-bab8b12a61d5"
}
```
##### Response
201403500
application/json Copy Transaction created successfully
```
{
"transaction_id": "01F0KHK7DN3H5JZ4QJKMYAM6GB",
"created_at": "03/04/2021, 1:04:05 PM EST"
}
```
application/json Copy 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 Copy 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
1
| 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 `201``application/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 `403``application/json`
2 fields
403 invalid error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message. |
| `url` | `string` | Error additional URL. |
##### Response `500``application/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 Copy
```
{}
```
##### Response
201400 CreateCollectionError400 text/html403404 CreateCollectionError404 text/html500
application/json Copy Collection created successfully
```
{}
```
application/json Copy Error
```
{
"message": "Unable to create collection. Please check the collection data"
}
```
text/html Copy Error
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy 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 Copy Resource not found
```
{
"message": "Unable to create collection. Please check the transaction ID."
}
```
text/html Copy Resource not found
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy 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
2
| 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 `400``application/json`
1 fields
Error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Either message object with more properties. |
##### Response `403``application/json`
2 fields
403 invalid error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message. |
| `url` | `string` | Error additional URL. |
##### Response `404``application/json`
1 fields
Resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `500``application/json`
1 fields
Internal server error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message. |
##### Other responses
`201``405`
`GET` `/transactions/{transaction_id}/collections/{collection_id}`
#### Retrieve Collection
`retrieveCollection`
Retrieve Collection returns the content of a given `collection_id` associated with a `transaction_id`.
##### Response
200403404 GetCollectionError404 GetCollectionsError500
application/json Copy Successfully Retrieved Collection
```
{}
```
application/json Copy 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 Copy Resource not found
```
{
"message": "Unable to get collection. Please check the given ids"
}
```
application/json Copy Resource not found
```
{
"message": "Unable to get collections of given transaction. Please check the transaction id"
}
```
application/json Copy 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
3
| 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 `403``application/json`
2 fields
403 invalid error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message. |
| `url` | `string` | Error additional URL. |
##### Response `404``application/json`
1 fields
Resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `500``application/json`
1 fields
Internal server error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message. |
##### Other responses
`200``400`
`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
InvokeByFlowNameInvokeByTagsInvokeWithRequestDataInvokeWithFlowOptionsCollectionsInvokeWithFlowOptionsRequestDataInvokeByFlowNameOptionsInvokeByVendorNameOptionsInvokeWaterfall
application/json Copy
```
{
"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 Copy
```
{
"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 Copy
```
{
"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 Copy
```
{
"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 Copy
```
{
"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 Copy
```
{
"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 Copy
```
{
"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 Copy
```
{
"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
201400403404422500
application/json Copy 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 Copy Request data failed validation
```
{
"message": "{\"data\": [\"Missing data for required field.\"]}"
}
```
application/json Copy 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"
}
```
text/html Copy Resource not found
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy 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 Copy 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
1
| 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 `201``application/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 `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Message |
##### Response `403``application/json`
2 fields
403 invalid error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message. |
| `url` | `string` | Error additional URL. |
##### Response `404``application/json`
1 fields
Resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `422``application/json`
1 fields
Unprocessable entity error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message. |
##### Response `500``application/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
200400403404500
application/json Copy Transaction collection retrieved successfully
```
{}
```
text/html Copy Error
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy 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 Copy Resource not found
```
{
"message": "Unable to get collections of given transaction. Please check the transaction id"
}
```
application/json Copy 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
2
| 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 `400``application/json`
1 fields
Error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Either message object with more properties. |
##### Response `403``application/json`
2 fields
403 invalid error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message. |
| `url` | `string` | Error additional URL. |
##### Response `404``application/json`
1 fields
Resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `500``application/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
200 Example1200 Example2400403404 GetProduct404 text/html500
application/json Copy Successfully retrieved product partners.
```
[
{
"Partner": "partner_name",
"order": 1,
"active": true,
"status": "active",
"verification_type": "borrower",
"byoc": true
}
]
```
application/json Copy Successfully retrieved product partners.
```
[
{
"Partner": "partner_name",
"order": 1,
"active": false,
"status": "upcoming",
"verification_type": "borrower",
"byoc": true
}
]
```
application/json Copy 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 Copy 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 Copy Resource not found
```
{
"type": "string",
"description": "Error Message."
}
```
text/html Copy Resource not found
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy 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
2
| 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 `200``application/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 `400``application/json`
1 fields
Validation Error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Message |
##### Response `403``application/json`
2 fields
403 invalid error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message. |
| `url` | `string` | Error additional URL. |
##### Response `404``application/json`
1 fields
Resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message. |
##### Response `500``application/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
400403500
application/json Copy 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 Copy 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 Copy 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
2
| Parameter | Type | Example | Description |
| --- | --- | --- | --- |
| `product_name` required | `string` path | `Document` | product name |
| `language_name` required | `string` query | `train-documents-irsw2` | language name |
##### Response `200``application/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 `400``application/json`
1 fields
Validation Error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Message |
##### Response `403``application/json`
2 fields
403 invalid error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message. |
| `url` | `string` | Error additional URL. |
##### Response `500``application/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
400403500
application/json Copy 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 Copy 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 Copy 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
3
| 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 `400``application/json`
1 fields
Validation Error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Message |
##### Response `403``application/json`
2 fields
403 invalid error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message. |
| `url` | `string` | Error additional URL. |
##### Response `500``application/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
200400 DataObjectNotProvided400 text/html403404 GetProduct404 text/html500
application/json Copy Successfully returned the object requested
```
{}
```
application/json Copy Error
```
{
"message": "data_object should be any of the following strings: request, response or merged."
}
```
text/html Copy Error
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy 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 Copy Resource not found
```
{
"type": "string",
"description": "Error Message."
}
```
text/html Copy Resource not found
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy 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
4
| 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 `400``application/json`
1 fields
Error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `403``application/json`
2 fields
403 invalid error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message. |
| `url` | `string` | Error additional URL. |
##### Response `404``application/json`
1 fields
Resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error Message. |
##### Response `500``application/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
200 ProductFlowStatus200 WaterfallStatusCompleted200 WaterfallStatusFailed400403404500
application/json Copy 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 Copy 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 Copy 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 Copy Request data failed validation
```
{
"message": "{\"data\": [\"Missing data for required field.\"]}"
}
```
application/json Copy 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"
}
```
text/html Copy Resource not found
```
\r\n400 Bad Request\r\n\r\n400 Bad Request
\r\n\r\n\r\n
```
application/json Copy 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
3
| 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 `200``application/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_REQUIRED``COMPLETED``FAILED``RUNNING``STARTED` |
| `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 `400``application/json`
1 fields
Request data failed validation
| Field | Type | Description |
| --- | --- | --- |
| `message` | `one of` | Message |
##### Response `403``application/json`
2 fields
403 invalid error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message. |
| `url` | `string` | Error additional URL. |
##### Response `404``application/json`
1 fields
Resource not found
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Message |
##### Response `500``application/json`
1 fields
Internal server error
| Field | Type | Description |
| --- | --- | --- |
| `message` | `string` | Error message. |
## Providers
- Ephesoft
- Mindee
- Ocrolus
- SoftworksAI
## Errors
`400``403``404``405``422``500`
## More in Validation
- Previous product: Appraisal
- Next product: Title