Boarding

Moving a closed loan into a servicer's system of record.

Boarding is a translation problem with a deadline. A servicer expects the loan in its own format, with its own required fields, within a defined window after closing — and a rejected board is manual work at the least convenient moment.

The product maps the canonical loan record into the servicer's expected shape, submits it, and returns the acknowledgment or the rejection with the field-level reasons.

How it works

The mapping is a language configuration like any vendor mapping, which means a new servicer is a configuration rather than a code change. The general mechanism is documented under Translation.

Operations

Workflow

POST /import

Import

importLoans

Import loans from client's environment

Boarding supports the import of loan documents from Google Cloud storage and SFTP. Boarding expects your loans to be organized in a certain way. All documents in a loan should be in the same folder, a loan folder. The loan folder's name will be used as a loan identifier. All the loan folders should be in the same parent folder.

If you are going to import unclassified loans, set "import_classified_documents" to false. Then, the only required field is "loan_file_path" which maps the path for the loans.

Show the rest

If you are going to import classified loans, set "import_classified_documents" to true. Then, the import request body must specify the mapping for loan documents. All mapping files should be in the same folder, a mapping folder. The mapping folder and loan folder should be in the same parent folder. The mapping folder should contain CSV files that describe the document types and document paths (with respect to loan folder mentioned above). Also, as part of the import request body, it provides the document type mapping language for converting given document types to Staircase document types. User can create own language from here: Language Product This language should contain 1-1 mapping between user document type and Staircase document type.

In Google Cloud platform type; there is an additional field called loan_ids. With this field; user can specify the loan ids that needs to imported in loan file path.

This API supports using batch configuration. Instead of inputting all required information; you can input "batch_id" and it will use the import configuration that given batch contains. Note that batch configuration will override the other input. Batch configuration can be created from here: Create Batch

The API will return an execution id for successful requests. To see the results use Get Operation Result

Request

application/json

{
  "platform": "google_cloud",
  "batch_info": {
    "import_classified_documents": true,
    "bucket_name": "test_bucket_staircase",
    "loan_file_path": "f2022-04-12/initial_onboarding_docs",
    "document_type_file_path": "f2022-04-12/output_docs/onboarding_input_document_tag_files",
    "document_type_mapping_language": "doctype_to_staircase"
  }
}

application/json

{
  "platform": "google_cloud",
  "batch_info": {
    "import_classified_documents": true,
    "bucket_name": "test_bucket_staircase",
    "loan_file_path": "f2022-04-12/initial_onboarding_docs",
    "document_type_file_path": "f2022-04-12/output_docs/onboarding_input_document_tag_files",
    "document_type_mapping_language": "doctype_to_staircase",
    "loan_ids": [
      1001,
      1002,
      1003
    ]
  }
}

application/json

{
  "platform": "google_drive",
  "batch_info": {
    "import_classified_documents": true,
    "folder_name": "test_folder",
    "loan_file_path": "loans",
    "document_type_file_path": "mappings",
    "document_type_mapping_language": "doctype_to_staircase"
  }
}

application/json

{
  "platform": "sftp",
  "batch_info": {
    "import_classified_documents": true,
    "user_name": "user",
    "loan_file_path": "example_batch_folder/loan_folder",
    "document_type_file_path": "example_batch_folder/mapping_folder",
    "document_type_mapping_language": "doctype_to_staircase"
  }
}

application/json

{
  "platform": "sftp_client",
  "batch_info": {
    "import_classified_documents": false,
    "loan_file_path": "example_batch_folder/loan_folder",
    "sftp_url": "sftp_server_url",
    "sftp_user_name": "sftp_user_name",
    "sftp_password": "sftp_password",
    "folder_name": "folder_name"
  }
}

Response

application/json

Successfully returned status of import request

{
  "code": 200,
  "message": {
    "execution_id": "01G3BC9MPZH4M0XQ45X6D1EA2V"
  }
}

Parameters

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
`platform`	`string`	The platform where the loan documents exist`google_cloudgoogle_drivesftpsftp_client`
`batch_info`	`object`	Information needed to import batch
`bucket_name`	`string`	Google Cloud storage bucket name
`loan_file_path`	`string`	The path of the folder that contains loan folders
`doc_type_file_path`	`string`	The path of the folder that contains mapping files in CSV format
`loan_ids`	`string[]`	If you only want to import specific loan ids, you can filter out rest of them with using this field

Response `200application/json`

2 fields

Successfully returned status of import request

Field	Type	Description
`code`	`string`	Status code
`message`	`object`	message
`execution_id`	`string`	Execution id of the operation

Response `400application/json`

1 fields

Request data failed validation

Field	Type	Description
`error`	`object`	Unprocessed entity error.
`code`required	`string`	Error name.
`message`required	`string`	Error description.

Response `422application/json`

1 fields

Unprocessed Entity

Field	Type	Description
`error`	`object`	Unprocessed entity error.
`code`required	`string`	Error name.
`message`required	`string`	Error description.

POST /onboard

Onboard

onboardLoan

Process a loan

Onboard invokes an automated process that turns raw loan documents into onboarded loan data for mortgage servicing systems.

To invoke Onboard, you will need:

For each loan, a transaction_id. The transaction_id needs to imported from a data source and must contain loan identifier information along with loan documents.
If you want to use ml, the "ml_enabled" field should be true; otherwise set it to false.
If you want to use labeling, "labeling_enabled" field should be true; otherwise set it to false.
If you want to use Staircase Classification, "classify_enabled" field should be true; otherwise set it to false.
For the "operation_type" field, select "extraction" and "classification_and_extraction"
"delay_between_transactions" is an optional field and default delay time is 10 seconds. If you provide input for this field, Boarding will use this time value to create a delay between transactions.
"fast_ml_option_enabled" is an optional field for ML product and default value is false. If it's true, it will use dedicated endpoints for ML
"fields_to_label" is optional field for Labeling product to filter what should be on Labeling UI to label for given document type. For reviewing all available fields for labeling, you can check product overview: Overview

