# Employment # 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 Copy ``` { "partner": "partner_name", "environment": "my-domain.staircaseapi.com" } ``` ##### Response 200400403422500 application/json Copy 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." } ``` application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy Invalid key for service ``` { "message": "Please check the key you used to call this service", "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` application/json Copy Request data failed validation ``` { "message": "Invalid request body", "error": "[object has missing required properties ([\"client_secret\"])]" } ``` application/json Copy The product has encountered an internal server error ``` { "message": "The product has encountered an internal server error" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Staircase Environment API Key | ##### Request body`application/json` 2 fields | Field | Type | Description | | --- | --- | --- | | `partner`required | `string` | Partner name that needs to be activated | | `environment`required | `string` | Environment for which the partner needs to be activated. | ##### Response `200``application/json` 1 fields Request to Activate API Triggered Successfully | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `403``application/json` 2 fields Invalid key for service | Field | Type | Description | | --- | --- | --- | | `message` | `string` | — | | `url` | `string` | — | ##### Response `422``application/json` 2 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | | `error` | `string` | Message | ##### Response `500``application/json` 1 fields The product has encountered an internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error 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 Copy ``` { "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 200400403422500 application/json Copy Request to Partner Widget Token API Triggered Successfully ``` { "widget_token": "" } ``` application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy Invalid key for service ``` { "message": "Please check the key you used to call this service", "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` application/json Copy Request data failed validation ``` { "message": "Invalid request body", "error": "[object has missing required properties ([\"client_secret\"])]" } ``` application/json Copy The product has encountered an internal server error ``` { "message": "The product has encountered an internal server error" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Staircase Environment API Key | ##### Request body`application/json` 3 fields | Field | Type | Description | | --- | --- | --- | | `partner`required | `string` | Partner name which credentials need to be set | | `styles`required | `object` | Styles object for widget | | `callback_url` | `string` | Callback URL for callback when widget status changes. | ##### Response `200``application/json` 1 fields Request to Partner Widget Token API Triggered Successfully | Field | Type | Description | | --- | --- | --- | | `widget_token` | `string` | Widget Token for staircase NPM package. | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `403``application/json` 2 fields Invalid key for service | Field | Type | Description | | --- | --- | --- | | `message` | `string` | — | | `url` | `string` | — | ##### Response `422``application/json` 2 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | | `error` | `string` | Message | ##### Response `500``application/json` 1 fields The product has encountered an internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error 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 Copy ``` { "client_id": "--------", "client_secret": "", "link_key": "--------", "contract": "BYOC", "type": "test" } ``` ##### Response 200400403422500 application/json Copy Setup API Triggered Successfully ``` { "message": "Credentials are saved and verified" } ``` application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy Invalid key for service ``` { "message": "Please check the key you used to call this service", "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` application/json Copy Request data failed validation ``` { "message": "Invalid request body", "error": "[object has missing required properties ([\"client_secret\"])]" } ``` application/json Copy The product has encountered an internal server error ``` { "message": "The product has encountered an internal server error" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Staircase Environment API Key | ##### Request body`application/json` 5 fields | Field | Type | Description | | --- | --- | --- | | `client_id`required | `string` | Argyle client ID value | | `client_secret`required | `string` | Argyle client secret value | | `link_key`required | `string` | Argyle link key | | `contract` | `string` | Partner contract type, Staircase contract (SC) or bring your own contract (BYOC) - if not set default value is BYOC | | `type`required | `string` | Type of credentials, can be either test or production | ##### Response `200``application/json` 1 fields Setup API Triggered Successfully | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `403``application/json` 2 fields Invalid key for service | Field | Type | Description | | --- | --- | --- | | `message` | `string` | — | | `url` | `string` | — | ##### Response `422``application/json` 2 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | | `error` | `string` | Message | ##### Response `500``application/json` 1 fields The product has encountered an internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error 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. 1. In the navigation menu browse to Settings. 1. Under Webhooks, click the Add endpoint button. 1. 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. 1. 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 Copy ``` { "client_key": "--------", "client_secret": "", "username": "test@test.com", "password": "", "contract": "SC", "type": "test" } ``` ##### Response 200400403422500 application/json Copy Setup API Triggered Successfully ``` { "message": "Credentials are saved and verified" } ``` application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy Invalid key for service ``` { "message": "Please check the key you used to call this service", "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` application/json Copy Request data failed validation ``` { "message": "Invalid request body", "error": "[object has missing required properties ([\"client_secret\"])]" } ``` application/json Copy The product has encountered an internal server error ``` { "message": "The product has encountered an internal server error" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Staircase Environment API Key | ##### Request body`application/json` 6 fields | Field | Type | Description | | --- | --- | --- | | `client_key` | `string` | Atomic client key | | `client_secret`required | `string` | Atomic client secret | | `username`required | `string` | Atomic username | | `password`required | `string` | Atomic password | | `contract` | `string` | Partner contract type, Staircase contract (SC) or bring your own contract (BYOC) - if not set default value is BYOC | | `type`required | `string` | Type of credentials, can be either test or production | ##### Response `200``application/json` 1 fields Setup API Triggered Successfully | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `403``application/json` 2 fields Invalid key for service | Field | Type | Description | | --- | --- | --- | | `message` | `string` | — | | `url` | `string` | — | ##### Response `422``application/json` 2 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | | `error` | `string` | Message | ##### Response `500``application/json` 1 fields The product has encountered an internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error 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. 1. In the navigation menu browse to Developer. 1. Under API Settings, Production Webhooks click the Edit button. 1. Under the Add Production Webhook section click the Event input and select "Verification Request Status Changed" 1. 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 Copy ``` { "token": "", "username": "test@test.com", "password": "", "contract": "BYOC", "type": "test" } ``` ##### Response 200400403422500 application/json Copy Setup API Triggered Successfully ``` { "message": "Credentials are saved and verified" } ``` application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy Invalid key for service ``` { "message": "Please check the key you used to call this service", "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` application/json Copy Request data failed validation ``` { "message": "Invalid request body", "error": "[object has missing required properties ([\"client_secret\"])]" } ``` application/json Copy The product has encountered an internal server error ``` { "message": "The product has encountered an internal server error" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Staircase Environment API Key | ##### Request body`application/json` 5 fields | Field | Type | Description | | --- | --- | --- | | `token`required | `string` | Truework token for API | | `username`required | `string` | Truework username | | `password`required | `string` | Truework password | | `contract` | `string` | Partner contract type, Staircase contract (SC) or bring your own contract (BYOC) - if not set default value is BYOC | | `type`required | `string` | Type of credentials, can be either test or production | ##### Response `200``application/json` 1 fields Setup API Triggered Successfully | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `403``application/json` 2 fields Invalid key for service | Field | Type | Description | | --- | --- | --- | | `message` | `string` | — | | `url` | `string` | — | ##### Response `422``application/json` 2 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | | `error` | `string` | Message | ##### Response `500``application/json` 1 fields The product has encountered an internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error 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. 1. In the navigation menu browse to Developer. 1. Under API Settings, Production Webhooks click the Edit button. 1. Under the Add Production Webhook section click the Event input and select "Verification Request Status Changed" 1. 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 Copy ``` { "token": "", "username": "test@test.com", "password": "", "contract": "SC", "type": "test" } ``` ##### Response 200400403422500 application/json Copy Setup API Triggered Successfully ``` { "message": "Credentials are saved and verified" } ``` application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy Invalid key for service ``` { "message": "Please check the key you used to call this service", "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` application/json Copy Request data failed validation ``` { "message": "Invalid request body", "error": "[object has missing required properties ([\"client_secret\"])]" } ``` application/json Copy The product has encountered an internal server error ``` { "message": "The product has encountered an internal server error" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Staircase Environment API Key | ##### Request body`application/json` 5 fields | Field | Type | Description | | --- | --- | --- | | `token`required | `string` | Truework-Instant token for API | | `username`required | `string` | Truework-Instant username | | `password`required | `string` | Truework-Instant password | | `contract` | `string` | Partner contract type, Staircase contract (SC) or bring your own contract (BYOC) - if not set default value is BYOC | | `type`required | `string` | Type of credentials, can be either test or production | ##### Response `200``application/json` 1 fields Setup API Triggered Successfully | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `403``application/json` 2 fields Invalid key for service | Field | Type | Description | | --- | --- | --- | | `message` | `string` | — | | `url` | `string` | — | ##### Response `422``application/json` 2 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | | `error` | `string` | Message | ##### Response `500``application/json` 1 fields The product has encountered an internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error 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 Copy ``` { "x_api_secret": "--------", "contract": "BYOC", "type": "production" } ``` ##### Response 200400403422500 application/json Copy Setup API Triggered Successfully ``` { "message": "Credentials are saved and verified" } ``` application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy Invalid key for service ``` { "message": "Please check the key you used to call this service", "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` application/json Copy Request data failed validation ``` { "message": "Invalid request body", "error": "[object has missing required properties ([\"client_secret\"])]" } ``` application/json Copy The product has encountered an internal server error ``` { "message": "The product has encountered an internal server error" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Staircase Environment API Key | ##### Request body`application/json` 3 fields | Field | Type | Description | | --- | --- | --- | | `x_api_secret`required | `string` | Pinwheel API secret | | `contract` | `string` | Partner contract type, Staircase contract (SC) or bring your own contract (BYOC) - if not set default value is BYOC | | `type`required | `string` | Type of credentials, can be either test or production | ##### Response `200``application/json` 1 fields Setup API Triggered Successfully | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `403``application/json` 2 fields Invalid key for service | Field | Type | Description | | --- | --- | --- | | `message` | `string` | — | | `url` | `string` | — | ##### Response `422``application/json` 2 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | | `error` | `string` | Message | ##### Response `500``application/json` 1 fields The product has encountered an internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error 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 Copy ``` { "client_id": "--------", "client_secret": "", "mcl": "--------", "domain": "example.domain.com", "type": "test" } ``` ##### Response 200400403422500 application/json Copy Setup API Triggered Successfully ``` { "message": "Credentials are saved and verified" } ``` application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy Invalid key for service ``` { "message": "Please check the key you used to call this service", "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` application/json Copy Request data failed validation ``` { "message": "Invalid request body", "error": "[object has missing required properties ([\"client_secret\"])]" } ``` application/json Copy The product has encountered an internal server error ``` { "message": "The product has encountered an internal server error" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Staircase Environment API Key | ##### Request body`application/json` 6 fields | Field | Type | Description | | --- | --- | --- | | `client_id`required | `string` | Meridian client ID | | `client_secret`required | `string` | Meridian client secret | | `domain`required | `string` | Meridian domain | | `mcl`required | `string` | Meridian MCL schema | | `contract` | `string` | Partner contract type, Staircase contract (SC) or bring your own contract (BYOC) - if not set default value is BYOC | | `type`required | `string` | Type of credentials, can be either test or production | ##### Response `200``application/json` 1 fields Setup API Triggered Successfully | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `403``application/json` 2 fields Invalid key for service | Field | Type | Description | | --- | --- | --- | | `message` | `string` | — | | `url` | `string` | — | ##### Response `422``application/json` 2 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | | `error` | `string` | Message | ##### Response `500``application/json` 1 fields The product has encountered an internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error 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 Copy ``` { "partnerId": "--------", "partnerSecret": "--------", "apiKey": "", "contract": "BYOC", "type": "test" } ``` ##### Response 200400403422500 application/json Copy Setup API Triggered Successfully ``` { "message": "Credentials are saved and verified" } ``` application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy Invalid key for service ``` { "message": "Please check the key you used to call this service", "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` application/json Copy Request data failed validation ``` { "message": "Invalid request body", "error": "[object has missing required properties ([\"client_secret\"])]" } ``` application/json Copy The product has encountered an internal server error ``` { "message": "The product has encountered an internal server error" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Staircase Environment API Key | ##### Request body`application/json` 5 fields | Field | Type | Description | | --- | --- | --- | | `partnerId`required | `string` | Finicity partner ID | | `partnerSecret`required | `string` | Finicity partner secret | | `apiKey`required | `string` | Finicity API key | | `contract` | `string` | Partner contract type, Staircase contract (SC) or bring your own contract (BYOC) - if not set default value is BYOC | | `type`required | `string` | Type of credentials, can be either test or production | ##### Response `200``application/json` 1 fields Setup API Triggered Successfully | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `403``application/json` 2 fields Invalid key for service | Field | Type | Description | | --- | --- | --- | | `message` | `string` | — | | `url` | `string` | — | ##### Response `422``application/json` 2 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | | `error` | `string` | Message | ##### Response `500``application/json` 1 fields The product has encountered an internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error 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 Copy ``` { "twn_username": "UserNameIntgTEST@5005", "twn_password": "I_9087POK", "pfx_certificate_password": "9huoiqhiokopj9iu", "contract": "BYOC", "type": "production" } ``` ##### Response 200400403422500 application/json Copy Setup API Triggered Successfully ``` { "message": "Credentials are saved and verified" } ``` application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy Invalid key for service ``` { "message": "Please check the key you used to call this service", "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` application/json Copy Request data failed validation ``` { "message": "Invalid request body", "error": "[object has missing required properties ([\"client_secret\"])]" } ``` application/json Copy The product has encountered an internal server error ``` { "message": "The product has encountered an internal server error" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Staircase Environment API Key | ##### Request body`application/json` 5 fields | Field | Type | Description | | --- | --- | --- | | `twn_username`required | `string` | Equifax The Work Number username | | `twn_password`required | `string` | Equifax The Work Number password | | `pfx_certificate_password` | `string` | Equifax PFX Certificate password | | `contract` | `string` | Partner contract type, Staircase contract (SC) or bring your own contract (BYOC) - if not set default value is BYOC | | `type` | `string` | Type of credentials, can be either test or production | ##### Response `200``application/json` 1 fields Setup API Triggered Successfully | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `403``application/json` 2 fields Invalid key for service | Field | Type | Description | | --- | --- | --- | | `message` | `string` | — | | `url` | `string` | — | ##### Response `422``application/json` 2 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | | `error` | `string` | Message | ##### Response `500``application/json` 1 fields The product has encountered an internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error 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 Copy ``` Select option 'binary' in order to upload file ``` ##### Response 200400403500 application/json Copy Setup API Triggered Successfully ``` { "message": "Certificate uploaded and saved successfully" } ``` application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy Invalid key for service ``` { "message": "Please check the key you used to call this service", "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` application/json Copy The product has encountered an internal server error ``` { "message": "The product has encountered an internal server error" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Staircase Environment API Key | ##### Response `200``application/json` 1 fields Setup API Triggered Successfully | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `403``application/json` 2 fields Invalid key for service | Field | Type | Description | | --- | --- | --- | | `message` | `string` | — | | `url` | `string` | — | ##### Response `500``application/json` 1 fields The product has encountered an internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error 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 Copy ``` Select option 'binary' in order to upload file ``` ##### Response 201403500 application/json Copy Blob uploaded ``` { "blob_id": "01EZY9J8SEFM2JKDJ1Q3YX65HS" } ``` application/json Copy 403 invalid error ``` { "message": "Please check the key you used to call this service", "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` application/json Copy Internal server error ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. | ##### Response `201``application/json` 1 fields Blob uploaded | Field | Type | Description | | --- | --- | --- | | `blob_id` | `string` | Created blob ID | ##### Response `403``application/json` 2 fields 403 invalid error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | | `url` | `string` | Error additional URL. | ##### Response `500``application/json` 1 fields Internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | ##### Other responses `400``405``422` `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 200403500 application/json Copy 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" } } } ``` application/json Copy 403 invalid error ``` { "message": "Please check the key you used to call this service", "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` application/json Copy Internal server error ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 2 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. | | `blob_id` required | `string` path | `01EZY9J8SEFM2JKDJ1Q3YX65HS` | Blob identifier | ##### Response `200``application/json` 4 fields Blob retrieved successfully. | Field | Type | Description | | --- | --- | --- | | `blob_id` | `string` | Blob ID | | `extension` | `string` | File extension | | `message` | `string` | Blob retrieved successfully. | | `presigned_urls` | `object` | Presigned URL | ##### Response `403``application/json` 2 fields 403 invalid error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | | `url` | `string` | Error additional URL. | ##### Response `500``application/json` 1 fields Internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | ##### Other responses `400``404``405` `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 200403 application/json Copy 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" } } } ``` application/json Copy 403 invalid error ``` { "message": "Please check the key you used to call this service", "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` ##### Parameters 3 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `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 `200``application/json` 1 fields Presigned URL created successfully. | Field | Type | Description | | --- | --- | --- | | `presigned_urls` | `object` | Presigned URLs | ##### Response `403``application/json` 2 fields 403 invalid error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | | `url` | `string` | Error additional URL. | ##### Other responses `400``404` `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 200403500 application/json Copy Presigned URL retrieved successfully. ``` { "url": "https://dev-data-manager-blobs-bucket.s3.amazonaws.com/01EZY9J8SEFM2JKDJ1Q3YX65HS" } ``` application/json Copy 403 invalid error ``` { "message": "Please check the key you used to call this service", "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` application/json Copy Internal server error ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 3 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. | | `blob_id` required | `string` path | `01EZY9J8SEFM2JKDJ1Q3YX65HS` | Blob identifier | | `action` required | `string` path | `upload` | Possible actions: - upload - download | ##### Response `200``application/json` 1 fields Presigned URL retrieved successfully. | Field | Type | Description | | --- | --- | --- | | `url` | `string` | Presigned url | ##### Response `403``application/json` 2 fields 403 invalid error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | | `url` | `string` | Error additional URL. | ##### Response `500``application/json` 1 fields Internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | ##### Other responses `400``404` `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 200403 application/json Copy Presigned URLs retrieved successfully. ``` { "upload": { "url": "https://dev-data-manager-blobs-bucket.s3.amazonaws.com/01EZY9J8SEFM2JKDJ1Q3YX65HS" } } ``` application/json Copy 403 invalid error ``` { "message": "Please check the key you used to call this service", "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` ##### Parameters 2 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. | | `blob_id` required | `string` path | `01EZY9J8SEFM2JKDJ1Q3YX65HS` | Blob identifier | ##### Response `200``application/json` 1 fields Presigned URLs retrieved successfully. | Field | Type | Description | | --- | --- | --- | | `presigned_urls` | `object` | Presigned URLs | ##### Response `403``application/json` 2 fields 403 invalid error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | | `url` | `string` | Error additional URL. | ##### Other responses `400``404` `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 Copy ``` Blob content from partner ``` ##### Response 201400 UnableToRetrieveURL400 UnableToExtractValues403422500 application/json Copy Presigned URLs retrieved successfully. ``` { "blob_id": "01F739J4XDSNCZMMJSJCB83PCQ" } ``` application/json Copy Invalid body request. ``` { "message": "Unable to retrieve url" } ``` application/json Copy Invalid body request. ``` { "message": "Unable to extract data from URL" } ``` application/json Copy 403 invalid error ``` { "message": "Please check the key you used to call this service", "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` application/json Copy Unprocessable entity error ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` application/json Copy Internal server error ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. | ##### Request body`application/json` 5 fields | Field | Type | Description | | --- | --- | --- | | `extension_path` | `string` | JSON path where the extension is in the response object. If it is not specified, extension will be "pdf".Example `$.DocumentExension` | | `content_path`required | `string` | JSON path where the actual content is in the response object.Example `$.DocumentData` | | `decode_from_base64` | `boolean` | Need to decode a content from base64. | | `encode_to_base64` | `boolean` | Need to encode a content to base64. | | `url`required | `string` | URL with the partner response.Example `https://google.com` | ##### Response `201``application/json` 1 fields Presigned URLs retrieved successfully. | Field | Type | Description | | --- | --- | --- | | `blob_id` | `string` | ID of the returned blob. | ##### Response `400``application/json` 1 fields Invalid body request. | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message | ##### Response `403``application/json` 2 fields 403 invalid error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | | `url` | `string` | Error additional URL. | ##### Response `422``application/json` 1 fields Unprocessable entity error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error Message. | ##### Response `500``application/json` 1 fields Internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | ### 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 200 Example1200 Example2400403404 GetProduct404 text/html500 application/json Copy Successfully retrieved product partners. ``` { "partners": [ { "Partner": "partner_name", "order": 1, "active": true, "status": "active", "verification_type": "borrower", "byoc": true } ] } ``` application/json Copy Successfully retrieved product partners. ``` { "partners": [ { "Partner": "partner_name", "order": 1, "active": false, "status": "upcoming", "verification_type": "borrower", "byoc": true } ] } ``` application/json Copy Validation Error ``` { "message": "3 is not of type 'string'. Failed validating 'type' in schema['properties']['deal_sets']['items'][0]['properties']['parties']['items'][0]['properties']['customer_transaction_ID']:" } ``` application/json Copy 403 invalid error ``` { "message": "Please check the key you used to call this service", "url": "https://api.staircase.co/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` application/json Copy Resource not found ``` { "type": "string", "description": "Error Message." } ``` text/html Copy Resource not found ``` \r\n400 Bad Request\r\n\r\n

