Skip to content
Staircase

Employment

Employment verification across a roster of vendors, tried in a committed order until one returns a record.

A caller sends the borrower and employer. The product works down the ordering below, stopping at the first vendor that returns a verified record, and returns one canonical employment response regardless of which vendor answered.

Vendor selection is its own service. Separating routing from the product's own logic is what allowed the ordering to be retuned without touching the product.

How it works

A vendor not covering an employer is an expected outcome, not a fault. The integration returns a completed response carrying a coverage code, which is what lets the next vendor be tried automatically rather than paging an on-call engineer for a miss.

The ordering is not alphabetical and not arbitrary — it is the committed sequence in the product's own configuration file, reproduced below exactly as recorded.

Operations

Setup

POST /partner/activate

Request to Activate Partner

activatePartner

If you wish to use Staircase contract to activate a partner, please execute this endpoint.

By executing this API Staircase will be informed that you as our customer want to use requested partner for verification process.

The request body should contain which partner needs to be activated and for which environment. Once the request is received it will take between 1-3 working days to activate a partner. Once the partner is set up the partner will be active and ready to be used. You can check the partner status by calling the Retrieve Partners endpoint. If response for specific partner is "active": true, partner is ready to be used for verification.

List of partners available for activation: Argyle, Atomic, Equifax, Finicity, Meridian, Pinwheel, Truework and Truework-instant.

Request
application/json
{
  "partner": "partner_name",
  "environment": "my-domain.staircaseapi.com"
}
Response
application/json

Request to Activate API Triggered Successfully

{
  "message": "We have started with enabling Partner, Partner will be activated automatically after process is finished within X working days."
}
Parameters
1
ParameterTypeExampleDescription
x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Staircase Environment API Key
Request bodyapplication/json
2 fields
FieldTypeDescription
partnerrequiredstringPartner name that needs to be activated
environmentrequiredstringEnvironment for which the partner needs to be activated.
Response 200application/json
1 fields

Request to Activate API Triggered Successfully

FieldTypeDescription
messagestringMessage
Response 400application/json
1 fields

Request data failed validation

FieldTypeDescription
messagestringMessage
Response 403application/json
2 fields

Invalid key for service

FieldTypeDescription
messagestring
urlstring
Response 422application/json
2 fields

Request data failed validation

FieldTypeDescription
messagestringMessage
errorstringMessage
Response 500application/json
1 fields

The product has encountered an internal server error

FieldTypeDescription
messagestringError Message
Other responses

404

POST /partner/widget

Partner Widget Token

partnerWidgetToken

Partner Widget Token endpoint allows you to request a widget token which you can use together with our Staircase Partner Credentials NPM package to create a UI for partner credentials set up.

The endpoint will return a widget_token which should be used with the NPM package to display a UI to enter the required credentials based on the partner that needs to be set up.

Show the rest

partner name should be one of the valid partners available for Employment product

You can provide your own CSS styles which will customize a widget. Below is a complete example of the styles you can use:

{
 "submitButton": {
 "fontSize": "14px",
 "fontWeight": "bold",
 "margin": "20px 0px 10px 0px",
 "height": "40px",
 "width": "100%",
 "color": "#fff",
 "backgroundColor": "#b79833"
 },
 "submitButton:hover": {
 "color": "#fff",
 "backgroundColor": "#337ab7"
 },
 "input": {
 "color": "red"
 },
 "input:active": {
 "background": "yellow"
 },
 "input:focus": {
 "background": "orange"
 },
 "input:focusWithin": {
 "background": "gray"
 },
 "input:hover": {
 "background": "purple"
 },
 "input:visited": {
 "background": "teal"
 },
 "inputLabel": {
 "fontSize": "18px"
 },
 "title": {
 "fontSize": "23px"
 },
 "root": {
 "background": "#e6cccc"
 }
}
Request
application/json
{
  "partner": "partner_name",
  "styles": {
    "submitButton": {
      "fontSize": "14px",
      "fontWeight": "bold",
      "margin": "20px 0px 10px 0px",
      "height": "40px",
      "width": "100%",
      "color": "#fff",
      "backgroundColor": "#1d2236"
    },
    "root": {
      "background": "#d8e6cc"
    }
  },
  "callback_url": "www.callback.url/example"
}
Response
application/json

Request to Partner Widget Token API Triggered Successfully

{
  "widget_token": "<redacted>"
}
Parameters
1
ParameterTypeExampleDescription
x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Staircase Environment API Key
Request bodyapplication/json
3 fields
FieldTypeDescription
partnerrequiredstringPartner name which credentials need to be set
stylesrequiredobjectStyles object for widget
callback_urlstringCallback URL for callback when widget status changes.
Response 200application/json
1 fields

Request to Partner Widget Token API Triggered Successfully

FieldTypeDescription
widget_tokenstringWidget Token for staircase NPM package.
Response 400application/json
1 fields

Request data failed validation

FieldTypeDescription
messagestringMessage
Response 403application/json
2 fields

Invalid key for service

FieldTypeDescription
messagestring
urlstring
Response 422application/json
2 fields

Request data failed validation

FieldTypeDescription
messagestringMessage
errorstringMessage
Response 500application/json
1 fields

The product has encountered an internal server error

FieldTypeDescription
messagestringError Message
Other responses

404

POST /argyle/credentials

Set Argyle Credentials

setArgyleCredentials

By using Set Argyle Credentials API we allow our customers to configure Argyle in customer environment.

If you don't have Argyle contract, please use our Request to Activate Partner API. Partner will be activated within next business day.

If you want to use your own Argyle contract for verification, please check Request body Schema example for required values from partner side and run Set Argyle Credentials API.

You can check the partner status by calling the Retrieve Partners endpoint.

Request
application/json
{
  "client_id": "--------",
  "client_secret": "<redacted>",
  "link_key": "--------",
  "contract": "BYOC",
  "type": "test"
}
Response
application/json

Setup API Triggered Successfully

{
  "message": "Credentials are saved and verified"
}
Parameters
1
ParameterTypeExampleDescription
x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Staircase Environment API Key
Request bodyapplication/json
5 fields
FieldTypeDescription
client_idrequiredstringArgyle client ID value
client_secretrequiredstringArgyle client secret value
link_keyrequiredstringArgyle link key
contractstringPartner contract type, Staircase contract (SC) or bring your own contract (BYOC) - if not set default value is BYOC
typerequiredstringType of credentials, can be either test or production
Response 200application/json
1 fields

Setup API Triggered Successfully

FieldTypeDescription
messagestringMessage
Response 400application/json
1 fields

Request data failed validation

FieldTypeDescription
messagestringMessage
Response 403application/json
2 fields

Invalid key for service

FieldTypeDescription
messagestring
urlstring
Response 422application/json
2 fields

Request data failed validation

FieldTypeDescription
messagestringMessage
errorstringMessage
Response 500application/json
1 fields

The product has encountered an internal server error

FieldTypeDescription
messagestringError Message
Other responses

404

POST /atomic/credentials

Set Atomic Credentials

setAtomicCredentials

By using Set Atomic Credentials API we allow our customers to configure Atomic partner in customer environment.

If you don't have Atomic contract, please use our Request to Activate Partner API. Partner will be activated within next business day.

If you want to use your own Atomic contract for verification , please check Request body Schema example for required values from partner side and run Set Atomic Credentials API

Show the rest

Below is a step-by-step guide on how to add the webhook on partner dashboard.

If you don't add webhook on partner dashboard, verification will be triggered, but response of the verification will not be available, and you can be charged for verification.

Adding webhook workflow:

  1. Login to your Atomic Dashboard using your username and password.
  2. In the navigation menu browse to Settings.
  3. Under Webhooks, click the Add endpoint button.
  4. Add the following URL to the Endpoint URL input field:

NOTE: Change SUBDOMAIN value with your actual domain name

  1. Add Task status updates to the Events input field.
  2. Click on Add endpoint.

Please check Request body Schema example for required values from partner side.

You can check the partner status by calling the Retrieve Partners endpoint.

You are now ready to use the partner integration.

Request
application/json
{
  "client_key": "--------",
  "client_secret": "<redacted>",
  "username": "test@test.com",
  "password": "<redacted>",
  "contract": "SC",
  "type": "test"
}
Response
application/json

Setup API Triggered Successfully

{
  "message": "Credentials are saved and verified"
}
Parameters
1
ParameterTypeExampleDescription
x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Staircase Environment API Key
Request bodyapplication/json
6 fields
FieldTypeDescription
client_keystringAtomic client key
client_secretrequiredstringAtomic client secret
usernamerequiredstringAtomic username
passwordrequiredstringAtomic password
contractstringPartner contract type, Staircase contract (SC) or bring your own contract (BYOC) - if not set default value is BYOC
typerequiredstringType of credentials, can be either test or production
Response 200application/json
1 fields

Setup API Triggered Successfully

FieldTypeDescription
messagestringMessage
Response 400application/json
1 fields

Request data failed validation

FieldTypeDescription
messagestringMessage
Response 403application/json
2 fields

Invalid key for service

FieldTypeDescription
messagestring
urlstring
Response 422application/json
2 fields

Request data failed validation

FieldTypeDescription
messagestringMessage
errorstringMessage
Response 500application/json
1 fields

The product has encountered an internal server error

FieldTypeDescription
messagestringError Message
Other responses

404

POST /truework/credentials

Set Truework Credentials

setTrueworkCredentials

By using Set Truework Credentials API we allow our customers to configure Truework partner in customer environment.

If you don't have Truework contract, please use our Request to Activate Partner API. Partner will be activated within next business day.

If you want to use your own Truework contract for verification , please check Request body Schema example for required values from partner side and run Set Truework Credentials API

Show the rest

Below is a step-by-step guide on how to add the webhook on partner dashboard:

If you don't add webhook on partner dashboard, verification will be triggered, but response of the verification will not be available, and you can be charged for verification.

  1. Login to your Truework Dashboard using your username and password.
  2. In the navigation menu browse to Developer.
  3. Under API Settings, Production Webhooks click the Edit button.
  4. Under the Add Production Webhook section click the Event input and select "Verification Request Status Changed"
  5. Select the Target input and add the following URL:

NOTE: Change SUBDOMAIN value with your actual domain name

  1. Click on Create.

Please check Request body Schema example for required values from partner side.

You can check the partner status by calling the Retrieve Partners endpoint

You are now ready to use the partner integration.

Request
application/json
{
  "token": "<redacted>",
  "username": "test@test.com",
  "password": "<redacted>",
  "contract": "BYOC",
  "type": "test"
}
Response
application/json

Setup API Triggered Successfully

{
  "message": "Credentials are saved and verified"
}
Parameters
1
ParameterTypeExampleDescription
x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Staircase Environment API Key
Request bodyapplication/json
5 fields
FieldTypeDescription
tokenrequiredstringTruework token for API
usernamerequiredstringTruework username
passwordrequiredstringTruework password
contractstringPartner contract type, Staircase contract (SC) or bring your own contract (BYOC) - if not set default value is BYOC
typerequiredstringType of credentials, can be either test or production
Response 200application/json
1 fields

Setup API Triggered Successfully

FieldTypeDescription
messagestringMessage
Response 400application/json
1 fields

Request data failed validation

FieldTypeDescription
messagestringMessage
Response 403application/json
2 fields

Invalid key for service

FieldTypeDescription
messagestring
urlstring
Response 422application/json
2 fields

Request data failed validation

FieldTypeDescription
messagestringMessage
errorstringMessage
Response 500application/json
1 fields

The product has encountered an internal server error

FieldTypeDescription
messagestringError Message
Other responses

404

POST /truework-instant/credentials

Set Truework Instant Credentials

setTrueworkInstantCredentials

Set Truework-Instant Credentials

By using Set Truework-Instant Credentials API we allow our customers to configure Truework partner in customer environment for instant verification.

If you don't have Truework contract, please use our Request to Activate Partner API. Partner will be activated within next business day.

If you want to use your own Truework contract for verification , please check Request body Schema example for required values from partner side and run Set Truework Credentials API

Show the rest

Below is a step-by-step guide on how to add the webhook on partner dashboard:

If you don't add webhook on partner dashboard, verification will be triggered, but response of the verification will not be available, and you can be charged for verification.

  1. Login to your Truework Dashboard using your username and password.
  2. In the navigation menu browse to Developer.
  3. Under API Settings, Production Webhooks click the Edit button.
  4. Under the Add Production Webhook section click the Event input and select "Verification Request Status Changed"
  5. Select the Target input and add the following URL:

NOTE: Change SUBDOMAIN value with your actual domain name

  1. Click on Create.

Please check Request body Schema example for required values from partner side.

You can check the partner status by calling the Retrieve Partners endpoint

You are now ready to use the partner integration.

Request
application/json
{
  "token": "<redacted>",
  "username": "test@test.com",
  "password": "<redacted>",
  "contract": "SC",
  "type": "test"
}
Response
application/json

Setup API Triggered Successfully

{
  "message": "Credentials are saved and verified"
}
Parameters
1
ParameterTypeExampleDescription
x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Staircase Environment API Key
Request bodyapplication/json
5 fields
FieldTypeDescription
tokenrequiredstringTruework-Instant token for API
usernamerequiredstringTruework-Instant username
passwordrequiredstringTruework-Instant password
contractstringPartner contract type, Staircase contract (SC) or bring your own contract (BYOC) - if not set default value is BYOC
typerequiredstringType of credentials, can be either test or production
Response 200application/json
1 fields

Setup API Triggered Successfully

FieldTypeDescription
messagestringMessage
Response 400application/json
1 fields

Request data failed validation

FieldTypeDescription
messagestringMessage
Response 403application/json
2 fields

Invalid key for service

FieldTypeDescription
messagestring
urlstring
Response 422application/json
2 fields

Request data failed validation

FieldTypeDescription
messagestringMessage
errorstringMessage
Response 500application/json
1 fields

The product has encountered an internal server error

FieldTypeDescription
messagestringError Message
Other responses

404

POST /pinwheel/credentials

Set Pinwheel Credentials

setPinwheelCredentials

By using Set Pinwheel Credentials API we allow our customers to configure Pinwheel partner in customer environment.

If you don't have Pinwheel contract, please use our Request to Activate Partner API. Partner will be activated within next business day.

If you want to use your own Pinwheel contract for verification , please check Request body Schema example for required values from partner side and run Set Pinwheel Credentials API.

You can check the partner status by calling the Retrieve Partners endpoint

Request
application/json
{
  "x_api_secret": "--------",
  "contract": "BYOC",
  "type": "production"
}
Response
application/json

Setup API Triggered Successfully

{
  "message": "Credentials are saved and verified"
}
Parameters
1
ParameterTypeExampleDescription
x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Staircase Environment API Key
Request bodyapplication/json
3 fields
FieldTypeDescription
x_api_secretrequiredstringPinwheel API secret
contractstringPartner contract type, Staircase contract (SC) or bring your own contract (BYOC) - if not set default value is BYOC
typerequiredstringType of credentials, can be either test or production
Response 200application/json
1 fields

Setup API Triggered Successfully

FieldTypeDescription
messagestringMessage
Response 400application/json
1 fields

Request data failed validation

FieldTypeDescription
messagestringMessage
Response 403application/json
2 fields

Invalid key for service

FieldTypeDescription
messagestring
urlstring
Response 422application/json
2 fields

Request data failed validation

FieldTypeDescription
messagestringMessage
errorstringMessage
Response 500application/json
1 fields

The product has encountered an internal server error

FieldTypeDescription
messagestringError Message
Other responses

404

POST /meridian/credentials

Set Meridian Credentials

setMeridianCredentials

By using Set Meridian Credentials API we allow our customers to configure Meridian in customer environment.

If you want to use your own Meridian contract for verification , please check Request body Schema example for required values from partner side and run Set Meridian Credentials API.

We currently can't provide Staircase contract for Meridian.

You can check the partner status by calling the Retrieve Partners endpoint

Request
application/json
{
  "client_id": "--------",
  "client_secret": "<redacted>",
  "mcl": "--------",
  "domain": "example.domain.com",
  "type": "test"
}
Response
application/json

Setup API Triggered Successfully

{
  "message": "Credentials are saved and verified"
}
Parameters
1
ParameterTypeExampleDescription
x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Staircase Environment API Key
Request bodyapplication/json
6 fields
FieldTypeDescription
client_idrequiredstringMeridian client ID
client_secretrequiredstringMeridian client secret
domainrequiredstringMeridian domain
mclrequiredstringMeridian MCL schema
contractstringPartner contract type, Staircase contract (SC) or bring your own contract (BYOC) - if not set default value is BYOC
typerequiredstringType of credentials, can be either test or production
Response 200application/json
1 fields

Setup API Triggered Successfully

FieldTypeDescription
messagestringMessage
Response 400application/json
1 fields

Request data failed validation

FieldTypeDescription
messagestringMessage
Response 403application/json
2 fields

Invalid key for service

FieldTypeDescription
messagestring
urlstring
Response 422application/json
2 fields

Request data failed validation

FieldTypeDescription
messagestringMessage
errorstringMessage
Response 500application/json
1 fields

The product has encountered an internal server error

FieldTypeDescription
messagestringError Message
Other responses

404

POST /finicity/credentials

Set Finicity Credentials

setFinicityCredentials

By using Set Finicity Credentials API we allow our customers to configure Finicity partner in customer environment.

If you don't have Finicity contract, please use our Request to Activate Partner API. Partner will be activated within next business day.

If you want to use your own Finicity contract for verification , please check Request body Schema example for required values from partner side and run Set Finicity Credentials API.

You can check the partner status by calling the Retrieve Partners endpoint

Request
application/json
{
  "partnerId": "--------",
  "partnerSecret": "--------",
  "apiKey": "<redacted>",
  "contract": "BYOC",
  "type": "test"
}
Response
application/json

Setup API Triggered Successfully