Once you have a transaction_id (or multiple transaction ids) which contains loan data, you can send them as part of the transaction_ids request body object.

Show the rest

This API supports using batch configuration. Instead of inputting all required information; you can input "batch_id" and it will use the onboard configuration that given batch contains. Note that batch configuration will override the other input. Batch configuration can be created from here: Create Batch

Example input with extraction operation type:

 {
 "transaction_ids": [
 "01FYXZWD3JE1ZX9J0MR35RC8XM"
 ],
 "request_payload": {
 "ml_enabled": true,
 "labeling_enabled": true,
 "operation_type": "extraction"
 }
 }

Example input with classification and extraction operation type, the user needs to select classification partner; available partners are ephesoft and documentai:

 {
 "transaction_ids": [
 "01FYXZWD3JE1ZX9J0MR35RC8XM"
 ],
 "request_payload": {
 "selected_classification_partners": [
 "documentai",
 "ephesoft"
 ]
 "ml_enabled": true,
 "labeling_enabled": true,
 "classify_enabled": true,
 "operation_type": "classification_and_extraction"
 }
 }

Example input with batch_id:

 {
 "transaction_ids": [
 "01FYXZWD3JE1ZX9J0MR35RC8XM"
 ],
 "batch_id": "batch_id"
 }

Example input with extraction operation type with fields_to_label:

 {
 "transaction_ids": [
 "01FYXZWD3JE1ZX9J0MR35RC8XM"
 ],
 "request_payload": {
 "ml_enabled": true,
 "labeling_enabled": true,
 "operation_type": "extraction",
 "fields_to_label": {
 "bank_statement": [
 "Checking_Account_Checks_Paid",
 "Savings_Account_No",
 "Savings_Account_Name",
 "Savings_Account_Deposits_And_Additions",
 "Checking_Account_Fees"
 ]
 }
 }
 }

View the status of the onboarded transactions using Status.

Request

application/json

{
  "transaction_ids": [
    "01FYXZWD3JE1ZX9J0MR35RC8XM"
  ],
  "request_payload": {
    "ml_enabled": true,
    "labeling_enabled": false,
    "operation_type": "extraction"
  }
}

application/json

{
  "transaction_ids": [
    "01FYXZWD3JE1ZX9J0MR35RC8XM"
  ],
  "request_payload": {
    "ml_enabled": true,
    "labeling_enabled": false,
    "classify_enabled": false,
    "operation_type": "classification_and_extraction",
    "selected_classification_partners": [
      "ephesoft"
    ]
  }
}

application/json

{
  "transaction_ids": [
    "01GGCT4ZZRSSDXD5SS8F0522CB"
  ],
  "request_payload": {
    "delay_between_transactions": 15,
    "ml_enabled": false,
    "labeling_enabled": true,
    "operation_type": "extraction",
    "fields_to_label": {
      "bank_statement": [
        "Checking_Account_Checks_Paid",
        "Savings_Account_No",
        "Savings_Account_Name",
        "Savings_Account_Deposits_And_Additions",
        "Checking_Account_Fees"
      ]
    }
  }
}

Response

application/json

Request data failed validation

{
  "code": 400,
  "message": "Bad Request"
}

Parameters

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

Request body`application/json`

2 fields

Field	Type	Description
`transaction_ids`	`string[]`	Transaction IDs for the loans that you imported and want to onboard
`request_payload`	`object`	Request payload for onboard
`delay_between_transactions`	`integer`	Delay information
`ml_enabled`	`boolean`	ML information
`labeling_enabled`	`boolean`	Labeling information
`classify_enabled`	`boolean`	Staircase classification information
`automatic_training_enabled`	`boolean`	Automatic training information
`operation_type`	`string`	Operation type selection`classification_and_extractionextraction`
`selected_classification_partners`	`string[]`	Selected classification partners

Response `200application/json`

1 fields

Response collection

Field	Type	Description
`message`	`string`	Onboard result message

Response `400application/json`

1 fields

Request data failed validation

Field	Type	Description
`error`	`object`	Unprocessed entity error.
`code`required	`string`	Error name.
`message`required	`string`	Error description.

Response `422application/json`

1 fields

Unprocessed Entity

Field	Type	Description
`error`	`object`	Unprocessed entity error.
`code`required	`string`	Error name.
`message`required	`string`	Error description.

POST /export

Export

exportLoan

Export a loan

Export requires one or more onboarded loan transaction_id's as input, and converts them from Staircase data to customer data, for subsequent delivery to a customer environment.

To invoke Export, you will need a transaction_id for each loan. Before exporting a loan transaction, make sure that it has been onboarded and has an onboarding result. A transaction should be processed by /onboard before it is exported.

Show the rest