400 Bad Request

\r\n\r\n\r\n ``` application/json Copy Internal server error ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 2 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. | | `active` | `boolean` query | `false` | Include vendors with active product flows | ##### Response `200``application/json` 1 fields Successfully retrieved product partners. | Field | Type | Description | | --- | --- | --- | | `partners` | `object[]` | List of vendors. | | `partner` | `string` | Partner name | | `order` | `number` | Order of the product flows associated with this partner | | `active` | `boolean` | Partner has active flows | | `status` | `string` | Status of the partner | | `verification_type` | `string` | Type of verification | | `byoc` | `boolean` | Specify whether customer should add its own partner credentials or not | ##### Response `400``application/json` 1 fields Validation Error | Field | Type | Description | | --- | --- | --- | | `message` | `one of` | Message | ##### Response `403``application/json` 2 fields 403 invalid error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | | `url` | `string` | Error additional URL. | ##### Response `404``application/json` 1 fields Resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error Message. | ##### Response `500``application/json` 1 fields Internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | `GET` `/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 200400403404 GetProduct404 text/html500 application/json Copy Successfully retrieved partners ordering. ``` [ { "partner": "partner1", "order": 1 }, { "partner": "partner2", "order": 2 } ] ``` application/json Copy Validation Error ``` { "message": "3 is not of type 'string'. Failed validating 'type' in schema['properties']['deal_sets']['items'][0]['properties']['parties']['items'][0]['properties']['customer_transaction_ID']:" } ``` application/json Copy 403 invalid error ``` { "message": "Please check the key you used to call this service", "url": "https://api.staircase.co/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` application/json Copy Resource not found ``` { "type": "string", "description": "Error Message." } ``` text/html Copy Resource not found ``` \r\n400 Bad Request\r\n\r\n

400 Bad Request

\r\n\r\n\r\n ``` application/json Copy Internal server error ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. | ##### Response `200``application/json` 1 fields Successfully retrieved partners ordering. | Field | Type | Description | | --- | --- | --- | | `partner_order` | `object` | Partner and order | | `partner` | `string` | Example `partner1` | | `order` | `number` | Example `1` | ##### Response `400``application/json` 1 fields Validation Error | Field | Type | Description | | --- | --- | --- | | `message` | `one of` | Message | ##### Response `403``application/json` 2 fields 403 invalid error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | | `url` | `string` | Error additional URL. | ##### Response `404``application/json` 1 fields Resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error Message. | ##### Response `500``application/json` 1 fields Internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | `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 Copy ``` { "active": true } ``` ##### Response 200400 application/json400 text/html403404 GetProduct404 text/html500 application/json Copy Successfully updated active parameter for the partner. ``` { "message": "Partner status updated." } ``` application/json Copy Failed to update the partner from one of the reasons. ``` { "message": "Partner doesn't exist in database." } ``` text/html Copy Failed to update the partner from one of the reasons. ``` \r\n400 Bad Request\r\n\r\n

400 Bad Request

