Borrower bank and asset verification over several account-data vendors, returning canonical account and balance records.
A caller sends a borrower and receives account records: institution, account type, balances, and the transaction history a verification report covers. The ordering below is the committed sequence.
How it works
One vendor had no webhook. Its verification is long-running, and the vendor's own guidance was to poll — which would have put a polling loop inside every caller.
The integration was split into three declarative flows instead: a main flow, a status-checking flow that polls on an interval, and an on-demand status call. When the status flow sees completion it emits the webhook message the main flow was waiting for. The main flow is written as though the webhook exists.
The reason that matters is what happens next: when the vendor ships the real webhook, the two supporting flows are deleted and the main flow is unchanged. The emulation was built to be removable, and the design note on disk says so.
Operations
Platform
PUT/blobs/{blob_id}/presigned-urls/{action}
Create Report Download URL
createPresignedUrl
Create Report Download URL creates a presigned URL in Staircase. It expires one hour after creation.
If partner provides a report in the documents, you can generate a download url with using staircase blob ID.
{
"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"
}
Parameters
3
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Environment API Key.
blob_idrequired
stringpath
01EZY9J8SEFM2JKDJ1Q3YX65HS
Blob identifier
actionrequired
stringpath
upload
Action, one of one of ['upload', 'download']
Response 200application/json
2 fields
Presigned URL created successfully.
Field
Type
Description
upload
object
Action
url
string
Presigned_url
download
object
Action
url
string
Presigned_url
Response 403application/json
2 fields
403 invalid error
Field
Type
Description
message
string
Error message.
url
string
Error additional URL.
Other responses
400404
GET/response-elements
Retrieve Response Elements
responseElements
Retrieve Response Elements provides a list of elements that will be returned by a partner performing verification of assets.
Response
application/json
Invalid key for service
{
"message": "Please check the key you used to call this service",
"url": "https://api.staircase.co/docs/DevOps/Distribute/Account/get-retrieve-credentials"
}
application/json
Resource not found
{
"message": "Unable to get collections of given transaction. Please check the transaction id"
}
application/json
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
{
"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
Bad gateway.
{
"message": "Internal server error."
}
Response 200application/json
2 fields
Elements retrieved successfully
Field
Type
Description
path
string
Contains the path in Staircase language
value
string
Enter your own values here
Response 403application/json
2 fields
Invalid key for service
Field
Type
Description
message
string
—
url
string
—
Response 404application/json
1 fields
Resource not found
Field
Type
Description
message
string
Message
Response 500application/json
1 fields
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
Field
Type
Description
message
string
—
Response 502application/json
1 fields
Bad gateway.
Field
Type
Description
message
string
Error Message.
GET/products/asset/schema/{data_object}
Retrieve Product Schema
retrieveProductSchema
Retrieve Product Schema retrieves a JSON schema for the request and response collection that you can provide to the invocation.
If you'd like to retrieve some examples for the request or response collection, use return_examples=True query parameter.
Product Schema Collection Description
Borrower
Lexicon Path
Description
$.people[0].@type
Type of person (borrower)
$.people[0].has_first_name
.has_value
The first name of the individual represented by the parent object.
$.people[0].has_last_name
.has_value
The last naShow the rest
me of the individual represented by the parent object.
$.people[0].has_birth_date
.has_value
Borrower's date of birth. Collected in lieu of AGE in URLA, Section III, second line, third field.
$.people[0].has_taxpayer_identifier_value
.has_value
The specific value of the taxpayer identifier as assigned by the Internal Revenue Service (IRS) to the individual or legal entity.
$.people[0].with_address
Address Information
$.people[0].contact_at
Contact Information
Address
Lexicon Path
Description
$.addresses[0].@type
Type of address (residential_address)
$.people[0].has_address_line_1_text
.has_value
Address Line 1
$.people[0].has_address_line_2_text
.has_value
Address Line 2
$.people[0].has_city_name
.has_value
The name of the city or Military APO FPO designation.
$.people[0].has_state_code
.has_value
The two-character representation of the US state, US Territory, Canadian Province/Territory, or Military Address abbreviation (for example: AE, AP, AA).
$.people[0].has_postal_code
.has_value
The postal code (ZIP Code in the US) for the address. ZIP Code may be either 5 or 9 digits.
$.people[0].has_country_name
.has_value
The name of the country.
Contact
Lexicon Path
Description
$.contact_information[0].@type
organization
$.contact_information[0].has_phone_number
.has_value
Borrowers Phone Number
$.contact_information[0].has_email_address
.has_value
Borrowers Email
Response
application/json
Successfully returned the list of elements needed for product waterfall.
{
"message": "Please provide one of valid return examples values: true, false"
}
text/html
Error
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
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"
}
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
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
3
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Environment API Key.
data_objectrequired
stringpath
request
Data Object
return_examples
booleanquery
false
If included and set to `true`, returns one or more pre-filled examples that conform to the schema. Default to `false`
Response 200application/json
1 fields
Successfully returned the list of elements needed for product waterfall.
Field
Type
Description
schema
object
Element key / value
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.
GET/schema/{data_object}
Retrieve Schema
retrieveSchema
Retrieve Schema retrieves a JSON schema for the request and the response returned by the product.
Response
application/json
Error
{
"message": "Please provide one of valid data object values: request, response"
}
application/json
Error
{
"message": "Please provide one of valid version values: v0"
}
application/json
Error
{
"message": "Please make sure your query parameters contains version parameter."
}
application/json
Error
{
"message": "Please provide one of valid return examples values: true, false"
}
application/json
Invalid key for service
{
"message": "Please check the key you used to call this service",
"url": "https://api.staircase.co/docs/DevOps/Distribute/Account/get-retrieve-credentials"
}
application/json
Resource not found
{
"message": "Unable to get collections of given transaction. Please check the transaction id"
}
application/json
Bad gateway.
{
"message": "Internal server error."
}
Parameters
3
Parameter
Type
Example
Description
data_objectrequired
stringpath
request
Describes the particular data object you are getting a schema for.
return_examples
booleanquery
false
If included and set to `true`, returns one or more pre-filled examples that conform to the schema. Default to `false`
versionrequired
stringquery
v0
Defines the version of the Staircase language you want the JSON to return in.
Response 200application/json
1 fields
Successfully returned the list of elements needed for AUS.
Update Collection allows you to update the content of a given collection_id associated with a transaction_id.
Response
application/json
Error
{
"description": "",
"message": "Unable to update collection. Please check the collection data"
}
application/json
Invalid key for service
{
"message": "Please check the key you used to call this service",
"url": "https://api.staircase.co/docs/DevOps/Distribute/Account/get-retrieve-credentials"
}
application/json
Resource not found
{
"message": "Unable to update collection. Please check the given ids"
}
application/json
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
{
"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
Bad gateway.
{
"message": "Internal server error."
}
Parameters
2
Parameter
Type
Example
Description
transaction_idrequired
string (ulid)path
01F5X9B9JBE958CWAXPB8MNFW1
Staircase Transaction Identifier
collection_idrequired
string (ulid)path
01F5X9BCPQFR3HS2MQ1EW9X2NZ
Staircase collection_id
Request bodyapplication/json
2 fields
Field
Type
Description
data
object
Staircase collections can hold any type of valid JSON data
metadata
object
The metadata object describes properties that a Staircase collection has
created_at
string
Example 03/03/2021, 8:24:04 AM EST
updated_at
string
Example 03/03/2021, 8:24:04 AM EST
validation
boolean
Describes whether the collection has been validated against Staircase language schemaExample false
partner_name
string
Staircase partner name that was used to generate the collection
results
object
Contains the results of an operation that generated the collection
status
string
Describes the state of the operation that generated the collectionCOMPLETEDERRORIN_PROGRESSTIMED_OUTExample COMPLETED
product
string
Name of the Staircase product that generated the collectionExample Assets
Response 200application/json
4 fields
Collection updated successfully
Field
Type
Description
data
object
—
deal_sets
object
—
deal_set
object[]
—
deals
object
—
metadata
object
The metadata object describes properties that a Staircase collection has
created_at
string
Example 03/03/2021, 8:24:04 AM EST
updated_at
string
Example 03/03/2021, 8:24:04 AM EST
validation
boolean
Describes whether the collection has been validated against Staircase language schemaExample false
partner_name
string
Staircase partner name that was used to generate the collection
results
object
Contains the results of an operation that generated the collection
status
string
Describes the state of the operation that generated the collectionCOMPLETEDERRORIN_PROGRESSTIMED_OUTExample COMPLETED
product
string
Name of the Staircase product that generated the collectionExample Assets
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
Field
Type
Description
message
string
—
Response 502application/json
1 fields
Bad gateway.
Field
Type
Description
message
string
Error Message.
Blobs
POST/blobs/upload
Update Blob
uploadBlob
Upload Blob
Upload Blob allows a customer to upload a document in .pdf form.
Upload Blob uploads a .pdf document (blob) to Persistence product.
You can upload PDF using HTML Request Maker Try It Out.
Place your api_key in the request header, set the request body to binary and browse to your document.
Click Send to upload your document.
To upload a document programmatically, use the programmatic upload example below.
After the approval document is successfully uploaded, a blob_id value is provided.
Example: 'blob_id': '01EZYHKY4EXFW4Z8RKWHDP1KHB'
After you got successful response, you need to use the blob_id in collection with the following path.
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/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
1
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Environment API Key.
Response 201application/json
1 fields
Blob uploaded
Field
Type
Description
blob_id
string
Created blob ID
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
400405422
GET/blobs/{blob_id}
Retrieve Blob
retrieveBlob
Retrieve Blob retrieves, for a given blob_id, extension and presigned URLs for uploading and downloading the blob to and from Staircase.
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/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
2
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Environment API Key.
blob_idrequired
stringpath
01EZY9J8SEFM2JKDJ1Q3YX65HS
Blob identifier
Response 200application/json
4 fields
Blob retrieved successfully.
Field
Type
Description
blob_id
string
Blob ID
extension
string
File extension
message
string
Blob retrieved successfully.
presigned_urls
object
Presigned URL
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
400404405
GET/blobs/{blob_id}/presigned-urls/{action}
Retrieve Presigned URL for Action
retrievePresignedUrl
Retrieve Presigned URL for Action retrieves a presigned URL for a specific action. An action can be download or upload.
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/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
3
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Environment API Key.
blob_idrequired
stringpath
01EZY9J8SEFM2JKDJ1Q3YX65HS
Blob identifier
actionrequired
stringpath
upload
Possible actions: - upload - download
Response 200application/json
1 fields
Presigned URL retrieved successfully.
Field
Type
Description
url
string
Presigned url
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
400404
GET/blobs/{blob_id}/presigned-urls
Retrieve Presigned URLs
retrievePresignedUrls
Retrieve Presigned URLs retrieves, for a given blob_id, presigned URLs for uploading and downloading the blob to and from Staircase.
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
Parameters
2
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Environment API Key.
blob_idrequired
stringpath
01EZY9J8SEFM2JKDJ1Q3YX65HS
Blob identifier
Response 200application/json
1 fields
Presigned URLs retrieved successfully.
Field
Type
Description
presigned_urls
object
Presigned URLs
Response 403application/json
2 fields
403 invalid error
Field
Type
Description
message
string
Error message.
url
string
Error additional URL.
Other responses
400404
POST/create_blob_from_content
Create Blob from Partner content
createBlobFromContent
Create Blob from Partner content will create a blob from the content that a partner has returned. The payload will be the extension path of the blob to be created in the vendor response object, content_path is the path of the content element in the vendor response object.
Request
application/json
Blob content from partner
Response
application/json
Presigned URLs retrieved successfully.
{
"blob_id": "01F739J4XDSNCZMMJSJCB83PCQ"
}
application/json
Invalid body request.
{
"message": "Unable to retrieve url"
}
application/json
Invalid body request.
{
"message": "Unable to extract data from URL"
}
application/json
403 invalid error
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/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
1
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Environment API Key.
Request bodyapplication/json
5 fields
Field
Type
Description
extension_path
string
JSON path where the extension is in the response object. If it is not specified, extension will be "pdf".Example $.DocumentExension
content_pathrequired
string
JSON path where the actual content is in the response object.Example $.DocumentData
decode_from_base64
boolean
Need to decode a content from base64.
encode_to_base64
boolean
Need to encode a content to base64.
urlrequired
string
URL with the partner response.Example https://google.com
Response 201application/json
1 fields
Presigned URLs retrieved successfully.
Field
Type
Description
blob_id
string
ID of the returned blob.
Response 400application/json
1 fields
Invalid body request.
Field
Type
Description
message
string
Error message
Response 403application/json
2 fields
403 invalid error
Field
Type
Description
message
string
Error message.
url
string
Error additional URL.
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.
Partners
GET/partners
Retrieve Partners
retrievePartners
Retrieve Partners retrieves an object containing all partners active for the product and information about them.
You can use the partner_name to invoke the partner directly in the product invocation.
{
"message": "Please check the key you used to call this service",
"url": "https://api.staircase.co/docs/DevOps/Distribute/Account/get-retrieve-credentials"
}
application/json
Resource not found
{
"message": "Unable to get collections of given transaction. Please check the transaction id"
}
application/json
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
{
"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
Bad gateway.
{
"message": "Internal server error."
}
Response 200application/json
6 fields
Successfully returned the partner object
Field
Type
Description
byoc
boolean
If value is set to "True", customer must add its own partner credentials to be able to use this partner for verification.
active
boolean
If set to "True" partner can be used for verification. If set to "False" partner will be disabled for verification and excluded from the waterfall.
status
string
Parameter for documentation. Can be set to "active" and "upcoming".
verification_type
string
If value is set to "borrower", borrower needs to authorize verification process via provided URL. Whether value is set to "instant", verification process is done without any third party interventions. If value is set to "manual", verification process needs to be approved manually by selected data partner.borrowerinstantmanual
partner
string
Partner name.
order
integer
Order value provides priority on waterfall execution, where number 1 represents the highest priority and such will be executed first in the waterfall feature.
Response 403application/json
2 fields
Invalid key for service
Field
Type
Description
message
string
—
url
string
—
Response 404application/json
1 fields
Resource not found
Field
Type
Description
message
string
Message
Response 500application/json
1 fields
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
Field
Type
Description
message
string
—
Response 502application/json
1 fields
Bad gateway.
Field
Type
Description
message
string
Error Message.
GET/products/asset/partners
Retrieve Product Partners
getVendors
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).'
{
"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"
}
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
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
2
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Environment API Key.
active
booleanquery
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/asset/partners/ordering
Retrieve Partners Ordering
getPartnersOrdering
Retrieve Partners Ordering retrieves the partners'' order for the product waterfall invocation according to the configured Product Waterfall Settings.
If there is no waterfall for the product configured, partners will be retrieved with the default of the order inside Product Flows.
{
"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"
}
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
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
1
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Environment API Key.
Response 200application/json
1 fields
Successfully retrieved partners ordering.
Field
Type
Description
partner_order
object
Partner and order
partner
string
Example partner1
order
number
Example 1
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.
PUT/partners/{partner}/status
Update Partner Status
updatePartnerStatus
Update partner status
Update Partner Status updates the active parameter of a partner to either true or false. Set partner name that you want to enable/disable.
Request
application/json
{
"active": true
}
Response
application/json
Successfully updated active parameter for the partner
{
"message": "Partner status updated!"
}
application/json
Failed to update the partner from one of the reasons
{
"message": "Partner doesn't exist in database"
}
application/json
Invalid key for service
{
"message": "Please check the key you used to call this service",
"url": "https://api.staircase.co/docs/DevOps/Distribute/Account/get-retrieve-credentials"
}
application/json
Resource not found
{
"message": "Unable to get status. Please check the given ids"
}
application/json
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
{
"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-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Staircase Documentation Environment API Key
partnerrequired
stringpath
partner_name
Name of the partner for which we wan't to update status
Request bodyapplication/json
1 fields
Field
Type
Description
activerequired
boolean
Example true
Response 200application/json
1 fields
Successfully updated active parameter for the partner
Field
Type
Description
message
string
Partner status updated!
Response 400application/json
1 fields
Failed to update the partner from one of the reasons
Field
Type
Description
message
string
Partner doesn't exist in database
Response 403application/json
2 fields
Invalid key for service
Field
Type
Description
message
string
—
url
string
—
Response 404application/json
1 fields
Resource not found
Field
Type
Description
message
string
Message
Response 500application/json
1 fields
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
Field
Type
Description
message
string
—
PUT/products/asset/partners/ordering
Update Partners Ordering
UpdatePartnersOrdering
Update Partners Order updates the order of execution of the product flows associated with the partner by updating their order in the product waterfall settings.
Failed to update the partner from one of the reasons
{
"message": "Partner doesn't exist in database"
}
text/html
Failed to update the partner from one of the reasons
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
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"
}
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
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
1
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Environment API Key.
Request bodyapplication/json
1 fields
Field
Type
Description
ordering
object[]
—
partner
string
Partner nameExample wage
order
number
Partner orderExample 1
Response 200application/json
2 fields
Successfully updated partners ordering.
Field
Type
Description
partner
string
Partner nameExample wage
order
number
Partner orderExample 1
Response 400application/json
1 fields
Failed to update the partner from one of the reasons
Field
Type
Description
message
string
Partner doesn't exist in database
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.
PATCH/products/asset/partners/{partner}/status
Update Partner Status
updatePartnerStatus
Update Partner Status updates the active value of a specific partner to value true or false. This shall activate or deactivate the flows configured for this partner in Product Flows.
Successfully updated active parameter for the partner.
{
"message": "Partner status updated."
}
application/json
Failed to update the partner from one of the reasons.
{
"message": "Partner doesn't exist in database."
}
text/html
Failed to update the partner from one of the reasons.
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
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"
}
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
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
2
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Environment API Key.
partnerrequired
stringpath
partner_name
Name of the partner for which we wan't to update status.
Request bodyapplication/json
4 fields
Field
Type
Description
activerequired
boolean
Example true
byoc
boolean
Specify whether customer should add its own partner credentials or not
status
string
Status of the vendor
verification_type
string
Type of verification
Response 200application/json
1 fields
Successfully updated active parameter for the partner.
Field
Type
Description
message
string
Partner status updated.
Response 400application/json
1 fields
Failed to update the partner from one of the reasons.
Field
Type
Description
message
string
Partner doesn't exist in database.
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/partners/{partner}/schema
Retrieve Partner Schema
getPartnerSchema
Retrieve Partner Schema retrieves the required partner schema for credentials.
{
"message": "Please check the key you used to call this service",
"url": "https://api.staircase.co/docs/DevOps/Distribute/Account/get-retrieve-credentials"
}
application/json
Resource not found
{
"message": "Unable to get collections of given transaction. Please check the transaction id"
}
application/json
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
{
"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
Bad gateway.
{
"message": "Internal server error."
}
Parameters
2
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Staircase Documentation Environment API Key
partnerrequired
stringpath
partner_name
Name of the partner for which we wan't to retrieve schema
Response 200application/json
10 fields
Successfully returned the partner schema object
Field
Type
Description
schema
string
Schema URL
id
string
Schema ID
type
string
JSON type
title
string
Schema title
description
string
Schema description
webhook
boolean
Value that indicates if partner requires webhook setup
default
object
Default value for schema
examples
object[]
List of examples
key1
string
Example 1
key2
string
Example 2
required
string[]
Required fields
properties
object
Properties of Schema
key1
object
Key 1 Schema
id
string
Property ID
type
string
Property value type
title
string
Title for property
description
string
Description for property
default
string
Default value if exists
examples
string[]
List of examples for given property
key2
object
Key 2 Schema
id
string
Property ID
type
string
Property value type
title
string
Title for property
description
string
Description for property
default
string
Default value if exists
examples
string[]
List of examples for given property
Response 400application/json
1 fields
Bad Request
Field
Type
Description
message
string
Partner not found
Response 403application/json
2 fields
Invalid key for service
Field
Type
Description
message
string
—
url
string
—
Response 404application/json
1 fields
Resource not found
Field
Type
Description
message
string
Message
Response 500application/json
1 fields
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
Field
Type
Description
message
string
—
Response 502application/json
1 fields
Bad gateway.
Field
Type
Description
message
string
Error Message.
Workflow
POST/products/asset/invocations
Verify Asset
invokeProductFlow
This endpoint creates an asset verification request for the provided transaction, collection and selected partner
Usage
You can send a request in two different ways:
Using transaction_id and collection_id: If you already have a request collection, you can provide its details using these two parameters. Note that in this case Response Collection would be created in the provided Transaction.
Using request_data: If you provide this parameter, flow invocation would use the data here as input. If you also provide a transaction_id in the request body, Response Collection would be created in the related Transaction object. If you don't provide a transaction_id we will automatically create a Transaction for you and Response Collection would be created in this new Transaction as well.
Retrieving the Invocation Result
After invocation, endpoint returns an invocation_id which you can poll for its status using /products/asset/invocations/{invocation_id} endpoint. Once the invocation is completed, the Response Collection is populated with these search results.
Show the rest
If you would rather receive a callback once the invocation is completed instead of polling it, you can set callback_url parameter in the request body.
Enabling Waterfall
If the waterfall feature is enabled, partner is selected based on the partner ordering.
To use the waterfall feature set the partner name to default. This way verification will be executed following the ordering for all available data partners. Use Update Partners Ordering and Retrieve Partners Ordering to set and get the orderings. If two data partners share the same legal entity full name the verification will be done based on the ordering of data partners.
Initiate Equifax Verification
This endpoint flow initiates Equifax asset verification.
You need to create people, contact_information, addresses, organizations, loans and additional_information arrays in your request collection. Each of these arrays contains corresponding @id and @type fields.
people array's element:
For people you need to provide the following borrower information:
first name
last name
birthdate
taxpayer identifier
contact_at relation with the contact_information object (this value needs to be unique)
with_address relation with the addresses object (this value needs to be unique)
contact_information array's element:
For contact_information you need to provide the following borrower contact information:
email address
addresses array's element:
For addresses you need to provide the following borrower address information:
address
city name
state code
postal code
organizations array's element:
For organizations you need to provide the following organization information:
organization name
loans array's element:
For loans you need to provide the following loan information:
loan identifier
additional_information array's element:
For additional_information you need to provide multiple objects, each containing a pair of information:
additional information key identifier
additional information value
Additional information key identifiers are:
monitoringDuration
permissiblePurpose
orderStartDate
orderEndDate
ccEmail
Please find a corresponding request example at the bottom of this page.
Initiate Equifax Re-Verification
This endpoint flow initiates Equifax asset re-verification.
You need to create additional_information and organizations arrays in your request collection. Each of these arrays contains corresponding @id and @type fields.
additional_information array's element:
For additional_information you need to provide multiple objects, each containing a pair of information:
additional information key identifier
additional information value
Additional information key identifiers are:
referenceNumber
consumerIdentifierLast4
organizations array's element:
For organizations you need to provide the following organization information:
organization name
Please find a corresponding request example at the bottom of this page.
Check Equifax Verification Status
This endpoint flow checks Equifax asset verification status.
You need to create additional_information and organizations arrays in your request collection. Each of these arrays contains corresponding @id and @type fields.
additional_information array's element:
For additional_information you need to provide multiple objects, each containing a pair of information:
additional information key identifier
additional information value
Additional information key identifiers are:
referenceNumber
consumerIdentifierLast4
organizations array's element:
For organizations you need to provide the following organization information:
organization name
Please find a corresponding request example at the bottom of this page.
{
"message": "{'data': ['Missing data for required field.']}"
}
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"
}
text/html
Resource not found
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
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
1
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Environment API Key.
Request bodyapplication/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_idrequired
string
Invocation ID.
invocation_statusrequired
string
The status of the invocation.STARTED
transaction_idrequired
string
Transaction ID.
request_collection_idrequired
string
Request collection ID.
response_collection_idrequired
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 500application/json
1 fields
Internal server error
Field
Type
Description
message
string
Error message.
POST/transactions
Create Transaction
createTransaction
Create Transaction creates a transaction in Staircase.
Transactions in Staircase are containers for all the data related to an instance of a transaction type. They enable you to correlate the output of various products to a single transaction type, where the transaction type depends on your line of business.
Transactions are identified by a unique key called transaction_id. As you use different Staircase products to gather the data needed for a specific instance of your transaction type, and receive different sets of output from each product, use the same transaction_id to correlate all the outputs to the same transaction.
A transaction_id, when used properly, gives you a holistic view of the data related to the transaction you’ve assembled.
To access all collections associated with a given transaction_id, try out /transactions/{transaction_id}/collections
{
"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
1
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Environment API Key.
Request bodyapplication/json
2 fields
Field
Type
Description
callback_url
string (url)
URL for receiving events about changes inside transaction
{
"message": "{'data': ['Missing data for required field.']}"
}
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"
}
text/html
Resource not found
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
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
2
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Environment API Key.
invocation_idrequired
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.
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_urlsrequired
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_invocationrequired
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.
GET/request-elements
Retrieve Request Elements
requestElements
Retrieve Request Elements retrieves a list of elements needed to invoke a partner for asset verification.
Response
application/json
Invalid key for service
{
"message": "Please check the key you used to call this service",
"url": "https://api.staircase.co/docs/DevOps/Distribute/Account/get-retrieve-credentials"
}
application/json
Resource not found
{
"message": "Unable to get collections of given transaction. Please check the transaction id"
}
application/json
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
{
"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
Bad gateway.
{
"message": "Internal server error."
}
Response 200application/json
2 fields
Elements retrieved successfully
Field
Type
Description
path
string
Contains the path in Staircase language
value
string
Enter your own values here
Response 403application/json
2 fields
Invalid key for service
Field
Type
Description
message
string
—
url
string
—
Response 404application/json
1 fields
Resource not found
Field
Type
Description
message
string
Message
Response 500application/json
1 fields
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
Field
Type
Description
message
string
—
Response 502application/json
1 fields
Bad gateway.
Field
Type
Description
message
string
Error Message.
POST/build-payload
Build JSON Payload
retrieveExampleJSON
Build JSON Payload helps you build a JSON payload using the JSON paths from Request Elements or Response Elements. You can use this payload to either:
submit a request for asset verification
simulate a response containing asset verification details.
Simply add key/value pairs of path/desired output and POST to /build-payload. It will then build a nested JSON. You can find examples below.
Response
application/json
Request data failed validation
{
"message": "{'data': ['Missing data for required field.']}"
}
application/json
Invalid key for service
{
"message": "Please check the key you used to call this service",
"url": "https://api.staircase.co/docs/DevOps/Distribute/Account/get-retrieve-credentials"
}
application/json
Resource not found
{
"message": "Unable to get collections of given transaction. Please check the transaction id"
}
application/json
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
{
"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
Bad gateway.
{
"message": "Internal server error."
}
Request bodyapplication/json
2 fields
Field
Type
Description
path
string
Contains the path in Staircase language
value
string
Enter your own values here
Response 200application/json
1 fields
Asset Verification Payload.
Field
Type
Description
deal_sets
object
—
deal_set
object[]
—
deals
object
—
deal
object[]
—
Response 400application/json
1 fields
Request data failed validation
Field
Type
Description
message
string
Message
Response 403application/json
2 fields
Invalid key for service
Field
Type
Description
message
string
—
url
string
—
Response 404application/json
1 fields
Resource not found
Field
Type
Description
message
string
Message
Response 500application/json
1 fields
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
Field
Type
Description
message
string
—
Response 502application/json
1 fields
Bad gateway.
Field
Type
Description
message
string
Error Message.
POST/transactions/{transaction_id}/collections
Create Collection
createCollection
Create Collection creates a collection of data points required for asset verification. A collection contains a digital representation of the borrower and is identified by collection_id. A collection_id is passed to the partner when requesting asset verification.
The Example below contains a sample collection that you can use to make the product invocation in /verify-assets
Response
application/json
Error
{
"message": "Unable to create collection. Please check the collection data"
}
application/json
Invalid key for service
{
"message": "Please check the key you used to call this service",
"url": "https://api.staircase.co/docs/DevOps/Distribute/Account/get-retrieve-credentials"
}
application/json
Resource not found
{
"message": "Unable to create collection. Please check the transaction Id"
}
application/json
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
{
"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
Bad gateway.
{
"message": "Internal server error."
}
Parameters
1
Parameter
Type
Example
Description
transaction_idrequired
string (ulid)path
01F5X9B9JBE958CWAXPB8MNFW1
Staircase Transaction Identifier
Response 201application/json
4 fields
Collection created successfully
Field
Type
Description
data
object
—
deal_sets
object
—
deal_set
object[]
—
deals
object
—
metadata
object
The metadata object describes properties that a Staircase collection has
created_at
string
Example 03/03/2021, 8:24:04 AM EST
updated_at
string
Example 03/03/2021, 8:24:04 AM EST
validation
boolean
Describes whether the collection has been validated against Staircase language schemaExample false
partner_name
string
Staircase partner name that was used to generate the collection
results
object
Contains the results of an operation that generated the collection
status
string
Describes the state of the operation that generated the collectionCOMPLETEDERRORIN_PROGRESSTIMED_OUTExample COMPLETED
product
string
Name of the Staircase product that generated the collectionExample Assets
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
Field
Type
Description
message
string
—
Response 502application/json
1 fields
Bad gateway.
Field
Type
Description
message
string
Error Message.
POST/verify-assets
Verify Assets
verifyAsset
Verify Asset
Verify Assets verifies account balances, historical transactions,
and account holder identity information for various asset types. In
order to receive a successful response, you need to provide a valid
transaction_id, a valid collection_id and a valid partner_name.
The partner_name parameter is optional. You can retrieve partner_name
information by querying the /partners endpoint.
Show the rest
To see how the entire flow works, please navigate to the Product
Overview page. The
overview page also contains the credentials needed for testing.
The widget_url returned is only valid for a certain timeframe. You can
extract the timeframe by using the expiration_time denoted in the
response. Once the timeframe has lapsed, the borrower will not be able
to submit their information and the link will have expired.
Verification options
Redirect URL parameter
Providing the redirect_url is optional and allows you to redirect the
borrower to a URL of your choosing after linking the borrower's assets.
If left empty or no options parameter is passed, this URL defaults to
the Staircase homepage.
Send SMS parameter
The send_sms option enables you to send an SMS when an authorization for the verification is needed. The default SMS text is "Lender has provided verification link to your E-mail address, please open link in browser, and finish verification process", if you wish to change the default SMS text you can send an optional sms_text parameter with your custom text message.
Send Email parameter
The send_email option enables you to email the borrower when an authorization for the verification is needed. The Email will be sent to the email address specified in the input collection. The Email uses the standard email template voa_email_template, if you wish to update the template please refer to the Update Email Template documentation. Please note that the template takes in one passed variable, which is the applet URL, and that is a required variable and should not be altered, for more info check the Email Product section.
Dry Run parameter
The dry_run option enables you to test the flow without actually connecting to the partners.
Response
application/json
General error
{
"message": "Please make sure your body contains transaction_id."
}
application/json
General error
{
"message": "Please make sure your body contains collection_id"
}
application/json
General error
{
"message": "Please make sure your body contains partner_name"
}
application/json
General error
{
"message": "Please provide a valid partner name. To get available partners, you can use /partners endpoint."
}
application/json
General error
{
"message": "Request body had invalid format. Please provide a valid JSON"
}
application/json
Invalid key for service
{
"message": "Please check the key you used to call this service",
"url": "https://api.staircase.co/docs/DevOps/Distribute/Account/get-retrieve-credentials"
}
application/json
Resource not found
{
"message": "Unable to get collection. Please check input collection id"
}
application/json
Unprocessable Entity
{
"message": "transaction_id value had non-alphanumeric characters. Please check transaction id"
}
application/json
Unprocessable Entity
{
"message": "collection_id value had non-alphanumeric characters. Please check collection id"
}
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
{
"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"
}
To get available partners, you can use /partners endpoint
options
object
—
redirect_url
string
URL that the borrower will get redirected to after linking their assets through the partner formExample http://www.staircase.co
send_sms
boolean
This option allows us to send SMS to the number in the collection. The SMS text is "Lender has provided verification link to your E-mail address, please open link in browser, and finish verify process"
dry_run
boolean
If set to true, product will mock successful asset report
Response 201application/json
3 fields
Request for Asset Report created successfully. Please take the contained widget_url and forward it to the borrower. The URL is valid until the `expiration_time`. The `expiration_time` is denoted in EST.
Expiration time in EST. The operation will result in failure after this date has passed.
Response 403application/json
2 fields
Invalid key for service
Field
Type
Description
message
string
—
url
string
—
Response 404application/json
1 fields
Resource not found
Field
Type
Description
message
string
Message
Response 422application/json
1 fields
Unprocessable Entity
Field
Type
Description
message
string
Message
Response 500application/json
1 fields
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
Field
Type
Description
message
string
—
Response 502application/json
1 fields
Bad gateway.
Field
Type
Description
message
string
Error Message.
Other responses
400
POST/request-elements/complete
Validate Collection
validateCollection
Validate Collection allows you to validate an input collection prior to submitting to our partners.
This endpoint will give messages with all the corrections you need to make to your collection in order for it to be accepted by our partner call.
Response
application/json
Invalid key for service
{
"message": "Please check the key you used to call this service",
"url": "https://api.staircase.co/docs/DevOps/Distribute/Account/get-retrieve-credentials"
}
application/json
Resource not found
{
"message": "Unable to get collections of given transaction. Please check the transaction id"
}
application/json
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
{
"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
Bad gateway.
{
"message": "Internal server error."
}
Request bodyapplication/json
2 fields
Field
Type
Description
data
object
Staircase collections can hold any type of valid JSON data
metadata
object
The metadata object describes properties that a Staircase collection has
created_at
string
Example 03/03/2021, 8:24:04 AM EST
updated_at
string
Example 03/03/2021, 8:24:04 AM EST
validation
boolean
Describes whether the collection has been validated against Staircase language schemaExample false
partner_name
string
Staircase partner name that was used to generate the collection
results
object
Contains the results of an operation that generated the collection
status
string
Describes the state of the operation that generated the collectionCOMPLETEDERRORIN_PROGRESSTIMED_OUTExample COMPLETED
product
string
Name of the Staircase product that generated the collectionExample Assets
Response 200application/json
1 fields
Collection is valid
Field
Type
Description
message
string
Message
Response 403application/json
2 fields
Invalid key for service
Field
Type
Description
message
string
—
url
string
—
Response 404application/json
1 fields
Resource not found
Field
Type
Description
message
string
Message
Response 500application/json
1 fields
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
Field
Type
Description
message
string
—
Response 502application/json
1 fields
Bad gateway.
Field
Type
Description
message
string
Error Message.
Other responses
400
GET/status/{transaction_id}/{collection_id}
Retrieve Status
retrieveStatus
Retrieve Status determines if a partner has completed asset verification.
Response
application/json
Invalid key for service
{
"message": "Please check the key you used to call this service",
"url": "https://api.staircase.co/docs/DevOps/Distribute/Account/get-retrieve-credentials"
}
application/json
Resource not found
{
"message": "Unable to get status. Please check the given ids"
}
application/json
Unprocessable Entity
{
"message": "transaction_id value had non-alphanumeric characters. Please check transaction id"
}
application/json
Unprocessable Entity
{
"message": "collection_id value had non-alphanumeric characters. Please check collection id"
}
application/json
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
{
"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
Bad gateway.
{
"message": "Internal server error."
}
Parameters
2
Parameter
Type
Example
Description
transaction_idrequired
string (ulid)path
01F5X9B9JBE958CWAXPB8MNFW1
Staircase Transaction Identifier
collection_idrequired
string (ulid)path
01F5X9BCPQFR3HS2MQ1EW9X2NZ
Staircase collection_id
Response 200application/json
3 fields
Status retrieved successfully
Field
Type
Description
status
string
Potential status responses: 'COMPLETED', 'ERROR', 'IN_PROGRESS', 'TIMED_OUT'COMPLETEDERRORIN_PROGRESSTIMED_OUT
message
string
—
updated_at
string
Example 03/10/2021, 9:49:25 AM EST
Response 403application/json
2 fields
Invalid key for service
Field
Type
Description
message
string
—
url
string
—
Response 404application/json
1 fields
Resource not found
Field
Type
Description
message
string
Message
Response 422application/json
1 fields
Unprocessable Entity
Field
Type
Description
message
string
Message
Response 500application/json
1 fields
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
Field
Type
Description
message
string
—
Response 502application/json
1 fields
Bad gateway.
Field
Type
Description
message
string
Error Message.
Other responses
400
GET/report/{blob_id}
Retrieve Report
retrieveReport
Retrieve Report retrieves a PDF report from a successful verification. This endpoint takes in one path parameter, the blob ID, which can be found in the response collection of a successful verification.
Response
application/json
Report URL retrieved successfully
{
"url": "www.domain.com/reportURL"
}
application/json
Bad Request
{
"message": "Blod ID is not valid or not provided"
}
application/json
Bad Request
{
"message": "No report found for this blob_id"
}
application/json
Invalid key for service
{
"message": "Please check the key you used to call this service",
"url": "https://api.staircase.co/docs/DevOps/Distribute/Account/get-retrieve-credentials"
}
application/json
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
{
"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-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Staircase Documentation Environment API Key
blob_idrequired
stringpath
01FVFBXHVD5WT2MJAGG96CPBJD
Blob ID for report that needs to retrieved.
Response 200application/json
1 fields
Report URL retrieved successfully
Field
Type
Description
url
string
Report URL
Response 400application/json
1 fields
Bad Request
Field
Type
Description
message
string
Partner not found
Response 403application/json
2 fields
Invalid key for service
Field
Type
Description
message
string
—
url
string
—
Response 500application/json
1 fields
The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used.
{
"message": "{'data': ['Missing data for required field.']}"
}
application/json
403 invalid error
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
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
1
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Environment API Key.
Response 200application/json
4 fields
Successfully returned the report templates.
Field
Type
Description
name
string
Name of template
template_type
string
Template typejinja
body
string
Template HTML string body
product_name
string
Product name
Response 400application/json
1 fields
Request data failed validation
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.
POST/products/asset/report-templates
Create Report Template
createReportTemplate
Create Report Template helps you to create templates for report generation.
The template shall be in multiple formats, currently supported is Jinja HTML templates
powered by the Jinja template engine.
Below is example markup written in Jinja logic as HTML.
{
"name": "report_styles_example",
"template_type": "jinja",
"body": "<body><div class=\\\"wrapper\\\"><div class=\\\"titles-wrap\\\"><h3 class=\\\"styles-title\\\">Title</h3><h1 class=\\\"title\\\">h1 - Report Title</h1><h2 class=\\\"title\\\">h2 - Report Title</h2><h3 class=\\\"title\\\">h3 - Report Title</h3><h3 class=\\\"title blue\\\">h3 - Report Title</h3></div><div class=\\\"letter-styles\\\"><h3 class=\\\"styles-title\\\">BODY normal / bold / italic</h3><p class=\\\"text-styles\\\"> Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna <b>aliqua</b>. Ut enim ad minim veniam, <i>quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.</i> Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non <b>proident</b>, sunt in culpa qui officia <i>deserunt mollit anim id est laborum.</i></p></div><div class=\\\"columns-fields\\\"><div class=\\\"column-wrap\\\"><h3 class=\\\"styles-title\\\">2 columns</h3><div class=\\\"columns-2\\\"><table class=\\\"default-table\\\"><tr><td><div class=\\\"main-field\\\"> <span>First Name:</span><p>Richard</p></div></td><td><div class=\\\"main-field\\\"> <span>Last Name:</span><p>Grant</p></div></td></tr></table></div></div><div class=\\\"column-wrap\\\"><h3 class=\\\"styles-title\\\">3 columns</h3><div class=\\\"columns-3\\\"><table class=\\\"default-table\\\"><tr><td><div class=\\\"main-field\\\"> <span>Phone Number:</span><p>+1 808 3722 9914</p></div></td><td><div class=\\\"main-field\\\"> <span>SSN:</span><p>34923832</p></div></td><td><div class=\\\"main-field\\\"> <span>Email:</span><p>richardgrant@gmail.com</p></div></td></tr></table></div></div><div class=\\\"column-wrap\\\"><h3 class=\\\"styles-title\\\">5 columns</h3><div class=\\\"columns-5\\\"><table class=\\\"default-table\\\"><tr><td><div class=\\\"main-field\\\"> <span>State:</span><p>NY</p></div></td><td><div class=\\\"main-field\\\"> <span>City:</span><p>New York</p></div></td><td><div class=\\\"main-field\\\"> <span>Neighbourhood:</span><p>Brooklyn</p></div></td><td><div class=\\\"main-field\\\"> <span>Postal Code:</span><p>10001</p></div></td><td><div class=\\\"main-field\\\"> <span>Country:</span><p>United States</p></div></td></tr></table></div></div></div><p class=\\\"info-acc\\\"> <b> Information as accurate as of: </b> Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.</p><div class=\\\"bulleted-list\\\"><h3 class=\\\"styles-title\\\">Bulleted list</h3><ul><li> asset randomly chooses between Atomic and Argyle and checks to see if the data partner is able to provide a VOE response for the given company.</li><li> asset randomly chooses between Atomic and Argyle and checks to see if the data partner is able to provide a VOE response for the given company.</li><li> asset randomly chooses between Atomic and Argyle and checks to see if the data partner is able to provide a VOE response for the given company.</li></ul></div><div class=\\\"number-list\\\"><h3 class=\\\"styles-title\\\">Number list</h3><ul><li> <span class=\\\"list-number\\\">1.</span> asset randomly chooses between Atomic and Argyle and checks to see if the data partner is able to provide a VOE response for the given company.</li><li> <span class=\\\"list-number\\\">2.</span> asset randomly chooses between Atomic and Argyle and checks to see if the data partner is able to provide a VOE response for the given company.</li><li> <span class=\\\"list-number\\\">3.</span> asset randomly chooses between Atomic and Argyle and checks to see if the data partner is able to provide a VOE response for the given company.</li></ul></div><div class=\\\"checklist-list\\\"><h3 class=\\\"styles-title\\\">Check list</h3><ul><li> <img src=\\\"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABUAAAAXCAMAAADTAfSvAAAAOVBMVEUAAAAoGGgnGWknGmknGmknGWkgEHAmGmooG2goGGgnGmknGWklG2cqG2UmGmonG2knGWYmGWknGmnimifOAAAAEnRSTlMAIN+A778Qn2BAr3AwMM+PcFDFj4syAAAAeUlEQVQY042RSQ6AIAxFpYACgkPvf1h/w0JpWUjCgpf+IWX5f1aLXCxsYA7MpGEDDE7LiZmbjhGYtP4E9Bp6wM10AiTTlXq81e9GPzUtMP3oa5RXwmh+4SV26D82laG4eLWTyoJx7yEngNh836kzRWdLEVOafcox6h8gEAZf0A2yYAAAAABJRU5ErkJggg==\\\" alt=\\\"check\\\">asset randomly chooses between Atomic and Argyle and checks to see if the data partner is able to provide a VOE response for the given company.</li><li> <img src=\\\"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABUAAAAXCAMAAADTAfSvAAAAOVBMVEUAAAAoGGgnGWknGmknGmknGWkgEHAmGmooG2goGGgnGmknGWklG2cqG2UmGmonG2knGWYmGWknGmnimifOAAAAEnRSTlMAIN+A778Qn2BAr3AwMM+PcFDFj4syAAAAeUlEQVQY042RSQ6AIAxFpYACgkPvf1h/w0JpWUjCgpf+IWX5f1aLXCxsYA7MpGEDDE7LiZmbjhGYtP4E9Bp6wM10AiTTlXq81e9GPzUtMP3oa5RXwmh+4SV26D82laG4eLWTyoJx7yEngNh836kzRWdLEVOafcox6h8gEAZf0A2yYAAAAABJRU5ErkJggg==\\\" alt=\\\"check\\\">asset randomly chooses between Atomic and Argyle and checks to see if the data partner is able to provide a VOE response for the given company.</li><li> <img src=\\\"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABUAAAAXCAMAAADTAfSvAAAAOVBMVEUAAAAoGGgnGWknGmknGmknGWkgEHAmGmooG2goGGgnGmknGWklG2cqG2UmGmonG2knGWYmGWknGmnimifOAAAAEnRSTlMAIN+A778Qn2BAr3AwMM+PcFDFj4syAAAAeUlEQVQY042RSQ6AIAxFpYACgkPvf1h/w0JpWUjCgpf+IWX5f1aLXCxsYA7MpGEDDE7LiZmbjhGYtP4E9Bp6wM10AiTTlXq81e9GPzUtMP3oa5RXwmh+4SV26D82laG4eLWTyoJx7yEngNh836kzRWdLEVOafcox6h8gEAZf0A2yYAAAAABJRU5ErkJggg==\\\" alt=\\\"check\\\">asset randomly chooses between Atomic and Argyle and checks to see if the data partner is able to provide a VOE response for the given company.</li></ul></div><div class=\\\"tags-wrap\\\"><h3 class=\\\"styles-title\\\">Tags</h3><div class=\\\"tags\\\"><table><tr><td><div class=\\\"tag tag-1\\\">TAG 1</div></td><td><div class=\\\"tag tag-2\\\">TAG 2</div></td></tr></table></div></div><div class=\\\"breadcrums-wrap\\\"><h3 class=\\\"styles-title\\\">Breadcrums</h3><ul><li> <a href=\\\"#\\\">Level 1</a> <img src=\\\"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAoAAAAQBAMAAADdUfNzAAAAHlBMVEUAAAC+vr6+vr6/v7+8vLy+vr69vb28vLy6urq+vr4suSPSAAAACXRSTlMAz98QIO9wUDAJ8cTPAAAAMUlEQVQI12NgaDdgAAJNYRApORHEcZoJ4rBoonIYwBwICRGByEJUwhRCNEWCTXMDMgFNFAxgyg4mqQAAAABJRU5ErkJggg==\\\" alt=\\\">\\\"></li><li> <a href=\\\"#\\\">Level 2</a> <img src=\\\"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAoAAAAQBAMAAADdUfNzAAAAHlBMVEUAAAC+vr6+vr6/v7+8vLy+vr69vb28vLy6urq+vr4suSPSAAAACXRSTlMAz98QIO9wUDAJ8cTPAAAAMUlEQVQI12NgaDdgAAJNYRApORHEcZoJ4rBoonIYwBwICRGByEJUwhRCNEWCTXMDMgFNFAxgyg4mqQAAAABJRU5ErkJggg==\\\" alt=\\\">\\\"></li><li> <a href=\\\"#\\\">Level 3</a> <img src=\\\"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAoAAAAQBAMAAADdUfNzAAAAHlBMVEUAAAC+vr6+vr6/v7+8vLy+vr69vb28vLy6urq+vr4suSPSAAAACXRSTlMAz98QIO9wUDAJ8cTPAAAAMUlEQVQI12NgaDdgAAJNYRApORHEcZoJ4rBoonIYwBwICRGByEJUwhRCNEWCTXMDMgFNFAxgyg4mqQAAAABJRU5ErkJggg==\\\" alt=\\\">\\\"></li><li> <a href=\\\"#\\\">Level 4</a> <img src=\\\"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAoAAAAQBAMAAADdUfNzAAAAHlBMVEUAAAC+vr6+vr6/v7+8vLy+vr69vb28vLy6urq+vr4suSPSAAAACXRSTlMAz98QIO9wUDAJ8cTPAAAAMUlEQVQI12NgaDdgAAJNYRApORHEcZoJ4rBoonIYwBwICRGByEJUwhRCNEWCTXMDMgFNFAxgyg4mqQAAAABJRU5ErkJggg==\\\" alt=\\\">\\\"></li></ul></div><div class=\\\"divider-wrap\\\"><h3 class=\\\"styles-title\\\">Divider</h3><div class=\\\"divider\\\"></div></div><div class=\\\"notes-wrap\\\"><h3 class=\\\"styles-title\\\">Notes</h3><div class=\\\"note\\\"><div class=\\\"inner-note\\\"><h4>NOTE</h4><p> Do not activate the API key for the documentation environment. If you have activated your API Key for the documentation environment, it cannot be used for any other environment.</p></div></div></div><div class=\\\"table-wrap\\\"><h3 class=\\\"styles-title\\\">2 columns</h3><div class=\\\"table-columns\\\"><div class=\\\"columns-table columns-2-table\\\"><table class=\\\"default-table table-grid\\\"><tr><th><div>column 1</div></th><th><div>column 2</div></th></tr><tr><td><div class=\\\"text-column\\\">Text column 1</div></td><td><div class=\\\"text-column\\\">Text column 2</div></td></tr><tr><td><div class=\\\"text-column\\\">Text column 1</div></td><td><div class=\\\"text-column\\\">Text column 2</div></td></tr><tr><td><div class=\\\"text-column\\\">Text column 1</div></td><td><div class=\\\"text-column\\\">Text column 2</div></td></tr></table></div></div></div><div class=\\\"table-wrap\\\"><h3 class=\\\"styles-title\\\">3 columns</h3><div class=\\\"table-columns\\\"><div class=\\\"columns-table columns-3-table\\\"><table class=\\\"default-table table-grid\\\"><tr><th><div>column 1</div></th><th><div>column 2</div></th><th><div>column 3</div></th></tr><tr><td><div class=\\\"text-column\\\">Text column 1</div></td><td><div class=\\\"text-column\\\">Text column 2</div></td><td><div class=\\\"text-column\\\">Text column 3</div></td></tr><tr><td><div class=\\\"text-column\\\">Text column 1</div></td><td><div class=\\\"text-column\\\">Text column 2</div></td><td><div class=\\\"text-column\\\">Text column 3</div></td></tr><tr><td><div class=\\\"text-column\\\">Text column 1</div></td><td><div class=\\\"text-column\\\">Text column 2</div></td><td><div class=\\\"text-column\\\">Text column 3</div></td></tr></table></div></div></div></div></body>\n"
}
{
"message": "{'data': ['Missing data for required field.']}"
}
application/json
403 invalid error
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
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"
}
{
"message": "{'data': ['Missing data for required field.']}"
}
application/json
403 invalid error
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
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"
}
{
"message": "{'data': ['Missing data for required field.']}"
}
application/json
403 invalid error
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
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"
}
{
"message": "{'data': ['Missing data for required field.']}"
}
text/html
Request data failed validation
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
application/json
403 invalid error
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
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"
}
{
"message": "{'data': ['Missing data for required field.']}"
}
application/json
403 invalid error
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
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
1
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Environment API Key.
Request bodyapplication/json
4 fields
Field
Type
Description
template_namerequired
string
Name of template
product_name
string
Product name
transaction_idrequired
string
Transaction ID
collection_idrequired
string
Collection ID
Response 200application/json
6 fields
Report successfully generated.
Field
Type
Description
template_name
string
Name of template
product_name
string
Product name
transaction_id
string
Transaction ID
collection_id
string
Collection ID
blob_id
string
Blob ID of generated report
download_url
string
Presigned URL to view/download generated report
Response 400application/json
1 fields
Request data failed validation
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.
Product Specifications
GET/products/asset/request-schema
Retrieve Request Schema
retrieveRequestSchema
Retrieve Request Schema retrieves a JSON schema for the request to the product waterfall. It also has the option of returning an example for the request object expected through the return_example attribute.
Response
application/json
Successfully returned the list of elements needed for product waterfall.
{
"message": "Please provide one of valid return examples values: true, false"
}
text/html
Error
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
application/json
403 invalid error
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
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
2
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Environment API Key.
return_examples
booleanquery
false
If included and set to `true`, returns one or more pre-filled examples that conform to the schema. Default to `false`
Response 200application/json
1 fields
Successfully returned the list of elements needed for product waterfall.
Field
Type
Description
schema
object
Element key / value
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.
GET/products/asset/response-schema
Retrieve Response Schema
retrieveResponseSchema
Retrieve Schema retrieves a JSON schema for the response returned by the product. It can also return an example for the response output object through return_example attribute.
Response
application/json
Successfully returned the list of elements of response of the product waterfall.
{
"message": "Please provide one of valid return examples values: true, false"
}
text/html
Error
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
application/json
403 invalid error
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
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
2
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Environment API Key.
return_examples
booleanquery
false
If included and set to `true`, returns one or more pre-filled examples that conform to the schema. Default to `false`
Response 200application/json
1 fields
Successfully returned the list of elements of response of the product waterfall.
Field
Type
Description
schema
object
Element key / value element
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.
GET/products/asset/request-elements
Retrieve Request Elements
requestElements
Retrieve Request Elements retrieves a list of elements needed to invoke a data partner for product function invocation.
Response
application/json
Example for the Product Invocation Request Elements object
{
"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://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
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
1
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Environment API Key.
Response 200application/json
1 fields
Elements were retrieved successfully
Field
Type
Description
elementsrequired
string[]
List of elements.
Response 400application/json
1 fields
Validation 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.
GET/products/asset/response-elements
Retrieve Response Elements
responseElements
Retrieve Response Elements provides a list of elements that will be returned by a data partner after invoking the product.
Response
application/json
Example for the Product Invocation Request Elements object
{
"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://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
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
1
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Environment API Key.
Response 200application/json
1 fields
Elements were retrieved successfully
Field
Type
Description
elementsrequired
string[]
List of elements.
Response 400application/json
1 fields
Validation 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.
POST/products/asset/request-elements/validate
Validate Collection
validateCollection
Validate Collection allows you to validate an input collection prior to submitting to our partners for a specific product.
This endpoint will give messages with all the corrections you need to make to your collection in order for it to be accepted by our partner call.
{
"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://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
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
1
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Environment API Key.
Request bodyapplication/json
1 fields
Field
Type
Description
deal_sets
object
Deal sets object.
deal_set
object[]
Deal set object.
deals
object
Deals object.
deal
object[]
Deal array.
Response 200application/json
1 fields
Collection is valid
Field
Type
Description
message
string
Message
Response 400application/json
1 fields
Validation 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.
Product Waterfalls
GET/products/asset/waterfall
Retrieve Product Waterfall
retrieveProductWaterfall
Retrieve Product Waterfall retrieves a specific product waterfall.
{
"message": "{'data': ['Missing data for required field.']}"
}
application/json
403 invalid error
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
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"
}
{
"message": "{'data': ['Missing data for required field.']}"
}
application/json
403 invalid error
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
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
1
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Environment API Key.
Request bodyapplication/json
1 fields
Field
Type
Description
waterfallrequired
object[]
Product waterfall steps.
priorityrequired
integer
Priority of waterfall step.
flow_name
string
Flow name
vendor_name
string
Vendor name
Response 200application/json
1 fields
Product waterfall successfully added.
Field
Type
Description
waterfallrequired
object[]
Product waterfall steps.
priorityrequired
integer
Priority of waterfall step.
flow_name
string
Flow name
vendor_name
string
Vendor name
Response 400application/json
1 fields
Request data failed validation
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.
DELETE/products/asset/waterfall
Delete Product Waterfall
deleteProductWaterfall
Delete Product Waterfall deletes a product waterfall.
Response
application/json
Request data failed validation
{
"message": "{'data': ['Missing data for required field.']}"
}
text/html
Request data failed validation
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
application/json
403 invalid error
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
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
1
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Environment API Key.
Response 400application/json
1 fields
Request data failed validation
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
204
POST/products/asset/waterfall/invocations
Invoke Product Waterfall
invokeProductWaterfall
Invoke Product Waterfall helps you to invoke product waterfall. Product waterfall invocation shall invoke the product flows as per the order of the waterfall settings or using the default order of the flows. The invocation endpoint shall try to invoke the flows one by one till one of them succeed and return the needed outcome.
There are two options for using transactions and collections while invoking a waterfall product:
Show the rest
Any of the transaction_id, request_collection_id, response_collection_id was pre-created, in this case the product shall validate them.
Customer provide only request data, in this case product shall:
Create transaction.
Create input collection with the provided request_data.
Create empty output collection.
Optional Parameters:
tags: when tags are provided product shall filter the product flows associated with these tags before invoking the waterfall.
options: key/value pairs passed to the products called by Product during invocation.
callback_url : will be used by the product to send a callback, when the flow execution will be finished.
The callback request body is a JSON with the following schema:
{
"message": "{'data': ['Missing data for required field.']}"
}
application/json
403 invalid error
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
text/html
Resource not found
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
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
1
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Environment API Key.
Request bodyapplication/json
6 fields
Field
Type
Description
transaction_id
string
Transaction ID used for flow_invocations.
request_collection_id
string
Request Collection ID.
callback_url
string (uri)
Callback URL.
request_data
object
Request JSON body for product flows.
tags
string[]
Flow tags.
options
object
Additional information that should be passed to the connector but not be added to the request collection. Will be passed to every product flow invocation.
Response 201application/json
9 fields
Successfully started flow invocation.
Field
Type
Description
invocation_idrequired
string
Invocation ID.
invocation_statusrequired
string
The status of the invocation.STARTED
transaction_id
string
Transaction ID.
callback_url
string
Callback URL.
request_data
object
The data for the request collection.
request_collection_id
string
Request Collection ID.
tags
string[]
Flow tags.
options
object
Additional information that should be passed to the connector but not be added to the request collection. Will be passed to every product flow invocation.
{
"message": "{'data': ['Missing data for required field.']}"
}
application/json
403 invalid error
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
text/html
Resource not found
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
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
2
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Environment API Key.
invocation_idrequired
string (ulid)path
d7ccedb8-8889-4657-add4-bc1s4xs97637
Product flow invocation identifier
Response 200application/json
11 fields
Successfully returned status of the Product Waterfall Invocation.
Field
Type
Description
invocation_idrequired
string
Invocation ID.
invocation_statusrequired
string
The status of the invocation.ACTION_REQUIREDCOMPLETEDFAILEDRUNNINGSTARTED
transaction_idrequired
string
Transaction ID.
callback_url
string
Callback URL.
request_data
object
The data for the request collection.
request_collection_id
string
Request Collection ID.
request_collection
object
Request Collection.
tags
string[]
Flow tags.
options
object
Options that were passed to the waterfall invocation.
flows_responsesrequired
object
Responses for each flow invocation.
metadatarequired
object
Metadata of waterfall.
actual_flow_name
string
Actual flow name invoked.
Response 400application/json
1 fields
Request data failed validation
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
Message
Response 500application/json
1 fields
Internal server error
Field
Type
Description
message
string
Error message.
Verification
POST/verification
Verify Asset
InvokeAssetVerificationFlow
This endpoint does an asset verification for the selected partner and request data.
Please find various request examples at Request Body section.
Request Payload
In order to invoke asset verification, add partner name in partner_name field and provide the following information in request_data:
You need to create people, contact_information, addresses arrays in your request collection.
Each of these array elements should have corresponding @id and @type fields.
Show the rest
For people array's element you need to provide the following borrower information:
first name
last name
birthdate
taxpayer identifier
contact_at relation with the contact_information object (unique identifier referencing element id from contact_information array)
with_address relation with the addresses object (unique identifier referencing element id from addresses array)
For contact_information array's element you need to provide the following borrower contact information:
email address
For addresses array's element you need to provide the following borrower address information:
address line 1
city name
state code
postal code
Additionally, following fields can be specified:
organizations array's element with the following organization information:
organization name
loans array's element with the following loan information:
loan identifier
For additional_information array's element you may provide multiple objects, each containing both of the following fields:
additional information key identifier
additional information value
Additional information key identifiers are:
monitoringDuration
permissiblePurpose
orderStartDate
orderEndDate
ccEmail
In case of invalid request data, you will receive 400 status code with information about missing fields.
Mock Request
If you want to test the system and see possible verification results without invoking real asset verification you can do mock request instead.
Create payload as described in Request Payload section above but use following SSNs (taxpayer identifiers) for different scenarios.
SSN
Mock Scenario
000000001
Generic Success Scenario
990000001
Application not available
990000002
Asset View Report not available
990000003
Missing reference number
990000004
Invalid reference number
990000005
Invalid partner
Enabling Waterfall
If the waterfall feature is enabled, the endpoint invokes verification that will execute following the ordering for all available data partners.
To use this feature, set the partner name in request payload to waterfall.
Use Update Partners Ordering and Retrieve Partners Ordering to set and get the orderings.
If two data partners share the same legal entity full name, the verification will be done based on the ordering of data partners.
Retrieving the Invocation Result
After request, endpoint returns an id which you can poll for its status using verification/asset/verification/{id} endpoint.
If you would rather receive a callback once the invocation is completed instead of polling it, you can set callback_url parameter in the request payload.
Monitoring the health of the Asset product
The Asset product is integrated with the Health product, a cloud-based DevOps service that monitors the health of APIs.
With the help of Health product, you can monitor the process of verification.
To check the health of the asset product, you can use the create async health query execution API.
This API allows you to specify a time period, a response collection ID ("id" returned as result of asset verification), and a product or API identifier.
Here are the relevant product and API identifiers for the Asset product:
To retrieve the results of your health query, use the get async health query result API. This API takes the query execution ID returned by the create async health query execution API as a parameter.
When you retrieve the results of your health query, you should see at least one health metric with corresponding status information (e.g. "SUCCEEDED", "FAILED").
Setting up alarms
You can set up alarms to be notified when the health of the asset product. To do this, use the create_health_alarm API.
This API allows you to specify a threshold value and a notification method.
{
"message": "{'data': ['Missing data for required field.']}"
}
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"
}
text/html
Resource not found
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
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
1
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Environment API Key.
Request bodyapplication/json
2 fields
Field
Type
Description
partner_namerequired
string
Partner name.Example equifax
request_datarequired
object
Request data for asset verification.
Response 201application/json
1 fields
Successfully started flow invocation.
Field
Type
Description
idrequired
string
Response collection ID.
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.
GET/verification/{id}
Retrieve Asset Verification Status
RetrieveAssetVerificationFlowInvocationStatus
Retrieves the result of running Asset Verification.
Response Body
As the result of the successful invocation you are expected to receive addresses, asset_holders, assets, contact_information, currency_information, documents, mortgage_products, names, organizations, people, transactions arrays.
Show the rest
The element of addresses array will include following information:
address line 1
city name
state code
postal code
country name
The element of asset_holders array will include following information:
with_name relation with the names object (unique identifier referencing element id from names array)
The element of assets array will include following information:
account identifier
asset description
asset type
other asset type description
market value amount
held_by_financial_institution relations with organizations object (unique identifier referencing element id from organizations array)
with_asset_holder relation with the asset_holders object (unique identifier referencing element id from asset_holders array)
with_currency relation with the currency_information object (unique identifier referencing element id from currency_information array)
with_transaction relation with the transactions object (unique identifier referencing element id from transactions array)
The element of contact_information array will include following information:
email address
The element of currency_information array will include following information:
currency code
The element of documents array will include following information:
document description
document mime type
document name
blob identifier
document category type
The element of mortgage_products array will include following information:
partner name
partner product name
partner transaction identifier (Reference number)
service response data
The element of names array will include following information:
first name
last name
The element of organizations array will include following information:
organization identifier
organization name
The element of people array will include following information:
first name
last name
birthdate
taxpayer identifier
contact_at relation with the contact_information object (unique identifier referencing element id from contact_information array)
with_address relation with the addresses object (unique identifier referencing element id from addresses array)
The element of transactions array will include following information:
transaction amount
transaction date
transaction description
Response
application/json
Successfully returned result of the Asset Verification.
{
"message": "{'data': ['Missing data for required field.']}"
}
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"
}
text/html
Resource not found
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
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"
}
{
"message": "Credentials are saved and verified"
}
application/json
Request data failed validation
{
"message": "{'data': ['Missing data for required field.']}"
}
application/json
Invalid key for service
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
{
"message": "Credentials are saved and verified"
}
application/json
Request data failed validation
{
"message": "{'data': ['Missing data for required field.']}"
}
application/json
Invalid key for service
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
{
"message": "Credentials are saved and verified"
}
application/json
Request data failed validation
{
"message": "{'data': ['Missing data for required field.']}"
}
application/json
Invalid key for service
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
The product has encountered an internal server error
{
"message": "The product has encountered an internal server error"
}
Parameters
1
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Staircase Environment API Key
Request bodyapplication/json
3 fields
Field
Type
Description
client_idrequired
string
Plaid client ID
secretrequired
string
Plaid secret
domainrequired
string
Plaid domain
Response 200application/json
1 fields
Setup API Triggered Successfully
Field
Type
Description
message
string
Message
Response 400application/json
1 fields
Request data failed validation
Field
Type
Description
message
string
Message
Response 403application/json
2 fields
Invalid key for service
Field
Type
Description
message
string
—
url
string
—
Response 422application/json
2 fields
Request data failed validation
Field
Type
Description
message
string
Message
error
string
Message
Response 500application/json
1 fields
The product has encountered an internal server error
Field
Type
Description
message
string
Error Message
Other responses
404
GET/{partner_name}/credentials
Retrieve Partner Credentials Schema
getCredentials
Get Credentials Schema
Get credentials schema for specific partner. You can use retrieved schema for updating the partner credentials.
Response
application/json
Request data failed validation
{
"message": "{'data': ['Missing data for required field.']}"
}
application/json
Invalid key for service
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
application/json
403 invalid error
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
application/json
Resource not found
{
"message": "Unable to get collections of given transaction. Please check the transaction id"
}
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
2
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Environment API Key.
transaction_idrequired
string (ulid)path
01F0KHK7DN3H5JZ4QJKMYAM6GB
Staircase Transaction Identifier
Response 200application/json
4 fields
Transaction collection retrieved successfully
Field
Type
Description
transaction_id
string (ulid)
Transaction idExample 01EZQ32PJQGKRA6HR8D72Q9FFF
collection_id
string (ulid)
Collection idExample 01EZQ32PJQGKRA6HR8D72Q9FFF
data
array
—
metadata
object
Metadata about collection, f.e version of used Staircase schema
{
"message": "Please check the key you used to call this service",
"url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post"
}
application/json
Resource not found
{
"message": "Unable to get collection. Please check the given ids"
}
application/json
Resource not found
{
"message": "Unable to get collections of given transaction. Please check the transaction id"
}
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
3
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Environment API Key.
transaction_idrequired
string (ulid)path
01F0KHK7DN3H5JZ4QJKMYAM6GB
Staircase Transaction Identifier
collection_idrequired
string (ulid)path
01F0KHKADN0HRFXMCQQXPA6AFZ
Staircase collection_id
Response 200application/json
2 fields
Successfully Retrieved Collection
Field
Type
Description
data
object
—
deal_sets
object
—
deal_set
object[]
—
deals
object
—
document_sets
object
—
document_set
object[]
—
documents
object
—
metadata
—
—
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
400
Reverification
POST/reverification
Reverify Asset
InvokeAssetReverificationFlow
This endpoint does an asset reverification for the selected partner and request data.
Please find various request examples at Request Body section.
Request Payload
In order to invoke asset reverification, add partner name in partner_name field and provide the following information in request_data:
You need to create people, contact_information, addresses, mortgage_product arrays in your request collection.
Each of these array elements should have corresponding @id and @type fields.
Show the rest
For people array's element you need to provide the following borrower information:
first name
last name
birthdate
taxpayer identifier
contact_at relation with the contact_information object (unique identifier referencing element id from contact_information array)
with_address relation with the addresses object (unique identifier referencing element id from addresses array)
For contact_information array's element you need to provide the following borrower contact information:
email address
For addresses array's element you need to provide the following borrower address information:
address line 1
city name
state code
postal code
For mortgage_products array's element you need to provide the following information:
partner transaction identifier (Reference number)
In case of invalid request data, you will receive 400 status code with information about missing fields.
Mock Request
If you want to test the system and see possible reverification results without invoking real asset reverification you can do mock request instead.
Create payload as described in Request Payload section above but use following SSNs (taxpayer identifiers) for different scenarios.
SSN
Mock Scenario
000000001
Generic Success Scenario
990000001
Application not available
990000002
Asset View Report not available
990000003
Missing reference number
990000004
Invalid reference number
990000005
Invalid partner
Retrieving the Invocation Result
After request, endpoint returns an id which you can poll for its status using verification/asset/reverification/{id} endpoint.
If you would rather receive a callback once the invocation is completed instead of polling it, you can set callback_url parameter in the request payload.
Monitoring the health of the Asset product
The Asset product is integrated with the Health product, a cloud-based DevOps service that monitors the health of APIs.
With the help of Health product, you can monitor the process of reverification.
To check the health of the asset product, you can use the create async health query execution API.
This API allows you to specify a time period, a response collection ID ("id" returned as result of asset reverification), and a product or API identifier.
Here are the relevant product and API identifiers for the Asset product:
To retrieve the results of your health query, use the get async health query result API. This API takes the query execution ID returned by the create async health query execution API as a parameter.
When you retrieve the results of your health query, you should see at least one health metric with corresponding status information (e.g. "SUCCEEDED", "FAILED").
Setting up alarms
You can set up alarms to be notified when the health of the asset product. To do this, use the create_health_alarm API.
This API allows you to specify a threshold value and a notification method.
{
"message": "{'data': ['Missing data for required field.']}"
}
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"
}
text/html
Resource not found
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
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
1
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Environment API Key.
Request bodyapplication/json
2 fields
Field
Type
Description
partner_namerequired
string
Partner name.Example equifax
request_datarequired
object
Request data for asset reverification.
Response 201application/json
1 fields
Successfully started flow invocation.
Field
Type
Description
idrequired
string
Response collection ID.
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.
GET/reverification/{id}
Retrieve Asset Reverification Status
RetrieveAssetReverificationFlowInvocationStatus
Retrieves the result of running Asset Reverification.
Response Body
As the result of the successful invocation you are expected to receive addresses, asset_holders, assets, contact_information, currency_information, documents, mortgage_products, names, organizations, people, transactions arrays.
Show the rest
The element of addresses array will include following information:
address line 1
city name
state code
postal code
country name
The element of asset_holders array will include following information:
with_name relation with the names object (unique identifier referencing element id from names array)
The element of assets array will include following information:
account identifier
asset description
asset type
other asset type description
market value amount
held_by_financial_institution relations with organizations object (unique identifier referencing element id from organizations array)
with_asset_holder relation with the asset_holders object (unique identifier referencing element id from asset_holders array)
with_currency relation with the currency_information object (unique identifier referencing element id from currency_information array)
with_transaction relation with the transactions object (unique identifier referencing element id from transactions array)
The element of contact_information array will include following information:
email address
The element of currency_information array will include following information:
currency code
The element of documents array will include following information:
document description
document mime type
document name
blob identifier
document category type
The element of mortgage_products array will include following information:
partner name
partner product name
partner transaction identifier (Reference number)
service response data
The element of names array will include following information:
first name
last name
The element of organizations array will include following information:
organization identifier
organization name
The element of people array will include following information:
first name
last name
birthdate
taxpayer identifier
contact_at relation with the contact_information object (unique identifier referencing element id from contact_information array)
with_address relation with the addresses object (unique identifier referencing element id from addresses array)
The element of transactions array will include following information:
transaction amount
transaction date
transaction description
Response
application/json
Successfully returned result of the Asset Reverification.
{
"message": "{'data': ['Missing data for required field.']}"
}
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"
}
text/html
Resource not found
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
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"
}
Successfully returned result of the Asset Reverification.
Field
Type
Description
transaction_id
string (ulid)
Transaction ID.Example 01EZQ32PJQGKRA6HR8D72Q9FFF
collection_id
string (ulid)
Collection ID.Example 01EZQ32PJQGKRA6HR8D72Q9FFF
data
object
Asset Data in Staircase language schema.
metadata
object
Metadata about collection, f.e version of used Staircase schema.
product_name
string
Product nameExample asset
partner_name
string
Partner nameExample equifax
created_at
string
Time of creation
last_updated_at
string
Time of last update
invocation_status
string
Status of the Asset Reverification.COMPLETEDFAILEDRUNNINGSTARTED
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.
Status Check
POST/status
Create Status Check Query
InvokeAssetRetrieveStatusFlow
Asset Create Status Check
This endpoint allows creating status check query of asset verification or reverification.
Please find various request examples at Request Body section.
Request Payload
In order to invoke asset status check, add partner name in partner_name field and provide the following information in request_data:
You need to create staircase_collection_reference array in your request collection with the following information:
In case of invalid request data, you will receive 400 status code with information about missing field.
Mock Request
If you want to test the system and see possible check status results without invoking real asset status check you can do mock request instead.
Create payload as described in Request Payload section above but use following Invocation ID's for different scenarios.
Invocation ID
Mock Scenario
00XXXXXXXXXXXXXXXXXXXXXX01
Success Scenario
00XXXXXXXXXXXXXXXXXXXXXX02
Asset Report not ready
99XXXXXXXXXXXXXXXXXXXXXX01
Invalid partner
99XXXXXXXXXXXXXXXXXXXXXX02
Fail Scenario
Retrieving the Invocation Result
After request, endpoint returns an id which you can poll for its status using verification/asset/status/{id} endpoint.
If you would rather receive a callback once the invocation is completed instead of polling it, you can set callback_url parameter in the request payload.
Monitoring the health of the Asset product
The Asset product is integrated with the Health product, a cloud-based DevOps service that monitors the health of APIs.
With the help of Health product, you can monitor the process of status check.
To check the health of the asset product, you can use the create async health query execution API.
This API allows you to specify a time period, a response collection ID ("id" returned as result of asset invocation), and a product or API identifier.
Here are the relevant product and API identifiers for the Asset product:
To retrieve the results of your health query, use the get async health query result API. This API takes the query execution ID returned by the create async health query execution API as a parameter.
When you retrieve the results of your health query, you should see at least one health metric with corresponding status information (e.g. "SUCCEEDED", "FAILED").
Setting up alarms
You can set up alarms to be notified when the health of the asset product. To do this, use the create_health_alarm API.
This API allows you to specify a threshold value and a notification method.
{
"message": "{'data': ['Missing data for required field.']}"
}
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"
}
text/html
Resource not found
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
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
1
Parameter
Type
Example
Description
x-api-keyrequired
stringheader
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Environment API Key.
Request bodyapplication/json
2 fields
Field
Type
Description
partner_namerequired
string
Partner name.Example equifax
request_datarequired
object
Request data for asset status retrieval.
Response 201application/json
1 fields
Successfully started flow invocation.
Field
Type
Description
idrequired
string
Response collection ID.
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.
GET/status/{id}
Get Asset Status Check Result
RetrieveAssetRetrieveStatusFlowInvocationStatus
Retrieve Asset Status Check Result
Retrieves the result of running Asset Retrieve Status invocation.
Response Body
As the result of the successful invocation you are expected to receive statuses and mortgage_products arrays.
The element of statuses array will include following information:
status code
status name
status description
The element of mortgage_products array will include following information:
partner name
product name
partner transaction identifier (reference number)
Response
application/json
Successfully returned result of the Asset Status Check.
{
"message": "{'data': ['Missing data for required field.']}"
}
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"
}
text/html
Resource not found
<html>\r\n<head><title>400 Bad Request</title></head>\r\n<body>\r\n<center><h1>400 Bad Request</h1></center>\r\n</body>\r\n</html>\r\n
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"
}