{
  "message": "Credentials are saved and verified"
}
Parameters
1
ParameterTypeExampleDescription
x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Staircase Environment API Key
Request bodyapplication/json
5 fields
FieldTypeDescription
partnerIdrequiredstringFinicity partner ID
partnerSecretrequiredstringFinicity partner secret
apiKeyrequiredstringFinicity API key
contractstringPartner contract type, Staircase contract (SC) or bring your own contract (BYOC) - if not set default value is BYOC
typerequiredstringType of credentials, can be either test or production
Response 200application/json
1 fields

Setup API Triggered Successfully

FieldTypeDescription
messagestringMessage
Response 400application/json
1 fields

Request data failed validation

FieldTypeDescription
messagestringMessage
Response 403application/json
2 fields

Invalid key for service

FieldTypeDescription
messagestring
urlstring
Response 422application/json
2 fields

Request data failed validation

FieldTypeDescription
messagestringMessage
errorstringMessage
Response 500application/json
1 fields

The product has encountered an internal server error

FieldTypeDescription
messagestringError Message
Other responses

404

POST /equifax/credentials

Set Equifax Credentials

setEquifaxCredentials

Set Equifax Credentials

By using Set Equifax Credentials API we allow our customers to configure Equifax partner in customer environment. You can add your own existing Equifax contract, or you can request to use Staircase contract to activate a partner in your environment by executing Request to activate partner API.

To enable partner Equifax for verification you need to:

Show the rest

Setting credentials

Add all key values for your Equifax, TheWorkNumber Account : "twn_username", "twn_password" , "pfx_certificate_password" and "type" in request body. Please check request body schema example.

PFX certificate

In addition to setting credentials for Equifax you need to upload a PFX certificate. Use Upload Equifax Certificate API to upload certificate to your environment. PFX Certificate needs to be provided by Equifax. If you don't have it, you will not be able to use Equifax as partner for verification. If this is the case please contact your Equifax Account Manager, and get PFX certificate and password for certificate.

Public IP address

Public IP address of your environment needs to be added to Equifax firewall. To enable public IP address for your environment you need to enable static IP feature using APIs Enable static IP feature and Get IP Allocation Status. If public IP address is not allowed through Equifax firewall, you will not be able to use Equifax as partner for verification.

When you get public IP address please contact your Equifax Account Manager, so they allow public IP address of your environment through Equifax firewall

You can check the partner status by calling the Retrieve Partners endpoint

Request
application/json
{
  "twn_username": "UserNameIntgTEST@5005",
  "twn_password": "I_9087POK",
  "pfx_certificate_password": "9huoiqhiokopj9iu",
  "contract": "BYOC",
  "type": "production"
}
Response
application/json

Setup API Triggered Successfully

{
  "message": "Credentials are saved and verified"
}
Parameters
1
ParameterTypeExampleDescription
x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Staircase Environment API Key
Request bodyapplication/json
5 fields
FieldTypeDescription
twn_usernamerequiredstringEquifax The Work Number username
twn_passwordrequiredstringEquifax The Work Number password
pfx_certificate_passwordstringEquifax PFX Certificate password
contractstringPartner contract type, Staircase contract (SC) or bring your own contract (BYOC) - if not set default value is BYOC
typestringType of credentials, can be either test or production
Response 200application/json
1 fields

Setup API Triggered Successfully

FieldTypeDescription
messagestringMessage
Response 400application/json
1 fields

Request data failed validation

FieldTypeDescription
messagestringMessage
Response 403application/json
2 fields

Invalid key for service

FieldTypeDescription
messagestring
urlstring
Response 422application/json
2 fields

Request data failed validation

FieldTypeDescription
messagestringMessage
errorstringMessage
Response 500application/json
1 fields

The product has encountered an internal server error

FieldTypeDescription
messagestringError Message
Other responses

404

POST /equifax/certificate

Upload Equifax Certificate

uploadEquifaxCertificate

Upload Equifax Certificate

For uploading Equifax PFX Certificate you will need to issue a POST request to this endpoint. Upload Equifax Certificate uploads a .pfx document to our services. You can upload the certificate using HTML Request Maker Try It Out. Place your api_key in the request header, please make sure Content-Type is set to application/x-pkcs12. Set the request body to binary and browse to your PFX Certificate. Click Send to upload your certificate.

To upload a certificate programmatically, use the upload example below. After you get a successful response, you can start using the Equifax integration.

import requests
url = ""
payload = open("certificate.pfx", "rb")
headers = {
 'x-api-key': 'API_KEY',
 'Content-Type': 'application/x-pkcs12'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
Request
application/json
Select option 'binary' in order to upload file
Response
application/json

Setup API Triggered Successfully

{
  "message": "Certificate uploaded and saved successfully"
}
Parameters
1
ParameterTypeExampleDescription
x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Staircase Environment API Key
Response 200application/json
1 fields

Setup API Triggered Successfully

FieldTypeDescription
messagestringMessage
Response 400application/json
1 fields

Request data failed validation

FieldTypeDescription
messagestringMessage
Response 403application/json
2 fields

Invalid key for service

FieldTypeDescription
messagestring
urlstring
Response 500application/json
1 fields

The product has encountered an internal server error

FieldTypeDescription
messagestringError Message
Other responses

404

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.

Show the rest
$.document_sets.document_set[0].documents.document[0].foreign_objects.foreign_object[0].staircase_blob_id

To upload a document within code, you can to use a below example.

import requests

with open("document.pdf", "rb") as document:
 payload = document.read

url = ""
headers = {
 "x-api-key": ...,
 "Content-Type": "application/pdf"
}
response = requests.post(url, headers=headers, data=payload)
if response.ok:
 blob_id = response.json["blob_id"]
Request
application/octet-stream
Select option 'binary' in order to upload file
Response
application/json

Blob uploaded

{
  "blob_id": "01EZY9J8SEFM2JKDJ1Q3YX65HS"
}
Parameters
1
ParameterTypeExampleDescription
x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Environment API Key.
Response 201application/json
1 fields

Blob uploaded

FieldTypeDescription
blob_idstringCreated blob ID
Response 403application/json
2 fields

403 invalid error

FieldTypeDescription
messagestringError message.
urlstringError additional URL.
Response 500application/json
1 fields

Internal server error

FieldTypeDescription
messagestringError 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.

Response
application/json

Blob retrieved successfully.

{
  "blob_id": "01EZY9ENJGRMTW4S9CS4V1Y6XH",
  "extension": ".pdf",
  "message": "Blob retrieved successfully.",
  "presigned_urls": {
    "upload": {
      "url": "https://dev-data-manager-blobs-bucket-us-east-1-867210375911.s3.amazonaws.com/01EZY9ENJGRMTW4S9CS4V1Y6XH"
    }
  }
}
Parameters
2
ParameterTypeExampleDescription
x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Environment API Key.
blob_id required string path 01EZY9J8SEFM2JKDJ1Q3YX65HS Blob identifier
Response 200application/json
4 fields

Blob retrieved successfully.

FieldTypeDescription
blob_idstringBlob ID
extensionstringFile extension
messagestringBlob retrieved successfully.
presigned_urlsobjectPresigned URL
Response 403application/json
2 fields

403 invalid error

FieldTypeDescription
messagestringError message.
urlstringError additional URL.
Response 500application/json
1 fields

Internal server error

FieldTypeDescription
messagestringError message.
Other responses

400404405

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

Create Presigned URL

createPresignedUrl

Create Presigned URL creates a presigned URL in Staircase. The presigned URL is used to upload or download a blob (document). It expires one hour after creation.

Response
application/json

Presigned URL created successfully.

{
  "presigned_urls": {
    "upload": {
      "url": "https://dev-data-manager-blobs-bucket.s3.amazonaws.com/01EZY9J8SEFM2JKDJ1Q3YX65HS"
    },
    "download": {
      "url": "https://dev-data-manager-blobs-bucket.s3.amazonaws.com/01EZY9J8SEFM2JKDJ1Q3YX65HS"
    }
  }
}
Parameters
3
ParameterTypeExampleDescription
x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Environment API Key.
blob_id required string path 01EZY9J8SEFM2JKDJ1Q3YX65HS Blob identifier
action required string path upload Action, one of one of ['upload', 'donwload']
Response 200application/json
1 fields

Presigned URL created successfully.

FieldTypeDescription
presigned_urlsobjectPresigned URLs
Response 403application/json
2 fields

403 invalid error

FieldTypeDescription
messagestringError message.
urlstringError additional URL.
Other responses

400404

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.

Response
application/json

Presigned URL retrieved successfully.

{
  "url": "https://dev-data-manager-blobs-bucket.s3.amazonaws.com/01EZY9J8SEFM2JKDJ1Q3YX65HS"
}
Parameters
3
ParameterTypeExampleDescription
x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Environment API Key.
blob_id required string path 01EZY9J8SEFM2JKDJ1Q3YX65HS Blob identifier
action required string path upload Possible actions: - upload - download
Response 200application/json
1 fields

Presigned URL retrieved successfully.

FieldTypeDescription
urlstringPresigned url
Response 403application/json
2 fields

403 invalid error

FieldTypeDescription
messagestringError message.
urlstringError additional URL.
Response 500application/json
1 fields

Internal server error

FieldTypeDescription
messagestringError 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.

Response
application/json

Presigned URLs retrieved successfully.

{
  "upload": {
    "url": "https://dev-data-manager-blobs-bucket.s3.amazonaws.com/01EZY9J8SEFM2JKDJ1Q3YX65HS"
  }
}
Parameters
2
ParameterTypeExampleDescription
x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Environment API Key.
blob_id required string path 01EZY9J8SEFM2JKDJ1Q3YX65HS Blob identifier
Response 200application/json
1 fields

Presigned URLs retrieved successfully.

FieldTypeDescription
presigned_urlsobjectPresigned URLs
Response 403application/json
2 fields

403 invalid error

FieldTypeDescription
messagestringError message.
urlstringError 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"
}
Parameters
1
ParameterTypeExampleDescription
x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Environment API Key.
Request bodyapplication/json
5 fields
FieldTypeDescription
extension_pathstringJSON path where the extension is in the response object. If it is not specified, extension will be "pdf".Example $.DocumentExension
content_pathrequiredstringJSON path where the actual content is in the response object.Example $.DocumentData
decode_from_base64booleanNeed to decode a content from base64.
encode_to_base64booleanNeed to encode a content to base64.
urlrequiredstringURL with the partner response.Example https://google.com
Response 201application/json
1 fields

Presigned URLs retrieved successfully.

FieldTypeDescription
blob_idstringID of the returned blob.
Response 400application/json
1 fields

Invalid body request.

FieldTypeDescription
messagestringError message
Response 403application/json
2 fields

403 invalid error

FieldTypeDescription
messagestringError message.
urlstringError additional URL.
Response 422application/json
1 fields

Unprocessable entity error

FieldTypeDescription
messagestringError Message.
Response 500application/json
1 fields

Internal server error

FieldTypeDescription
messagestringError message.

Partners

GET /partners

Retrieve Partners

getVendors

Retrieve Partners retrieves an object containing all available employment verification partners. Use the partner_name to invoke the partner when calling Verify Employment.

Response
application/json

Successfully retrieved product partners.

{
  "partners": [
    {
      "Partner": "partner_name",
      "order": 1,
      "active": true,
      "status": "active",
      "verification_type": "borrower",
      "byoc": true
    }
  ]
}
Parameters
2
ParameterTypeExampleDescription
x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Environment API Key.
active boolean query false Include vendors with active product flows
Response 200application/json
1 fields

Successfully retrieved product partners.

FieldTypeDescription
partnersobject[]List of vendors.
partnerstringPartner name
ordernumberOrder of the product flows associated with this partner
activebooleanPartner has active flows
statusstringStatus of the partner
verification_typestringType of verification
byocbooleanSpecify whether customer should add its own partner credentials or not
Response 400application/json
1 fields

Validation Error

FieldTypeDescription
messageone ofMessage
Response 403application/json
2 fields

403 invalid error

FieldTypeDescription
messagestringError message.
urlstringError additional URL.
Response 404application/json
1 fields

Resource not found

FieldTypeDescription
messagestringError Message.
Response 500application/json
1 fields

Internal server error

FieldTypeDescription
messagestringError message.
GET /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.

Response
application/json

Successfully retrieved partners ordering.

[
  {
    "partner": "partner1",
    "order": 1
  },
  {
    "partner": "partner2",
    "order": 2
  }
]
Parameters
1
ParameterTypeExampleDescription
x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Environment API Key.
Response 200application/json
1 fields

Successfully retrieved partners ordering.

FieldTypeDescription
partner_orderobjectPartner and order
partnerstringExample partner1
ordernumberExample 1
Response 400application/json
1 fields

Validation Error

FieldTypeDescription
messageone ofMessage
Response 403application/json
2 fields

403 invalid error

FieldTypeDescription
messagestringError message.
urlstringError additional URL.
Response 404application/json
1 fields

Resource not found

FieldTypeDescription
messagestringError Message.
Response 500application/json
1 fields

Internal server error

FieldTypeDescription
messagestringError message.
PATCH /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.

Request
application/json
{
  "active": true
}
Response
application/json

Successfully updated active parameter for the partner.

{
  "message": "Partner status updated."
}
Parameters
2
ParameterTypeExampleDescription
x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Environment API Key.
partner required string path partner_name Name of the partner for which we wan't to update status.
Request bodyapplication/json
1 fields
FieldTypeDescription
activerequiredbooleanExample true
Response 200application/json
1 fields

Successfully updated active parameter for the partner.

FieldTypeDescription
messagestringPartner status updated.
Response 400application/json
1 fields

Failed to update the partner from one of the reasons.

FieldTypeDescription
messagestringPartner doesn't exist in database.
Response 403application/json
2 fields

403 invalid error

FieldTypeDescription
messagestringError message.
urlstringError additional URL.
Response 404application/json
1 fields

Resource not found

FieldTypeDescription
messagestringError Message.
Response 500application/json
1 fields

Internal server error

FieldTypeDescription
messagestringError 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.

If partner has active set to false you won't be able to use this partner when doing employment verification or while using Company Search.

If partner has active set to true you will be able to use this partner when doing employment verification and for Company Search.

Please note that a given partner can only be activated if credentials are set, please use the Setup endpoints to set credentials.

Request
application/json
{
  "active": true
}
Response
application/json

Successfully updated active parameter for the partner

{
  "message": "Partner status updated!"
}
Parameters
2
ParameterTypeExampleDescription
x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Staircase Environment API Key
partner required string path partner_name Name of the partner for which we wan't to update status
Request bodyapplication/json
1 fields
FieldTypeDescription
activerequiredbooleanExample true
Response 200application/json
1 fields

Successfully updated active parameter for the partner

FieldTypeDescription
messagestringPartner status updated!
Response 400application/json
1 fields

Failed to update the partner from one of the reasons

FieldTypeDescription
messagestringPartner doesn't exist in database
Response 403application/json
2 fields

Invalid key for service

FieldTypeDescription
messagestring
urlstring
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.

FieldTypeDescription
messagestring
PUT /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.

Request
application/json
{
  "ordering": [
    {
      "partner": "partner1",
      "order": 1
    },
    {
      "partner": "partner2",
      "order": 10
    }
  ]
}
Response
application/json

Successfully updated partners ordering.

[
  {
    "partner": "partner1",
    "order": 1
  },
  {
    "partner": "partner2",
    "order": 10
  }
]
Parameters
1
ParameterTypeExampleDescription
x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Environment API Key.
Request bodyapplication/json
1 fields
FieldTypeDescription
orderingobject[]
partnerstringPartner nameExample wage
ordernumberPartner orderExample 1
Response 200application/json
2 fields

Successfully updated partners ordering.

FieldTypeDescription
partnerstringPartner nameExample wage
ordernumberPartner orderExample 1
Response 400application/json
1 fields

Failed to update the partner from one of the reasons

FieldTypeDescription
messagestringPartner doesn't exist in database
Response 403application/json
2 fields

403 invalid error

FieldTypeDescription
messagestringError message.
urlstringError additional URL.
Response 404application/json
1 fields

Resource not found

FieldTypeDescription
messagestringError Message.
Response 500application/json
1 fields

Internal server error

FieldTypeDescription
messagestringError message.
GET /partners/{partner}/schema

Retrieve Partner Credentials Schema

getPartnerSchema

Retrieve Partner Schema retrieves the required partner schema for credentials.

Response
application/json

Successfully returned the partner schema object

{
  "$schema": "http://json-schema.org/draft-07/schema",
  "$id": "http://example.com/example.json",
  "type": "object",
  "title": "Partner root schema",
  "description": "Partner credentials schema for connector flows.",
  "webhook": false,
  "default": {},
  "examples": [
    {
      "key1": "value1",
      "key2": "value2"
    }
  ],
  "required": [
    "key1",
    "key2"
  ],
  "properties": {
    "key1": {
      "$id": "#/properties/key1",
      "type": "string",
      "title": "Partner key1 schema",
      "description": "Partner key1",
      "default": "",
      "examples": [
        "value1"
      ]
    },
    "key2": {
      "$id": "#/properties/key2",
      "type": "string",
      "title": "Partner key2 schema",
      "description": "Partner key2",
      "default": "",
      "examples": [
        "value2"
      ]
    }
  },
  "additionalProperties": true
}
Parameters
2
ParameterTypeExampleDescription
x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Staircase Environment API Key
partner required string path 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

FieldTypeDescription
schemastringSchema URL
idstringSchema ID
typestringJSON type
titlestringSchema title
descriptionstringSchema description
webhookbooleanValue that indicates if partner requires webhook setup
defaultobjectDefault value for schema
examplesobject[]List of examples
key1stringExample 1
key2stringExample 2
requiredstring[]Required fields
propertiesobjectProperties of Schema
key1objectKey 1 Schema
idstringProperty ID
typestringProperty value type
titlestringTitle for property
descriptionstringDescription for property
defaultstringDefault value if exists
examplesstring[]List of examples for given property
key2objectKey 2 Schema
idstringProperty ID
typestringProperty value type
titlestringTitle for property
descriptionstringDescription for property
defaultstringDefault value if exists
examplesstring[]List of examples for given property
Response 400application/json
1 fields

