Workflow Engine Integration Guide

API Integration Guide

Auth

To authorize queries to the API, an initial query is made to the auth endpoint using clientId and secret:

curl --request POST \
     --url https://{auth_base_url}/identity/resources/auth/v1/api-token \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "clientId": "string",
  "secret": "string"
}

The response will contain the accessToken that must be used as token in all subsequent calls. There is also a refreshToken that can be used to obtain a new accessToken when the current one expires.

Routes

Workflows are executed using the AltScore Borrower Central API. All routes can be seen here.

When implementing the workflow, you must choose whether you want a synchronous or asynchronous workflow.

Evaluating a Synchronous Workflow

To evaluate a workflow, a request is made to the /execute route using the previously obtained workflow_alias and workflow_version during implementation.

 
curl --location '{base_url}/v1/workflows/{workflow_alias}/{workflow_version}/execute' \
--header 'Authorization: Bearer {token}' \
--data '
		{
        "inputKey0": "this_is_a_required_input_key",
        "inputKey1": ["this is a requiered item key",
                      "this is another requiered item"],
        "inputKey2": {"subKey0": 1,
                      "subKey1":"required subkey"}
}'

The workflow will respond to the call at the end of the execution of all its logic with the result of the execution. That is, the response of the request will contain the result of the evaluation.

Evaluating an Asynchronous Workflow

In the case of an asynchronous workflow, the request is made in the same way, but it will respond "instantly" with the executionId corresponding to the execution.

The executionId can be used to perform "polling" of the execution status until it has finished. To perform the "polling," a request is made to the /output route.

curl --location '{base_url}/v1/executions/{execution_id}/output'\
--header 'Authorization: Bearer {token}'

Response

For both synchronous and asynchronous cases, the request's response will have the following base structure:

 
{
  "isSuccess": true,
  "statusCode": 200,
  "attachments": [
    {
      "url": "https://example.com/path/to/attachment1",
      "fileExtension": "pdf",
      "metadata": {
        "date": "2024-01-31"
      }
    }
  ],
  "output": {...}, // See explanation below
  "customOutput": {...}, // See explanation below
  "errorMessage": null,
  "notes": [
    "Note 1",
    "Note 2"
  ],
  "notices": [
    { "message": "Notice 1", "severity": "info" },
    { "message": "Notice 2", "severity": "error" }
  ]
}

The fields of attachments, customOutput, errorMessage, notes, and notices can be null fields, depending on the implementation or the result of the evaluation.

Output

The content of the output field depends on the type of workflow you want to execute:

Data Source Query Outputs

One use case is if you wish to make queries to data sources.

If you want to obtain information about a certain data source, the format of the output field contains the following response format:

{
  "isSuccess": true,
  "billableId": "12345",
  "data": [
    {
      "key1": "value1",
      "key2": "value2"
    }
  ],
  "fields": {
    "field1": "data1",
    "field2": "data2"
  }
}

Alert Utilization Outputs

Another use case is if you wish to use alerts in the workflow.

Alerts allow for quick visibility of potential "issues" that the assessment case might have. For example, we can query the OFAC blacklist by name and obtain possible matches, in which case we could generate an alert.

The content of the output field in this case will have the following format:

 
{
  "isSuccess": true,
  "billableId": "12345",
  "alerts": [
    {
      "ruleId": "rule_001",
      "ruleCode": "RC001",
      "label": "High Risk",
      "level": 3,
      "borrowerId": "borrower_123",
      "message": "The borrower has a high-risk profile."
    },
    {
      "ruleId": "rule_002",
      "ruleCode": "RC002",
      "label": "Incomplete Data",
      "level": -1,
      "borrowerId": "borrower_123",
      "message": "Missing essential data for borrower assessment."
    }
  ],
  "data": [
    {
      "key1": "value1",
      "key2": "value2"
    }
  ],
  "fields": {
    "field1": "data1",
    "field2": "data2"
  }
}

Credit Score Assessment Outputs

Another alternative is if you wish to obtain a risk score using models. AltScore is compatible with using 'whitebox' models within the workflow.

In the case of using 'whitebox' models within the workflow, the content of output will have the following format:

 
{
  "billableId": "123456789",
  "borrowerId": "987654321",
  "isSuccess": true,
  "fields": {
    "totalIncome": 5000,
    "age": 34
  },
  "data": [
    {
      "type": "transaction",
      "date": "2024-04-08",
      "amount": 1000
    }
  ],
  "score": {
    "key": "creditScore",
    "label": "Credit Score",
    "value": 750,
    "maxValue": 850
  },
  "scorecard": [
    {
      "field": "totalIncome",
      "order": 1,
      "value": 5000,
      "bucket": 3,
      "points": 20,
      "maxPoints": 25,
      "label": "Income",
      "bucketLabel": "High"
    },
    {
      "field": "age",
      "order": 2,
      "value": 34,
      "bucket": 2,
      "points": 15,
      "maxPoints": 20,
      "label": "Age",
      "bucketLabel": "Mid"
    }
  ],
  "metrics": [
    {
      "key": "loanToIncomeRatio",
      "label": "Loan to Income Ratio",
      "value": 0.2
    }
  ],
  "rules": [
    {
      "id": "rule1",
      "order": 1,
      "code": "incomeCheck",
      "label": "Income Verification",
      "value": "Passed",
      "alertLevel": 0,
      "hit": true
    }
  ],
  "alerts": [
   {
      "ruleId": "rule_001",
      "ruleCode": "RC001",
      "label": "High Risk",
      "level": 3,
      "borrowerId": "borrower_123",
      "message": "The borrower has a high-risk profile."
    }
  ],
  "decision": "Manual Review"
}
 