Once you have a transaction_id (or multiple transaction_id's) which contains onboard data, add them to the request body to export them. In export operation:

"ruleset_name" is an optional field for applying rules to boarding result. User can create own rules from here: Rule Product Or user can apply default rules that has been provided with "default_rules" ruleset name. You can download detailed information in Overview page.
"language_name" is an optional field for translating from Staircase v2 language to given user language. User can create own language from here: Language Product

This API supports using batch configuration. Instead of inputting all information; you can input "batch_id" and it will use the export configuration that given batch contains. Note that batch configuration will override the other input. Batch configuration can be created from here: Create Batch

Examples:

{
"transaction_ids": [
"01FYXZWD3JE1ZX9J0MR35RC8XM"
]
}

{
"transaction_ids": [
"01FYXZWD3JE1ZX9J0MR35RC8XM"
],
"request_payload": {
"ruleset_name": "default_rules"
"language_name": "language_name"
}
}

{
"transaction_ids": [
"01FYXZWD3JE1ZX9J0MR35RC8XM"
],
"batch_id": "batch_id"
}

The endpoint will return an execution id for successful requests. To see the results use Get Operation Result

Request

application/json

{
  "transaction_ids": [
    "01FYXZWD3JE1ZX9J0MR35RC8XM"
  ],
  "request_payload": {
    "ruleset_name": "default_rules",
    "language_name": "language_name"
  }
}

Response

application/json

Successfully returned export request

{
  "code": 200,
  "message": {
    "execution_id": "01G23BGPVAP4YEH0KY2K8M9GR7"
  }
}

Parameters

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
`transaction_ids`	`string[]`	Transaction_ids for loans which are going to be resumed

Response `200application/json`

2 fields

Successfully returned export request

Field	Type	Description
`code`	`number`	Status code
`message`	`object`	Message

Response `400application/json`

1 fields

Request data failed validation

Field	Type	Description
`error`	`object`	Unprocessed entity error.
`code`required	`string`	Error name.
`message`required	`string`	Error description.

Response `422application/json`

1 fields

Unprocessed Entity

Field	Type	Description
`error`	`object`	Unprocessed entity error.
`code`required	`string`	Error name.
`message`required	`string`	Error description.

POST /status

Status

status

Get status of the loans in onboard process

Check the onboarding status of a loan at any point in the process, by using the loan transaction id which was returned after performing the onboard operation.

This API supports using batch configuration. Instead of inputting transaction ids; you can input "batch_id" and it will use the registered transactions in the batch. Note that batch configuration will override the other input. Transactions can be registered to the batch from here: Register Transactions to Batch

The API will return an execution_id for successful requests. To see the results, use Get Operation Result until it's message.status is SUCCEEDED.

Request

application/json

{
  "transaction_ids": [
    "01G394T6AP0F0XY7ER5TAY1YH4",
    "01G23BF87W7W5HKFYEMQAETNZG",
    "01G23BGR0K6S5XESPHPZXWB1ZJ",
    "01G23BGPVAP4YEH0KY2K8M9GR7"
  ]
}

Response

application/json

Successfully returned status request

{
  "code": 200,
  "message": {
    "execution_id": "01G23BGPVAP4YEH0KY2K8M9GR7"
  }
}

Parameters

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
`transaction_ids`	`string[]`	Loan transaction_id list whose statuses are going to be provided

Response `200application/json`

2 fields

Successfully returned status request

Field	Type	Description
`code`	`number`	Status code
`message`	`object`	Message

Response `400application/json`

1 fields

Request data failed validation

Field	Type	Description
`error`	`object`	Unprocessed entity error.
`code`required	`string`	Error name.
`message`required	`string`	Error description.

Response `422application/json`

1 fields

Unprocessed Entity

Field	Type	Description
`error`	`object`	Unprocessed entity error.
`code`required	`string`	Error name.
`message`required	`string`	Error description.

POST /deliver

Deliver

deliver

Deliver processed loans to a customer environment

After a loan is exported, it is ready to be delivered to a customer environment. With this API, user can deliver exported result to given destination. Boarding currently supports delivery to Google Cloud storage, Staircase SFTP and SFTP Client.

You can see the status of the transactions that you delivered using Status.

This API supports using batch configuration. Instead of inputting all required information; you can input "batch_id" and it will use the delivery configuration that given batch contains. Note that batch configuration will override the other input. Batch configuration can be created from here: Create Batch

Request

application/json

{
  "transaction_ids": [
    "01G394T6AP0F0XY7ER5TAY1YH4"
  ],
  "request_payload": {
    "bucket_name": "test_bucket_staircase",
    "result_file_path": "batch_folder/result",
    "mime_type": "application_json"
  }
}

Response

application/json

Successfully returned status of import request

{
  "code": 200,
  "message": "Deliver operation has started for the loan outputs"
}

Parameters

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

Request body`application/json`

2 fields

Field	Type	Description
`transaction_ids`	`string[]`	id of transactions for the loans that you are going to deliver
`request_payload`	`object`	Information needed to deliver boarding result
`bucket_name`	`string`	The Google Cloud storage bucket to which the results are going to be delivered
`user_name`	`string`	Username for SFTP server, this field should be provided if platform is SFTP
`loan_file_path`	`string`	The path of the folder where the results are going to be delivered
`mime_type`	`string`	The type of result files that are going to be delivered`application_jsonapplication_ld_jsonapplication_xml`
`platform`	`string`	The platform that the results are going to be delivered`google_cloudgoogle_drivesftpsftp_client`

Response `200application/json`

2 fields

Successfully returned status of import request

Field	Type	Description
`code`	`string`	Status code
`message`	`string`	Message

Response `400application/json`

1 fields

Request data failed validation

Field	Type	Description
`error`	`object`	Unprocessed entity error.
`code`required	`string`	Error name.
`message`required	`string`	Error description.

Response `422application/json`

1 fields

Unprocessed Entity

Field	Type	Description
`error`	`object`	Unprocessed entity error.
`code`required	`string`	Error name.
`message`required	`string`	Error description.

POST /query

Query

query

Get loan id of the loans

Query provides loan id information and document count for one or more loans. The API will return an execution_id for successful requests. To see the results, use Get Operation Result.

Example result:

{
 "code": 202,
 "message": {
 "start_date": "2022-05-27 13:07:06",
 "stop_date": "2022-05-27 13:07:10",
 "status": "SUCCEEDED",
 "data": {
 "loans": [
 {
 "transaction_id": "01G406KR4KR5K8DVWJW59XYQYC",
 "loan_id": "100001"
 "document_count": 10
 },
 {
 "transaction_id": "01G406KJFV21RGN69X4H1C8TBM",
 "loan_id": "100002"
 "document_count": 20
 },
 {
 "transaction_id": "01G406KKHNE52KCVZN9WKMSPZ2",
 "loan_id": "100003"
 "document_count": 30
 }
 ]
 }
 }
}

Request

application/json

{
  "transaction_ids": [
    "01G394T6AP0F0XY7ER5TAY1YH4",
    "01G23BF87W7W5HKFYEMQAETNZG",
    "01G23BGR0K6S5XESPHPZXWB1ZJ",
    "01G23BGPVAP4YEH0KY2K8M9GR7"
  ]
}

Response

application/json

Successfully returned status of query request

{
  "code": 200,
  "message": {
    "response_collection_id": "01G23BGPVAP4YEH0KY2K8M9GR7"
  }
}

Parameters

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
`transaction_ids`	`string[]`	Transaction id list of loans to be queried

Response `200application/json`

2 fields

Successfully returned status of query request

Field	Type	Description
`code`	`number`	Status code
`message`	`object`	Message

Response `400application/json`

1 fields

Request data failed validation

Field	Type	Description
`error`	`object`	Unprocessed entity error.
`code`required	`string`	Error name.
`message`required	`string`	Error description.

Response `422application/json`

1 fields

Unprocessed Entity

Field	Type	Description
`error`	`object`	Unprocessed entity error.
`code`required	`string`	Error name.
`message`required	`string`	Error description.

POST /{transaction_id}/status

Transaction Status

transactionStatus

Checking transaction status with document details

Transaction Status provides the status for each document in a transaction. Statuses include GTL_EXTRACTION_COMPLETED, TRAIN_EXTRACTION_COMPLETED, COULD NOT FIND TRAIN OR GTL RESULT FOR THIS DOCUMENT. This API requires a transaction_id in the request and returns an execution_id for successful requests. To see the results, use Get Operation Result.

Example transaction status result:

Show the rest

"message": {
"start_date": "2022-06-10 07:43:15",
"stop_date": "2022-06-10 07:43:23",
"status": "SUCCEEDED",
"data": [
{
"document_name": "test_note.pdf",
"created_at": "2022-05-31T19:50:10.161363-04:00",
"status": "GTL_EXTRACTION_COMPLETED",
"last_updated_at": "2022-06-03T04:47:53.041720-04:00"
},
{
"document_name": "test_appraisal.pdf",
"created_at": "2022-05-31T19:50:05.323109-04:00",
"status": "GTL_EXTRACTION_COMPLETED",
"last_updated_at": "2022-06-01T07:55:20.965616-04:00"
},
{
"document_name": "test_w2.pdf",
"created_at": "2022-05-31T19:50:13.886317-04:00",
"status": "GTL_EXTRACTION_COMPLETED",
"last_updated_at": "2022-06-01T00:40:17.638374-04:00"
}
]
}

Response

application/json

Successfully returned status of transaction status request

{
  "code": 200,
  "message": {
    "execution_id": "01G3BC9MPZH4M0XQ45X6D1EA2V"
  }
}

Parameters

Parameter	Type	Example	Description
`x-api-key` required	`string` header	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`	Environment API Key.
`transaction_id` required	`string` path	`01G4CPJSW76SWNW88CN907KNZF`	Transaction id

Response `200application/json`

2 fields

Successfully returned status of transaction status request

Field	Type	Description
`code`	`string`	Status code
`message`	`object`	message
`execution_id`	`string`	Execution id of the operation

Response `400application/json`

1 fields

Request data failed validation

Field	Type	Description
`error`	`object`	Unprocessed entity error.
`code`required	`string`	Error name.
`message`required	`string`	Error description.

Response `422application/json`

1 fields

Unprocessed Entity

Field	Type	Description
`error`	`object`	Unprocessed entity error.
`code`required	`string`	Error name.
`message`required	`string`	Error description.

GET /operations/{operation_name}/executions/{execution_id}

Operation Result

operationResult

Get execution results of boarding operations

The following boarding operations return execution id:

/import
/status
/query
/{transaction_id}/status

When executing the API with execution_id and the operation_name you will receive a response that with status RUNNING or SUCCEEDED. If it's still RUNNING please query it till you get a message.status = SUCCEEDED.

Response

application/json

Successfully fetched operation result

{
  "code": 200,
  "message": {
    "transactions": [
      {
        "transaction_id": "01GAR1889DFA56FCQVBWT8DTPM",
        "transaction_created_at": "2022-08-18T04:31:25.537694-04:00",
        "onboarding_status": "ONBOARDING_COMPLETED",
        "status_updated_at": "2022-08-18T06:13:25.219153-04:00"
      }
    ]
  }
}

application/json

Successfully fetched operation result

{
  "code": 202,
  "message": {
    "start_date": "2022-05-27 13:07:06",
    "stop_date": "2022-05-27 13:07:10",
    "status": "SUCCEEDED",
    "data": {
      "loans": [
        {
          "transaction_id": "01G406KR4KR5K8DVWJW59XYQTS",
          "loan_id": "101101"
        }
      ]
    }
  }
}

application/json

Successfully fetched operation result

{
  "code": 200,
  "message": {
    "start_date": "2022-08-31T20:15:46.588000-04:00",
    "stop_date": "2022-08-31T20:16:08.246000-04:00",
    "status": "SUCCEEDED",
    "data": {
      "transactions": [
        {
          "transaction_id": {
            "transaction_id": "01GBTQX9PPY7XET65RMXAANGMT",
            "transaction_created_at": "2022-08-31T16:01:35.336279-04:00",
            "onboarding_status": "IN_ML",
            "status_updated_at": "2022-08-31T16:19:16.638650-04:00"
          }
        }
      ]
    }
  }
}

application/json

Successfully fetched operation result

{
  "code": 202,
  "message": {
    "start_date": "2022-05-27 11:57:51",
    "stop_date": "2022-05-27 11:58:37",
    "status": "SUCCEEDED",
    "data": {
      "transaction_ids": [
        "01G42P3K5YNKJQVCEBHA14E3XD",
        "01G42P3JYZYS5EK2WHPA8Y07AG"
      ],
      "errors": [
        null
      ]
    }
  }
}

Parameters

Parameter	Type	Example	Description
`operation_name` required	`string` path	`import`	Operation name
`execution_id` required	`string` path	`01G42T1CQ7TKF14MPW6NA840FM`	Execution Id
`x-api-key` required	`string` header	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`	Environment API Key.

Response `200application/json`

2 fields

Successfully fetched operation result

Field	Type	Description
`code`	`number`	Status code
`message`	`object`	Message

Response `400application/json`

1 fields

Request data failed validation

Field	Type	Description
`error`	`object`	Unprocessed entity error.
`code`required	`string`	Error name.
`message`required	`string`	Error description.

Response `422application/json`

1 fields

Unprocessed Entity

Field	Type	Description
`error`	`object`	Unprocessed entity error.
`code`required	`string`	Error name.
`message`required	`string`	Error description.

Batch Configuration

POST /batches

Create Batch

createBatch

With this API user can create a batch object that may contain information for whole boarding process: import, onboard, export, delivery and general batch information.

Request

application/json

{
  "import_configuration": {
    "platform": "google_drive",
    "folder_name": "folder_name",
    "loan_file_path": "abc/def",
    "import_classified_documents": true,
    "document_type_file_path": "abc/def/ghj",
    "document_type_mapping_language": "test",
    "bucket_name": "bucket_name",
    "user_name": "user_name",
    "sftp_user_name": "sftp_user_name",
    "sftp_password": "sftp_password",
    "sftp_url": "sftp_url"
  },
  "onboard_configuration": {
    "operation_type": "extraction",
    "ml_enabled": true,
    "labeling_enabled": false,
    "classify_enabled": true,
    "selected_classification_partners": [
      "ephesoft"
    ],
    "delay_between_transactions": 10,
    "automatic_training_enabled": false,
    "fast_ml_option_enabled": true,
    "fields_to_label": {
      "bank_statement": [
        "Checking_Account_Checks_Paid",
        "Savings_Account_No",
        "Savings_Account_Name",
        "Savings_Account_Deposits_And_Additions",
        "Checking_Account_Fees"
      ]
    }
  },
  "export_configuration": {
    "ruleset_name": "ruleset_name",
    "language_name": "language_name"
  },
  "delivery_configuration": {
    "platform": "google_drive",
    "mime_type": "mime_type",
    "result_file_path": "result_file_path",
    "folder_name": "folder_name",
    "bucket_name": "bucket_name",
    "user_name": "user_name",
    "sftp_user_name": "sftp_user_name",
    "sftp_password": "sftp_password",
    "sftp_url": "sftp_url"
  },
  "batch_information": {
    "loan_count": 1000,
    "register_date": "22/10/2022",
    "start_date": "22/10/2022",
    "completion_date": "22/10/2022",
    "daily_quota": 20,
    "daily_labeler_count": 10
  }
}

Response

application/json

Successfully created batch id

{
  "code": 200,
  "message": {
    "batch_id": "01G23BGPVAP4YEH0KY2K8M9GR7"
  }
}

Parameters

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
`import_configuration`	`object`	Import configuration object
`platform`	`string`	The platform where the loan documents exist`google_cloudgoogle_drivesftpsftp_client`
`folder_name`	`string`	Folder_name for Google Drive
`loan_file_path`	`string`	Loan location
`import_classified_documents`	`boolean`	Indicator for classified loan information
`document_type_file_path`	`string`	Location for document type information
`document_type_mapping_language`	`string`	Language name for document type mapping
`bucket_name`	`string`	Bucket name for Google Cloud
`user_name`	`string`	Username for Staircase SFTP server login
`sftp_user_name`	`string`	Username for Staircase SFTP client login
`sftp_password`	`string`	Password for Staircase SFTP client login
`sftp_url`	`string`	URL for Staircase SFTP client login
`onboard_configuration`	`object`	Onboard configuration object
`operation_type`	`string`	Operation type
`ml_enabled`	`boolean`	Indicator for enabling/disabling ML in onboard operation
`labeling_enabled`	`boolean`	Indicator for enabling/disabling labeling in onboard operation
`classify_enabled`	`boolean`	Indicator for enabling/disabling Staircase Classification in onboard operation
`selected_classification_partners`	`array`	Array for selected partners for classification
`delay_between_transactions`	`integer`	Delay seconds between loans in onboarding
`automatic_training_enabled`	`boolean`	Indicator for enabling/disabling auto-training for ML in onboard operation
`fast_ml_option_enabled`	`boolean`	Indicator for enabling/disabling dedicated endpoints for ML in onboard operation
`fields_to_label`	`array`	Array for fields to label
`export_configuration`	`object`	Export configuration object
`ruleset_name`	`string`	Ruleset name for applying rules
`language_name`	`string`	Language name for applying rules
`delivery_configuration`	`object`	Delivery configuration object
`platform`	`string`	The platform where the loan documents exist`google_cloudgoogle_drivesftpsftp_client`
`mime_type`	`string`	Mime type for to be delivered document`application_jsonapplication_ld_jsonapplication_xml`
`result_file_path`	`string`	Location for delivery
`folder_name`	`string`	Folder name for Google Drive
`bucket_name`	`string`	Bucket name for Google Cloud
`user_name`	`string`	Username for Staircase SFTP server login
`sftp_user_name`	`string`	Username for Staircase SFTP client login
`sftp_password`	`string`	Password for Staircase SFTP client login
`sftp_url`	`string`	URL for Staircase SFTP client login
`batch_information`	`object`	Batch information object
`loan_count`	`integer`	Loan count in the batch
`register_date`	`string`	The date that loans are registered
`start_date`	`string`	The date that boarding operation started
`completion_date`	`string`	The date that boarding operation completed
`daily_quota`	`integer`	Daily quota for completed loans
`daily_labeler_count`	`integer`	Labeler counts that works on the process

Response `200application/json`

2 fields

Successfully created batch id

Field	Type	Description
`code`	`number`	Status code
`message`	`object`	Message

Response `400application/json`

1 fields

Request data failed validation

Field	Type	Description
`error`	`object`	Unprocessed entity error.
`code`required	`string`	Error name.
`message`required	`string`	Error description.

Response `422application/json`

1 fields

Unprocessed Entity

Field	Type	Description
`error`	`object`	Unprocessed entity error.
`code`required	`string`	Error name.
`message`required	`string`	Error description.

GET /batches/{batch_id}

Retrieve Batch

retrieveBatch

Get batch configuration

With this API, the batch configuration can be retrieved with given batch id

Response

application/json

Successfully retrieved batch

{
  "import_configurations": [
    {
      "has_platform_type": null,
      "has_value": "google_drive",
      "has_folder_name": {
        "has_value": "folder_name"
      },
      "has_file_path": {
        "has_value": "abc/def"
      },
      "has_import_classified_documents_indicator": {
        "has_value": true
      },
      "document_type_file_path": {
        "has_value": "abc/def/ghj"
      },
      "has_document_type_mapping_language": {
        "has_value": "test"
      },
      "has_bucket_name": {
        "has_value": "bucket_name"
      },
      "has_user_name": {
        "has_value": "user_name"
      },
      "has_sftp_user_name": {
        "has_value": "sftp_user_name"
      },
      "has_sftp_password": {
        "has_value": "sftp_password"
      },
      "has_sftp_server_url": {
        "has_value": "sftp_url"
      },
      "@type": "import_configuration",
      "@id": "01GF87MAY70RA11JT8ZZCRG7DE"
    }
  ],
  "classification_partners": [
    {
      "@type": "classification_partner",
      "@id": "01GF87MAY7EV6AE4NW9BKQWR9G",
      "has_classification_partner_type": {
        "has_value": "ephesoft"
      }
    }
  ],
  "onboard_configurations": [
    {
      "has_operation_type": {
        "has_value": "extraction"
      },
      "has_ml_enabled_indicator": {
        "has_value": true
      },
      "has_labeling_enabled_indicator": {
        "has_value": false
      },
      "has_delay_between_transactions_seconds": {
        "has_value": 10
      },
      "has_automatic_training_enabled_indicator": {
        "has_value": false
      },
      "has_fast_ml_option_enabled_indicator": {
        "has_value": true
      },
      "@type": "onboard_configuration",
      "@id": "01GF87MAY7VQFAAKJVGKAYN648",
      "with_classification_partner": [
        "01GF87MAY7EV6AE4NW9BKQWR9G"
      ]
    }
  ],
  "export_configurations": [
    {
      "has_ruleset_name": {
        "has_value": "ruleset_name"
      },
      "has_language_name": {
        "has_value": "language_name"
      },
      "@type": "export_configuration",
      "@id": "01GF87MAY7MM8TZWHFZHDN5A9W"
    }
  ],
  "delivery_configurations": [
    {
      "has_platform_type": {
        "has_value": "google_drive"
      },
      "has_mime_type": {
        "has_value": "mime_type"
      },
      "has_file_path": {
        "has_value": "result_file_path"
      },
      "has_folder_name": {
        "has_value": "folder_name"
      },
      "has_bucket_name": {
        "has_value": "bucket_name"
      },
      "has_user_name": {
        "has_value": "user_name"
      },
      "has_sftp_user_name": {
        "has_value": "sftp_user_name"
      },
      "has_sftp_password": {
        "has_value": "sftp_password"
      },
      "has_sftp_server_url": {
        "has_value": "sftp_url"
      },
      "@type": "delivery_configuration",
      "@id": "01GF87MAY7MVW7Q5K4VX42GD85"
    }
  ],
  "batch_informations": [
    {
      "has_loan_count": {
        "has_value": 1000
      },
      "has_register_date": {
        "has_value": "22/10/2022"
      },
      "has_start_date": {
        "has_value": "22/10/2022"
      },
      "has_completion_date": {
        "has_value": "22/10/2022"
      },
      "has_daily_quota_count": {
        "has_value": 20
      },
      "has_daily_labeler_count": {
        "has_value": 10
      },
      "@type": "batch_information",
      "@id": "01GF87MAY70MAESV359HRTVCP6"
    }
  ],
  "loan_boarding_batches": [
    {
      "with_import_configuration": [
        "01GF87MAY70RA11JT8ZZCRG7DE"
      ],
      "with_onboard_configuration": [
        "01GF87MAY7VQFAAKJVGKAYN648"
      ],
      "with_export_configuration": [
        "01GF87MAY7MM8TZWHFZHDN5A9W"
      ],
      "with_delivery_configuration": [
        "01GF87MAY7MVW7Q5K4VX42GD85"
      ],
      "with_batch_information": [
        "01GF87MAY70MAESV359HRTVCP6"
      ],
      "@type": "loan_boarding_batch",
      "@id": "01GF87MAY7JMNN9Y60BD5C14ND"
    }
  ]
}

Parameters

Parameter	Type	Example	Description
`batch_id` required	`string` path	`01G42T1CQ7TKF14MPW6NA840FM`	Batch Id
`x-api-key` required	`string` header	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`	Environment API Key.

Response `200application/json`

2 fields

Successfully retrieved batch

Field	Type	Description
`code`	`number`	Status code
`message`	`object`	Message

Response `400application/json`

1 fields

Request data failed validation

Field	Type	Description
`error`	`object`	Unprocessed entity error.
`code`required	`string`	Error name.
`message`required	`string`	Error description.

Response `422application/json`

1 fields

Unprocessed Entity

Field	Type	Description
`error`	`object`	Unprocessed entity error.
`code`required	`string`	Error name.
`message`required	`string`	Error description.

PUT /batches/{batch_id}

Update Batch

updateBatch

With this API user can update the batch object that may contain information for whole boarding process: import, onboard, export, delivery and general batch information.

Request

application/json

{
  "import_configuration": {
    "platform": "google_drive",
    "folder_name": "folder_name",
    "loan_file_path": "abc/def",
    "import_classified_documents": true,
    "document_type_file_path": "abc/def/ghj",
    "document_type_mapping_language": "test",
    "bucket_name": "bucket_name",
    "user_name": "user_name",
    "sftp_user_name": "sftp_user_name",
    "sftp_password": "sftp_password",
    "sftp_url": "sftp_url"
  },
  "onboard_configuration": {
    "operation_type": "extraction",
    "ml_enabled": true,
    "labeling_enabled": false,
    "selected_classification_partners": [
      "ephesoft"
    ],
    "delay_between_transactions": 10,
    "automatic_training_enabled": false,
    "fast_ml_option_enabled": true
  },
  "export_configuration": {
    "ruleset_name": "ruleset_name",
    "language_name": "language_name"
  },
  "delivery_configuration": {
    "platform": "google_drive",
    "mime_type": "mime_type",
    "result_file_path": "result_file_path",
    "folder_name": "folder_name",
    "bucket_name": "bucket_name",
    "user_name": "user_name",
    "sftp_user_name": "sftp_user_name",
    "sftp_password": "sftp_password",
    "sftp_url": "sftp_url"
  },
  "batch_information": {
    "loan_count": 1000,
    "register_date": "22/10/2022",
    "start_date": "22/10/2022",
    "completion_date": "22/10/2022",
    "daily_quota": 20,
    "daily_labeler_count": 10
  }
}

Response

application/json

Successfully updated batch id

{
  "code": 200,
  "message": {
    "batch_id": "01G23BGPVAP4YEH0KY2K8M9GR7"
  }
}

Parameters

Parameter	Type	Example	Description
`batch_id` required	`string` path	`01G42T1CQ7TKF14MPW6NA840FM`	Batch Id
`x-api-key` required	`string` header	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`	Environment API Key.

Request body`application/json`

5 fields

Field	Type	Description
`import_configuration`	`object`	Import configuration object
`platform`	`string`	The platform where the loan documents exist`google_cloudgoogle_drivesftpsftp_client`
`folder_name`	`string`	Folder_name for Google Drive
`loan_file_path`	`string`	Loan location
`import_classified_documents`	`boolean`	Indicator for classified loan information
`document_type_file_path`	`string`	Location for document type information
`document_type_mapping_language`	`string`	Language name for document type mapping
`bucket_name`	`string`	Bucket name for Google Cloud
`user_name`	`string`	Username for Staircase SFTP server login
`sftp_user_name`	`string`	Username for Staircase SFTP client login
`sftp_password`	`string`	Password for Staircase SFTP client login
`sftp_url`	`string`	URL for Staircase SFTP client login
`onboard_configuration`	`object`	Onboard configuration object
`operation_type`	`string`	Operation type
`ml_enabled`	`boolean`	Indicator for enabling/disabling ML in onboard operation
`labeling_enabled`	`boolean`	Indicator for enabling/disabling labeling in onboard operation
`selected_classification_partners`	`array`	Array for selected partners for classification
`delay_between_transactions`	`integer`	Delay seconds between loans in onboarding
`automatic_training_enabled`	`boolean`	Indicator for enabling/disabling auto-training for ML in onboard operation
`fast_ml_option_enabled`	`boolean`	Indicator for enabling/disabling dedicated endpoints for ML in onboard operation
`export_configuration`	`object`	Export configuration object
`ruleset_name`	`string`	Ruleset name for applying rules
`language_name`	`string`	Language name for applying rules
`delivery_configuration`	`object`	Delivery configuration object
`platform`	`string`	The platform where the loan documents exist`google_cloudgoogle_drivesftpsftp_client`
`mime_type`	`string`	Mime type for to be delivered document`application_jsonapplication_ld_jsonapplication_xml`
`result_file_path`	`string`	Location for delivery
`folder_name`	`string`	Folder name for Google Drive
`bucket_name`	`string`	Bucket name for Google Cloud
`user_name`	`string`	Username for Staircase SFTP server login
`sftp_user_name`	`string`	Username for Staircase SFTP client login
`sftp_password`	`string`	Password for Staircase SFTP client login
`sftp_url`	`string`	URL for Staircase SFTP client login
`batch_information`	`object`	Batch information object
`loan_count`	`integer`	Loan count in the batch
`register_date`	`string`	The date that loans are registered
`start_date`	`string`	The date that boarding operation started
`completion_date`	`string`	The date that boarding operation completed
`daily_quota`	`integer`	Daily quota for completed loans
`daily_labeler_count`	`integer`	Labeler counts that works on the process

Response `200application/json`

2 fields

Successfully updated batch id

Field	Type	Description
`code`	`number`	Status code
`message`	`object`	Message

Response `400application/json`

1 fields

Request data failed validation

Field	Type	Description
`error`	`object`	Unprocessed entity error.
`code`required	`string`	Error name.
`message`required	`string`	Error description.

Response `422application/json`

1 fields

Unprocessed Entity

Field	Type	Description
`error`	`object`	Unprocessed entity error.
`code`required	`string`	Error name.
`message`required	`string`	Error description.

POST /batches/{batch_id}/register

Register Transactions to Batch

registerTransactionsToBatch

With this API, given transactions can be registered to the given batch. After this operation, you can use batch id for tracking status of the loans that has registered via status API: Status

Request

application/json

{
  "transaction_ids": [
    "01FYXZWD3JE1ZX9J0MR35RC8XM"
  ]
}

Response

application/json

Request data failed validation

{
  "code": 400,
  "message": "Bad Request"
}

Parameters

Parameter	Type	Example	Description
`batch_id` required	`string` path	`01G42T1CQ7TKF14MPW6NA840FM`	Batch Id
`x-api-key` required	`string` header	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`	Environment API Key.

Request body`application/json`

1 fields

Field	Type	Description
`transaction_ids`	`string[]`	Transaction IDs for the loans that you imported and want to register

Response `200application/json`

1 fields

Successfully retrieved batch

Field	Type	Description
`message`	`string`	Onboard result message

Response `400application/json`

1 fields

Request data failed validation

Field	Type	Description
`error`	`object`	Unprocessed entity error.
`code`required	`string`	Error name.
`message`required	`string`	Error description.

Response `422application/json`

1 fields

Unprocessed Entity

Field	Type	Description
`error`	`object`	Unprocessed entity error.
`code`required	`string`	Error name.
`message`required	`string`	Error description.

POST /batches/{batch_id}/execute

Execute Registered Transactions in Batch

executeRegisteredTransactionsInBatch

With this API, user can execute the all registered transactions to the end of boarding process. Executed transactions are going to onboard, export and delivered with batch configuration. To complete all steps, batch configuration must contain onboard configuration and delivery configuration. Otherwise, batch execution cannot be started. Export configuration is optional; but if user wants to apply rules or translate result to customer language, export configuration is also required in the batch configuration.

The status of the batch can be tracked with status API with batch id: Status

Response

application/json

Request data failed validation

{
  "code": 400,
  "message": "Bad Request"
}

Parameters

Parameter	Type	Example	Description
`batch_id` required	`string` path	`01G42T1CQ7TKF14MPW6NA840FM`	Batch Id
`x-api-key` required	`string` header	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`	Environment API Key.

Response `200application/json`

1 fields

Successfully retrieved batch

Field	Type	Description
`message`	`string`	Batch Execution result message

Response `400application/json`

1 fields

Request data failed validation

Field	Type	Description
`error`	`object`	Unprocessed entity error.
`code`required	`string`	Error name.
`message`required	`string`	Error description.

Response `422application/json`

1 fields

Unprocessed Entity

Field	Type	Description
`error`	`object`	Unprocessed entity error.
`code`required	`string`	Error name.
`message`required	`string`	Error description.

Providers

Valon

Errors

400422

How it works

Operations

Workflow

Import

Request

Response

Parameters

Request bodyapplication/json

Response 200application/json

Response 400application/json

Response 422application/json

Onboard

Request

Response

Parameters

Request bodyapplication/json

Response 200application/json

Response 400application/json

Response 422application/json

Export

Request

Response

Parameters

Request bodyapplication/json

Response 200application/json

Response 400application/json

Response 422application/json

Status

Request

Response

Parameters

Request bodyapplication/json

Response 200application/json

Response 400application/json

Response 422application/json

Deliver

Request

Response

Parameters

Request bodyapplication/json

Response 200application/json

Response 400application/json

Response 422application/json

Query

Request

Response

Parameters

Request bodyapplication/json

Response 200application/json

Response 400application/json

Response 422application/json

Transaction Status

Response

Parameters

Response 200application/json

Response 400application/json

Response 422application/json

Operation Result

Response

Parameters

Response 200application/json

Response 400application/json

Response 422application/json

Batch Configuration

Create Batch

Request

Response

Parameters

Request bodyapplication/json

Response 200application/json

Response 400application/json

Response 422application/json

Retrieve Batch

Response

Parameters

Response 200application/json

Response 400application/json

Response 422application/json

Update Batch

Request

Request body`application/json`

Response `200application/json`

Response `400application/json`

Response `422application/json`

Request body`application/json`

Response `200application/json`

Response `400application/json`

Response `422application/json`

Request body`application/json`

Response `200application/json`

Response `400application/json`

Response `422application/json`

Request body`application/json`

Response `200application/json`

Response `400application/json`

Response `422application/json`

Request body`application/json`

Response `200application/json`

Response `400application/json`

Response `422application/json`

Request body`application/json`

Response `200application/json`

Response `400application/json`

Response `422application/json`

Response `200application/json`

Response `400application/json`

Response `422application/json`

Response `200application/json`

Response `400application/json`

Response `422application/json`

Request body`application/json`

Response `200application/json`

Response `400application/json`

Response `422application/json`

Response `200application/json`

Response `400application/json`

Response `422application/json`

Request body`application/json`

Response `200application/json`

Response `400application/json`

Response `422application/json`

Request body`application/json`

Response `200application/json`

Response `400application/json`

Response `422application/json`

Response `200application/json`

Response `400application/json`

Response `422application/json`