Bad Request

FieldTypeDescription
messagestringPartner not found
Response 403application/json
2 fields

Invalid key for service

FieldTypeDescription
messagestring
urlstring
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.

FieldTypeDescription
messagestring

Product Invocation

POST /products/employment/invocations

Invoke Product Flow

invokeProductFlow

Invoke Product Flow helps you to invoke product flow.

There are two options for using transactions and collections while invoking a product:

  • 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:

    Show the rest
  • Create transaction.

  • Create input collection with the provided request_data.

  • Create empty output collection.

  • Optional Parameters:

    • product_flow_name : to invoke specific product flow by name,if not provided default_product_flow will be invoked.
    • vendor_name: default_vendor_flow will be invoked. Otherwise, first flow for this vendor will be invoked.
    • tags: when tags are provided product shall filter the product flows associated with these tags before picking the product flow to invoke.
    • 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:

    {
    "type": "object",
    "$schema": "",
    "required": [
    "invocation_id",
    "invocation_status"
    ],
    "properties": {
    "invocation_id": {
    "type": "string",
    "format": "uuid"
    },
    "invocation_status": {
    "type": "string",
    "enum": [
    "COMPLETED",
    "FAILED"
    ]
    },
    "response_data": {
    "type": "object",
    "additionalProperties": true
    },
    "failure_reason": {
    "type": "string"
    }
    }
    }
    

    Product flow invocation shall:

    • Validate the input data.
    • Create customer transaction, request and response collections if they are not provided.
    • Pick a product flow to invoke:
    • Exclude the inactive flows.
    • If 'product_flow_name' was provided, then use it.
    • Else, If 'vendor_name' was provided then use the default_vendor_flow if not found, use the first flow for this vendor.
    • If 'tags' are provided, then:
    • Filter the product flows according to the tags if provided.
    • Pick the default_product_flow if defined, otherwise, use the first flow in the list.
    • Translate input using the configured input translation language.
    • Invoke the connector flow.
    • Translate the output using the configured output translation language.
    • Generate the reports if configured on the product.
    Request
    application/json
    {
      "product_flow_name": "Wage",
      "transaction_id": "01F6NAMXWN2XVBD1YJ92A6S6R4",
      "response_collection_id": "01F6NAQ4894HPMCBGB4P0G95XK",
      "request_collection_id": "01F6QF1QJF20DMSXH4SYXKB1SN",
      "callback_url": "https://webhook.site/3706b519-9426-4533-9868-14a7dec4fd97",
      "request_data": {
        "deal_sets": {
          "deal_set": [
            {
              "deals": {
                "deal": [
                  {
                    "parties": {
                      "party": [
                        {
                          "customer_transaction_ID": "e171ec31-75b4-4fd6-ada1-a0c48373c079",
                          "individual": {
                            "contact_points": {
                              "contact_point": [
                                {
                                  "contact_point_telephone": {
                                    "value": "+1234567890"
                                  },
                                  "contact_point_email": {
                                    "value": "test@test.com"
                                  }
                                }
                              ]
                            },
                            "name": {
                              "first": "John",
                              "last": "Jackson"
                            }
                          },
                          "roles": {
                            "role": [
                              {
                                "borrower": {
                                  "birth_date": "1984-01-01",
                                  "employers": {
                                    "employer": [
                                      {
                                        "legal_entity": {
                                          "full_name": "Amazon"
                                        }
                                      }
                                    ]
                                  },
                                  "residences": {
                                    "residence": [
                                      {
                                        "address": {
                                          "additional_line_text": "None",
                                          "city": "NEW YORK",
                                          "country": "US",
                                          "line_text": "33 IRVING PLACE",
                                          "postal_code": "10003",
                                          "state_code": "NY",
                                          "state": "NY"
                                        }
                                      }
                                    ]
                                  }
                                }
                              }
                            ]
                          },
                          "taxpayer_identifiers": {
                            "taxpayer_identifier": [
                              {
                                "value": "317210001"
                              }
                            ]
                          }
                        }
                      ]
                    }
                  }
                ]
              }
            }
          ]
        },
        "document_sets": {
          "document_set": [
            {
              "documents": {
                "document": [
                  {
                    "document_classification": {
                      "document_classes": {
                        "document_class": [
                          {
                            "staircase_type": "Staircase",
                            "type": "BorrowerApproval"
                          }
                        ]
                      }
                    },
                    "foreign_objects": {
                      "foreign_object": [
                        {
                          "description": "BorrowerApproval",
                          "mime_type_identifier": "application/pdf",
                          "name": "01F1Z5KG9E3CPD78P7GYB3TYC1.pdf",
                          "staircase_blob_id": "01F1Z5KG9E3CPD78P7GYB3TYC1"
                        }
                      ]
                    }
                  }
                ]
              }
            }
          ]
        }
      }
    }
    Response
    application/json

    Successfully started flow invocation.

    {
      "invocation_id": "9aefb465-90fb-4d50-8ae6-2df2b58373f4",
      "status": "STARTED",
      "output_language_name": "staircase",
      "transaction_id": "01F6NAMXWN2XVBD1YJ92A6S6R4",
      "request_collection_id": "01F6NAQ4894HPMCBGB4P0G95XK",
      "response_collection_id": "01F6QF1QJF20DMSXH4SYXKB1SN",
      "tags": [
        "manual verification"
      ]
    }
    Parameters
    1
    ParameterTypeExampleDescription
    x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Environment API Key.
    Request bodyapplication/json
    9 fields
    FieldTypeDescription
    product_flow_namestringProduct 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_namestringVendor name. Cannot be specified together with product_flow_name.
    transaction_idstringTransaction ID used for invocation.
    request_collection_idstringRequest Collection ID.
    response_collection_idstringResponse Collection ID.
    callback_urlstring (uri)Callback URL.
    request_dataobjectRequest JSON body.
    tagsstring[]List of tags.
    optionsobjectAdditional information that should be passed to the connector but not be added to the request collection.
    Response 201application/json
    10 fields

    Successfully started flow invocation.

    FieldTypeDescription
    invocation_idrequiredstringInvocation ID.
    invocation_statusrequiredstringThe status of the invocation.STARTED
    transaction_idrequiredstringTransaction ID.
    product_flow_namestringProduct flow name.
    metadataobjectThe metadata of the invoked product flow.
    callback_urlstringCallback URL.
    request_dataobjectThe data for the request collection.
    tagsstring[]List of tags.
    optionsobjectAdditional information that should be passed to the connector but not be added to the request collection.
    connector_job_idstringConnector job ID.
    Response 400application/json
    1 fields

    Request data failed validation

    FieldTypeDescription
    messagestringMessage
    Response 403application/json
    2 fields

    403 invalid error

    FieldTypeDescription
    messagestringError message.
    urlstringError additional URL.
    Response 404application/json
    1 fields

    Resource not found

    FieldTypeDescription
    messagestringMessage
    Response 500application/json
    1 fields

    Internal server error

    FieldTypeDescription
    messagestringError message.
    GET /products/employment/invocations/{invocation_id}

    Retrieve Product Flow Invocation Status

    RetrieveProductFlowInvocationStatus

    Retrieves the status of running Product flow invocation.

    Response
    application/json

    Successfully returned status of the Product flow Invocation.

    {
      "invocation_id": "9aefb465-90fb-4d50-8ae6-2df2b58373f4",
      "status": "STARTED",
      "output_language_name": "staircase",
      "transaction_id": "01F6NAMXWN2XVBD1YJ92A6S6R4",
      "request_collection_id": "01F6NAQ4894HPMCBGB4P0G95XK",
      "response_collection_id": "01F6QF1QJF20DMSXH4SYXKB1SN",
      "tags": [
        "manual verification"
      ]
    }
    Parameters
    2
    ParameterTypeExampleDescription
    x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Environment API Key.
    invocation_id required string (ulid) path d7ccedb8-8889-4657-add4-bc1s4xs97637 Product flow invocation identifier
    Response 200application/json
    12 fields

    Successfully returned status of the Product flow Invocation.

    FieldTypeDescription
    invocation_idrequiredstringInvocation ID.
    invocation_statusrequiredstringInvocation Status.ACTION_REQUIREDCOMPLETEDFAILEDRUNNINGSTARTED
    transaction_idrequiredstringTransaction ID used for invocation.
    request_collection_idstringRequest Collection ID.
    request_collectionobjectCollection.
    transaction_idstring (ulid)Transaction ID.Example 01EZQ32PJQGKRA6HR8D72Q9FFF
    collection_idstring (ulid)Collection ID.Example 01EZQ32PJQGKRA6HR8D72Q9FFF
    dataobjectData in Staircase language schema.
    metadataobjectMetadata about collection, f.e version of used Staircase schema.
    response_collection_idstringResponse Collection ID.
    response_collectionobjectCollection.
    transaction_idstring (ulid)Transaction ID.Example 01EZQ32PJQGKRA6HR8D72Q9FFF
    collection_idstring (ulid)Collection ID.Example 01EZQ32PJQGKRA6HR8D72Q9FFF
    dataobjectData in Staircase language schema.
    metadataobjectMetadata about collection, f.e version of used Staircase schema.
    callback_urlstringURL that was specified in flow invocation and will be used to send the callback when flow invocation will be finished.
    widget_urlstring (uri)URL of the widget.
    metadataobjectResponse Collection ID.
    optionsOptions that were passed to the flow invocation.
    connector_job_idstringConnector job ID.
    Response 400application/json
    1 fields

    Request data failed validation

    FieldTypeDescription
    messagestringMessage
    Response 403application/json
    2 fields

    403 invalid error

    FieldTypeDescription
    messagestringError message.
    urlstringError additional URL.
    Response 404application/json
    1 fields

    Resource not found

    FieldTypeDescription
    messagestringMessage
    Response 500application/json
    1 fields

    Internal server error

    FieldTypeDescription
    messagestringError message.

    Product Reports

    GET /products/employment/report-templates

    Retrieve Report Templates

    retrieveReportTemplates

    Retrieve Report Templates retrieves product report templates.

    Response
    application/json

    Successfully returned the report templates.

    {
      "name": "voe_template",
      "template_type": "jinja",
      "product_name": "employment",
      "body": "<!DOCTYPE html><html lang=\\\"en\\\"><head><title>Staircase</title></head><body><h3>First Name</h3>{{ collection[\\\"deal_sets\\\"][\\\"deal_set\\\"][0][\\\"deals\\\"][\\\"deal\\\"][0][\\\"parties\\\"][\\\"party\\\"][0][\\\"individual\\\"][\\\"name\\\"][\\\"first\\\"] }}</body></html>"
    }
    Parameters
    1
    ParameterTypeExampleDescription
    x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Environment API Key.
    Response 200application/json
    4 fields

    Successfully returned the report templates.

    FieldTypeDescription
    namestringName of template
    template_typestringTemplate typejinja
    bodystringTemplate HTML string body
    product_namestringProduct name
    Response 400application/json
    1 fields

    Request data failed validation

    FieldTypeDescription
    messagestringMessage
    Response 403application/json
    2 fields

    403 invalid error

    FieldTypeDescription
    messagestringError message.
    urlstringError additional URL.
    Response 404application/json
    1 fields

    Resource not found

    FieldTypeDescription
    messagestringError Message.
    Response 500application/json
    1 fields

    Internal server error

    FieldTypeDescription
    messagestringError message.
    POST /products/employment/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.

    <!DOCTYPE html>
    <html lang="en">
    <head>
     <title>Staircase</title>
    </head>
    <body>
     <h1 style="align-content: center; color: red">Staircase</h1>
    
     <h3>First Name</h3>
     {{ collection["deal_sets"]["deal_set"][0]["deals"]["deal"][0]["parties"]["party"][0]["individual"]["name"]["first"] }}
    
     <h3>Last Name</h3>
     {{ collection["deal_sets"]["deal_set"][0]["deals"]["deal"][0]["parties"]["party"][0]["individual"]["name"]["last"] }}
    
     <h3>List</h3>
     <ul>
     {% for item in collection.deal_sets.deal_set[0].deals.deal[0].parties.party[0].individual.contact_points.contact_point %}
     <li>Email: {{ item.email }}</li>
     <li>Phone: {{ item.contact_point_telephone.value }}</li>
     
    
     {% endfor %}
     </ul>
    
     <h3>Table</h3>
     <table style="border: 1px solid black;">
     <tr>
     {%- for header in ["Name", "Email", "Phone"] %}
     <th style="border: 1px solid black;">{{ header }} </th>
     {%- endfor %}
     </tr>
     {%- for row in collection.deal_sets.deal_set[0].deals.deal[0].parties.party[0].individual.contact_points.contact_point %}
     <tr>
     <td style="border: 1px solid black;">{{ collection["deal_sets"]["deal_set"][0]["deals"]["deal"][0]["parties"]["party"][0]["individual"]["name"]["first"] }} </td>
     <td style="border: 1px solid black;">{{row.email}}</td>
     <td style="border: 1px solid black;">{{row.contact_point_telephone.value}}</td>
     </tr>
     {%- endfor %}
     </table>
    </body>
    </html>
    

    Refer to Jinja documentation for more information on the logic used.

    Show the rest

    Example Reports

    Please refer to the example reports and style guidelines in the request examples below.

    Notes:

    • Report header and footer are implicit and will automatically wrap your content. You only need to create a template for your content.
    • The below example reports HTML is minified for display. Please unminify to convert back to normal HTML file and update with your logic.
    • You may use the style guidelines if a table, bulleted-list, etc. are needed.
    Request
    application/json
    {
      "name": "voe_template",
      "template_type": "jinja",
      "body": "<!DOCTYPE html><html lang=\\\"en\\\"><head><title>Staircase</title></head><body><h3>First Name</h3>{{ collection[\\\"deal_sets\\\"][\\\"deal_set\\\"][0][\\\"deals\\\"][\\\"deal\\\"][0][\\\"parties\\\"][\\\"party\\\"][0][\\\"individual\\\"][\\\"name\\\"][\\\"first\\\"] }}</body></html>"
    }
    Response
    application/json

    Report template successfully added.

    {
      "name": "voe_template",
      "template_type": "jinja",
      "product_name": "employment",
      "body": "<!DOCTYPE html><html lang=\\\"en\\\"><head><title>Staircase</title></head><body><h3>First Name</h3>{{ collection[\\\"deal_sets\\\"][\\\"deal_set\\\"][0][\\\"deals\\\"][\\\"deal\\\"][0][\\\"parties\\\"][\\\"party\\\"][0][\\\"individual\\\"][\\\"name\\\"][\\\"first\\\"] }}</body></html>"
    }
    Parameters
    1
    ParameterTypeExampleDescription
    x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Environment API Key.
    Request bodyapplication/json
    3 fields
    FieldTypeDescription
    namerequiredstringName of template
    template_typerequiredstringTemplate typejinja
    bodyrequiredstringTemplate HTML string body
    Response 200application/json
    4 fields

    Report template successfully added.

    FieldTypeDescription
    namestringName of template
    template_typestringTemplate typejinja
    bodystringTemplate HTML string body
    product_namestringProduct name
    Response 400application/json
    1 fields

    Request data failed validation

    FieldTypeDescription
    messagestringMessage
    Response 403application/json
    2 fields

    403 invalid error

    FieldTypeDescription
    messagestringError message.
    urlstringError additional URL.
    Response 404application/json
    1 fields

    Resource not found

    FieldTypeDescription
    messagestringError Message.
    Response 500application/json
    1 fields

    Internal server error

    FieldTypeDescription
    messagestringError message.
    GET /products/employment/report-templates/{template_name}

    Retrieve Report Template

    retrieveReportTemplate

    Retrieve Report Template retrieves a specific report template.

    Response
    application/json

    Successfully returned the report template.

    {
      "name": "voe_template",
      "template_type": "jinja",
      "product_name": "employment",
      "body": "<!DOCTYPE html><html lang=\\\"en\\\"><head><title>Staircase</title></head><body><h3>First Name</h3>{{ collection[\\\"deal_sets\\\"][\\\"deal_set\\\"][0][\\\"deals\\\"][\\\"deal\\\"][0][\\\"parties\\\"][\\\"party\\\"][0][\\\"individual\\\"][\\\"name\\\"][\\\"first\\\"] }}</body></html>"
    }
    Parameters
    2
    ParameterTypeExampleDescription
    x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Environment API Key.
    template_name required string path demo_template Report Template Name
    Response 200application/json
    4 fields

    Successfully returned the report template.

    FieldTypeDescription
    namestringName of template
    template_typestringTemplate typejinja
    bodystringTemplate HTML string body
    product_namestringProduct name
    Response 400application/json
    1 fields

    Request data failed validation

    FieldTypeDescription
    messagestringMessage
    Response 403application/json
    2 fields

    403 invalid error

    FieldTypeDescription
    messagestringError message.
    urlstringError additional URL.
    Response 404application/json
    1 fields

    Resource not found

    FieldTypeDescription
    messagestringError Message.
    Response 500application/json
    1 fields

    Internal server error

    FieldTypeDescription
    messagestringError message.
    PATCH /products/employment/report-templates/{template_name}

    Update Report Template

    updateReportTemplate

    Update report template

    Request
    application/json
    {
      "name": "voe_template",
      "template_type": "jinja",
      "body": "<!DOCTYPE html><html lang=\\\"en\\\"><head><title>Staircase</title></head><body><h3>First Name</h3>{{ collection[\\\"deal_sets\\\"][\\\"deal_set\\\"][0][\\\"deals\\\"][\\\"deal\\\"][0][\\\"parties\\\"][\\\"party\\\"][0][\\\"individual\\\"][\\\"name\\\"][\\\"first\\\"] }}</body></html>"
    }
    Response
    application/json

    Report template successfully updated.

    {
      "name": "voe_template",
      "template_type": "jinja",
      "product_name": "employment",
      "body": "<!DOCTYPE html><html lang=\\\"en\\\"><head><title>Staircase</title></head><body><h3>First Name</h3>{{ collection[\\\"deal_sets\\\"][\\\"deal_set\\\"][0][\\\"deals\\\"][\\\"deal\\\"][0][\\\"parties\\\"][\\\"party\\\"][0][\\\"individual\\\"][\\\"name\\\"][\\\"first\\\"] }}</body></html>"
    }
    Parameters
    2
    ParameterTypeExampleDescription
    x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Environment API Key.
    template_name required string path demo_template Report Template Name
    Request bodyapplication/json
    3 fields
    FieldTypeDescription
    namerequiredstringName of template
    template_typerequiredstringTemplate typejinja
    bodyrequiredstringTemplate HTML string body
    Response 200application/json
    4 fields

    Report template successfully updated.

    FieldTypeDescription
    namestringName of template
    template_typestringTemplate typejinja
    bodystringTemplate HTML string body
    product_namestringProduct name
    Response 400application/json
    1 fields

    Request data failed validation

    FieldTypeDescription
    messagestringMessage
    Response 403application/json
    2 fields

    403 invalid error

    FieldTypeDescription
    messagestringError message.
    urlstringError additional URL.
    Response 404application/json
    1 fields

    Resource not found

    FieldTypeDescription
    messagestringError Message.
    Response 500application/json
    1 fields

    Internal server error

    FieldTypeDescription
    messagestringError message.
    DELETE /products/employment/report-templates/{template_name}

    Delete Report Template

    deleteReportTemplate

    Delete Report Template deletes a report template.

    Response
    application/json

    Request data failed validation

    {
      "message": "{'data': ['Missing data for required field.']}"
    }
    Parameters
    2
    ParameterTypeExampleDescription
    x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Environment API Key.
    template_name required string path demo_template Report Template Name
    Response 400application/json
    1 fields

    Request data failed validation

    FieldTypeDescription
    messagestringMessage
    Response 403application/json
    2 fields

    403 invalid error

    FieldTypeDescription
    messagestringError message.
    urlstringError additional URL.
    Response 404application/json
    1 fields

    Resource not found

    FieldTypeDescription
    messagestringError Message.
    Response 500application/json
    1 fields

    Internal server error

    FieldTypeDescription
    messagestringError message.
    Other responses

    204

    POST /products/employment/reports

    Generate Report

    generateTemplate

    Generate report for a product

    Request
    application/json
    {
      "product_name": "employment",
      "template_name": "voe_template",
      "transaction_id": "01FCWK741N7GWYBVG4Z3N74V16",
      "collection_id": "01FCWK741N7GWYBVG4Z3N74V16"
    }
    Response
    application/json

    Report successfully generated.

    {
      "product_name": "employment",
      "template_name": "voe_template",
      "transaction_id": "01FCWK741N7GWYBVG4Z3N74V16",
      "collection_id": "01FCWK741N7GWYBVG4Z3N74V16",
      "blob_id": "01EZYHKY4EXFW4Z8RKWHDP1KHB",
      "download_url": "https://dev-data-manager-blobs-bucket.s3.amazonaws.com/01EZY9J8SEFM2JKDJ1Q3YX65HS"
    }
    Parameters
    1
    ParameterTypeExampleDescription
    x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Environment API Key.
    Request bodyapplication/json
    4 fields
    FieldTypeDescription
    template_namerequiredstringName of template
    product_namestringProduct name
    transaction_idrequiredstringTransaction ID
    collection_idrequiredstringCollection ID
    Response 200application/json
    6 fields

    Report successfully generated.

    FieldTypeDescription
    template_namestringName of template
    product_namestringProduct name
    transaction_idstringTransaction ID
    collection_idstringCollection ID
    blob_idstringBlob ID of generated report
    download_urlstringPresigned URL to view/download generated report
    Response 400application/json
    1 fields

    Request data failed validation

    FieldTypeDescription
    messagestringMessage
    Response 403application/json
    2 fields

    403 invalid error

    FieldTypeDescription
    messagestringError message.
    urlstringError additional URL.
    Response 404application/json
    1 fields

    Resource not found

    FieldTypeDescription
    messagestringError Message.
    Response 500application/json
    1 fields

    Internal server error

    FieldTypeDescription
    messagestringError message.

    Product Specifications

    GET /products/employment/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.

    {
      "data": {
        "deal_sets": {
          "deal_set": [
            {
              "deals": {
                "deal": [
                  {
                    "parties": {
                      "party": [
                        {
                          "customer_transaction_ID": "e171ec31-75b4-4fd6-ada1-a0c48373c079",
                          "individual": {
                            "contact_points": {
                              "contact_point": [
                                {
                                  "contact_point_telephone": {
                                    "value": "+1234567890"
                                  },
                                  "contact_point_email": {
                                    "value": "test@test.com"
                                  }
                                }
                              ]
                            },
                            "name": {
                              "first": "John",
                              "last": "Jackson"
                            }
                          },
                          "roles": {
                            "role": [
                              {
                                "borrower": {
                                  "birth_date": "1984-01-01",
                                  "employers": {
                                    "employer": [
                                      {
                                        "legal_entity": {
                                          "full_name": "Amazon"
                                        }
                                      }
                                    ]
                                  },
                                  "residences": {
                                    "residence": [
                                      {
                                        "address": {
                                          "additional_line_text": "None",
                                          "city": "NEW YORK",
                                          "country": "US",
                                          "line_text": "33 IRVING PLACE",
                                          "postal_code": "10003",
                                          "state_code": "NY",
                                          "state": "NY"
                                        }
                                      }
                                    ]
                                  }
                                }
                              }
                            ]
                          },
                          "taxpayer_identifiers": {
                            "taxpayer_identifier": [
                              {
                                "value": "317210001"
                              }
                            ]
                          }
                        }
                      ]
                    }
                  }
                ]
              }
            }
          ]
        },
        "document_sets": {
          "document_set": [
            {
              "documents": {
                "document": [
                  {
                    "document_classification": {
                      "document_classes": {
                        "document_class": [
                          {
                            "staircase_type": "Staircase",
                            "type": "BorrowerApproval"
                          }
                        ]
                      }
                    },
                    "foreign_objects": {
                      "foreign_object": [
                        {
                          "description": "BorrowerApproval",
                          "mime_type_identifier": "application/pdf",
                          "name": "01F1Z5KG9E3CPD78P7GYB3TYC1.pdf",
                          "staircase_blob_id": "01F1Z5KG9E3CPD78P7GYB3TYC1"
                        }
                      ]
                    }
                  }
                ]
              }
            }
          ]
        }
      },
      "metadata": {}
    }
    Parameters
    2
    ParameterTypeExampleDescription
    x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Environment API Key.
    return_examples boolean query 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.

    FieldTypeDescription
    schemaobjectElement key / value
    Response 400application/json
    1 fields

    Error

    FieldTypeDescription
    messagestringMessage
    Response 403application/json
    2 fields

    403 invalid error

    FieldTypeDescription
    messagestringError message.
    urlstringError additional URL.
    Response 404application/json
    1 fields

    Resource not found

    FieldTypeDescription
    messagestringError Message.
    Response 500application/json
    1 fields

    Internal server error

    FieldTypeDescription
    messagestringError message.
    GET /products/employment/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.

    {
      "data": {
        "deal_sets": {
          "deal_set": [
            {
              "deals": {
                "deal": [
                  {
                    "parties": {
                      "party": [
                        {
                          "customer_transaction_ID": "e171ec31-75b4-4fd6-ada1-a0c48373c079",
                          "individual": {
                            "contact_points": {
                              "contact_point": [
                                {
                                  "contact_point_telephone": {
                                    "value": "+1234567890"
                                  },
                                  "contact_point_email": {
                                    "value": "test@test.com"
                                  }
                                }
                              ]
                            },
                            "name": {
                              "first": "John",
                              "last": "Jackson"
                            }
                          },
                          "roles": {
                            "role": [
                              {
                                "borrower": {
                                  "birth_date": "1984-01-01",
                                  "employers": {
                                    "employer": [
                                      {
                                        "legal_entity": {
                                          "full_name": "Amazon"
                                        }
                                      }
                                    ]
                                  },
                                  "residences": {
                                    "residence": [
                                      {
                                        "address": {
                                          "additional_line_text": "None",
                                          "city": "NEW YORK",
                                          "country": "US",
                                          "line_text": "33 IRVING PLACE",
                                          "postal_code": "10003",
                                          "state_code": "NY",
                                          "state": "NY"
                                        }
                                      }
                                    ]
                                  }
                                }
                              }
                            ]
                          },
                          "taxpayer_identifiers": {
                            "taxpayer_identifier": [
                              {
                                "value": "317210001"
                              }
                            ]
                          }
                        }
                      ]
                    }
                  }
                ]
              }
            }
          ]
        },
        "document_sets": {
          "document_set": [
            {
              "documents": {
                "document": [
                  {
                    "document_classification": {
                      "document_classes": {
                        "document_class": [
                          {
                            "staircase_type": "Staircase",
                            "type": "BorrowerApproval"
                          }
                        ]
                      }
                    },
                    "foreign_objects": {
                      "foreign_object": [
                        {
                          "description": "BorrowerApproval",
                          "mime_type_identifier": "application/pdf",
                          "name": "01F1Z5KG9E3CPD78P7GYB3TYC1.pdf",
                          "staircase_blob_id": "01F1Z5KG9E3CPD78P7GYB3TYC1"
                        }
                      ]
                    }
                  }
                ]
              }
            }
          ]
        }
      },
      "metadata": {}
    }
    Parameters
    2
    ParameterTypeExampleDescription
    x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Environment API Key.
    return_examples boolean query 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.

    FieldTypeDescription
    schemaobjectElement key / value element
    Response 400application/json
    1 fields

    Error

    FieldTypeDescription
    messagestringMessage
    Response 403application/json
    2 fields

    403 invalid error

    FieldTypeDescription
    messagestringError message.
    urlstringError additional URL.
    Response 404application/json
    1 fields

    Resource not found

    FieldTypeDescription
    messagestringError Message.
    Response 500application/json
    1 fields

    Internal server error

    FieldTypeDescription
    messagestringError message.
    GET /products/employment/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

    {
      "elements": [
        "$.deal_sets.deal_set[*].deals.deal[*].parties.party[*].customer_transaction_ID",
        "$.deal_sets.deal_set[*].deals.deal[*].parties.party[*].individual.contact_points.contact_point[*].contact_point_telephone.value",
        "$.deal_sets.deal_set[*].deals.deal[*].parties.party[*].individual.contact_points.contact_point[*].contact_point_email.value",
        "$.deal_sets.deal_set[*].deals.deal[*].parties.party[*].individual.name.first",
        "$.deal_sets.deal_set[*].deals.deal[*].parties.party[*].individual.name.last",
        "$.deal_sets.deal_set[*].deals.deal[*].parties.party[*].roles.role[*].borrower.birth_date",
        "$.deal_sets.deal_set[*].deals.deal[*].parties.party[*].roles.role[*].borrower.employers.employer[*].legal_entity.full_name",
        "$.deal_sets.deal_set[*].deals.deal[*].parties.party[*].roles.role[*].borrower.residences.residence[*].address.additional_line_text",
        "$.deal_sets.deal_set[*].deals.deal[*].parties.party[*].roles.role[*].borrower.residences.residence[*].address.city",
        "$.deal_sets.deal_set[*].deals.deal[*].parties.party[*].roles.role[*].borrower.residences.residence[*].address.country",
        "$.deal_sets.deal_set[*].deals.deal[*].parties.party[*].roles.role[*].borrower.residences.residence[*].address.line_text",
        "$.deal_sets.deal_set[*].deals.deal[*].parties.party[*].roles.role[*].borrower.residences.residence[*].address.postal_code",
        "$.deal_sets.deal_set[*].deals.deal[*].parties.party[*].roles.role[*].borrower.residences.residence[*].address.state_code",
        "$.deal_sets.deal_set[*].deals.deal[*].parties.party[*].roles.role[*].borrower.residences.residence[*].address.state",
        "$.deal_sets.deal_set[*].deals.deal[*].parties.party[*].taxpayer_identifiers.taxpayer_identifier[*].value",
        "$.document_sets.document_set[*].documents.document[*].document_classification.document_classes.document_class[*].staircase_type",
        "$.document_sets.document_set[*].documents.document[*].document_classification.document_classes.document_class[*].type",
        "$.document_sets.document_set[*].documents.document[*].foreign_objects.foreign_object[*].description",
        "$.document_sets.document_set[*].documents.document[*].foreign_objects.foreign_object[*].mime_type_identifier",
        "$.document_sets.document_set[*].documents.document[*].foreign_objects.foreign_object[*].name",
        "$.document_sets.document_set[*].documents.document[*].foreign_objects.foreign_object[*].staircase_blob_id"
      ]
    }
    Parameters
    1
    ParameterTypeExampleDescription
    x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Environment API Key.
    Response 200application/json
    1 fields

    Elements were retrieved successfully

    FieldTypeDescription
    elementsrequiredstring[]List of elements.
    Response 400application/json
    1 fields

    Validation Error

    FieldTypeDescription
    messagestringMessage
    Response 403application/json
    2 fields

    403 invalid error

    FieldTypeDescription
    messagestringError message.
    urlstringError additional URL.
    Response 404application/json
    1 fields

    Resource not found

    FieldTypeDescription
    messagestringError Message.
    Response 500application/json
    1 fields

    Internal server error

    FieldTypeDescription
    messagestringError message.
    GET /products/employment/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

    {
      "elements": [
        "$.deal_sets.deal_set[*].deals.deal[*].parties.party[*].individual.contact_points.contact_point[*].email",
        "$.deal_sets.deal_set[*].deals.deal[*].parties.party[*].individual.name.first",
        "$.deal_sets.deal_set[*].deals.deal[*].parties.party[*].individual.name.last",
        "$.deal_sets.deal_set[*].deals.deal[*].parties.party[*].roles.role[*].borrower.birth_date",
        "$.deal_sets.deal_set[*].deals.deal[*].parties.party[*].taxpayer_identifiers.taxpayer_identifier[*].value"
      ]
    }
    Parameters
    1
    ParameterTypeExampleDescription
    x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Environment API Key.
    Response 200application/json
    1 fields

    Elements were retrieved successfully

    FieldTypeDescription
    elementsrequiredstring[]List of elements.
    Response 400application/json
    1 fields

    Validation Error

    FieldTypeDescription
    messagestringMessage
    Response 403application/json
    2 fields

    403 invalid error

    FieldTypeDescription
    messagestringError message.
    urlstringError additional URL.
    Response 404application/json
    1 fields

    Resource not found

    FieldTypeDescription
    messagestringError Message.
    Response 500application/json
    1 fields

    Internal server error

    FieldTypeDescription
    messagestringError message.
    POST /products/employment/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.

    Request
    application/json
    {
      "data": {
        "deal_sets": {
          "deal_set": [
            {
              "deals": {
                "deal": [
                  {
                    "parties": {
                      "party": [
                        {
                          "customer_transaction_ID": "e171ec31-75b4-4fd6-ada1-a0c48373c079",
                          "individual": {
                            "contact_points": {
                              "contact_point": [
                                {
                                  "contact_point_telephone": {
                                    "value": "+1234567890"
                                  },
                                  "contact_point_email": {
                                    "value": "test@test.com"
                                  }
                                }
                              ]
                            },
                            "name": {
                              "first": "John",
                              "last": "Jackson"
                            }
                          },
                          "roles": {
                            "role": [
                              {
                                "borrower": {
                                  "birth_date": "1984-01-01",
                                  "employers": {
                                    "employer": [
                                      {
                                        "legal_entity": {
                                          "full_name": "Amazon"
                                        }
                                      }
                                    ]
                                  },
                                  "residences": {
                                    "residence": [
                                      {
                                        "address": {
                                          "additional_line_text": "None",
                                          "city": "NEW YORK",
                                          "country": "US",
                                          "line_text": "33 IRVING PLACE",
                                          "postal_code": "10003",
                                          "state_code": "NY",
                                          "state": "NY"
                                        }
                                      }
                                    ]
                                  }
                                }
                              }
                            ]
                          },
                          "taxpayer_identifiers": {
                            "taxpayer_identifier": [
                              {
                                "value": "317210001"
                              }
                            ]
                          }
                        }
                      ]
                    }
                  }
                ]
              }
            }
          ]
        },
        "document_sets": {
          "document_set": [
            {
              "documents": {
                "document": [
                  {
                    "document_classification": {
                      "document_classes": {
                        "document_class": [
                          {
                            "staircase_type": "Staircase",
                            "type": "BorrowerApproval"
                          }
                        ]
                      }
                    },
                    "foreign_objects": {
                      "foreign_object": [
                        {
                          "description": "BorrowerApproval",
                          "mime_type_identifier": "application/pdf",
                          "name": "01F1Z5KG9E3CPD78P7GYB3TYC1.pdf",
                          "staircase_blob_id": "01F1Z5KG9E3CPD78P7GYB3TYC1"
                        }
                      ]
                    }
                  }
                ]
              }
            }
          ]
        }
      },
      "metadata": {}
    }
    Response
    application/json

    Collection is valid

    {
      "message": "Collection is valid."
    }
    Parameters
    1
    ParameterTypeExampleDescription
    x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Environment API Key.
    Request bodyapplication/json
    1 fields
    FieldTypeDescription
    deal_setsobjectDeal sets object.
    deal_setobject[]Deal set object.
    dealsobjectDeals object.
    dealobject[]Deal array.
    Response 200application/json
    1 fields

    Collection is valid

    FieldTypeDescription
    messagestringMessage
    Response 400application/json
    1 fields

    Validation Error

    FieldTypeDescription
    messagestringMessage
    Response 403application/json
    2 fields

    403 invalid error

    FieldTypeDescription
    messagestringError message.
    urlstringError additional URL.
    Response 404application/json
    1 fields

    Resource not found

    FieldTypeDescription
    messagestringError Message.
    Response 500application/json
    1 fields

    Internal server error

    FieldTypeDescription
    messagestringError message.

    Product Waterfalls

    GET /products/employment/waterfall

    Retrieve Product Waterfall

    retrieveProductWaterfall

    Retrieve Product Waterfall retrieves a specific product waterfall.

    Response
    application/json

    Successfully returned the product waterfall.

    {
      "waterfall": [
        {
          "priority": 1,
          "flow_name": "VOE"
        }
      ]
    }
    Parameters
    1
    ParameterTypeExampleDescription
    x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Environment API Key.
    Response 200application/json
    1 fields

    Successfully returned the product waterfall.

    FieldTypeDescription
    waterfallrequiredobject[]Product waterfall steps.
    priorityrequiredintegerPriority of waterfall step.
    flow_namestringFlow name
    vendor_namestringVendor name
    Response 400application/json
    1 fields

    Request data failed validation

    FieldTypeDescription
    messagestringMessage
    Response 403application/json
    2 fields

    403 invalid error

    FieldTypeDescription
    messagestringError message.
    urlstringError additional URL.
    Response 404application/json
    1 fields

    Resource not found

    FieldTypeDescription
    messagestringError Message.
    Response 500application/json
    1 fields

    Internal server error

    FieldTypeDescription
    messagestringError message.
    PUT /products/employment/waterfall

    Create Product Waterfall

    addProductFlow

    Create Product waterfall

    Add custom settings for product waterfall

    Request
    application/json
    {
      "waterfall": [
        {
          "priority": 1,
          "flow_name": "VOE"
        }
      ]
    }
    Response
    application/json

    Product waterfall successfully added.

    {
      "waterfall": [
        {
          "priority": 1,
          "flow_name": "VOE"
        }
      ]
    }
    Parameters
    1
    ParameterTypeExampleDescription
    x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Environment API Key.
    Request bodyapplication/json
    1 fields
    FieldTypeDescription
    waterfallrequiredobject[]Product waterfall steps.
    priorityrequiredintegerPriority of waterfall step.
    flow_namestringFlow name
    vendor_namestringVendor name
    Response 200application/json
    1 fields

    Product waterfall successfully added.

    FieldTypeDescription
    waterfallrequiredobject[]Product waterfall steps.
    priorityrequiredintegerPriority of waterfall step.
    flow_namestringFlow name
    vendor_namestringVendor name
    Response 400application/json
    1 fields

    Request data failed validation

    FieldTypeDescription
    messagestringMessage
    Response 403application/json
    2 fields

    403 invalid error

    FieldTypeDescription
    messagestringError message.
    urlstringError additional URL.
    Response 404application/json
    1 fields

    Resource not found

    FieldTypeDescription
    messagestringError Message.
    Response 500application/json
    1 fields

    Internal server error

    FieldTypeDescription
    messagestringError message.
    DELETE /products/employment/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.']}"
    }
    Parameters
    1
    ParameterTypeExampleDescription
    x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Environment API Key.
    Response 400application/json
    1 fields

    Request data failed validation

    FieldTypeDescription
    messagestringMessage
    Response 403application/json
    2 fields

    403 invalid error

    FieldTypeDescription
    messagestringError message.
    urlstringError additional URL.
    Response 404application/json
    1 fields

    Resource not found

    FieldTypeDescription
    messagestringError Message.
    Response 500application/json
    1 fields

    Internal server error

    FieldTypeDescription
    messagestringError message.
    Other responses

    204

    POST /products/employment/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:

    {
    "type": "object",
    "$schema": "",
    "required": [
    "invocation_id",
    "invocation_status"
    ],
    "properties": {
    "invocation_id": {
    "type": "string",
    "format": "uuid"
    },
    "invocation_status": {
    "type": "string",
    "enum": [
    "COMPLETED",
    "FAILED"
    ]
    },
    "response_data": {
    "type": "object",
    "additionalProperties": true
    },
    "failure_reason": {
    "type": "string"
    }
    }
    }
    
    Request
    application/json
    {
      "transaction_id": "01F6NAMXWN2XVBD1YJ92A6S6R4",
      "request_collection_id": "01F6QF1QJF20DMSXH4SYXKB1SN",
      "callback_url": "https://webhook.site/3706b519-9426-4533-9868-14a7dec4fd97"
    }
    Response
    application/json

    Successfully started flow invocation.

    {
      "invocation_id": "68a4aa6a-bf18-4f7d-be7d-bc26503adeb1",
      "invocation_status": "STARTED",
      "transaction_id": "01FCWK741N7GWYBVG4Z3N74V16",
      "request_data": {
        "foo": "bar",
        "biz": "baz"
      },
      "callback_url": "https://webhook.site/68a4aa6a-bf18-4f7d-be7d-bc26503adeb2",
      "tags": [
        "manual verification"
      ]
    }
    Parameters
    1
    ParameterTypeExampleDescription
    x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Environment API Key.
    Request bodyapplication/json
    6 fields
    FieldTypeDescription
    transaction_idstringTransaction ID used for flow_invocations.
    request_collection_idstringRequest Collection ID.
    callback_urlstring (uri)Callback URL.
    request_dataobjectRequest JSON body for product flows.
    tagsstring[]Flow tags.
    optionsobjectAdditional 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.

    FieldTypeDescription
    invocation_idrequiredstringInvocation ID.
    invocation_statusrequiredstringThe status of the invocation.STARTED
    transaction_idstringTransaction ID.
    callback_urlstringCallback URL.
    request_dataobjectThe data for the request collection.
    request_collection_idstringRequest Collection ID.
    tagsstring[]Flow tags.
    optionsobjectAdditional information that should be passed to the connector but not be added to the request collection. Will be passed to every product flow invocation.
    connector_job_idstringConnector job ID.
    Response 400application/json
    1 fields

    Request data failed validation

    FieldTypeDescription
    messagestringMessage
    Response 403application/json
    2 fields

    403 invalid error

    FieldTypeDescription
    messagestringError message.
    urlstringError additional URL.
    Response 404application/json
    1 fields

    Resource not found

    FieldTypeDescription
    messagestringMessage
    Response 500application/json
    1 fields

    Internal server error

    FieldTypeDescription
    messagestringError message.
    GET /products/employment/waterfall/invocations/{invocation_id}

    Retrieve Product Waterfall Invocation Status

    RetrieveProductWaterfallInvocationStatus

    Retrieves the status of running Product waterfall invocation.

    Response
    application/json

    Successfully returned status of the Product Waterfall Invocation.

    {
      "invocation_id": "fbc19f9b-1d37-4ced-9f1d-d2769b018b0a",
      "invocation_status": "COMPLETED",
      "request_collection_id": "01FCWK741N7GWYBVG4Z3N74V16",
      "callback_url": "https://webhook.site/68a4aa6a-bf18-4f7d-be7d-bc26503adeb2",
      "transaction_id": "01FCWK72GC1MFM5003SXJHMWNG",
      "request_collection": {
        "data": {
          "foo": "bar",
          "biz": "baz"
        },
        "metadata": {
          "created_at": "2021-08-12T03:11:25.749933-04:00",
          "validation": false
        },
        "transaction_id": "01FCWK72GC1MFM5003SXJHMWNG",
        "collection_id": "01FCWK741N7GWYBVG4Z3N74V16"
      },
      "flows_responses": {
        "flow1": {
          "response_collection_id": "01FCWSAQD3QDKEW91K7CPXN4Y2",
          "invocation_id": "7a8980a1-73ac-4313-ada5-e0e976c38ebb",
          "invocation_status": "FAILED",
          "transaction_id": "01FCWSAH1RVMC0DH6GRQ9JSAE7",
          "product_flow_name": "demo_product_flow_422",
          "failure_reason": "Service Connector failed. Connector flow failed. Response payload: {'Error': 'CallVendorError', 'Cause': {'errorMessage': '', 'errorType': 'CallVendorError'}}",
          "response_collection": {
            "collection_id": "01FCWSAQD3QDKEW91K7CPXN4Y2",
            "data": {},
            "transaction_id": "01FCWSAH1RVMC0DH6GRQ9JSAE7",
            "metadata": {
              "created_at": "2021-08-12T04:58:15.331517-04:00",
              "validation": false
            }
          }
        },
        "flow2": {
          "response_collection_id": "01FCWSMVWW7192SZXR9MP52B4A",
          "invocation_id": "c861def5-5e5d-4690-9313-2f25427029a8",
          "invocation_status": "COMPLETED",
          "transaction_id": "01FCWSMNZM271WVQY6FDS2CB6M",
          "product_flow_name": "demo_product_flow",
          "response_collection": {
            "data": {},
            "collection_id": "01FCWSMVWW7192SZXR9MP52B4A",
            "transaction_id": "01FCWSMNZM271WVQY6FDS2CB6M",
            "metadata": {
              "created_at": "2021-08-12T05:03:47.612771-04:00",
              "validation": false
            }
          }
        }
      }
    }
    Parameters
    2
    ParameterTypeExampleDescription
    x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Environment API Key.
    invocation_id required 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.

    FieldTypeDescription
    invocation_idrequiredstringInvocation ID.
    invocation_statusrequiredstringThe status of the invocation.ACTION_REQUIREDCOMPLETEDFAILEDRUNNINGSTARTED
    transaction_idrequiredstringTransaction ID.
    callback_urlstringCallback URL.
    request_dataobjectThe data for the request collection.
    request_collection_idstringRequest Collection ID.
    request_collectionobjectRequest Collection.
    tagsstring[]Flow tags.
    optionsobjectOptions that were passed to the waterfall invocation.
    flows_responsesrequiredobjectResponses for each flow invocation.
    metadatarequiredobjectMetadata of waterfall.
    actual_flow_namestringActual flow name invoked.
    Response 400application/json
    1 fields

    Request data failed validation

    FieldTypeDescription
    messagestringMessage
    Response 403application/json
    2 fields

    403 invalid error

    FieldTypeDescription
    messagestringError message.
    urlstringError additional URL.
    Response 404application/json
    1 fields

    Resource not found

    FieldTypeDescription
    messagestringMessage
    Response 500application/json
    1 fields

    Internal server error

    FieldTypeDescription
    messagestringError message.

    Platform

    GET /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

    {
      "elements": [
        "$.deal_sets.deal_set[*].deals.deal[*].parties.party[*].individual.contact_points.contact_point[*].email",
        "$.deal_sets.deal_set[*].deals.deal[*].parties.party[*].individual.name.first",
        "$.deal_sets.deal_set[*].deals.deal[*].parties.party[*].individual.name.last",
        "$.deal_sets.deal_set[*].deals.deal[*].parties.party[*].roles.role[*].borrower.birth_date",
        "$.deal_sets.deal_set[*].deals.deal[*].parties.party[*].taxpayer_identifiers.taxpayer_identifier[*].value"
      ]
    }
    Parameters
    1
    ParameterTypeExampleDescription
    x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Environment API Key.
    Response 200application/json
    1 fields

    Elements were retrieved successfully

    FieldTypeDescription
    elementsrequiredstring[]List of elements.
    Response 400application/json
    1 fields

    Validation Error

    FieldTypeDescription
    messageone ofMessage
    Response 403application/json
    2 fields

    403 invalid error

    FieldTypeDescription
    messagestringError message.
    urlstringError additional URL.
    Response 404application/json
    1 fields

    Resource not found

    FieldTypeDescription
    messagestringError Message.
    Response 500application/json
    1 fields

    Internal server error

    FieldTypeDescription
    messagestringError message.
    GET /schema/{data_object}

    Retrieve Example Schema

    retrieveSchema

    Retrieve Schema retrieves a JSON schema for the request and the response returned by the product. It can also return an example of a json object defined with schema.

    Testing Employment:

    If you want an example collection:

    • To path parameter data_object add request
    • In the query parameters set return_examples to true

    You can directly pass an example returned by the /schema endpoint into the Create Collection endpoint as a request body.

    Response
    application/json

    Successfully returned the list of elements needed for Employment.

    {
      "deal_sets": {
        "deal_set": [
          {
            "deals": {
              "deal": [
                {
                  "parties": {
                    "party": [
                      {
                        "customer_transaction_id": "e171ec31-75b4-4fd6-ada1-nesto",
                        "individual": {
                          "name": {
                            "first": "Jane",
                            "last": "Consumer"
                          },
                          "contact_points": {
                            "contact_point": [
                              {
                                "contact_point_telephone": {
                                  "value": "+1234567890"
                                }
                              },
                              {
                                "contact_point_email": {
                                  "value": "test@test.com"
                                }
                              }
                            ]
                          }
                        },
                        "roles": {
                          "role": [
                            {
                              "borrower": {
                                "birth_date": "1984-01-01T00:00:00.000Z",
                                "employers": {
                                  "employer": [
                                    {
                                      "legal_entity": {
                                        "full_name": "Uber"
                                      }
                                    }
                                  ]
                                },
                                "residences": {
                                  "residence": [
                                    {
                                      "address": {
                                        "additional_line_text": "None",
                                        "city": "NEW YORK",
                                        "country": "US",
                                        "line_text": "33 IRVING PLACE",
                                        "postal_code": "10003",
                                        "state_code": "NY"
                                      }
                                    }
                                  ]
                                }
                              }
                            }
                          ]
                        },
                        "taxpayer_identifiers": {
                          "taxpayer_identifier": [
                            {
                              "value": "000000001"
                            }
                          ]
                        }
                      }
                    ]
                  }
                },
                {
                  "loans": {
                    "loan": {
                      "loan_identifiers": {
                        "loan_identifier": [
                          {
                            "identifier": "6f039329-3fd6-44c1-a460-9af546e798de"
                          }
                        ]
                      }
                    }
                  }
                }
              ]
            }
          }
        ]
      },
      "document_sets": {
        "document_set": [
          {
            "documents": {
              "document": [
                {
                  "document_classification": {
                    "document_classes": {
                      "document_class": [
                        {
                          "staircase_type": "Staircase",
                          "type": "BorrowerApproval"
                        }
                      ]
                    }
                  },
                  "foreign_objects": {
                    "foreign_object": [
                      {
                        "description": "BorrowerApproval",
                        "mime_type_identifier": "application/pdf",
                        "name": "01F1Z5KG9E3CPD78P7GYB3TYC1.pdf",
                        "staircase_blob_id": "01F1Z5KG9E3CPD78P7GYB3TYC1"
                      }
                    ]
                  }
                }
              ]
            }
          }
        ]
      }
    }
    Parameters
    4
    ParameterTypeExampleDescription
    x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Staircase Environment API Key
    data_object required string path request Describes the particular data object you are getting a schema for.
    version string query v0 Defines the version of the Staircase language you want the JSON to return in.
    return_examples boolean query false If included and set to `true`, returns one or more pre-filled examples that conform to the schema.
    Other responses

    200400403

    GET /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.

    {
      "data": {},
      "metadata": {}
    }
    Parameters
    2
    ParameterTypeExampleDescription
    x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Environment API Key.
    return_examples boolean query 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.

    FieldTypeDescription
    schemaobjectElement key / value
    Response 400application/json
    1 fields

    Error

    FieldTypeDescription
    messagestringMessage
    Response 403application/json
    2 fields

    403 invalid error

    FieldTypeDescription
    messagestringError message.
    urlstringError additional URL.
    Response 404application/json
    1 fields

    Resource not found

    FieldTypeDescription
    messagestringError Message.
    Response 500application/json
    1 fields

    Internal server error

    FieldTypeDescription
    messagestringError message.
    GET /company/{company_name}

    Search Company

    searchCompany

    Search Company verifies a company's existence by querying all partners and returns the name of the partner that can provide employment verification for that company.

    Please check list of active partners in your environment with Retrieve Partners.

    Response
    application/json

    Company found

    {
      "Partner 1": [
        "The Home Depot"
      ],
      "Partner 2": [
        "The Home Depot"
      ],
      "Partner 3": [
        "Home Depot"
      ],
      "Partner 4": [
        "Home depot"
      ],
      "Partner 5": [
        "Home Depot 401k"
      ]
    }
    Parameters
    4
    ParameterTypeExampleDescription
    x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Staircase Environment API Key
    company_name required string path Uber, Amazon Use Employer name (Company name) to check coverage.
    exclude_borrower boolean query false The exclude_borrower option enables you to filter partners that require borrower interaction during verification process.When exclude_borrower=true, **Search Company** excludes partners that need borrower authorization in order to successfully finish the verification process.
    manual_verification boolean query true The manual_verification option enables you to filter partners that perform manual employment verifications. When manual_verification=false, **Search Company** excludes, from the search response, all partners that perform manual VOE. This limits the coverage response for partners performing VOE, and also reduces the time it takes to complete a VOE.
    Response 200application/json
    5 fields

    Company found

    FieldTypeDescription
    Partner 1string[]
    Partner 2string[]
    Partner 3string[]
    Partner 4string[]
    Partner 5string[]
    Response 403application/json
    2 fields

    Invalid key for service

    FieldTypeDescription
    messagestring
    urlstring
    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.

    FieldTypeDescription
    messagestring
    Other responses

    400404

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

    Update Collection

    updateCollection

    Update Collection allows you to update the content of a given collection_id associated with a transaction_id.

    Request
    application/json
    {
      "deal_sets": {
        "deal_set": [
          {
            "deals": {
              "deal": [
                {
                  "parties": {
                    "party": [
                      {
                        "customer_transaction_id": "e171ec31-75b4-4fd6-ada1-nesto",
                        "individual": {
                          "name": {
                            "first": "Jane",
                            "last": "Consumer"
                          },
                          "contact_points": {
                            "contact_point": [
                              {
                                "contact_point_telephone": {
                                  "value": "+1234567890"
                                }
                              },
                              {
                                "contact_point_email": {
                                  "value": "test@test.com"
                                }
                              }
                            ]
                          }
                        },
                        "roles": {
                          "role": [
                            {
                              "borrower": {
                                "birth_date": "1984-01-01T00:00:00.000Z",
                                "employers": {
                                  "employer": [
                                    {
                                      "legal_entity": {
                                        "full_name": "Uber"
                                      }
                                    }
                                  ]
                                },
                                "residences": {
                                  "residence": [
                                    {
                                      "address": {
                                        "additional_line_text": "None",
                                        "city": "NEW YORK",
                                        "country": "US",
                                        "line_text": "33 IRVING PLACE",
                                        "postal_code": "10003",
                                        "state_code": "NY"
                                      }
                                    }
                                  ]
                                }
                              }
                            }
                          ]
                        },
                        "taxpayer_identifiers": {
                          "taxpayer_identifier": [
                            {
                              "value": "000000001"
                            }
                          ]
                        }
                      }
                    ]
                  }
                },
                {
                  "loans": {
                    "loan": {
                      "loan_identifiers": {
                        "loan_identifier": [
                          {
                            "identifier": "6f039329-3fd6-44c1-a460-9af546e798de"
                          }
                        ]
                      }
                    }
                  }
                }
              ]
            }
          }
        ]
      },
      "document_sets": {
        "document_set": [
          {
            "documents": {
              "document": [
                {
                  "document_classification": {
                    "document_classes": {
                      "document_class": [
                        {
                          "staircase_type": "Staircase",
                          "type": "BorrowerApproval"
                        }
                      ]
                    }
                  },
                  "foreign_objects": {
                    "foreign_object": [
                      {
                        "description": "BorrowerApproval",
                        "mime_type_identifier": "application/pdf",
                        "name": "01F1Z5KG9E3CPD78P7GYB3TYC1.pdf",
                        "staircase_blob_id": "01F1Z5KG9E3CPD78P7GYB3TYC1"
                      }
                    ]
                  }
                }
              ]
            }
          }
        ]
      }
    }
    Response
    application/json

    Collection updated successfully

    {
      "data": {
        "deal_sets": {
          "deal_set": [
            {
              "deals": {
                "deal": [
                  {
                    "parties": {
                      "party": [
                        {
                          "individual": {
                            "name": {
                              "first": "Jane",
                              "last": "Consumer"
                            }
                          },
                          "taxpayer_identifiers": {
                            "taxpayer_identifier": [
                              {
                                "value": 123456789
                              }
                            ]
                          }
                        }
                      ]
                    },
                    "loans": {
                      "loan": [
                        {
                          "loan_identifiers": {
                            "loan_identifier": [
                              {
                                "identifier": "6f039329-3fd6-44c1-a460-9af546e798de"
                              }
                            ]
                          }
                        }
                      ]
                    }
                  }
                ]
              }
            }
          ]
        }
      },
      "metadata": {
        "validation": false,
        "created_at": "03/04/2021, 1:18:35 PM EST"
      },
      "collection_id": "01F0KHKADN0HRFXMCQQXPA6AFZ",
      "transaction_id": "01F0KHK7DN3H5JZ4QJKMYAM6GB"
    }
    Parameters
    3
    ParameterTypeExampleDescription
    x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Staircase Environment API Key
    transaction_id required string (ulid) path 01F0KHK7DN3H5JZ4QJKMYAM6GB Staircase Transaction Identifier
    collection_id required string (ulid) path 01F0KHKADN0HRFXMCQQXPA6AFZ Staircase collection_id
    Response 200application/json
    4 fields

    Collection updated successfully

    FieldTypeDescription
    dataobject
    deal_setsrequiredobject
    deal_setrequiredobject[]
    dealsrequiredobject
    document_setsobject
    document_setobject[]
    documentsobject
    metadataobjectThe metadata object describes properties that a Staircase collection has
    created_atstringISO 8601 format with EST timezoneExample 03/03/2021, 8:24:04 AM EST
    updated_atstringISO 8601 format with EST timezoneExample 03/03/2021, 8:24:04 AM EST
    validationbooleanDescribes whether the collection has been validated against Staircase language schemaExample false
    partner_namestringStaircase partner name that was used to generate the collection
    exclude_borrowerbooleanSome of our partners include borrowers in the loop while executing the verification. Employment is verified by requesting information from borrower. If you want to exclude the borrower from the process, you must select *exclude_borrower* = *true* in options.
    manual_verificationbooleanThis option allows us to add partners that perform manual verification to your search list while finding the most suitable partner for you. This option takes a longer time and gives you a broader search.
    send_smsbooleanThis option allows us to send SMS to the borrower when an authorization for the verification is needed. The SMS text is "Lender has provided verification link to your E-mail address, please open link in browser, and finish verify process"
    verification_statestringDescribes the state of the operation that generated the collectionCANCELLEDCOMPLETEDFAILEDIN_PROGRESSTIME_OUT
    resultsobjectContains the results of an operation that generated the collection
    statusstringDescribes the state of the operation that generated the collectionCOMPLETEDERRORREQUEST_MADETIMED_OUTExample COMPLETED
    productstringName of the Staircase product that generated the collectionExample Employments
    infostringAdditional info about the status
    transaction_idstring (ulid)Staircase Transaction IdentifierExample 01F0KHK7DN3H5JZ4QJKMYAM6GB
    collection_idstring (ulid)Staircase Collection IdentifierExample 01F0KHKADN0HRFXMCQQXPA6AFZ
    Response 400application/json
    1 fields

    Error

    FieldTypeDescription
    messageone of
    Response 403application/json
    2 fields

    Invalid key for service

    FieldTypeDescription
    messagestring
    urlstring
    Response 404application/json
    1 fields

    Resource not found

    FieldTypeDescription
    messagestringMessage
    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.

    FieldTypeDescription
    messagestring
    POST /request-elements/complete

    Validate Collection

    validateCollection

    Validate Collection verifies that a collection contains all the elements needed to invoke a partner for employment verification.

    Request
    application/json
    {
      "deal_sets": {
        "deal_set": [
          {
            "deals": {
              "deal": [
                {
                  "parties": {
                    "party": [
                      {
                        "customer_transaction_id": "e171ec31-75b4-4fd6-ada1-nesto",
                        "individual": {
                          "name": {
                            "first": "Jane",
                            "last": "Consumer"
                          },
                          "contact_points": {
                            "contact_point": [
                              {
                                "contact_point_telephone": {
                                  "value": "+1234567890"
                                }
                              },
                              {
                                "contact_point_email": {
                                  "value": "test@test.com"
                                }
                              }
                            ]
                          }
                        },
                        "roles": {
                          "role": [
                            {
                              "borrower": {
                                "birth_date": "1984-01-01T00:00:00.000Z",
                                "employers": {
                                  "employer": [
                                    {
                                      "legal_entity": {
                                        "full_name": "Uber"
                                      }
                                    }
                                  ]
                                },
                                "residences": {
                                  "residence": [
                                    {
                                      "address": {
                                        "additional_line_text": "None",
                                        "city": "NEW YORK",
                                        "country": "US",
                                        "line_text": "33 IRVING PLACE",
                                        "postal_code": "10003",
                                        "state_code": "NY"
                                      }
                                    }
                                  ]
                                }
                              }
                            }
                          ]
                        },
                        "taxpayer_identifiers": {
                          "taxpayer_identifier": [
                            {
                              "value": "000000001"
                            }
                          ]
                        }
                      }
                    ]
                  }
                },
                {
                  "loans": {
                    "loan": {
                      "loan_identifiers": {
                        "loan_identifier": [
                          {
                            "identifier": "6f039329-3fd6-44c1-a460-9af546e798de"
                          }
                        ]
                      }
                    }
                  }
                }
              ]
            }
          }
        ]
      },
      "document_sets": {
        "document_set": [
          {
            "documents": {
              "document": [
                {
                  "document_classification": {
                    "document_classes": {
                      "document_class": [
                        {
                          "staircase_type": "Staircase",
                          "type": "BorrowerApproval"
                        }
                      ]
                    }
                  },
                  "foreign_objects": {
                    "foreign_object": [
                      {
                        "description": "BorrowerApproval",
                        "mime_type_identifier": "application/pdf",
                        "name": "01F1Z5KG9E3CPD78P7GYB3TYC1.pdf",
                        "staircase_blob_id": "01F1Z5KG9E3CPD78P7GYB3TYC1"
                      }
                    ]
                  }
                }
              ]
            }
          }
        ]
      }
    }
    Response
    application/json

    Collection is valid

    {
      "message": "Collection is valid."
    }
    Parameters
    1
    ParameterTypeExampleDescription
    x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Staircase Environment API Key
    Request bodyapplication/json
    2 fields
    FieldTypeDescription
    deal_setsrequiredobject
    deal_setrequiredobject[]
    dealsrequiredobject
    dealrequiredobject[]
    document_setsobject
    document_setobject[]
    documentsobject
    documentobject[]
    Response 200application/json
    1 fields

    Collection is valid

    FieldTypeDescription
    messagestringMessage
    Response 403application/json
    2 fields

    Invalid key for service

    FieldTypeDescription
    messagestring
    urlstring
    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.

    FieldTypeDescription
    messagestring
    Other responses

    400

    GET /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.

    {
      "data": {},
      "metadata": {}
    }
    Parameters
    2
    ParameterTypeExampleDescription
    x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Environment API Key.
    return_examples boolean query 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.

    FieldTypeDescription
    schemaobjectElement key / value element
    Response 400application/json
    1 fields

    Error

    FieldTypeDescription
    messagestringMessage
    Response 403application/json
    2 fields

    403 invalid error

    FieldTypeDescription
    messagestringError message.
    urlstringError additional URL.
    Response 404application/json
    1 fields

    Resource not found

    FieldTypeDescription
    messagestringError Message.
    Response 500application/json
    1 fields

    Internal server error

    FieldTypeDescription
    messagestringError message.

    Workflow

    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

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

    Transaction created successfully

    {
      "transaction_id": "01F0KHK7DN3H5JZ4QJKMYAM6GB",
      "created_at": "03/04/2021, 1:04:05 PM EST"
    }
    Parameters
    1
    ParameterTypeExampleDescription
    x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Environment API Key.
    Request bodyapplication/json
    2 fields
    FieldTypeDescription
    callback_urlstring (url)URL for receiving events about changes inside transaction
    labelstringTransaction label
    Response 201application/json
    2 fields

    Transaction created successfully

    FieldTypeDescription
    transaction_idstring (ulid)Staircase Transaction IdentifierExample 01F0KHK7DN3H5JZ4QJKMYAM6GB
    created_atstringStaircase time string.Example 03/03/2021, 8:24:04 AM EST
    Response 403application/json
    2 fields

    403 invalid error

    FieldTypeDescription
    messagestringError message.
    urlstringError additional URL.
    Response 500application/json
    1 fields

    Internal server error

    FieldTypeDescription
    messagestringError message.
    Other responses

    400

    GET /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

    {
      "elements": [
        "$.deal_sets.deal_set[*].deals.deal[*].parties.party[*].customer_transaction_ID",
        "$.deal_sets.deal_set[*].deals.deal[*].parties.party[*].individual.contact_points.contact_point[*].contact_point_telephone.value",
        "$.deal_sets.deal_set[*].deals.deal[*].parties.party[*].individual.contact_points.contact_point[*].contact_point_email.value",
        "$.deal_sets.deal_set[*].deals.deal[*].parties.party[*].individual.name.first",
        "$.deal_sets.deal_set[*].deals.deal[*].parties.party[*].individual.name.last",
        "$.deal_sets.deal_set[*].deals.deal[*].parties.party[*].roles.role[*].borrower.birth_date",
        "$.deal_sets.deal_set[*].deals.deal[*].parties.party[*].roles.role[*].borrower.employers.employer[*].legal_entity.full_name",
        "$.deal_sets.deal_set[*].deals.deal[*].parties.party[*].roles.role[*].borrower.residences.residence[*].address.additional_line_text",
        "$.deal_sets.deal_set[*].deals.deal[*].parties.party[*].roles.role[*].borrower.residences.residence[*].address.city",
        "$.deal_sets.deal_set[*].deals.deal[*].parties.party[*].roles.role[*].borrower.residences.residence[*].address.country",
        "$.deal_sets.deal_set[*].deals.deal[*].parties.party[*].roles.role[*].borrower.residences.residence[*].address.line_text",
        "$.deal_sets.deal_set[*].deals.deal[*].parties.party[*].roles.role[*].borrower.residences.residence[*].address.postal_code",
        "$.deal_sets.deal_set[*].deals.deal[*].parties.party[*].roles.role[*].borrower.residences.residence[*].address.state_code",
        "$.deal_sets.deal_set[*].deals.deal[*].parties.party[*].roles.role[*].borrower.residences.residence[*].address.state",
        "$.deal_sets.deal_set[*].deals.deal[*].parties.party[*].taxpayer_identifiers.taxpayer_identifier[*].value",
        "$.document_sets.document_set[*].documents.document[*].document_classification.document_classes.document_class[*].staircase_type",
        "$.document_sets.document_set[*].documents.document[*].document_classification.document_classes.document_class[*].type",
        "$.document_sets.document_set[*].documents.document[*].foreign_objects.foreign_object[*].description",
        "$.document_sets.document_set[*].documents.document[*].foreign_objects.foreign_object[*].mime_type_identifier",
        "$.document_sets.document_set[*].documents.document[*].foreign_objects.foreign_object[*].name",
        "$.document_sets.document_set[*].documents.document[*].foreign_objects.foreign_object[*].staircase_blob_id"
      ]
    }
    Parameters
    1
    ParameterTypeExampleDescription
    x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Environment API Key.
    Response 200application/json
    1 fields

    Elements were retrieved successfully

    FieldTypeDescription
    elementsrequiredstring[]List of elements.
    Response 400application/json
    1 fields

    Validation Error

    FieldTypeDescription
    messageone ofMessage
    Response 403application/json
    2 fields

    403 invalid error

    FieldTypeDescription
    messagestringError message.
    urlstringError additional URL.
    Response 404application/json
    1 fields

    Resource not found

    FieldTypeDescription
    messagestringError Message.
    Response 500application/json
    1 fields

    Internal server error

    FieldTypeDescription
    messagestringError message.
    POST /build-payload

    Build JSON Payload

    buildPayload

    Build JSON Payload retrieves a JSON schema for either:

    • a request for employment verification, or
    • a response containing employment verification details. To retrieve the employment verification request schema:
    1. Invoke Retrieve Request Elements to get an array of employment verification request elements.
    2. Place the output from Retrieve Request Elements into the Build JSON Payload request body.
    3. Place your api_key into the Build JSON Payload header.
    4. Send the request to Build JSON Payload. You will receive a JSON schema in response, with null values that must be replaced with your own. To retrieve theShow the rest
    employment verification response schema:
  • Invoke Retrieve Response Elements to get an array of employment verification response elements.
  • Place the output from Retrieve Response Elements into the Build JSON Payload request body.
  • Place your api_key into the Build JSON Payload header.
  • Send the request to Build JSON Payload. You will receive a JSON schema in response, with null values that will be replaced by the partner upon return of employment verification details.
  • Request
    application/json
    {
      "$.data.deal_sets.deal_set[0].deals.deal[0].parties.party[0].customer_transaction_id": null,
      "$.data.deal_sets.deal_set[0].deals.deal[0].parties.party[0].individual.name.first": null,
      "$.data.deal_sets.deal_set[0].deals.deal[0].parties.party[0].individual.name.last": null,
      "$.data.deal_sets.deal_set[0].deals.deal[0].parties.party[0].individual.contact_points.contact_point[0].contact_point_email.value": null,
      "$.data.deal_sets.deal_set[0].deals.deal[0].parties.party[0].individual.contact_points.contact_point[0].contact_point_telephone.value": null,
      "$.data.deal_sets.deal_set[0].deals.deal[0].parties.party[0].roles.role[0].borrower.birth_date": null,
      "$.data.deal_sets.deal_set[0].deals.deal[0].parties.party[0].roles.role[0].borrower.employers.employer[0].legal_entity.full_name": null,
      "$.data.deal_sets.deal_set[0].deals.deal[0].parties.party[0].roles.role[0].borrower.residences.residence[0].address.country": null,
      "$.data.deal_sets.deal_set[0].deals.deal[0].parties.party[0].roles.role[0].borrower.residences.residence[0].address.city": null,
      "$.data.deal_sets.deal_set[0].deals.deal[0].parties.party[0].roles.role[0].borrower.residences.residence[0].address.state_code": null,
      "$.data.deal_sets.deal_set[0].deals.deal[0].parties.party[0].roles.role[0].borrower.residences.residence[0].address.postal_code": null,
      "$.data.deal_sets.deal_set[0].deals.deal[0].parties.party[0].roles.role[0].borrower.residences.residence[0].address.line_text": null,
      "$.data.deal_sets.deal_set[0].deals.deal[0].parties.party[0].roles.role[0].borrower.residences.residence[0].address.additional_line_text": null,
      "$.data.deal_sets.deal_set[0].deals.deal[0].parties.party[0].taxpayer_identifiers.taxpayer_identifier[0].value": null,
      "$.data.document_sets.document_set[0].documents.document[0].document_classification.document_classes.document_class[0].staircase_type": null,
      "$.data.document_sets.document_set[0].documents.document[0].document_classification.document_classes.document_class[0].type": null,
      "$.data.document_sets.document_set[0].documents.document[0].foreign_objects.foreign_object[0].description": null,
      "$.data.document_sets.document_set[0].documents.document[0].foreign_objects.foreign_object[0].mime_type_identifier": null,
      "$.data.document_sets.document_set[0].documents.document[0].foreign_objects.foreign_object[0].name": null,
      "$.data.document_sets.document_set[0].documents.document[0].foreign_objects.foreign_object[0].staircase_blob_id": null
    }
    Response
    application/json

    Employment Verification Payload.

    {
      "deal_sets": {
        "deal_set": [
          {
            "deals": {
              "deal": [
                {
                  "parties": {
                    "party": [
                      {
                        "customer_transaction_id": "e171ec31-75b4-4fd6-ada1-nesto",
                        "individual": {
                          "name": {
                            "first": "Jane",
                            "last": "Consumer"
                          },
                          "contact_points": {
                            "contact_point": [
                              {
                                "contact_point_telephone": {
                                  "value": "+1234567890"
                                }
                              },
                              {
                                "contact_point_email": {
                                  "value": "test@test.com"
                                }
                              }
                            ]
                          }
                        },
                        "roles": {
                          "role": [
                            {
                              "borrower": {
                                "birth_date": "1984-01-01T00:00:00.000Z",
                                "employers": {
                                  "employer": [
                                    {
                                      "legal_entity": {
                                        "full_name": "Uber"
                                      }
                                    }
                                  ]
                                },
                                "residences": {
                                  "residence": [
                                    {
                                      "address": {
                                        "additional_line_text": "None",
                                        "city": "NEW YORK",
                                        "country": "US",
                                        "line_text": "33 IRVING PLACE",
                                        "postal_code": "10003",
                                        "state_code": "NY"
                                      }
                                    }
                                  ]
                                }
                              }
                            }
                          ]
                        },
                        "taxpayer_identifiers": {
                          "taxpayer_identifier": [
                            {
                              "value": "000000001"
                            }
                          ]
                        }
                      }
                    ]
                  }
                },
                {
                  "loans": {
                    "loan": {
                      "loan_identifiers": {
                        "loan_identifier": [
                          {
                            "identifier": "6f039329-3fd6-44c1-a460-9af546e798de"
                          }
                        ]
                      }
                    }
                  }
                }
              ]
            }
          }
        ]
      },
      "document_sets": {
        "document_set": [
          {
            "documents": {
              "document": [
                {
                  "document_classification": {
                    "document_classes": {
                      "document_class": [
                        {
                          "staircase_type": "Staircase",
                          "type": "BorrowerApproval"
                        }
                      ]
                    }
                  },
                  "foreign_objects": {
                    "foreign_object": [
                      {
                        "description": "BorrowerApproval",
                        "mime_type_identifier": "application/pdf",
                        "name": "01F1Z5KG9E3CPD78P7GYB3TYC1.pdf",
                        "staircase_blob_id": "01F1Z5KG9E3CPD78P7GYB3TYC1"
                      }
                    ]
                  }
                }
              ]
            }
          }
        ]
      }
    }
    Parameters
    1
    ParameterTypeExampleDescription
    x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Staircase Environment API Key
    Request bodyapplication/json
    2 fields
    FieldTypeDescription
    pathstringContains the path in Staircase language
    valuestringEnter your own values here
    Response 200application/json
    2 fields

    Employment Verification Payload.

    FieldTypeDescription
    deal_setsobject
    deal_setobject[]
    dealsobject
    dealobject[]
    document_setsobject
    document_setobject[]
    documentsobject
    documentobject[]
    Response 400application/json
    1 fields

    Request data failed validation

    FieldTypeDescription
    messagestringMessage
    Response 403application/json
    2 fields

    Invalid key for service

    FieldTypeDescription
    messagestring
    urlstring
    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.

    FieldTypeDescription
    messagestring
    POST /approval

    Upload Approval Document

    uploadBlob

    Upload Approval Document allows a Lender to upload a Borrower-signed approval document in .pdf form, to increase the employment verification success rate.

    Upload Approval Document uploads a .pdf document (blob) to Persistence.

    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 signed approval document. Click Send to upload your document.

    Show the rest

    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.

    $.document_sets.document_set[0].documents.document[0].foreign_objects.foreign_object[0].staircase_blob_id
    

    To upload a document within code, you can to use a below example.

    import requests
    url = ""
    payload = open("borrower_approval_document.pdf", "rb")
    headers = {
     'x-api-key': 'API_KEY',
     'Content-Type': 'application/pdf'
    }
    response = requests.request("POST", url, headers=headers, data=payload)
    print(response.text)
    
    Request
    application/octet-stream
    Select option 'binary' in order to upload file
    Response
    application/json

    Blob uploaded

    {
      "blob_id": "01EZY9J8SEFM2JKDJ1Q3YX65HS"
    }
    Parameters
    1
    ParameterTypeExampleDescription
    x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Environment API Key.
    Response 201application/json
    1 fields

    Blob uploaded

    FieldTypeDescription
    blob_idstringCreated blob ID
    Response 403application/json
    2 fields

    403 invalid error

    FieldTypeDescription
    messagestringError message.
    urlstringError additional URL.
    Response 500application/json
    1 fields

    Internal server error

    FieldTypeDescription
    messagestringError message.
    Other responses

    400405422

    POST /transactions/{transaction_id}/collections

    Create Collection

    createCollection

    Create Collection creates a collection of elements required for employment verification. A collection contains a digital representation of employment verification and is identified by collection_id. A collection_id is passed to the partner when requesting employment verification. To create an employment verification collection:

    1. Create a Transaction and receive a transaction_id in the response.
    2. Create the request collection adding the borrowers details to it:
    • Copy one of the example schemas given below for the request body, and replace the example values in schema with your values.
    • Invoke Retrieve Example JSON to get an example schema or an example collection (change the values with your own).
    1. Pass the transaction_id as a path parameter, and place the collection with your values in the request body.
    2. The endpoint returns a collection_id representing the collection you just created associated with the transaction_id that was passed in the path parameter.

    Once you have created a collection, you can send it, along with your api_key and transaction_id, to any of the employment verification partners as many times as you want.

    Show the rest
    Request
    application/json
    {
      "data": {
        "deal_sets": {
          "deal_set": [
            {
              "deals": {
                "deal": [
                  {
                    "parties": {
                      "party": [
                        {
                          "customer_transaction_id": "e171ec31-75b4-4fd6-ada1",
                          "individual": {
                            "name": {
                              "first": "Jane",
                              "last": "Consumer"
                            },
                            "contact_points": {
                              "contact_point": [
                                {
                                  "contact_point_telephone": {
                                    "value": "+1234567890"
                                  }
                                },
                                {
                                  "contact_point_email": {
                                    "value": "test@test.com"
                                  }
                                }
                              ]
                            }
                          },
                          "roles": {
                            "role": [
                              {
                                "borrower": {
                                  "birth_date": "1984-01-01T00:00:00.000Z",
                                  "employers": {
                                    "employer": [
                                      {
                                        "legal_entity": {
                                          "full_name": "Uber"
                                        }
                                      }
                                    ]
                                  },
                                  "residences": {
                                    "residence": [
                                      {
                                        "address": {
                                          "additional_line_text": "None",
                                          "city": "NEW YORK",
                                          "country": "US",
                                          "line_text": "33 IRVING PLACE",
                                          "postal_code": "10003",
                                          "state_code": "NY"
                                        }
                                      }
                                    ]
                                  }
                                }
                              }
                            ]
                          },
                          "taxpayer_identifiers": {
                            "taxpayer_identifier": [
                              {
                                "value": "000000001"
                              }
                            ]
                          }
                        }
                      ]
                    }
                  },
                  {
                    "loans": {
                      "loan": {
                        "loan_identifiers": {
                          "loan_identifier": [
                            {
                              "identifier": "6f039329-3fd6-44c1-a460-9af546e798de"
                            }
                          ]
                        }
                      }
                    }
                  }
                ]
              }
            }
          ],
          "document_sets": {
            "document_set": [
              {
                "documents": {
                  "document": [
                    {
                      "document_classification": {
                        "document_classes": {
                          "document_class": [
                            {
                              "staircase_type": "Staircase",
                              "type": "BorrowerApproval"
                            }
                          ]
                        }
                      },
                      "foreign_objects": {
                        "foreign_object": [
                          {
                            "description": "BorrowerApproval",
                            "mime_type_identifier": "application/pdf",
                            "name": "01F1Z5KG9E3CPD78P7GYB3TYC1.pdf",
                            "staircase_blob_id": "01F1Z5KG9E3CPD78P7GYB3TYC1"
                          }
                        ]
                      }
                    }
                  ]
                }
              }
            ]
          }
        }
      }
    }
    Response
    application/json

    Collection created successfully

    {
      "deal_sets": {
        "deal_set": [
          {
            "deals": {
              "deal": [
                {
                  "parties": {
                    "party": [
                      {
                        "customer_transaction_id": "e171ec31-75b4-4fd6-ada1-nesto",
                        "individual": {
                          "name": {
                            "first": "Jane",
                            "last": "Consumer"
                          },
                          "contact_points": {
                            "contact_point": [
                              {
                                "contact_point_telephone": {
                                  "value": "+1234567890"
                                }
                              },
                              {
                                "contact_point_email": {
                                  "value": "test@test.com"
                                }
                              }
                            ]
                          }
                        },
                        "roles": {
                          "role": [
                            {
                              "borrower": {
                                "birth_date": "1984-01-01T00:00:00.000Z",
                                "employers": {
                                  "employer": [
                                    {
                                      "legal_entity": {
                                        "full_name": "Uber"
                                      }
                                    }
                                  ]
                                },
                                "residences": {
                                  "residence": [
                                    {
                                      "address": {
                                        "additional_line_text": "None",
                                        "city": "NEW YORK",
                                        "country": "US",
                                        "line_text": "33 IRVING PLACE",
                                        "postal_code": "10003",
                                        "state_code": "NY"
                                      }
                                    }
                                  ]
                                }
                              }
                            }
                          ]
                        },
                        "taxpayer_identifiers": {
                          "taxpayer_identifier": [
                            {
                              "value": "000000001"
                            }
                          ]
                        }
                      }
                    ]
                  }
                },
                {
                  "loans": {
                    "loan": {
                      "loan_identifiers": {
                        "loan_identifier": [
                          {
                            "identifier": "6f039329-3fd6-44c1-a460-9af546e798de"
                          }
                        ]
                      }
                    }
                  }
                }
              ]
            }
          }
        ]
      },
      "document_sets": {
        "document_set": [
          {
            "documents": {
              "document": [
                {
                  "document_classification": {
                    "document_classes": {
                      "document_class": [
                        {
                          "staircase_type": "Staircase",
                          "type": "BorrowerApproval"
                        }
                      ]
                    }
                  },
                  "foreign_objects": {
                    "foreign_object": [
                      {
                        "description": "BorrowerApproval",
                        "mime_type_identifier": "application/pdf",
                        "name": "01F1Z5KG9E3CPD78P7GYB3TYC1.pdf",
                        "staircase_blob_id": "01F1Z5KG9E3CPD78P7GYB3TYC1"
                      }
                    ]
                  }
                }
              ]
            }
          }
        ]
      }
    }
    Parameters
    2
    ParameterTypeExampleDescription
    x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Staircase Environment API Key
    transaction_id required string (ulid) path 01F0KHK7DN3H5JZ4QJKMYAM6GB Staircase Transaction Identifier
    Response 201application/json
    4 fields

    Collection created successfully

    FieldTypeDescription
    dataobject
    deal_setsrequiredobject
    deal_setrequiredobject[]
    dealsrequiredobject
    document_setsobject
    document_setobject[]
    documentsobject
    metadataobjectThe metadata object describes properties that a Staircase collection has
    created_atstringISO 8601 format with EST timezoneExample 03/03/2021, 8:24:04 AM EST
    updated_atstringISO 8601 format with EST timezoneExample 03/03/2021, 8:24:04 AM EST
    validationbooleanDescribes whether the collection has been validated against Staircase language schemaExample false
    partner_namestringStaircase partner name that was used to generate the collection
    exclude_borrowerbooleanSome of our partners include borrowers in the loop while executing the verification. Employment is verified by requesting information from borrower. If you want to exclude the borrower from the process, you must select *exclude_borrower* = *true* in options.
    manual_verificationbooleanThis option allows us to add partners that perform manual verification to your search list while finding the most suitable partner for you. This option takes a longer time and gives you a broader search.
    send_smsbooleanThis option allows us to send SMS to the borrower when an authorization for the verification is needed. The SMS text is "Lender has provided verification link to your E-mail address, please open link in browser, and finish verify process"
    verification_statestringDescribes the state of the operation that generated the collectionCANCELLEDCOMPLETEDFAILEDIN_PROGRESSTIME_OUT
    resultsobjectContains the results of an operation that generated the collection
    statusstringDescribes the state of the operation that generated the collectionCOMPLETEDERRORREQUEST_MADETIMED_OUTExample COMPLETED
    productstringName of the Staircase product that generated the collectionExample Employments
    infostringAdditional info about the status
    transaction_idstring (ulid)Staircase Transaction IdentifierExample 01F0KHK7DN3H5JZ4QJKMYAM6GB
    collection_idstring (ulid)Staircase Collection IdentifierExample 01F0KHKADN0HRFXMCQQXPA6AFZ
    Response 400application/json
    1 fields

    Error

    FieldTypeDescription
    messageone of
    Response 403application/json
    2 fields

    Invalid key for service

    FieldTypeDescription
    messagestring
    urlstring
    Response 404application/json
    1 fields

    Resource not found

    FieldTypeDescription
    messagestringMessage
    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.

    FieldTypeDescription
    messagestring
    POST /

    Verify Employment

    invokeProductFlow

    Verify Employment creates an employment verification request for the provided transaction, collection and selected partner. To create an employment verification request:

    1. Make sure you have an api_key, received via email when you signed up for Staircase.
    2. Create a Transaction and receive a transaction_id in the response.
    3. Create a Collection and receive a collection_id in the response.
    4. Place the api_key in the request header, and place the transaction_id, collection_id and partner_name in the request body. Choose verification options and add them to the request body.
    5. Call Verify Employment and receive the response.
    6. If the response contains status with value ACTION_NEEDED, it will also contain a url which represents the link by which the borrower can authorize the verification. The url should be sent to the borrower for authorization.
    7. Check the status of the verification by calling Retrieve Status.
    8. After the response from Retrieve Status contains the status COMPLETED, retrieve the output collection by calling Retrieve Collection.
    9. The output collection contains blob_id with which you can retrieve the generated report.

    Verification options

    Manual Verification parameter

    Show the rest

    The manual_verification option enables you to add or remove partners that perform manual employment verifications. When manual_verification=false, Employment will exclude all partners performing manual VOE. This limits the search for partners performing VOE, and also reduces the time it takes to complete a VOE.

    Exclude Borrower parameter

    The exclude_borrower option enables you to remove the borrower from the VOE loop. When exclude_borrower=false, the borrower will be asked to provide credentials needed for employment verification prior to the partner performing the VOE. This increases borrower interaction, and also increases the chance that the VOE will be successfully completed. The borrower needs to authorize the verification by clicking on the url (link) that is provided in the verification response and entering a payroll provider or bank credentials. Test credentials for partners that offer the "borrower in the loop" option can be found in Retrieve Partners.

    Partner name parameter

    The partner_name option enables you to select preferred partner, or you can use "default" as value. If you use partner_name=default, Employment will find the best match and use that partner for the verification process. If you want to use a specific partner, call Retrieve Partners to determine what employment verification partners are available.

    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 *voe_email_template*, if you wish to update the template please refer to the Update Email Template documentation. Please note that the template takes in two passed variables, which are the applet URL and employer name, and those are required variables and should not be altered, for more info check the Email Product section.

    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 employment verification. If left empty or no options parameter is passed, this URL defaults to the Staircase homepage.

    Test scenarios

    To execute test scenarios please use 000000001 as your taxpayer identifier in the input collection. To variate between different data partners please change the legal entity full name field in the input collection to the one of the following values:

    1. "Fox Subacute" for Argyle data partner
    2. "Uber" for Atomic data partner
    3. "Amazon" for Equifax and Meridian data partners (if "waterfall" feature is enabled, partner is selected based on the partner ordering)
    4. "Fair port Little League Inc." for Pinwheel data partner
    5. "True work - DEMO" for True work and True work Instant data partners (if "waterfall" feature is enabled, partner is selected based on the partner ordering)

    To use "waterfall" feature set the partner name to "default". This way verification will be executed following the ordering (can be set previously) for all available data partners. For example if two data partners share the same legal entity full name verification will be done based on the ordering of data partners.

    Verify Employment returns, as a synchronous acknowledgement, a new collection_id. The new collection_id represents an empty container which will hold the partner's response once processing has completed. Call Retrieve Collection with the transaction_id and new collection_id to retrieve the verification result.

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

    Successfully started flow invocation.

    {
      "invocation_id": "9aefb465-90fb-4d50-8ae6-2df2b58373f4",
      "invocation_status": "STARTED",
      "product_flow_name": "VOE",
      "transaction_id": "01F6NAMXWN2XVBD1YJ92A6S6R4",
      "request_collection_id": "01F6NAQ4894HPMCBGB4P0G95XK",
      "response_collection_id": "01F6NAQ4894HPMCBGB4P0G78HG",
      "options": {
        "dry_run": false
      },
      "tags": [
        "manual verification"
      ]
    }
    Parameters
    1
    ParameterTypeExampleDescription
    x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Environment API Key.
    Request bodyapplication/json
    10 fields
    FieldTypeDescription
    product_flow_namestringProduct 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_namestringVendor name. Cannot be specified together with product_flow_name.
    transaction_idstringTransaction ID used for invocation.
    request_collection_idstringRequest Collection ID.
    response_collection_idstringResponse Collection ID.
    callback_urlstring (uri)Callback URL.
    request_dataobjectRequest JSON body.
    tagsstring[]List of tags.
    optionsobjectAdditional information that should be passed to the connector but not be added to the request collection.
    invocation_modestringThe invocation mode of a product flow single_flow or waterfall, default value single_flow
    Response 201application/json
    11 fields

    Successfully started flow invocation.

    FieldTypeDescription
    invocation_idrequiredstringInvocation ID.
    invocation_statusrequiredstringThe status of the invocation.STARTED
    transaction_idrequiredstringTransaction ID.
    reuest_collection_idrequiredstringRequest collection ID.
    response_collection_idrequiredstringResponse collection ID.
    product_flow_namestringProduct flow name.
    metadataobjectThe metadata of the invoked product flow.
    callback_urlstringCallback URL.
    request_dataobjectThe data for the request collection.
    tagsstring[]List of tags.
    optionsobjectAdditional information that should be passed to the connector but not be added to the request collection.
    Response 400application/json
    1 fields

    Request data failed validation

    FieldTypeDescription
    messageone ofMessage
    Response 403application/json
    2 fields

    403 invalid error

    FieldTypeDescription
    messagestringError message.
    urlstringError additional URL.
    Response 404application/json
    1 fields

    Resource not found

    FieldTypeDescription
    messagestringMessage
    Response 500application/json
    1 fields

    Internal server error

    FieldTypeDescription
    messagestringError message.
    POST /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.

    Request
    application/json
    {
      "data": {},
      "metadata": {}
    }
    Response
    application/json

    Collection is valid

    {
      "message": "Collection is valid."
    }
    Parameters
    1
    ParameterTypeExampleDescription
    x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Environment API Key.
    Request bodyapplication/json
    1 fields
    FieldTypeDescription
    deal_setsobjectDeal sets object.
    deal_setobject[]Deal set object.
    dealsobjectDeals object.
    dealobject[]Deal array.
    Response 200application/json
    1 fields

    Collection is valid

    FieldTypeDescription
    messagestringMessage
    Response 400application/json
    1 fields

    Validation Error

    FieldTypeDescription
    messageone ofMessage
    Response 403application/json
    2 fields

    403 invalid error

    FieldTypeDescription
    messagestringError message.
    urlstringError additional URL.
    Response 404application/json
    1 fields

    Resource not found

    FieldTypeDescription
    messagestringError Message.
    Response 500application/json
    1 fields

    Internal server error

    FieldTypeDescription
    messagestringError message.
    POST /cancel-verification

    Cancel Employment Verification

    cancelVerification

    Cancel Employment Verification invokes a partner to cancel an employment verification that has already started. This feature is currently available using the partner Truework.

    Request
    application/json
    {
      "transaction_id": "42u3784-324123-41234-21234",
      "collection_id": "42u3784-324123-41234-21234"
    }
    Response
    application/json

    Cancel employment verification triggered

    {
      "message": "Cancel employment verification request is succesfully taken"
    }
    Parameters
    1
    ParameterTypeExampleDescription
    x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Staircase Environment API Key
    Request bodyapplication/json
    2 fields
    FieldTypeDescription
    transaction_idrequiredstring (ulid)Staircase Transaction IdentifierExample 01F0KHK7DN3H5JZ4QJKMYAM6GB
    collection_idrequiredstring (ulid)Staircase Collection IdentifierExample 01F0KHKADN0HRFXMCQQXPA6AFZ
    Response 200application/json
    1 fields

    Cancel employment verification triggered

    FieldTypeDescription
    messagestringExample Cancel employment verification request is successfully taken
    Response 403application/json
    2 fields

    Invalid key for service

    FieldTypeDescription
    messagestring
    urlstring
    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.

    FieldTypeDescription
    messagestring
    Response 502application/json
    1 fields

    Bad gateway.

    FieldTypeDescription
    messagestringError Message.
    Other responses

    400404

    GET /status/{transaction_id}/{collection_id}

    Retrieve Status

    RetrieveStatus

    'Retrieve Status determines if a partner has completed employment verification.'

    Status Descriptions:

    • REQUEST_MADE: Indicates that execution is started
    • WAITING_FOR_RESPONSE: Indicates that execution is being processed
    • COMPLETED: Indicates execution has been successfully finished, and response collection can be retrieved
    • TIME_OUT: Indicates execution has timed out.
    • CANCELLED: Indicates execution has cancelled
    • FAILED: Indicates execution has failed
    Response
    application/json

    Successfully returned status of the Product Waterfall Invocation.

    {
      "status": "SUCCEEDED",
      "message": "Invocation completed successfully",
      "created_at": "2022-01-22T04:54:13.507355-05:00",
      "invocation_status": "COMPLETED",
      "last_updated_at": "2022-01-22T04:55:31.399320-05:00",
      "partner_language": "test-convert-v2-output_language",
      "service_invocation": {
        "Connector": {
          "connector_flow_name": "test-convert_flow",
          "debug_config": {
            "dry_run": true
          },
          "status": "COMPLETED",
          "invocation_id": "08589dde-d0ab-48d2-8912-6060f7413c52"
        },
        "Translator": {
          "output": {
            "status": "COMPLETED",
            "invocation_id": "f70d76d8-c57f-42c5-8685-ea64fcc64d16",
            "language_name": "staircase"
          },
          "input": {
            "status": "COMPLETED",
            "invocation_id": "b38f8b65-e5de-4acd-b2f3-7a372f922fc2",
            "language_name": "test-convert-v2-input_language"
          },
          "convert_output": {
            "status": "COMPLETED",
            "invocation_id": "f70d76d8-c57f-42c5-8685-ea64fcc64d16",
            "language_name": "staircase"
          },
          "convert_input": {
            "status": "COMPLETED",
            "invocation_id": "850d7d39-b90d-4ee5-a903-b3ad6d06ec4a",
            "language_name": "staircase"
          }
        }
      },
      "staircase_language_version": 2,
      "staircase_output_version": 0,
      "validation": false,
      "version": 2
    }
    Parameters
    3
    ParameterTypeExampleDescription
    x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Environment API Key.
    transaction_id required string (ulid) path 01F0KHK7DN3H5JZ4QJKMYAM6GB Staircase Transaction Identifier
    collection_id required string (ulid) path 01F0KHKADN0HRFXMCQQXPA6AFZ Staircase collection_id
    Response 200application/json
    6 fields

    Successfully returned status of the Product Waterfall Invocation.

    FieldTypeDescription
    statusstringMapped status of the invocation.Example STARTED
    messagestringMessage.Example Verification is completed, please check response collection to see verification data.
    created_atstringTime of creation
    invocation_statusstringStatus of the product invocation before mapping
    last_updated_atstringLast time the collection was updated
    service_invocationobjectIncludes underlying services invocation.
    ConnectorobjectResponse from Connector service.
    connector_flow_namestringVendor flow name.
    invocation_idstring (uuid)Connector job ID.
    statusstringConnector flow status.ACTION_REQUIREDCOMPLETEDFAILEDRUNNING
    TranslatorobjectResponse from Translator service about input and output translation.
    inputobjectInput translation status.
    language_namestringInput translation language.
    translation_idstring (uuid)Translation ID.
    statusstringInput translation status.COMPLETEDFAILEDRUNNING
    convert_inputobjectConvert input translation status.
    language_namestringInput translation language.
    translation_idstring (uuid)Translation ID.
    statusstringInput translation status.COMPLETEDFAILEDRUNNING
    outputobjectOutput translation status.
    language_namestringOutput translation language.
    translation_idstring (uuid)Translation ID.
    statusstringOutput translation status.COMPLETEFAILEDRUNNING
    convert_outputobjectConvert output translation status.
    language_namestringOutput translation language.
    translation_idstring (uuid)Translation ID.
    statusstringOutput translation status.COMPLETEFAILEDRUNNING
    Response 400application/json
    1 fields

    Request data failed validation

    FieldTypeDescription
    messageone ofMessage
    Response 403application/json
    2 fields

    403 invalid error

    FieldTypeDescription
    messagestringError message.
    urlstringError additional URL.
    Response 404application/json
    1 fields

    Resource not found

    FieldTypeDescription
    messagestringMessage
    Response 500application/json
    1 fields

    Internal server error

    FieldTypeDescription
    messagestringError message.
    GET //report/{blob_id}

    Retrieve Report

    retrievePresignedUrls

    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

    Presigned URLs retrieved successfully.

    {
      "upload": {
        "url": "https://dev-data-manager-blobs-bucket.s3.amazonaws.com/01EZY9J8SEFM2JKDJ1Q3YX65HS"
      }
    }
    Parameters
    2
    ParameterTypeExampleDescription
    x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Environment API Key.
    blob_id required string path 01EZY9J8SEFM2JKDJ1Q3YX65HS Blob identifier
    Response 200application/json
    1 fields

    Presigned URLs retrieved successfully.

    FieldTypeDescription
    presigned_urlsobjectPresigned URLs
    Response 403application/json
    2 fields

    403 invalid error

    FieldTypeDescription
    messagestringError message.
    urlstringError additional URL.
    Other responses

    400404

    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"
    }
    Parameters
    2
    ParameterTypeExampleDescription
    x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Staircase Environment API Key
    blob_id required string path 01FVFBXHVD5WT2MJAGG96CPBJD Blob ID for report that needs to retrieved.
    Response 200application/json
    1 fields

    Report URL retrieved successfully

    FieldTypeDescription
    urlstringReport URL
    Response 400application/json
    1 fields

    Bad Request

    FieldTypeDescription
    messagestringPartner not found
    Response 403application/json
    2 fields

    Invalid key for service

    FieldTypeDescription
    messagestring
    urlstring
    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.

    FieldTypeDescription
    messagestring

    Proxying

    GET /transactions/{transaction_id}/collections

    Retrieve Transaction Collections

    RetrieveTransactionCollections

    Retrieve Transaction Collections returns the content of a given collection_id associated with a specific transaction_id.

    Response
    application/json

    Transaction collection retrieved successfully

    [
      {
        "data": {
          "deal_sets": {
            "deal_set": [
              {
                "deals": {
                  "deal": [
                    {
                      "parties": {
                        "party": [
                          {
                            "customer_transaction_ID": "e171ec31-75b4-4fd6-ada1-a0c48373c079",
                            "individual": {
                              "contact_points": {
                                "contact_point": [
                                  {
                                    "contact_point_telephone": {
                                      "value": "+1234567890"
                                    },
                                    "contact_point_email": {
                                      "value": "test@test.com"
                                    }
                                  }
                                ]
                              },
                              "name": {
                                "first": "John",
                                "last": "Jackson"
                              }
                            },
                            "roles": {
                              "role": [
                                {
                                  "borrower": {
                                    "birth_date": "1984-01-01",
                                    "employers": {
                                      "employer": [
                                        {
                                          "legal_entity": {
                                            "full_name": "Amazon"
                                          }
                                        }
                                      ]
                                    },
                                    "residences": {
                                      "residence": [
                                        {
                                          "address": {
                                            "additional_line_text": "None",
                                            "city": "NEW YORK",
                                            "country": "US",
                                            "line_text": "33 IRVING PLACE",
                                            "postal_code": "10003",
                                            "state_code": "NY",
                                            "state": "NY"
                                          }
                                        }
                                      ]
                                    }
                                  }
                                }
                              ]
                            },
                            "taxpayer_identifiers": {
                              "taxpayer_identifier": [
                                {
                                  "value": "317210001"
                                }
                              ]
                            }
                          }
                        ]
                      }
                    }
                  ]
                }
              }
            ]
          },
          "document_sets": {
            "document_set": [
              {
                "documents": {
                  "document": [
                    {
                      "document_classification": {
                        "document_classes": {
                          "document_class": [
                            {
                              "staircase_type": "Staircase",
                              "type": "BorrowerApproval"
                            }
                          ]
                        }
                      },
                      "foreign_objects": {
                        "foreign_object": [
                          {
                            "description": "BorrowerApproval",
                            "mime_type_identifier": "application/pdf",
                            "name": "01F1Z5KG9E3CPD78P7GYB3TYC1.pdf",
                            "staircase_blob_id": "01F1Z5KG9E3CPD78P7GYB3TYC1"
                          }
                        ]
                      }
                    }
                  ]
                }
              }
            ]
          }
        },
        "metadata": {}
      },
      {
        "data": {
          "deal_sets": {
            "deal_set": [
              {
                "deals": {
                  "deal": [
                    {
                      "parties": {
                        "party": [
                          {
                            "roles": {
                              "role": [
                                {
                                  "borrower": {
                                    "employers": {
                                      "employer": [
                                        {
                                          "employment": {
                                            "end_date": "2020-09-10",
                                            "position_description": "Developer",
                                            "start_date": "2016-09-10",
                                            "status_type": "Current"
                                          },
                                          "legal_entity": {
                                            "full_name": "Amazing Community Pharmacy LLC"
                                          }
                                        }
                                      ]
                                    }
                                  }
                                }
                              ]
                            },
                            "taxpayer_identifiers": {
                              "taxpayer_identifier": [
                                {
                                  "value": "317210001"
                                }
                              ]
                            }
                          }
                        ]
                      },
                      "services": {
                        "service": [
                          {
                            "verification_of_employment": {
                              "verification_of_employment_response": {
                                "partner": "Wage",
                                "partner_data_source_date": "2021-07-19"
                              }
                            }
                          }
                        ]
                      }
                    }
                  ]
                }
              }
            ]
          }
        },
        "metadata": {}
      }
    ]
    Parameters
    2
    ParameterTypeExampleDescription
    x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Environment API Key.
    transaction_id required string (ulid) path 01F0KHK7DN3H5JZ4QJKMYAM6GB Staircase Transaction Identifier
    Response 200application/json
    4 fields

    Transaction collection retrieved successfully

    FieldTypeDescription
    transaction_idstring (ulid)Transaction idExample 01EZQ32PJQGKRA6HR8D72Q9FFF
    collection_idstring (ulid)Collection idExample 01EZQ32PJQGKRA6HR8D72Q9FFF
    dataarray
    metadataobjectMetadata about collection, f.e version of used Staircase schema
    Response 400application/json
    1 fields

    Error

    FieldTypeDescription
    messageone ofEither message object with more properties.
    Response 403application/json
    2 fields

    403 invalid error

    FieldTypeDescription
    messagestringError message.
    urlstringError additional URL.
    Response 404application/json
    1 fields

    Resource not found

    FieldTypeDescription
    messagestringMessage
    Response 500application/json
    1 fields

    Internal server error

    FieldTypeDescription
    messagestringError message.
    GET /transactions/{transaction_id}/collections/{collection_id}

    Retrieve Collection

    retrieveCollection

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

    Response
    application/json

    Successfully Retrieved Collection

    {
      "data": {
        "deal_sets": {
          "deal_set": [
            {
              "deals": {
                "deal": [
                  {
                    "parties": {
                      "party": [
                        {
                          "customer_transaction_ID": "e171ec31-75b4-4fd6-ada1-a0c48373c079",
                          "individual": {
                            "contact_points": {
                              "contact_point": [
                                {
                                  "contact_point_telephone": {
                                    "value": "+1234567890"
                                  },
                                  "contact_point_email": {
                                    "value": "test@test.com"
                                  }
                                }
                              ]
                            },
                            "name": {
                              "first": "John",
                              "last": "Jackson"
                            }
                          },
                          "roles": {
                            "role": [
                              {
                                "borrower": {
                                  "birth_date": "1984-01-01",
                                  "employers": {
                                    "employer": [
                                      {
                                        "legal_entity": {
                                          "full_name": "Amazon"
                                        }
                                      }
                                    ]
                                  },
                                  "residences": {
                                    "residence": [
                                      {
                                        "address": {
                                          "additional_line_text": "None",
                                          "city": "NEW YORK",
                                          "country": "US",
                                          "line_text": "33 IRVING PLACE",
                                          "postal_code": "10003",
                                          "state_code": "NY",
                                          "state": "NY"
                                        }
                                      }
                                    ]
                                  }
                                }
                              }
                            ]
                          },
                          "taxpayer_identifiers": {
                            "taxpayer_identifier": [
                              {
                                "value": "317210001"
                              }
                            ]
                          }
                        }
                      ]
                    }
                  }
                ]
              }
            }
          ]
        },
        "document_sets": {
          "document_set": [
            {
              "documents": {
                "document": [
                  {
                    "document_classification": {
                      "document_classes": {
                        "document_class": [
                          {
                            "staircase_type": "Staircase",
                            "type": "BorrowerApproval"
                          }
                        ]
                      }
                    },
                    "foreign_objects": {
                      "foreign_object": [
                        {
                          "description": "BorrowerApproval",
                          "mime_type_identifier": "application/pdf",
                          "name": "01F1Z5KG9E3CPD78P7GYB3TYC1.pdf",
                          "staircase_blob_id": "01F1Z5KG9E3CPD78P7GYB3TYC1"
                        }
                      ]
                    }
                  }
                ]
              }
            }
          ]
        }
      },
      "metadata": {}
    }
    Parameters
    3
    ParameterTypeExampleDescription
    x-api-key required string header xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Environment API Key.
    transaction_id required string (ulid) path 01F0KHK7DN3H5JZ4QJKMYAM6GB Staircase Transaction Identifier
    collection_id required string (ulid) path 01F0KHKADN0HRFXMCQQXPA6AFZ Staircase collection_id
    Response 200application/json
    2 fields

    Successfully Retrieved Collection

    FieldTypeDescription
    dataobject
    deal_setsobject
    deal_setobject[]
    dealsobject
    document_setsobject
    document_setobject[]
    documentsobject
    metadata
    Response 403application/json
    2 fields

    403 invalid error

    FieldTypeDescription
    messagestringError message.
    urlstringError additional URL.
    Response 404application/json
    1 fields

    Resource not found

    FieldTypeDescription
    messagestringMessage
    Response 500application/json
    1 fields

    Internal server error

    FieldTypeDescription
    messagestringError message.
    Other responses

    400

    Operations

    POST /employment/webhook

    Webhook to accept callback from TrueWork

    Response 200application/json
    1 fields

    200 response

    FieldTypeDescription
    valuesobject
    codenumber
    payloadobject
    Other responses

    403

    POST /extractor/webhook

    Webhook to accept callback from Ocrolus

    Response 200application/json
    1 fields

    200 response

    FieldTypeDescription
    valuesobject
    codenumber
    payloadobject
    Other responses

    403

    Providers

    The order below is the committed sequence. The roster underneath it is every vendor with integration evidence for this product, which is the larger set: a vendor can be integrated and absent from the committed ordering.

    1. MeridianLink
    2. Argyle
    3. Atomic
    4. Wage
    5. Finicity
    6. Experian
    7. Pinwheel
    8. Citadel
    9. Equifax
    10. Truework
    11. Truework

    Also integrated for this product, outside the committed ordering:

    Field mapping

    ProviderFlowCanonical inVendor inVendor outCanonical out
    Argyle income staircase-graph income-input income-argyle-output staircase-graph

    Errors

    400403404405422500502

    Type to search.