Custom Output

The customOutput field is configurable during implementation to contemplate any additional necessary use case beyond the existing ones.

Evaluating a Workflow in Batch

To execute the same workflow for multiple subjects in batch massively, a request is made to the route /execute-batch using the workflow_alias and workflow_version obtained previously during the implementation.

• label: A short label for the batch.
• description: Details about the batch.
• attachmentFileNames: Up to 5 files uploaded with pre-signed url containing the input data for the batch items with the expected format determined during implementation. See the section Generating a Pre-Signed URL to Upload Files.
• workflowInput: JSON with the batch's input data and metadata. The input data can be sent in multiple formats:
  • items: A list of dictionaries with input data for the execution of each item in the batch. This field is designed to perform quick tests of up to 10 items.
  • customInput: Custom-formatted input.
  • rawPackageIds: A list of previously created package IDs that contain attached files with information about the batch items and that will be read, validated and processed in the batch execution. Up to 5 packages can be sent.

All the workflowInput fields are optional, but at least one of the items, customInput, rawPackageIds fields or the external attachmentFileNames must be sent with valid values.

curl --location '{base_url}/v1/workflows/{workflow_alias}/{workflow_version}/execute-batch' \
--header 'Authorization: Bearer {token}' \
--data '
{
  "label": "kyc v1 batch #7",
  "description": "Batch of KYC evaluations",
  "attachmentFileNames": [
      "9ad44ab7-30a9-400e-a741-44c008817e84.xlsx",
      "286fc2d8-d953-45dd-99ac-402123330646.xlsx"
  ],
  "workflowInput": {
    "items": [
      { "person_id": "9999999999" },
      { "person_id": "1234567890" }
    ],
    "customInput": {},
    "rawPackageIds": []
  }
}'

The response will contain a executionBatchId that can be used to perform "polling" of the batch status until it has finished.

{
    "executionBatchId": "009bddb2-1856-4afc-ae61-c243b7eb7e83",
    "workflowId": "072386f4-42c1-4685-ad5f-35a724486b24",
    "workflowAlias": "kyc",
    "workflowVersion": "v0",
    "executedAt": "2024-12-12T17:54:02.677597"
}

A batch orchestration process will be spawn which will run multiple phases that validate your input, run the workflow for each item, and generate one or multiple files with the results in the formats determined during implementation. Whilst these processes run, you can poll the batch data to check the status field with:

GET /v1/execution-batches/:execution_batch_id

The possible statuses are:

• pending: The batch has just been created and is waiting to be processed.
• pre_processing: The batch input data is being validated and prepared.
• pre_processing_complete: The batch input data was successfully validated and the workflow executions are ready to start.
• pre_processing_failed: There was an error validating the batch input data.
• processing: The workflow is being executed for each batch item.
• post_processing: The final output files are being generated.
• post_processing_failed: There was an error generating the final output files.
• complete: The batch process has finished successfully.
• paused: The batch process was paused.
• cancelled: The batch process was cancelled.

Generating a Pre-Signed URL to Upload Files

Make a request specifying the file name of the file to be uploaded.

POST /v1/stores/packages/commands/attachments/generate-upload-signed-url

curl --location '{base_url}/v1/stores/packages/commands/attachments/generate-upload-signed-url' \
--header 'Authorization: Bearer {token}' \
--data '
{
    "fileName": "file-name.xlsx"
}
'

The response will look like this:

{
    "signedUrl": "https://signedurltouploadfile.com/...",
    "fileName": "286fc2d8-d953-45dd-99ac-402123330646.xlsx",
    "attachmentId": "286fc2d8-d953-45dd-99ac-402123330646",
    "contentType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
}

The fields are:

• signedUrl: The URL to upload the file.
• fileName: The name of the file to be uploaded that was generated during the signed URL creation. Notice this name is different from the original file name.
• attachmentId: The ID of this file attachment.
• contentType: The content type mime of the file to be uploaded that was defined during the signed URL creation.

To upload the file, make a PUT request to the signedUrl URL with the file data using the Content-Type header with the value of the contentType field.

curl -X PUT --location 'https://signedurltouploadfile.com/...' \
--header 'Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' \
--data-binary @path/to/file-name.xlsx

Obtaining the Resulting Files at the End of Batch Processing