\r\n\r\n\r\n ``` application/json Copy 403 invalid error ``` { "message": "Please check the key you used to call this service", "url": "https://api.staircase.co/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` application/json Copy Resource not found ``` { "type": "string", "description": "Error Message." } ``` text/html Copy Resource not found ``` \r\n400 Bad Request\r\n\r\n

400 Bad Request

\r\n\r\n\r\n ``` application/json Copy Internal server error ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 2 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. | | `partner` required | `string` path | `partner_name` | Name of the partner for which we wan't to update status. | ##### Request body`application/json` 1 fields | Field | Type | Description | | --- | --- | --- | | `active`required | `boolean` | Example `true` | ##### Response `200``application/json` 1 fields Successfully updated active parameter for the partner. | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Partner status updated. | ##### Response `400``application/json` 1 fields Failed to update the partner from one of the reasons. | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Partner doesn't exist in database. | ##### Response `403``application/json` 2 fields 403 invalid error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | | `url` | `string` | Error additional URL. | ##### Response `404``application/json` 1 fields Resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error Message. | ##### Response `500``application/json` 1 fields Internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | `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 Copy ``` { "active": true } ``` ##### Response 200400403500 application/json Copy Successfully updated active parameter for the partner ``` { "message": "Partner status updated!" } ``` application/json Copy Failed to update the partner from one of the reasons ``` { "message": "Partner doesn't exist in database" } ``` application/json Copy Invalid key for service ``` { "message": "Your API key is not valid, please refresh it.", "url": "https://api.staircase.co/docs/Console/Console/Account/post-customer-account" } ``` application/json Copy The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used. ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 2 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-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 body`application/json` 1 fields | Field | Type | Description | | --- | --- | --- | | `active`required | `boolean` | Example `true` | ##### Response `200``application/json` 1 fields Successfully updated active parameter for the partner | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Partner status updated! | ##### Response `400``application/json` 1 fields Failed to update the partner from one of the reasons | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Partner doesn't exist in database | ##### Response `403``application/json` 2 fields Invalid key for service | Field | Type | Description | | --- | --- | --- | | `message` | `string` | — | | `url` | `string` | — | ##### Response `500``application/json` 1 fields The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used. | Field | Type | Description | | --- | --- | --- | | `message` | `string` | — | `PUT` `/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 Copy ``` { "ordering": [ { "partner": "partner1", "order": 1 }, { "partner": "partner2", "order": 10 } ] } ``` ##### Response 200400 application/json400 text/html403404 GetProduct404 text/html500 application/json Copy Successfully updated partners ordering. ``` [ { "partner": "partner1", "order": 1 }, { "partner": "partner2", "order": 10 } ] ``` application/json Copy Failed to update the partner from one of the reasons ``` { "message": "Partner doesn't exist in database" } ``` text/html Copy Failed to update the partner from one of the reasons ``` \r\n400 Bad Request\r\n\r\n

400 Bad Request

\r\n\r\n\r\n ``` application/json Copy 403 invalid error ``` { "message": "Please check the key you used to call this service", "url": "https://api.staircase.co/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` application/json Copy Resource not found ``` { "type": "string", "description": "Error Message." } ``` text/html Copy Resource not found ``` \r\n400 Bad Request\r\n\r\n

400 Bad Request

\r\n\r\n\r\n ``` application/json Copy Internal server error ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. | ##### Request body`application/json` 1 fields | Field | Type | Description | | --- | --- | --- | | `ordering` | `object[]` | — | | `partner` | `string` | Partner nameExample `wage` | | `order` | `number` | Partner orderExample `1` | ##### Response `200``application/json` 2 fields Successfully updated partners ordering. | Field | Type | Description | | --- | --- | --- | | `partner` | `string` | Partner nameExample `wage` | | `order` | `number` | Partner orderExample `1` | ##### Response `400``application/json` 1 fields Failed to update the partner from one of the reasons | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Partner doesn't exist in database | ##### Response `403``application/json` 2 fields 403 invalid error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | | `url` | `string` | Error additional URL. | ##### Response `404``application/json` 1 fields Resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error Message. | ##### Response `500``application/json` 1 fields Internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | `GET` `/partners/{partner}/schema` #### Retrieve Partner Credentials Schema `getPartnerSchema` Retrieve Partner Schema retrieves the required partner schema for credentials. ##### Response 200400403500 application/json Copy 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 } ``` application/json Copy Bad Request ``` { "message": "Partner not found" } ``` application/json Copy Invalid key for service ``` { "message": "Your API key is not valid, please refresh it.", "url": "https://api.staircase.co/docs/Console/Console/Account/post-customer-account" } ``` application/json Copy The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used. ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 2 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-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 `200``application/json` 10 fields Successfully returned the partner schema object | Field | Type | Description | | --- | --- | --- | | `schema` | `string` | Schema URL | | `id` | `string` | Schema ID | | `type` | `string` | JSON type | | `title` | `string` | Schema title | | `description` | `string` | Schema description | | `webhook` | `boolean` | Value that indicates if partner requires webhook setup | | `default` | `object` | Default value for schema | | `examples` | `object[]` | List of examples | | `key1` | `string` | Example 1 | | `key2` | `string` | Example 2 | | `required` | `string[]` | Required fields | | `properties` | `object` | Properties of Schema | | `key1` | `object` | Key 1 Schema | | `id` | `string` | Property ID | | `type` | `string` | Property value type | | `title` | `string` | Title for property | | `description` | `string` | Description for property | | `default` | `string` | Default value if exists | | `examples` | `string[]` | List of examples for given property | | `key2` | `object` | Key 2 Schema | | `id` | `string` | Property ID | | `type` | `string` | Property value type | | `title` | `string` | Title for property | | `description` | `string` | Description for property | | `default` | `string` | Default value if exists | | `examples` | `string[]` | List of examples for given property | ##### Response `400``application/json` 1 fields Bad Request | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Partner not found | ##### Response `403``application/json` 2 fields Invalid key for service | Field | Type | Description | | --- | --- | --- | | `message` | `string` | — | | `url` | `string` | — | ##### Response `500``application/json` 1 fields The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used. | Field | Type | Description | | --- | --- | --- | | `message` | `string` | — | ### 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 InvokeByFlowNameInvokeByTagsInvokeWithRequestDataInvokeWithFlowOptionsCollectionsInvokeWithFlowOptionsRequestDataInvokeByFlowNameOptionsInvokeByVendorNameOptions application/json Copy ``` { "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" } ] } } ] } } ] } } } ``` application/json Copy ``` { "transaction_id": "01F6NAMXWN2XVBD1YJ92A6S6R4", "response_collection_id": "01F6NAQ4894HPMCBGB4P0G95XK", "request_collection_id": "01F6QF1QJF20DMSXH4SYXKB1SN", "callback_url": "https://webhook.site/3706b519-9426-4533-9868-14a7dec4fd97", "tags": [ "manual_verification" ] } ``` application/json Copy ``` { "product_flow_name": "get-document-from-byte", "transaction_id": "01F6NAMXWN2XVBD1YJ92A6S6R4", "response_collection_id": "01F6NAQ4894HPMCBGB4P0G95XK", "callback_url": "https://webhook.site/3706b519-9426-4533-9868-14a7dec4fd97", "request_data": { "deal_sets": { "deal_set": [ { "deals": { "deal": [ { "parties": { "party": [ { "individual": { "name": { "first": "Thomas", "last": "Alex" } }, "taxpayer_identifiers": { "taxpayer_identifier": [ { "value": "12345" } ] }, "roles": { "role": [ { "borrower": { "residences": { "residence": [ { "address": { "line_text": "street 101", "city": "example city", "state": "state", "postal_code": "1234", "street_name": "street 23" } } ] } } } ] } } ] } } ] } } ] } } } ``` application/json Copy ``` { "transaction_id": "01F6NAMXWN2XVBD1YJ92A6S6R4", "response_collection_id": "01F6NAQ4894HPMCBGB4P0G95XK", "request_collection_id": "01F6QF1QJF20DMSXH4SYXKB1SN", "callback_url": "https://webhook.site/3706b519-9426-4533-9868-14a7dec4fd97", "tags": [ "manual_verification" ], "options": { "option1": "test_option" } } ``` application/json Copy ``` { "transaction_id": "01F6NAMXWN2XVBD1YJ92A6S6R4", "response_collection_id": "01F6NAQ4894HPMCBGB4P0G95XK", "callback_url": "https://webhook.site/3706b519-9426-4533-9868-14a7dec4fd97", "request_data": { "deal_sets": { "deal_set": [ { "deals": { "deal": [ { "parties": { "party": [ { "individual": { "name": { "first": "Thomas", "last": "Alex" } }, "taxpayer_identifiers": { "taxpayer_identifier": [ { "value": "12345" } ] }, "roles": { "role": [ { "borrower": { "residences": { "residence": [ { "address": { "line_text": "street 101", "city": "example city", "state": "state", "postal_code": "1234", "street_name": "street 23" } } ] } } } ] } } ] } } ] } } ] } }, "tags": [ "manual_verification" ], "options": { "option1": "test_option" } } ``` application/json Copy ``` { "product_flow_name": "get-document-from-byte", "transaction_id": "01F6NAMXWN2XVBD1YJ92A6S6R4", "request_collection_id": "01F6QF1QJF20DMSXH4SYXKB1SN", "response_collection_id": "01F6NAQ4894HPMCBGB4P0G95XK", "callback_url": "https://webhook.site/3706b519-9426-4533-9868-14a7dec4fd97", "options": { "option1": "test_option" } } ``` application/json Copy ``` { "vendor_name": "argyle", "transaction_id": "01F6NAMXWN2XVBD1YJ92A6S6R4", "request_collection_id": "01F6QF1QJF20DMSXH4SYXKB1SN", "response_collection_id": "01F6NAQ4894HPMCBGB4P0G95XK", "callback_url": "https://webhook.site/3706b519-9426-4533-9868-14a7dec4fd97", "options": { "option1": "test_option" } } ``` ##### Response 201400403404500 application/json Copy 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" ] } ``` application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy 403 invalid error ``` { "message": "Please check the key you used to call this service", "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` text/html Copy Resource not found ``` \r\n400 Bad Request\r\n\r\n

400 Bad Request

\r\n\r\n\r\n ``` application/json Copy Internal server error ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. | ##### Request body`application/json` 9 fields | Field | Type | Description | | --- | --- | --- | | `product_flow_name` | `string` | Product flow name. If it is not specified, the default product flow will be invoked. If the product has no default product flow, the first created flow will be invoked. Cannot be specified together with vendor_name. | | `vendor_name` | `string` | Vendor name. Cannot be specified together with product_flow_name. | | `transaction_id` | `string` | Transaction ID used for invocation. | | `request_collection_id` | `string` | Request Collection ID. | | `response_collection_id` | `string` | Response Collection ID. | | `callback_url` | `string (uri)` | Callback URL. | | `request_data` | `object` | Request JSON body. | | `tags` | `string[]` | List of tags. | | `options` | `object` | Additional information that should be passed to the connector but not be added to the request collection. | ##### Response `201``application/json` 10 fields Successfully started flow invocation. | Field | Type | Description | | --- | --- | --- | | `invocation_id`required | `string` | Invocation ID. | | `invocation_status`required | `string` | The status of the invocation.`STARTED` | | `transaction_id`required | `string` | Transaction ID. | | `product_flow_name` | `string` | Product flow name. | | `metadata` | `object` | The metadata of the invoked product flow. | | `callback_url` | `string` | Callback URL. | | `request_data` | `object` | The data for the request collection. | | `tags` | `string[]` | List of tags. | | `options` | `object` | Additional information that should be passed to the connector but not be added to the request collection. | | `connector_job_id` | `string` | Connector job ID. | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `403``application/json` 2 fields 403 invalid error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | | `url` | `string` | Error additional URL. | ##### Response `404``application/json` 1 fields Resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `500``application/json` 1 fields Internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | `GET` `/products/employment/invocations/{invocation_id}` #### Retrieve Product Flow Invocation Status `RetrieveProductFlowInvocationStatus` Retrieves the status of running Product flow invocation. ##### Response 200400403404500 application/json Copy 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" ] } ``` application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy 403 invalid error ``` { "message": "Please check the key you used to call this service", "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` text/html Copy Resource not found ``` \r\n400 Bad Request\r\n\r\n

400 Bad Request

\r\n\r\n\r\n ``` application/json Copy Internal server error ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 2 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. | | `invocation_id` required | `string (ulid)` path | `d7ccedb8-8889-4657-add4-bc1s4xs97637` | Product flow invocation identifier | ##### Response `200``application/json` 12 fields Successfully returned status of the Product flow Invocation. | Field | Type | Description | | --- | --- | --- | | `invocation_id`required | `string` | Invocation ID. | | `invocation_status`required | `string` | Invocation Status.`ACTION_REQUIRED``COMPLETED``FAILED``RUNNING``STARTED` | | `transaction_id`required | `string` | Transaction ID used for invocation. | | `request_collection_id` | `string` | Request Collection ID. | | `request_collection` | `object` | Collection. | | `transaction_id` | `string (ulid)` | Transaction ID.Example `01EZQ32PJQGKRA6HR8D72Q9FFF` | | `collection_id` | `string (ulid)` | Collection ID.Example `01EZQ32PJQGKRA6HR8D72Q9FFF` | | `data` | `object` | Data in Staircase language schema. | | `metadata` | `object` | Metadata about collection, f.e version of used Staircase schema. | | `response_collection_id` | `string` | Response Collection ID. | | `response_collection` | `object` | Collection. | | `transaction_id` | `string (ulid)` | Transaction ID.Example `01EZQ32PJQGKRA6HR8D72Q9FFF` | | `collection_id` | `string (ulid)` | Collection ID.Example `01EZQ32PJQGKRA6HR8D72Q9FFF` | | `data` | `object` | Data in Staircase language schema. | | `metadata` | `object` | Metadata about collection, f.e version of used Staircase schema. | | `callback_url` | `string` | URL that was specified in flow invocation and will be used to send the callback when flow invocation will be finished. | | `widget_url` | `string (uri)` | URL of the widget. | | `metadata` | `object` | Response Collection ID. | | `options` | `—` | Options that were passed to the flow invocation. | | `connector_job_id` | `string` | Connector job ID. | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `403``application/json` 2 fields 403 invalid error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | | `url` | `string` | Error additional URL. | ##### Response `404``application/json` 1 fields Resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `500``application/json` 1 fields Internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | ### Product Reports `GET` `/products/employment/report-templates` #### Retrieve Report Templates `retrieveReportTemplates` Retrieve Report Templates retrieves product report templates. ##### Response 200400403404 GetProduct404 text/html500 application/json Copy Successfully returned the report templates. ``` { "name": "voe_template", "template_type": "jinja", "product_name": "employment", "body": "Staircase

First Name

{{ collection[\\\"deal_sets\\\"][\\\"deal_set\\\"][0][\\\"deals\\\"][\\\"deal\\\"][0][\\\"parties\\\"][\\\"party\\\"][0][\\\"individual\\\"][\\\"name\\\"][\\\"first\\\"] }}" } ``` application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy 403 invalid error ``` { "message": "Please check the key you used to call this service", "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` application/json Copy Resource not found ``` { "type": "string", "description": "Error Message." } ``` text/html Copy Resource not found ``` \r\n400 Bad Request\r\n\r\n

400 Bad Request

\r\n\r\n\r\n ``` application/json Copy Internal server error ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. | ##### Response `200``application/json` 4 fields Successfully returned the report templates. | Field | Type | Description | | --- | --- | --- | | `name` | `string` | Name of template | | `template_type` | `string` | Template type`jinja` | | `body` | `string` | Template HTML string body | | `product_name` | `string` | Product name | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `403``application/json` 2 fields 403 invalid error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | | `url` | `string` | Error additional URL. | ##### Response `404``application/json` 1 fields Resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error Message. | ##### Response `500``application/json` 1 fields Internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | `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. ``` Staircase

Staircase

First Name

{{ collection["deal_sets"]["deal_set"][0]["deals"]["deal"][0]["parties"]["party"][0]["individual"]["name"]["first"] }}

Last Name

{{ collection["deal_sets"]["deal_set"][0]["deals"]["deal"][0]["parties"]["party"][0]["individual"]["name"]["last"] }}

List

    {% for item in collection.deal_sets.deal_set[0].deals.deal[0].parties.party[0].individual.contact_points.contact_point %}
  • Email: {{ item.email }}
  • Phone: {{ item.contact_point_telephone.value }}
    • {% endfor %}

Table

{%- for header in ["Name", "Email", "Phone"] %} {%- endfor %} {%- for row in collection.deal_sets.deal_set[0].deals.deal[0].parties.party[0].individual.contact_points.contact_point %} {%- endfor %}
{{ header }}
{{ collection["deal_sets"]["deal_set"][0]["deals"]["deal"][0]["parties"]["party"][0]["individual"]["name"]["first"] }} {{row.email}} {{row.contact_point_telephone.value}}
``` 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 Example Jinja LogicVOE Report 1VOE Report 2Report Styles application/json Copy ``` { "name": "voe_template", "template_type": "jinja", "body": "Staircase

First Name

{{ collection[\\\"deal_sets\\\"][\\\"deal_set\\\"][0][\\\"deals\\\"][\\\"deal\\\"][0][\\\"parties\\\"][\\\"party\\\"][0][\\\"individual\\\"][\\\"name\\\"][\\\"first\\\"] }}" } ``` application/json Copy ``` { "name": "report1_example", "template_type": "jinja", "body": "Content
Verification Requested: Verification Acquired: Loan Number:

Data Source

Provided by:

Borrower Information

First Name:
Last Name:
Phone Number:
Email:
SSN:
Street:
City:
State:
Postal Code:
Country:

Employer Name

Company Name:
Position Description:
Start Date:
Status:

Information accurate as of:

\n" } ``` application/json Copy ``` { "name": "report2_example", "template_type": "jinja", "body": "Content

Verification Employment

Loan Number:
548712
Verification Requested:
10/08/2020
Verification Acquired:
10/27/2020

Data Source

Provided by:

Jason Barrera

Borrower Information

First Name:

Richard

Last Name:

Grant

Phone Number:

+1 808 3722 9914

SSN:

34923832

Email:

richardgrant@gmail.com

State:

NY

City:

New York

Neighbourhood:

Brooklyn

Postal Code:

10001

Country:

United States

Employer Name

Company Name:

Acme

Position Description:

Web Designer

Start Date:

11/08/2016

SSN:

80018422

\n" } ``` application/json Copy ``` { "name": "report_styles_example", "template_type": "jinja", "body": "

Title

h1 - Report Title

h2 - Report Title

h3 - Report Title

h3 - Report Title

BODY normal / bold / italic

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

2 columns

First Name:

Richard

Last Name:

Grant

3 columns

Phone Number:

+1 808 3722 9914

SSN:

34923832

Email:

richardgrant@gmail.com

5 columns

State:

NY

City:

New York

Neighbourhood:

Brooklyn

Postal Code:

10001

Country:

United States

Information as accurate as of: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Bulleted list

  • Employment randomly chooses between Atomic and Argyle and checks to see if the data partner is able to provide a VOE response for the given company.
  • Employment randomly chooses between Atomic and Argyle and checks to see if the data partner is able to provide a VOE response for the given company.
  • Employment randomly chooses between Atomic and Argyle and checks to see if the data partner is able to provide a VOE response for the given company.

Number list

  • 1. Employment randomly chooses between Atomic and Argyle and checks to see if the data partner is able to provide a VOE response for the given company.
  • 2. Employment randomly chooses between Atomic and Argyle and checks to see if the data partner is able to provide a VOE response for the given company.
  • 3. Employment randomly chooses between Atomic and Argyle and checks to see if the data partner is able to provide a VOE response for the given company.

Check list

  • \\\"check\\\"Employment randomly chooses between Atomic and Argyle and checks to see if the data partner is able to provide a VOE response for the given company.
  • \\\"check\\\"Employment randomly chooses between Atomic and Argyle and checks to see if the data partner is able to provide a VOE response for the given company.
  • \\\"check\\\"Employment randomly chooses between Atomic and Argyle and checks to see if the data partner is able to provide a VOE response for the given company.

Tags

TAG 1
TAG 2

Breadcrums

Divider

Notes

NOTE

Do not activate the API key for the documentation environment. If you have activated your API Key for the documentation environment, it cannot be used for any other environment.

2 columns

column 1
column 2
Text column 1
Text column 2
Text column 1
Text column 2
Text column 1
Text column 2

3 columns

column 1
column 2
column 3
Text column 1
Text column 2
Text column 3
Text column 1
Text column 2
Text column 3
Text column 1
Text column 2
Text column 3
\n" } ``` ##### Response 200400403404 GetProduct404 text/html500 application/json Copy Report template successfully added. ``` { "name": "voe_template", "template_type": "jinja", "product_name": "employment", "body": "Staircase

First Name

{{ collection[\\\"deal_sets\\\"][\\\"deal_set\\\"][0][\\\"deals\\\"][\\\"deal\\\"][0][\\\"parties\\\"][\\\"party\\\"][0][\\\"individual\\\"][\\\"name\\\"][\\\"first\\\"] }}" } ``` application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy 403 invalid error ``` { "message": "Please check the key you used to call this service", "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` application/json Copy Resource not found ``` { "type": "string", "description": "Error Message." } ``` text/html Copy Resource not found ``` \r\n400 Bad Request\r\n\r\n

400 Bad Request

\r\n\r\n\r\n ``` application/json Copy Internal server error ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. | ##### Request body`application/json` 3 fields | Field | Type | Description | | --- | --- | --- | | `name`required | `string` | Name of template | | `template_type`required | `string` | Template type`jinja` | | `body`required | `string` | Template HTML string body | ##### Response `200``application/json` 4 fields Report template successfully added. | Field | Type | Description | | --- | --- | --- | | `name` | `string` | Name of template | | `template_type` | `string` | Template type`jinja` | | `body` | `string` | Template HTML string body | | `product_name` | `string` | Product name | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `403``application/json` 2 fields 403 invalid error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | | `url` | `string` | Error additional URL. | ##### Response `404``application/json` 1 fields Resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error Message. | ##### Response `500``application/json` 1 fields Internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | `GET` `/products/employment/report-templates/{template_name}` #### Retrieve Report Template `retrieveReportTemplate` Retrieve Report Template retrieves a specific report template. ##### Response 200400403404 GetProduct404 text/html500 application/json Copy Successfully returned the report template. ``` { "name": "voe_template", "template_type": "jinja", "product_name": "employment", "body": "Staircase

First Name

{{ collection[\\\"deal_sets\\\"][\\\"deal_set\\\"][0][\\\"deals\\\"][\\\"deal\\\"][0][\\\"parties\\\"][\\\"party\\\"][0][\\\"individual\\\"][\\\"name\\\"][\\\"first\\\"] }}" } ``` application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy 403 invalid error ``` { "message": "Please check the key you used to call this service", "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` application/json Copy Resource not found ``` { "type": "string", "description": "Error Message." } ``` text/html Copy Resource not found ``` \r\n400 Bad Request\r\n\r\n

400 Bad Request

\r\n\r\n\r\n ``` application/json Copy Internal server error ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 2 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. | | `template_name` required | `string` path | `demo_template` | Report Template Name | ##### Response `200``application/json` 4 fields Successfully returned the report template. | Field | Type | Description | | --- | --- | --- | | `name` | `string` | Name of template | | `template_type` | `string` | Template type`jinja` | | `body` | `string` | Template HTML string body | | `product_name` | `string` | Product name | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `403``application/json` 2 fields 403 invalid error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | | `url` | `string` | Error additional URL. | ##### Response `404``application/json` 1 fields Resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error Message. | ##### Response `500``application/json` 1 fields Internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | `PATCH` `/products/employment/report-templates/{template_name}` #### Update Report Template `updateReportTemplate` Update report template ##### Request application/json Copy ``` { "name": "voe_template", "template_type": "jinja", "body": "Staircase

First Name

{{ collection[\\\"deal_sets\\\"][\\\"deal_set\\\"][0][\\\"deals\\\"][\\\"deal\\\"][0][\\\"parties\\\"][\\\"party\\\"][0][\\\"individual\\\"][\\\"name\\\"][\\\"first\\\"] }}" } ``` ##### Response 200400403404 GetProduct404 text/html500 application/json Copy Report template successfully updated. ``` { "name": "voe_template", "template_type": "jinja", "product_name": "employment", "body": "Staircase

First Name

{{ collection[\\\"deal_sets\\\"][\\\"deal_set\\\"][0][\\\"deals\\\"][\\\"deal\\\"][0][\\\"parties\\\"][\\\"party\\\"][0][\\\"individual\\\"][\\\"name\\\"][\\\"first\\\"] }}" } ``` application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy 403 invalid error ``` { "message": "Please check the key you used to call this service", "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` application/json Copy Resource not found ``` { "type": "string", "description": "Error Message." } ``` text/html Copy Resource not found ``` \r\n400 Bad Request\r\n\r\n

400 Bad Request

\r\n\r\n\r\n ``` application/json Copy Internal server error ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 2 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. | | `template_name` required | `string` path | `demo_template` | Report Template Name | ##### Request body`application/json` 3 fields | Field | Type | Description | | --- | --- | --- | | `name`required | `string` | Name of template | | `template_type`required | `string` | Template type`jinja` | | `body`required | `string` | Template HTML string body | ##### Response `200``application/json` 4 fields Report template successfully updated. | Field | Type | Description | | --- | --- | --- | | `name` | `string` | Name of template | | `template_type` | `string` | Template type`jinja` | | `body` | `string` | Template HTML string body | | `product_name` | `string` | Product name | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `403``application/json` 2 fields 403 invalid error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | | `url` | `string` | Error additional URL. | ##### Response `404``application/json` 1 fields Resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error Message. | ##### Response `500``application/json` 1 fields Internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | `DELETE` `/products/employment/report-templates/{template_name}` #### Delete Report Template `deleteReportTemplate` Delete Report Template deletes a report template. ##### Response 400 Example400 text/html403404 GetProduct404 text/html500 application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` text/html Copy Request data failed validation ``` \r\n400 Bad Request\r\n\r\n

400 Bad Request

\r\n\r\n\r\n ``` application/json Copy 403 invalid error ``` { "message": "Please check the key you used to call this service", "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` application/json Copy Resource not found ``` { "type": "string", "description": "Error Message." } ``` text/html Copy Resource not found ``` \r\n400 Bad Request\r\n\r\n

400 Bad Request

\r\n\r\n\r\n ``` application/json Copy Internal server error ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 2 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. | | `template_name` required | `string` path | `demo_template` | Report Template Name | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `403``application/json` 2 fields 403 invalid error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | | `url` | `string` | Error additional URL. | ##### Response `404``application/json` 1 fields Resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error Message. | ##### Response `500``application/json` 1 fields Internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | ##### Other responses `204` `POST` `/products/employment/reports` #### Generate Report `generateTemplate` Generate report for a product ##### Request application/json Copy ``` { "product_name": "employment", "template_name": "voe_template", "transaction_id": "01FCWK741N7GWYBVG4Z3N74V16", "collection_id": "01FCWK741N7GWYBVG4Z3N74V16" } ``` ##### Response 200400403404 GetProduct404 text/html500 application/json Copy 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" } ``` application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy 403 invalid error ``` { "message": "Please check the key you used to call this service", "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` application/json Copy Resource not found ``` { "type": "string", "description": "Error Message." } ``` text/html Copy Resource not found ``` \r\n400 Bad Request\r\n\r\n

400 Bad Request

\r\n\r\n\r\n ``` application/json Copy Internal server error ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. | ##### Request body`application/json` 4 fields | Field | Type | Description | | --- | --- | --- | | `template_name`required | `string` | Name of template | | `product_name` | `string` | Product name | | `transaction_id`required | `string` | Transaction ID | | `collection_id`required | `string` | Collection ID | ##### Response `200``application/json` 6 fields Report successfully generated. | Field | Type | Description | | --- | --- | --- | | `template_name` | `string` | Name of template | | `product_name` | `string` | Product name | | `transaction_id` | `string` | Transaction ID | | `collection_id` | `string` | Collection ID | | `blob_id` | `string` | Blob ID of generated report | | `download_url` | `string` | Presigned URL to view/download generated report | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `403``application/json` 2 fields 403 invalid error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | | `url` | `string` | Error additional URL. | ##### Response `404``application/json` 1 fields Resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error Message. | ##### Response `500``application/json` 1 fields Internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | ### 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 200400 InvalidReturnExamplesValue400 text/html403404 GetProduct404 text/html500 application/json Copy 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": {} } ``` application/json Copy Error ``` { "message": "Please provide one of valid return examples values: true, false" } ``` text/html Copy Error ``` \r\n400 Bad Request\r\n\r\n

400 Bad Request

\r\n\r\n\r\n ``` application/json Copy 403 invalid error ``` { "message": "Please check the key you used to call this service", "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` application/json Copy Resource not found ``` { "type": "string", "description": "Error Message." } ``` text/html Copy Resource not found ``` \r\n400 Bad Request\r\n\r\n

400 Bad Request

\r\n\r\n\r\n ``` application/json Copy Internal server error ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 2 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. | | `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 `200``application/json` 1 fields Successfully returned the list of elements needed for product waterfall. | Field | Type | Description | | --- | --- | --- | | `schema` | `object` | Element key / value | ##### Response `400``application/json` 1 fields Error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `403``application/json` 2 fields 403 invalid error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | | `url` | `string` | Error additional URL. | ##### Response `404``application/json` 1 fields Resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error Message. | ##### Response `500``application/json` 1 fields Internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | `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 200400 InvalidReturnExamplesValue400 text/html403404 GetProduct404 text/html500 application/json Copy 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": {} } ``` application/json Copy Error ``` { "message": "Please provide one of valid return examples values: true, false" } ``` text/html Copy Error ``` \r\n400 Bad Request\r\n\r\n

400 Bad Request

\r\n\r\n\r\n ``` application/json Copy 403 invalid error ``` { "message": "Please check the key you used to call this service", "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` application/json Copy Resource not found ``` { "type": "string", "description": "Error Message." } ``` text/html Copy Resource not found ``` \r\n400 Bad Request\r\n\r\n

400 Bad Request

\r\n\r\n\r\n ``` application/json Copy Internal server error ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 2 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. | | `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 `200``application/json` 1 fields Successfully returned the list of elements of response of the product waterfall. | Field | Type | Description | | --- | --- | --- | | `schema` | `object` | Element key / value element | ##### Response `400``application/json` 1 fields Error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `403``application/json` 2 fields 403 invalid error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | | `url` | `string` | Error additional URL. | ##### Response `404``application/json` 1 fields Resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error Message. | ##### Response `500``application/json` 1 fields Internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | `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 200400403404 GetProduct404 text/html500 application/json Copy 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" ] } ``` application/json Copy Validation Error ``` { "message": "3 is not of type 'string'. Failed validating 'type' in schema['properties']['deal_sets']['items'][0]['properties']['parties']['items'][0]['properties']['customer_transaction_ID']:" } ``` application/json Copy 403 invalid error ``` { "message": "Please check the key you used to call this service", "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` application/json Copy Resource not found ``` { "type": "string", "description": "Error Message." } ``` text/html Copy Resource not found ``` \r\n400 Bad Request\r\n\r\n

400 Bad Request

\r\n\r\n\r\n ``` application/json Copy Internal server error ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. | ##### Response `200``application/json` 1 fields Elements were retrieved successfully | Field | Type | Description | | --- | --- | --- | | `elements`required | `string[]` | List of elements. | ##### Response `400``application/json` 1 fields Validation Error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `403``application/json` 2 fields 403 invalid error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | | `url` | `string` | Error additional URL. | ##### Response `404``application/json` 1 fields Resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error Message. | ##### Response `500``application/json` 1 fields Internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | `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 200400403404 GetProduct404 text/html500 application/json Copy 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" ] } ``` application/json Copy Validation Error ``` { "message": "3 is not of type 'string'. Failed validating 'type' in schema['properties']['deal_sets']['items'][0]['properties']['parties']['items'][0]['properties']['customer_transaction_ID']:" } ``` application/json Copy 403 invalid error ``` { "message": "Please check the key you used to call this service", "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` application/json Copy Resource not found ``` { "type": "string", "description": "Error Message." } ``` text/html Copy Resource not found ``` \r\n400 Bad Request\r\n\r\n

400 Bad Request

\r\n\r\n\r\n ``` application/json Copy Internal server error ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. | ##### Response `200``application/json` 1 fields Elements were retrieved successfully | Field | Type | Description | | --- | --- | --- | | `elements`required | `string[]` | List of elements. | ##### Response `400``application/json` 1 fields Validation Error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `403``application/json` 2 fields 403 invalid error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | | `url` | `string` | Error additional URL. | ##### Response `404``application/json` 1 fields Resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error Message. | ##### Response `500``application/json` 1 fields Internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | `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 Copy ``` { "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 200400403404 GetProduct404 text/html500 application/json Copy Collection is valid ``` { "message": "Collection is valid." } ``` application/json Copy Validation Error ``` { "message": "3 is not of type 'string'. Failed validating 'type' in schema['properties']['deal_sets']['items'][0]['properties']['parties']['items'][0]['properties']['customer_transaction_ID']:" } ``` application/json Copy 403 invalid error ``` { "message": "Please check the key you used to call this service", "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` application/json Copy Resource not found ``` { "type": "string", "description": "Error Message." } ``` text/html Copy Resource not found ``` \r\n400 Bad Request\r\n\r\n

400 Bad Request

\r\n\r\n\r\n ``` application/json Copy Internal server error ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. | ##### Request body`application/json` 1 fields | Field | Type | Description | | --- | --- | --- | | `deal_sets` | `object` | Deal sets object. | | `deal_set` | `object[]` | Deal set object. | | `deals` | `object` | Deals object. | | `deal` | `object[]` | Deal array. | ##### Response `200``application/json` 1 fields Collection is valid | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `400``application/json` 1 fields Validation Error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `403``application/json` 2 fields 403 invalid error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | | `url` | `string` | Error additional URL. | ##### Response `404``application/json` 1 fields Resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error Message. | ##### Response `500``application/json` 1 fields Internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | ### Product Waterfalls `GET` `/products/employment/waterfall` #### Retrieve Product Waterfall `retrieveProductWaterfall` Retrieve Product Waterfall retrieves a specific product waterfall. ##### Response 200400403404 GetProduct404 text/html500 application/json Copy Successfully returned the product waterfall. ``` { "waterfall": [ { "priority": 1, "flow_name": "VOE" } ] } ``` application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy 403 invalid error ``` { "message": "Please check the key you used to call this service", "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` application/json Copy Resource not found ``` { "type": "string", "description": "Error Message." } ``` text/html Copy Resource not found ``` \r\n400 Bad Request\r\n\r\n

400 Bad Request

\r\n\r\n\r\n ``` application/json Copy Internal server error ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. | ##### Response `200``application/json` 1 fields Successfully returned the product waterfall. | Field | Type | Description | | --- | --- | --- | | `waterfall`required | `object[]` | Product waterfall steps. | | `priority`required | `integer` | Priority of waterfall step. | | `flow_name` | `string` | Flow name | | `vendor_name` | `string` | Vendor name | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `403``application/json` 2 fields 403 invalid error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | | `url` | `string` | Error additional URL. | ##### Response `404``application/json` 1 fields Resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error Message. | ##### Response `500``application/json` 1 fields Internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | `PUT` `/products/employment/waterfall` #### Create Product Waterfall `addProductFlow` Create Product waterfall Add custom settings for product waterfall ##### Request application/json Copy ``` { "waterfall": [ { "priority": 1, "flow_name": "VOE" } ] } ``` ##### Response 200400403404 GetProduct404 text/html500 application/json Copy Product waterfall successfully added. ``` { "waterfall": [ { "priority": 1, "flow_name": "VOE" } ] } ``` application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy 403 invalid error ``` { "message": "Please check the key you used to call this service", "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` application/json Copy Resource not found ``` { "type": "string", "description": "Error Message." } ``` text/html Copy Resource not found ``` \r\n400 Bad Request\r\n\r\n

400 Bad Request

\r\n\r\n\r\n ``` application/json Copy Internal server error ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. | ##### Request body`application/json` 1 fields | Field | Type | Description | | --- | --- | --- | | `waterfall`required | `object[]` | Product waterfall steps. | | `priority`required | `integer` | Priority of waterfall step. | | `flow_name` | `string` | Flow name | | `vendor_name` | `string` | Vendor name | ##### Response `200``application/json` 1 fields Product waterfall successfully added. | Field | Type | Description | | --- | --- | --- | | `waterfall`required | `object[]` | Product waterfall steps. | | `priority`required | `integer` | Priority of waterfall step. | | `flow_name` | `string` | Flow name | | `vendor_name` | `string` | Vendor name | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `403``application/json` 2 fields 403 invalid error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | | `url` | `string` | Error additional URL. | ##### Response `404``application/json` 1 fields Resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error Message. | ##### Response `500``application/json` 1 fields Internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | `DELETE` `/products/employment/waterfall` #### Delete Product Waterfall `deleteProductWaterfall` Delete Product Waterfall deletes a product waterfall. ##### Response 400 Example400 text/html403404 GetProduct404 text/html500 application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` text/html Copy Request data failed validation ``` \r\n400 Bad Request\r\n\r\n

400 Bad Request

\r\n\r\n\r\n ``` application/json Copy 403 invalid error ``` { "message": "Please check the key you used to call this service", "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` application/json Copy Resource not found ``` { "type": "string", "description": "Error Message." } ``` text/html Copy Resource not found ``` \r\n400 Bad Request\r\n\r\n

400 Bad Request

\r\n\r\n\r\n ``` application/json Copy Internal server error ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `403``application/json` 2 fields 403 invalid error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | | `url` | `string` | Error additional URL. | ##### Response `404``application/json` 1 fields Resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error Message. | ##### Response `500``application/json` 1 fields Internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | ##### Other responses `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 InvokeWithCollectionsInvokeWithTagsInvokeWithRequestDataInvokeWithOptionsCollectionsInvokeWithOptionsRequestData application/json Copy ``` { "transaction_id": "01F6NAMXWN2XVBD1YJ92A6S6R4", "request_collection_id": "01F6QF1QJF20DMSXH4SYXKB1SN", "callback_url": "https://webhook.site/3706b519-9426-4533-9868-14a7dec4fd97" } ``` application/json Copy ``` { "transaction_id": "01F6NAMXWN2XVBD1YJ92A6S6R4", "request_collection_id": "01F6QF1QJF20DMSXH4SYXKB1SN", "callback_url": "https://webhook.site/3706b519-9426-4533-9868-14a7dec4fd97", "tags": [ "manual_verification" ] } ``` application/json Copy ``` { "transaction_id": "01F6NAMXWN2XVBD1YJ92A6S6R4", "callback_url": "https://webhook.site/3706b519-9426-4533-9868-14a7dec4fd97", "request_data": { "deal_sets": { "deal_set": [ { "deals": { "deal": [ { "parties": { "party": [ { "individual": { "name": { "first": "Thomas", "last": "Alex" } }, "taxpayer_identifiers": { "taxpayer_identifier": [ { "value": "12345" } ] }, "roles": { "role": [ { "borrower": { "residences": { "residence": [ { "address": { "line_text": "street 101", "city": "example city", "state": "state", "postal_code": "1234", "street_name": "street 23" } } ] } } } ] } } ] } } ] } } ] } } } ``` application/json Copy ``` { "transaction_id": "01F6NAMXWN2XVBD1YJ92A6S6R4", "request_collection_id": "01F6QF1QJF20DMSXH4SYXKB1SN", "callback_url": "https://webhook.site/3706b519-9426-4533-9868-14a7dec4fd97", "tags": [ "manual_verification" ], "options": { "option1": "test_option" } } ``` application/json Copy ``` { "transaction_id": "01F6NAMXWN2XVBD1YJ92A6S6R4", "callback_url": "https://webhook.site/3706b519-9426-4533-9868-14a7dec4fd97", "request_data": { "deal_sets": { "deal_set": [ { "deals": { "deal": [ { "parties": { "party": [ { "individual": { "name": { "first": "Thomas", "last": "Alex" } }, "taxpayer_identifiers": { "taxpayer_identifier": [ { "value": "12345" } ] }, "roles": { "role": [ { "borrower": { "residences": { "residence": [ { "address": { "line_text": "street 101", "city": "example city", "state": "state", "postal_code": "1234", "street_name": "street 23" } } ] } } } ] } } ] } } ] } } ] } }, "tags": [ "manual_verification" ], "options": { "option1": "test_option" } } ``` ##### Response 201400403404500 application/json Copy 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" ] } ``` application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy 403 invalid error ``` { "message": "Please check the key you used to call this service", "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` text/html Copy Resource not found ``` \r\n400 Bad Request\r\n\r\n

400 Bad Request

\r\n\r\n\r\n ``` application/json Copy Internal server error ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. | ##### Request body`application/json` 6 fields | Field | Type | Description | | --- | --- | --- | | `transaction_id` | `string` | Transaction ID used for flow_invocations. | | `request_collection_id` | `string` | Request Collection ID. | | `callback_url` | `string (uri)` | Callback URL. | | `request_data` | `object` | Request JSON body for product flows. | | `tags` | `string[]` | Flow tags. | | `options` | `object` | Additional information that should be passed to the connector but not be added to the request collection. Will be passed to every product flow invocation. | ##### Response `201``application/json` 9 fields Successfully started flow invocation. | Field | Type | Description | | --- | --- | --- | | `invocation_id`required | `string` | Invocation ID. | | `invocation_status`required | `string` | The status of the invocation.`STARTED` | | `transaction_id` | `string` | Transaction ID. | | `callback_url` | `string` | Callback URL. | | `request_data` | `object` | The data for the request collection. | | `request_collection_id` | `string` | Request Collection ID. | | `tags` | `string[]` | Flow tags. | | `options` | `object` | Additional information that should be passed to the connector but not be added to the request collection. Will be passed to every product flow invocation. | | `connector_job_id` | `string` | Connector job ID. | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `403``application/json` 2 fields 403 invalid error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | | `url` | `string` | Error additional URL. | ##### Response `404``application/json` 1 fields Resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `500``application/json` 1 fields Internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | `GET` `/products/employment/waterfall/invocations/{invocation_id}` #### Retrieve Product Waterfall Invocation Status `RetrieveProductWaterfallInvocationStatus` Retrieves the status of running Product waterfall invocation. ##### Response 200 Completed200 Failed400403404500 application/json Copy 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 } } } } } ``` application/json Copy Successfully returned status of the Product Waterfall Invocation. ``` { "invocation_id": "fbc19f9b-1d37-4ced-9f1d-d2769b018b0a", "invocation_status": "FAILED", "request_collection_id": "01FCWK741N7GWYBVG4Z3N74V16", "callback_url": "https://webhook.site/68a4aa6a-bf18-4f7d-be7d-bc26503adeb2", "transaction_id": "01FCWK72GC1MFM5003SXJHMWNG", "failure_reason": "All product flows were failed.", "request_collection": { "data": { "foo": "bar", "biz": "baz" }, "metadata": { "created_at": "2021-08-12T03:11:25.749933-04:00", "validation": false }, "transaction_id": "01FCWK72GC1MFM5003SXJHMWNG", "collection_id": "01FCWK741N7GWYBVG4Z3N74V16" }, "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 } } } }, "metadata": { "actual_flow_name": "flow1" } } ``` application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy 403 invalid error ``` { "message": "Please check the key you used to call this service", "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` text/html Copy Resource not found ``` \r\n400 Bad Request\r\n\r\n

400 Bad Request

\r\n\r\n\r\n ``` application/json Copy Internal server error ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 2 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. | | `invocation_id` required | `string (ulid)` path | `d7ccedb8-8889-4657-add4-bc1s4xs97637` | Product flow invocation identifier | ##### Response `200``application/json` 11 fields Successfully returned status of the Product Waterfall Invocation. | Field | Type | Description | | --- | --- | --- | | `invocation_id`required | `string` | Invocation ID. | | `invocation_status`required | `string` | The status of the invocation.`ACTION_REQUIRED``COMPLETED``FAILED``RUNNING``STARTED` | | `transaction_id`required | `string` | Transaction ID. | | `callback_url` | `string` | Callback URL. | | `request_data` | `object` | The data for the request collection. | | `request_collection_id` | `string` | Request Collection ID. | | `request_collection` | `object` | Request Collection. | | `tags` | `string[]` | Flow tags. | | `options` | `object` | Options that were passed to the waterfall invocation. | | `flows_responses`required | `object` | Responses for each flow invocation. | | `metadata`required | `object` | Metadata of waterfall. | | `actual_flow_name` | `string` | Actual flow name invoked. | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `403``application/json` 2 fields 403 invalid error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | | `url` | `string` | Error additional URL. | ##### Response `404``application/json` 1 fields Resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `500``application/json` 1 fields Internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error 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 200400403404 GetProduct404 text/html500 application/json Copy 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" ] } ``` application/json Copy Validation Error ``` { "message": "3 is not of type 'string'. Failed validating 'type' in schema['properties']['deal_sets']['items'][0]['properties']['parties']['items'][0]['properties']['customer_transaction_ID']:" } ``` application/json Copy 403 invalid error ``` { "message": "Please check the key you used to call this service", "url": "https://api.staircase.co/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` application/json Copy Resource not found ``` { "type": "string", "description": "Error Message." } ``` text/html Copy Resource not found ``` \r\n400 Bad Request\r\n\r\n

400 Bad Request

\r\n\r\n\r\n ``` application/json Copy Internal server error ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. | ##### Response `200``application/json` 1 fields Elements were retrieved successfully | Field | Type | Description | | --- | --- | --- | | `elements`required | `string[]` | List of elements. | ##### Response `400``application/json` 1 fields Validation Error | Field | Type | Description | | --- | --- | --- | | `message` | `one of` | Message | ##### Response `403``application/json` 2 fields 403 invalid error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | | `url` | `string` | Error additional URL. | ##### Response `404``application/json` 1 fields Resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error Message. | ##### Response `500``application/json` 1 fields Internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | `GET` `/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 Copy 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 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `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 `200``400``403` `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 200400 InvalidReturnExamplesValue400 text/html403404 GetProduct404 text/html500 application/json Copy Successfully returned the list of elements needed for product waterfall. ``` { "data": {}, "metadata": {} } ``` application/json Copy Error ``` { "message": "Please provide one of valid return examples values: true, false" } ``` text/html Copy Error ``` \r\n400 Bad Request\r\n\r\n

400 Bad Request

\r\n\r\n\r\n ``` application/json Copy 403 invalid error ``` { "message": "Please check the key you used to call this service", "url": "https://api.staircase.co/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` application/json Copy Resource not found ``` { "type": "string", "description": "Error Message." } ``` text/html Copy Resource not found ``` \r\n400 Bad Request\r\n\r\n

400 Bad Request

\r\n\r\n\r\n ``` application/json Copy Internal server error ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 2 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. | | `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 `200``application/json` 1 fields Successfully returned the list of elements needed for product waterfall. | Field | Type | Description | | --- | --- | --- | | `schema` | `object` | Element key / value | ##### Response `400``application/json` 1 fields Error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `403``application/json` 2 fields 403 invalid error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | | `url` | `string` | Error additional URL. | ##### Response `404``application/json` 1 fields Resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error Message. | ##### Response `500``application/json` 1 fields Internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | `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 200403500 application/json Copy 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" ] } ``` application/json Copy Invalid key for service ``` { "message": "Your API key is not valid, please refresh it.", "url": "https://api.staircase.co/docs/Console/Console/Account/post-customer-account" } ``` application/json Copy The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used. ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 4 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `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 `200``application/json` 5 fields Company found | Field | Type | Description | | --- | --- | --- | | `Partner 1` | `string[]` | — | | `Partner 2` | `string[]` | — | | `Partner 3` | `string[]` | — | | `Partner 4` | `string[]` | — | | `Partner 5` | `string[]` | — | ##### Response `403``application/json` 2 fields Invalid key for service | Field | Type | Description | | --- | --- | --- | | `message` | `string` | — | | `url` | `string` | — | ##### Response `500``application/json` 1 fields The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used. | Field | Type | Description | | --- | --- | --- | | `message` | `string` | — | ##### Other responses `400``404` `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 Copy ``` { "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 200400403404500 application/json Copy 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" } ``` application/json Copy Error ``` { "message": "Unable to update collection. Please check the collection data" } ``` application/json Copy Invalid key for service ``` { "message": "Your API key is not valid, please refresh it.", "url": "https://api.staircase.co/docs/Console/Console/Account/post-customer-account" } ``` application/json Copy Resource not found ``` { "message": "Unable to update collection. Please check the given ids" } ``` application/json Copy The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used. ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 3 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `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 `200``application/json` 4 fields Collection updated successfully | Field | Type | Description | | --- | --- | --- | | `data` | `object` | — | | `deal_sets`required | `object` | — | | `deal_set`required | `object[]` | — | | `deals`required | `object` | — | | `document_sets` | `object` | — | | `document_set` | `object[]` | — | | `documents` | `object` | — | | `metadata` | `object` | The metadata object describes properties that a Staircase collection has | | `created_at` | `string` | ISO 8601 format with EST timezoneExample `03/03/2021, 8:24:04 AM EST` | | `updated_at` | `string` | ISO 8601 format with EST timezoneExample `03/03/2021, 8:24:04 AM EST` | | `validation` | `boolean` | Describes whether the collection has been validated against Staircase language schemaExample `false` | | `partner_name` | `string` | Staircase partner name that was used to generate the collection | | `exclude_borrower` | `boolean` | Some 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_verification` | `boolean` | This 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_sms` | `boolean` | This 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_state` | `string` | Describes the state of the operation that generated the collection`CANCELLED``COMPLETED``FAILED``IN_PROGRESS``TIME_OUT` | | `results` | `object` | Contains the results of an operation that generated the collection | | `status` | `string` | Describes the state of the operation that generated the collection`COMPLETED``ERROR``REQUEST_MADE``TIMED_OUT`Example `COMPLETED` | | `product` | `string` | Name of the Staircase product that generated the collectionExample `Employments` | | `info` | `string` | Additional info about the status | | `transaction_id` | `string (ulid)` | Staircase Transaction IdentifierExample `01F0KHK7DN3H5JZ4QJKMYAM6GB` | | `collection_id` | `string (ulid)` | Staircase Collection IdentifierExample `01F0KHKADN0HRFXMCQQXPA6AFZ` | ##### Response `400``application/json` 1 fields Error | Field | Type | Description | | --- | --- | --- | | `message` | `one of` | — | ##### Response `403``application/json` 2 fields Invalid key for service | Field | Type | Description | | --- | --- | --- | | `message` | `string` | — | | `url` | `string` | — | ##### Response `404``application/json` 1 fields Resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `500``application/json` 1 fields The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used. | Field | Type | Description | | --- | --- | --- | | `message` | `string` | — | `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 Copy ``` { "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 200400403500 application/json Copy Collection is valid ``` { "message": "Collection is valid." } ``` application/json Copy Validation Error ``` { "message": "3 is not of type 'string'. Failed validating 'type' in schema['properties']['deal_sets']['items'][0]['properties']['parties']['items'][0]['properties']['customer_transaction_id']:" } ``` application/json Copy Invalid key for service ``` { "message": "Your API key is not valid, please refresh it.", "url": "https://api.staircase.co/docs/Console/Console/Account/post-customer-account" } ``` application/json Copy The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used. ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Staircase Environment API Key | ##### Request body`application/json` 2 fields | Field | Type | Description | | --- | --- | --- | | `deal_sets`required | `object` | — | | `deal_set`required | `object[]` | — | | `deals`required | `object` | — | | `deal`required | `object[]` | — | | `document_sets` | `object` | — | | `document_set` | `object[]` | — | | `documents` | `object` | — | | `document` | `object[]` | — | ##### Response `200``application/json` 1 fields Collection is valid | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `403``application/json` 2 fields Invalid key for service | Field | Type | Description | | --- | --- | --- | | `message` | `string` | — | | `url` | `string` | — | ##### Response `500``application/json` 1 fields The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used. | Field | Type | Description | | --- | --- | --- | | `message` | `string` | — | ##### 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 200400 InvalidReturnExamplesValue400 text/html403404 GetProduct404 text/html500 application/json Copy Successfully returned the list of elements of response of the product waterfall. ``` { "data": {}, "metadata": {} } ``` application/json Copy Error ``` { "message": "Please provide one of valid return examples values: true, false" } ``` text/html Copy Error ``` \r\n400 Bad Request\r\n\r\n

400 Bad Request

\r\n\r\n\r\n ``` application/json Copy 403 invalid error ``` { "message": "Please check the key you used to call this service", "url": "https://api.staircase.co/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` application/json Copy Resource not found ``` { "type": "string", "description": "Error Message." } ``` text/html Copy Resource not found ``` \r\n400 Bad Request\r\n\r\n

400 Bad Request

\r\n\r\n\r\n ``` application/json Copy Internal server error ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 2 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. | | `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 `200``application/json` 1 fields Successfully returned the list of elements of response of the product waterfall. | Field | Type | Description | | --- | --- | --- | | `schema` | `object` | Element key / value element | ##### Response `400``application/json` 1 fields Error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `403``application/json` 2 fields 403 invalid error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | | `url` | `string` | Error additional URL. | ##### Response `404``application/json` 1 fields Resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error Message. | ##### Response `500``application/json` 1 fields Internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | ### 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 Copy ``` { "label": "first_transaction", "callback_url": "https://webhook.site/0c1c4e00-79d9-490b-a0f3-bab8b12a61d5" } ``` ##### Response 201403500 application/json Copy Transaction created successfully ``` { "transaction_id": "01F0KHK7DN3H5JZ4QJKMYAM6GB", "created_at": "03/04/2021, 1:04:05 PM EST" } ``` application/json Copy 403 invalid error ``` { "message": "Please check the key you used to call this service", "url": "https://api.staircase.co/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` application/json Copy Internal server error ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. | ##### Request body`application/json` 2 fields | Field | Type | Description | | --- | --- | --- | | `callback_url` | `string (url)` | URL for receiving events about changes inside transaction | | `label` | `string` | Transaction label | ##### Response `201``application/json` 2 fields Transaction created successfully | Field | Type | Description | | --- | --- | --- | | `transaction_id` | `string (ulid)` | Staircase Transaction IdentifierExample `01F0KHK7DN3H5JZ4QJKMYAM6GB` | | `created_at` | `string` | Staircase time string.Example `03/03/2021, 8:24:04 AM EST` | ##### Response `403``application/json` 2 fields 403 invalid error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | | `url` | `string` | Error additional URL. | ##### Response `500``application/json` 1 fields Internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | ##### Other responses `400` `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 200400403404 GetProduct404 text/html500 application/json Copy 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" ] } ``` application/json Copy Validation Error ``` { "message": "3 is not of type 'string'. Failed validating 'type' in schema['properties']['deal_sets']['items'][0]['properties']['parties']['items'][0]['properties']['customer_transaction_ID']:" } ``` application/json Copy 403 invalid error ``` { "message": "Please check the key you used to call this service", "url": "https://api.staircase.co/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` application/json Copy Resource not found ``` { "type": "string", "description": "Error Message." } ``` text/html Copy Resource not found ``` \r\n400 Bad Request\r\n\r\n

400 Bad Request

\r\n\r\n\r\n ``` application/json Copy Internal server error ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. | ##### Response `200``application/json` 1 fields Elements were retrieved successfully | Field | Type | Description | | --- | --- | --- | | `elements`required | `string[]` | List of elements. | ##### Response `400``application/json` 1 fields Validation Error | Field | Type | Description | | --- | --- | --- | | `message` | `one of` | Message | ##### Response `403``application/json` 2 fields 403 invalid error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | | `url` | `string` | Error additional URL. | ##### Response `404``application/json` 1 fields Resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error Message. | ##### Response `500``application/json` 1 fields Internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | `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. 1. Place the output from Retrieve Request Elements into the Build JSON Payload request body. 1. Place your api_key into the Build JSON Payload header. 1. 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: 1. Invoke Retrieve Response Elements to get an array of employment verification response elements. 1. Place the output from Retrieve Response Elements into the Build JSON Payload request body. 1. Place your api_key into the Build JSON Payload header. 1. 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 Copy ``` { "$.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 200400403500 application/json Copy 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" } ] } } ] } } ] } } ``` application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy Invalid key for service ``` { "message": "Your API key is not valid, please refresh it.", "url": "https://api.staircase.co/docs/Console/Console/Account/post-customer-account" } ``` application/json Copy The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used. ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Staircase Environment API Key | ##### Request body`application/json` 2 fields | Field | Type | Description | | --- | --- | --- | | `path` | `string` | Contains the path in Staircase language | | `value` | `string` | Enter your own values here | ##### Response `200``application/json` 2 fields Employment Verification Payload. | Field | Type | Description | | --- | --- | --- | | `deal_sets` | `object` | — | | `deal_set` | `object[]` | — | | `deals` | `object` | — | | `deal` | `object[]` | — | | `document_sets` | `object` | — | | `document_set` | `object[]` | — | | `documents` | `object` | — | | `document` | `object[]` | — | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `403``application/json` 2 fields Invalid key for service | Field | Type | Description | | --- | --- | --- | | `message` | `string` | — | | `url` | `string` | — | ##### Response `500``application/json` 1 fields The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used. | Field | Type | Description | | --- | --- | --- | | `message` | `string` | — | `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 Copy ``` Select option 'binary' in order to upload file ``` ##### Response 201403500 application/json Copy Blob uploaded ``` { "blob_id": "01EZY9J8SEFM2JKDJ1Q3YX65HS" } ``` application/json Copy 403 invalid error ``` { "message": "Please check the key you used to call this service", "url": "https://api.staircase.co/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` application/json Copy Internal server error ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. | ##### Response `201``application/json` 1 fields Blob uploaded | Field | Type | Description | | --- | --- | --- | | `blob_id` | `string` | Created blob ID | ##### Response `403``application/json` 2 fields 403 invalid error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | | `url` | `string` | Error additional URL. | ##### Response `500``application/json` 1 fields Internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | ##### Other responses `400``405``422` `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. 1. 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. 1. 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 Copy ``` { "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 201400403404500 application/json Copy 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" } ] } } ] } } ] } } ``` application/json Copy Error ``` { "message": "Unable to create collection. Please check the collection data" } ``` application/json Copy Invalid key for service ``` { "message": "Your API key is not valid, please refresh it.", "url": "https://api.staircase.co/docs/Console/Console/Account/post-customer-account" } ``` application/json Copy Resource not found ``` { "message": "Unable to create collection. Please check the transaction Id" } ``` application/json Copy The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used. ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 2 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Staircase Environment API Key | | `transaction_id` required | `string (ulid)` path | `01F0KHK7DN3H5JZ4QJKMYAM6GB` | Staircase Transaction Identifier | ##### Response `201``application/json` 4 fields Collection created successfully | Field | Type | Description | | --- | --- | --- | | `data` | `object` | — | | `deal_sets`required | `object` | — | | `deal_set`required | `object[]` | — | | `deals`required | `object` | — | | `document_sets` | `object` | — | | `document_set` | `object[]` | — | | `documents` | `object` | — | | `metadata` | `object` | The metadata object describes properties that a Staircase collection has | | `created_at` | `string` | ISO 8601 format with EST timezoneExample `03/03/2021, 8:24:04 AM EST` | | `updated_at` | `string` | ISO 8601 format with EST timezoneExample `03/03/2021, 8:24:04 AM EST` | | `validation` | `boolean` | Describes whether the collection has been validated against Staircase language schemaExample `false` | | `partner_name` | `string` | Staircase partner name that was used to generate the collection | | `exclude_borrower` | `boolean` | Some 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_verification` | `boolean` | This 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_sms` | `boolean` | This 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_state` | `string` | Describes the state of the operation that generated the collection`CANCELLED``COMPLETED``FAILED``IN_PROGRESS``TIME_OUT` | | `results` | `object` | Contains the results of an operation that generated the collection | | `status` | `string` | Describes the state of the operation that generated the collection`COMPLETED``ERROR``REQUEST_MADE``TIMED_OUT`Example `COMPLETED` | | `product` | `string` | Name of the Staircase product that generated the collectionExample `Employments` | | `info` | `string` | Additional info about the status | | `transaction_id` | `string (ulid)` | Staircase Transaction IdentifierExample `01F0KHK7DN3H5JZ4QJKMYAM6GB` | | `collection_id` | `string (ulid)` | Staircase Collection IdentifierExample `01F0KHKADN0HRFXMCQQXPA6AFZ` | ##### Response `400``application/json` 1 fields Error | Field | Type | Description | | --- | --- | --- | | `message` | `one of` | — | ##### Response `403``application/json` 2 fields Invalid key for service | Field | Type | Description | | --- | --- | --- | | `message` | `string` | — | | `url` | `string` | — | ##### Response `404``application/json` 1 fields Resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `500``application/json` 1 fields The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used. | Field | Type | Description | | --- | --- | --- | | `message` | `string` | — | `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. 1. Create a Transaction and receive a transaction_id in the response. 1. Create a Collection and receive a collection_id in the response. 1. 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. 1. Call Verify Employment and receive the response. 1. 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. 1. Check the status of the verification by calling Retrieve Status. 1. After the response from Retrieve Status contains the status COMPLETED, retrieve the output collection by calling Retrieve Collection. 1. 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 1. "Uber" for Atomic data partner 1. "Amazon" for Equifax and Meridian data partners (if "waterfall" feature is enabled, partner is selected based on the partner ordering) 1. "Fair port Little League Inc." for Pinwheel data partner 1. "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 InvokeByFlowNameInvokeByTagsInvokeWithRequestDataInvokeWithFlowOptionsCollectionsInvokeWithFlowOptionsRequestDataInvokeByFlowNameOptionsInvokeByVendorNameOptionsInvokeWaterfall application/json Copy ``` { "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": {} } ``` application/json Copy ``` { "transaction_id": "01F6NAMXWN2XVBD1YJ92A6S6R4", "response_collection_id": "01F6NAQ4894HPMCBGB4P0G95XK", "request_collection_id": "01F6QF1QJF20DMSXH4SYXKB1SN", "callback_url": "https://webhook.site/3706b519-9426-4533-9868-14a7dec4fd97", "tags": [ "manual_verification" ] } ``` application/json Copy ``` { "product_flow_name": "get-document-from-byte", "transaction_id": "01F6NAMXWN2XVBD1YJ92A6S6R4", "response_collection_id": "01F6NAQ4894HPMCBGB4P0G95XK", "callback_url": "https://webhook.site/3706b519-9426-4533-9868-14a7dec4fd97", "request_data": { "deal_sets": { "deal_set": [ { "deals": { "deal": [ { "parties": { "party": [ { "individual": { "name": { "first": "Thomas", "last": "Alex" } }, "taxpayer_identifiers": { "taxpayer_identifier": [ { "value": "12345" } ] }, "roles": { "role": [ { "borrower": { "residences": { "residence": [ { "address": { "line_text": "street 101", "city": "example city", "state": "state", "postal_code": "1234", "street_name": "street 23" } } ] } } } ] } } ] } } ] } } ] } } } ``` application/json Copy ``` { "transaction_id": "01F6NAMXWN2XVBD1YJ92A6S6R4", "response_collection_id": "01F6NAQ4894HPMCBGB4P0G95XK", "request_collection_id": "01F6QF1QJF20DMSXH4SYXKB1SN", "callback_url": "https://webhook.site/3706b519-9426-4533-9868-14a7dec4fd97", "tags": [ "manual_verification" ], "options": { "option1": "test_option" } } ``` application/json Copy ``` { "transaction_id": "01F6NAMXWN2XVBD1YJ92A6S6R4", "response_collection_id": "01F6NAQ4894HPMCBGB4P0G95XK", "callback_url": "https://webhook.site/3706b519-9426-4533-9868-14a7dec4fd97", "request_data": { "deal_sets": { "deal_set": [ { "deals": { "deal": [ { "parties": { "party": [ { "individual": { "name": { "first": "Thomas", "last": "Alex" } }, "taxpayer_identifiers": { "taxpayer_identifier": [ { "value": "12345" } ] }, "roles": { "role": [ { "borrower": { "residences": { "residence": [ { "address": { "line_text": "street 101", "city": "example city", "state": "state", "postal_code": "1234", "street_name": "street 23" } } ] } } } ] } } ] } } ] } } ] } }, "tags": [ "manual_verification" ], "options": { "option1": "test_option" } } ``` application/json Copy ``` { "product_flow_name": "get-document-from-byte", "transaction_id": "01F6NAMXWN2XVBD1YJ92A6S6R4", "request_collection_id": "01F6QF1QJF20DMSXH4SYXKB1SN", "response_collection_id": "01F6NAQ4894HPMCBGB4P0G95XK", "callback_url": "https://webhook.site/3706b519-9426-4533-9868-14a7dec4fd97", "options": { "option1": "test_option" } } ``` application/json Copy ``` { "vendor_name": "argyle", "transaction_id": "01F6NAMXWN2XVBD1YJ92A6S6R4", "request_collection_id": "01F6QF1QJF20DMSXH4SYXKB1SN", "response_collection_id": "01F6NAQ4894HPMCBGB4P0G95XK", "callback_url": "https://webhook.site/3706b519-9426-4533-9868-14a7dec4fd97", "options": { "option1": "test_option" } } ``` application/json Copy ``` { "transaction_id": "01F6NAMXWN2XVBD1YJ92A6S6R4", "request_collection_id": "01F6QF1QJF20DMSXH4SYXKB1SN", "response_collection_id": "01F6NAQ4894HPMCBGB4P0G95XK", "callback_url": "https://webhook.site/3706b519-9426-4533-9868-14a7dec4fd97", "invocation_mode": "waterfall" } ``` ##### Response 201400403404500 application/json Copy 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" ] } ``` application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy 403 invalid error ``` { "message": "Please check the key you used to call this service", "url": "https://api.staircase.co/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` text/html Copy Resource not found ``` \r\n400 Bad Request\r\n\r\n

400 Bad Request

\r\n\r\n\r\n ``` application/json Copy Internal server error ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. | ##### Request body`application/json` 10 fields | Field | Type | Description | | --- | --- | --- | | `product_flow_name` | `string` | Product flow name. If it is not specified, the default product flow will be invoked. If the product has no default product flow, the first created flow will be invoked. Cannot be specified together with vendor_name. | | `vendor_name` | `string` | Vendor name. Cannot be specified together with product_flow_name. | | `transaction_id` | `string` | Transaction ID used for invocation. | | `request_collection_id` | `string` | Request Collection ID. | | `response_collection_id` | `string` | Response Collection ID. | | `callback_url` | `string (uri)` | Callback URL. | | `request_data` | `object` | Request JSON body. | | `tags` | `string[]` | List of tags. | | `options` | `object` | Additional information that should be passed to the connector but not be added to the request collection. | | `invocation_mode` | `string` | The invocation mode of a product flow single_flow or waterfall, default value single_flow | ##### Response `201``application/json` 11 fields Successfully started flow invocation. | Field | Type | Description | | --- | --- | --- | | `invocation_id`required | `string` | Invocation ID. | | `invocation_status`required | `string` | The status of the invocation.`STARTED` | | `transaction_id`required | `string` | Transaction ID. | | `reuest_collection_id`required | `string` | Request collection ID. | | `response_collection_id`required | `string` | Response collection ID. | | `product_flow_name` | `string` | Product flow name. | | `metadata` | `object` | The metadata of the invoked product flow. | | `callback_url` | `string` | Callback URL. | | `request_data` | `object` | The data for the request collection. | | `tags` | `string[]` | List of tags. | | `options` | `object` | Additional information that should be passed to the connector but not be added to the request collection. | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `one of` | Message | ##### Response `403``application/json` 2 fields 403 invalid error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | | `url` | `string` | Error additional URL. | ##### Response `404``application/json` 1 fields Resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `500``application/json` 1 fields Internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | `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 Copy ``` { "data": {}, "metadata": {} } ``` ##### Response 200400403404 GetProduct404 text/html500 application/json Copy Collection is valid ``` { "message": "Collection is valid." } ``` application/json Copy Validation Error ``` { "message": "3 is not of type 'string'. Failed validating 'type' in schema['properties']['deal_sets']['items'][0]['properties']['parties']['items'][0]['properties']['customer_transaction_ID']:" } ``` application/json Copy 403 invalid error ``` { "message": "Please check the key you used to call this service", "url": "https://api.staircase.co/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` application/json Copy Resource not found ``` { "type": "string", "description": "Error Message." } ``` text/html Copy Resource not found ``` \r\n400 Bad Request\r\n\r\n

400 Bad Request

\r\n\r\n\r\n ``` application/json Copy Internal server error ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. | ##### Request body`application/json` 1 fields | Field | Type | Description | | --- | --- | --- | | `deal_sets` | `object` | Deal sets object. | | `deal_set` | `object[]` | Deal set object. | | `deals` | `object` | Deals object. | | `deal` | `object[]` | Deal array. | ##### Response `200``application/json` 1 fields Collection is valid | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `400``application/json` 1 fields Validation Error | Field | Type | Description | | --- | --- | --- | | `message` | `one of` | Message | ##### Response `403``application/json` 2 fields 403 invalid error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | | `url` | `string` | Error additional URL. | ##### Response `404``application/json` 1 fields Resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error Message. | ##### Response `500``application/json` 1 fields Internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | `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 Copy ``` { "transaction_id": "42u3784-324123-41234-21234", "collection_id": "42u3784-324123-41234-21234" } ``` ##### Response 200403500502 application/json Copy Cancel employment verification triggered ``` { "message": "Cancel employment verification request is succesfully taken" } ``` application/json Copy Invalid key for service ``` { "message": "Your API key is not valid, please refresh it.", "url": "https://api.staircase.co/docs/Console/Console/Account/post-customer-account" } ``` application/json Copy The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used. ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` application/json Copy Bad gateway. ``` { "message": "Internal server error." } ``` ##### Parameters 1 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Staircase Environment API Key | ##### Request body`application/json` 2 fields | Field | Type | Description | | --- | --- | --- | | `transaction_id`required | `string (ulid)` | Staircase Transaction IdentifierExample `01F0KHK7DN3H5JZ4QJKMYAM6GB` | | `collection_id`required | `string (ulid)` | Staircase Collection IdentifierExample `01F0KHKADN0HRFXMCQQXPA6AFZ` | ##### Response `200``application/json` 1 fields Cancel employment verification triggered | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Example `Cancel employment verification request is successfully taken` | ##### Response `403``application/json` 2 fields Invalid key for service | Field | Type | Description | | --- | --- | --- | | `message` | `string` | — | | `url` | `string` | — | ##### Response `500``application/json` 1 fields The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used. | Field | Type | Description | | --- | --- | --- | | `message` | `string` | — | ##### Response `502``application/json` 1 fields Bad gateway. | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error Message. | ##### Other responses `400``404` `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 200400403404500 application/json Copy 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 } ``` application/json Copy Request data failed validation ``` { "message": "{'data': ['Missing data for required field.']}" } ``` application/json Copy 403 invalid error ``` { "message": "Please check the key you used to call this service", "url": "https://api.staircase.co/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` text/html Copy Resource not found ``` \r\n400 Bad Request\r\n\r\n

400 Bad Request

\r\n\r\n\r\n ``` application/json Copy Internal server error ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 3 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. | | `transaction_id` required | `string (ulid)` path | `01F0KHK7DN3H5JZ4QJKMYAM6GB` | Staircase Transaction Identifier | | `collection_id` required | `string (ulid)` path | `01F0KHKADN0HRFXMCQQXPA6AFZ` | Staircase collection_id | ##### Response `200``application/json` 6 fields Successfully returned status of the Product Waterfall Invocation. | Field | Type | Description | | --- | --- | --- | | `status` | `string` | Mapped status of the invocation.Example `STARTED` | | `message` | `string` | Message.Example `Verification is completed, please check response collection to see verification data.` | | `created_at` | `string` | Time of creation | | `invocation_status` | `string` | Status of the product invocation before mapping | | `last_updated_at` | `string` | Last time the collection was updated | | `service_invocation` | `object` | Includes underlying services invocation. | | `Connector` | `object` | Response from Connector service. | | `connector_flow_name` | `string` | Vendor flow name. | | `invocation_id` | `string (uuid)` | Connector job ID. | | `status` | `string` | Connector flow status.`ACTION_REQUIRED``COMPLETED``FAILED``RUNNING` | | `Translator` | `object` | Response from Translator service about input and output translation. | | `input` | `object` | Input translation status. | | `language_name` | `string` | Input translation language. | | `translation_id` | `string (uuid)` | Translation ID. | | `status` | `string` | Input translation status.`COMPLETED``FAILED``RUNNING` | | `convert_input` | `object` | Convert input translation status. | | `language_name` | `string` | Input translation language. | | `translation_id` | `string (uuid)` | Translation ID. | | `status` | `string` | Input translation status.`COMPLETED``FAILED``RUNNING` | | `output` | `object` | Output translation status. | | `language_name` | `string` | Output translation language. | | `translation_id` | `string (uuid)` | Translation ID. | | `status` | `string` | Output translation status.`COMPLETE``FAILED``RUNNING` | | `convert_output` | `object` | Convert output translation status. | | `language_name` | `string` | Output translation language. | | `translation_id` | `string (uuid)` | Translation ID. | | `status` | `string` | Output translation status.`COMPLETE``FAILED``RUNNING` | ##### Response `400``application/json` 1 fields Request data failed validation | Field | Type | Description | | --- | --- | --- | | `message` | `one of` | Message | ##### Response `403``application/json` 2 fields 403 invalid error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | | `url` | `string` | Error additional URL. | ##### Response `404``application/json` 1 fields Resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `500``application/json` 1 fields Internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | `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 200403 application/json Copy Presigned URLs retrieved successfully. ``` { "upload": { "url": "https://dev-data-manager-blobs-bucket.s3.amazonaws.com/01EZY9J8SEFM2JKDJ1Q3YX65HS" } } ``` application/json Copy 403 invalid error ``` { "message": "Please check the key you used to call this service", "url": "https://api.staircase.co/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` ##### Parameters 2 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. | | `blob_id` required | `string` path | `01EZY9J8SEFM2JKDJ1Q3YX65HS` | Blob identifier | ##### Response `200``application/json` 1 fields Presigned URLs retrieved successfully. | Field | Type | Description | | --- | --- | --- | | `presigned_urls` | `object` | Presigned URLs | ##### Response `403``application/json` 2 fields 403 invalid error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | | `url` | `string` | Error additional URL. | ##### Other responses `400``404` `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 200400 BadRequestResp400 NoReportFound403500 application/json Copy Report URL retrieved successfully ``` { "url": "www.domain.com/reportURL" } ``` application/json Copy Bad Request ``` { "message": "Blod ID is not valid or not provided" } ``` application/json Copy Bad Request ``` { "message": "No report found for this blob_id" } ``` application/json Copy Invalid key for service ``` { "message": "Your API key is not valid, please refresh it.", "url": "https://api.staircase.co/docs/Console/Console/Account/post-customer-account" } ``` application/json Copy The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used. ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 2 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-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 `200``application/json` 1 fields Report URL retrieved successfully | Field | Type | Description | | --- | --- | --- | | `url` | `string` | Report URL | ##### Response `400``application/json` 1 fields Bad Request | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Partner not found | ##### Response `403``application/json` 2 fields Invalid key for service | Field | Type | Description | | --- | --- | --- | | `message` | `string` | — | | `url` | `string` | — | ##### Response `500``application/json` 1 fields The product has encountered an internal server error. If possible, please contact Staircase support with the transaction_id you used. | Field | Type | Description | | --- | --- | --- | | `message` | `string` | — | ### 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 200400403404500 application/json Copy 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": {} } ] ``` text/html Copy Error ``` \r\n400 Bad Request\r\n\r\n

400 Bad Request

\r\n\r\n\r\n ``` application/json Copy 403 invalid error ``` { "message": "Please check the key you used to call this service", "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` application/json Copy Resource not found ``` { "message": "Unable to get collections of given transaction. Please check the transaction id" } ``` application/json Copy Internal server error ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 2 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. | | `transaction_id` required | `string (ulid)` path | `01F0KHK7DN3H5JZ4QJKMYAM6GB` | Staircase Transaction Identifier | ##### Response `200``application/json` 4 fields Transaction collection retrieved successfully | Field | Type | Description | | --- | --- | --- | | `transaction_id` | `string (ulid)` | Transaction idExample `01EZQ32PJQGKRA6HR8D72Q9FFF` | | `collection_id` | `string (ulid)` | Collection idExample `01EZQ32PJQGKRA6HR8D72Q9FFF` | | `data` | `array` | — | | `metadata` | `object` | Metadata about collection, f.e version of used Staircase schema | ##### Response `400``application/json` 1 fields Error | Field | Type | Description | | --- | --- | --- | | `message` | `one of` | Either message object with more properties. | ##### Response `403``application/json` 2 fields 403 invalid error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | | `url` | `string` | Error additional URL. | ##### Response `404``application/json` 1 fields Resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `500``application/json` 1 fields Internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | `GET` `/transactions/{transaction_id}/collections/{collection_id}` #### Retrieve Collection `retrieveCollection` Retrieve Collection returns the content of a given `collection_id` associated with a `transaction_id`. ##### Response 200403404 GetCollectionError404 GetCollectionsError500 application/json Copy Successfully Retrieved Collection ``` { "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": {} } ``` application/json Copy 403 invalid error ``` { "message": "Please check the key you used to call this service", "url": "https://staircase.stoplight.io/docs/api-reference/customer-account-manager-service.yml/paths/~1products~1refresh/post" } ``` application/json Copy Resource not found ``` { "message": "Unable to get collection. Please check the given ids" } ``` application/json Copy Resource not found ``` { "message": "Unable to get collections of given transaction. Please check the transaction id" } ``` application/json Copy Internal server error ``` { "message": "The product has encountered an internal server error. If you have used a transaction_id to call our services, please submit it to Staircase support" } ``` ##### Parameters 3 | Parameter | Type | Example | Description | | --- | --- | --- | --- | | `x-api-key` required | `string` header | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Environment API Key. | | `transaction_id` required | `string (ulid)` path | `01F0KHK7DN3H5JZ4QJKMYAM6GB` | Staircase Transaction Identifier | | `collection_id` required | `string (ulid)` path | `01F0KHKADN0HRFXMCQQXPA6AFZ` | Staircase collection_id | ##### Response `200``application/json` 2 fields Successfully Retrieved Collection | Field | Type | Description | | --- | --- | --- | | `data` | `object` | — | | `deal_sets` | `object` | — | | `deal_set` | `object[]` | — | | `deals` | `object` | — | | `document_sets` | `object` | — | | `document_set` | `object[]` | — | | `documents` | `object` | — | | `metadata` | `—` | — | ##### Response `403``application/json` 2 fields 403 invalid error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | | `url` | `string` | Error additional URL. | ##### Response `404``application/json` 1 fields Resource not found | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Message | ##### Response `500``application/json` 1 fields Internal server error | Field | Type | Description | | --- | --- | --- | | `message` | `string` | Error message. | ##### Other responses `400` ### Operations `POST` `/employment/webhook` #### Webhook to accept callback from TrueWork ##### Response `200``application/json` 1 fields 200 response | Field | Type | Description | | --- | --- | --- | | `values` | `object` | — | | `code` | `number` | — | | `payload` | `object` | — | ##### Other responses `403` `POST` `/extractor/webhook` #### Webhook to accept callback from Ocrolus ##### Response `200``application/json` 1 fields 200 response | Field | Type | Description | | --- | --- | --- | | `values` | `object` | — | | `code` | `number` | — | | `payload` | `object` | — | ##### 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 1. Argyle 1. Atomic 1. Wage 1. Finicity 1. Experian 1. Pinwheel 1. Citadel 1. Equifax 1. Truework 1. Truework Also integrated for this product, outside the committed ordering: - Truv ## Field mapping | Provider | Flow | Canonical in | Vendor in | Vendor out | Canonical out | | --- | --- | --- | --- | --- | --- | | Argyle | `income` | `staircase-graph` | `income-input` | `income-argyle-output` | `staircase-graph` | ## Errors `400``403``404``405``422``500``502` ## More in Verification - Previous product: Credit - Next product: Identity