Once the complete phase is reached, the files with the results will be ready to be consumed. To download them, you must take the value of the field outputs.wBatchPostProcessingOutput.processedOutputPackageId GET /v1/execution-batches/:execution_batch_id request response, which is a package ID, and use it to obtain its attached files as shown in the section Obtaining Package Attachments.

Retrying a Failed Phase

Both pre-processing and post-processing can fail for different reasons. For example, pre-processing will fail if the input data does not meet the conditions determined in the implementation. Either of the two phases can fail due to unexpected network or similar reasons. In case one of these phases fails, the process will be blocked until the phase is retried (making the necessary changes to the input data if necessary) and is completed satisfactorily. You can retry the failed phase by making a request to the /retry route on the batch with the corresponding executionBatchId.

• attachmentFileNames: Same use as in /execute-batch. Optional field.
• workflowInput: Same use as in /execute-batch. Optional field.
• retryMode: Indicates which phase to retry. The values allowed are pre_processing or post_processing.
• usePreviousInputs: Indicates whether to use the same input data as in the previous execution. The allowed values are true or false. Optional field. By default, it is false. When retrying pre-processing, set this as true if the outputs.wBatchPreProcessingOutput.result is equal to unhandled_error as it may have happened due to a temporary issue (e.g. network or temporary service interruption) and the input data is correct.

curl --location '{base_url}/v1/execution-batches/{execution_batch_id}/retry' \
--header 'Authorization: Bearer {token}' \
--data '
{
  "retryMode": "pre_processing",
  "usePreviousInputs": false,
  "attachmentFileNames": [
      "9ad44ab7-30a9-400e-a741-44c008817e84.xlsx"
  ],
  "workflowInput": {
    "items": [],
    "customInput": {},
    "rawPackageIds": []
  }
}'

Retrying batch items

It's probable that some items in the batch fail during the processing phase. In this case, the batch will be marked as complete, but the state.batchItemsExecutionsSummary.failed field will have a number higher than zero. You can retry the failed items by making a request to the same /retry route, but with retryMode equal to failed_items on the batch with the corresponding executionBatchId.

Another case where retrying is useful is when you need to reprocess the items that were successful, but couldn't get the data of any of their target data sources due to data source system unavailability or similar reasons. You can check the state.batchItemsExecutionsSummary.unsuccessfulSources field to see if there are any items with this issue. In this case, the retryMode should be unsuccessful_sources_items.

You can retry both failed items and items with unsuccessful sources at the same time with the failed_and_unsuccessful_sources_items retryMode.

To see more information about batch processing routes in the Borrower Central API, you can check the documentation here.

Scheduling a Workflow for Recurrent Execution

Configure Scheduling

You can schedule a workflow to run recurrently at specific times.

curl --location --request POST '${base_url}/v1/workflows/commands/configure-schedules' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ${token}' \
--data '{
    "workflowId": "<your workflow ID>",
    "schedule": {
        "cron": "0 15 * * *",
        "utcDeltaHours": -5
    },
    "scheduleBatch": {
        "cron": "30 14 * * *",
        "utcDeltaHours": -5
    }
}'

The schedule parameter is an object that contains the scheduling information for the workflow (non-batch). The cron and utcDeltaHours fields are required. cron is a string that represents the scheduling in cron format. utcDeltaHours is an integer that represents the difference in hours with respect to UTC time. To configure the batch version of the workflow, the scheduleBatch parameter must be included with the same structure as schedule.

In the example, the workflow in its non-batch version will run every day at 15:00 UTC-5, and the batch version will run every day at 14:30 UTC-5.

Delete Scheduling Configuration

Likewise, you can delete the scheduling of a previously configured workflow.

schedule and scheduleBatch are optional boolean values. If their value is true, the corresponding scheduling configuration (batch or non-batch, respectively) will be deleted.

curl --location --request POST '${base_url}/v1/workflows/commands/delete-schedules' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ${token}' \
--data '{
    "workflowId": "<your workflow ID>",
    "schedule": true,
    "scheduleBatch": true
}'

Subscribing to Events via Webhooks

Instead of polling an execution's status, you can subscribe to the bc.execution.completed event and get notified as soon as the execution finishes.

Configuring the webhook

Register your endpoint from the AltScore hub, under Settings > Webhooks, and subscribe it to the bc.execution.completed event. That is also where you get the signing secret, see the delivery history and retry any messages that failed.

If you would rather do it via API, the reference is in Webhooks API:

curl --location 'https://bc.altscore.ai/v1/webhooks/endpoints' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ${token}' \
--data '{
    "name": "Your New Webhook",
    "url": "${endpoint}",
    "events": ["bc.execution.completed"]
}'

From that point on, whenever an execution finishes a POST request with the event information is sent to your endpoint. The payload structure is described in Events.

Disabling the webhook

To temporarily stop receiving notifications, change the endpoint's status without deleting it:

curl --location --request PATCH 'https://bc.altscore.ai/v1/webhooks/endpoints/${endpoint_id}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ${token}' \
--data '{
    "status": "disabled"
}'