API Reference

This reference documents the REST API endpoints for managing and executing workflows programmatically. All endpoints are available through the Borrower Central API.

Base URLs

Environment	Base URL
Production	`https://bc.altscore.ai`
Sandbox	`https://bc.sandbox.altscore.ai`

Authentication

All API requests require a valid JWT Bearer token. This section explains how to obtain and use tokens for API access.

Obtaining a Token

Tokens are obtained from the Frontegg authentication service using your client credentials.

Auth Base URLs:

Environment	Auth URL
Production	`https://auth.altscore.ai`
Sandbox	`https://auth.sandbox.altscore.ai`

curl --request POST \
  --url https://auth.altscore.ai/identity/resources/auth/v1/api-token \
  --header 'Content-Type: application/json' \
  --data '{
    "clientId": "your-client-id",
    "secret": "your-client-secret"
  }'

Response:

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "refresh-token-string",
  "expiresIn": 86400
}

Token Refresh

Access tokens expire after the time specified in expiresIn (typically 24 hours). Use the refresh token to obtain a new access token without re-authenticating:

curl --request POST \
  --url https://auth.altscore.ai/identity/resources/auth/v1/api-token/refresh \
  --header 'Content-Type: application/json' \
  --data '{
    "refreshToken": "your-refresh-token"
  }'

The Python SDK (altscore package) handles token management automatically, including refresh. For most use cases, simply initialize the client and let it manage authentication.

Request Headers

Include the following headers in all API requests:

Authorization: Bearer {access_token}
Content-Type: application/json

Example Authenticated Request

curl --request GET \
  --url https://bc.altscore.ai/v2/workflows \
  --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...' \
  --header 'Content-Type: application/json'

Workflow Management Endpoints

These endpoints use the V2 API for managing workflow definitions, including creation, updates, publishing, and archiving.

List Workflows

Retrieve a paginated list of all workflows in your tenant.

GET /v2/workflows

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`per-page`	integer	Items per page (default: 20, max: 100)
`status`	string	Filter by status: `draft`, `active`, `archived`
`search`	string	Search by name or alias

Response

{
  "data": [
    {
      "id": "wf_01HQ3K5X7Y8Z9ABCDEFGHIJK",
      "name": "KYC Verification Flow",
      "alias": "kyc-verification",
      "version": "v1",
      "status": "active",
      "description": "Automated KYC verification for new borrowers",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-20T14:45:00Z",
      "publishedAt": "2024-01-20T14:45:00Z"
    },
    {
      "id": "wf_01HQ3K5X7Y8Z9ABCDEFGHIJL",
      "name": "Credit Assessment",
      "alias": "credit-assessment",
      "version": "v2",
      "status": "draft",
      "description": "Credit scoring and risk assessment workflow",
      "createdAt": "2024-02-01T09:00:00Z",
      "updatedAt": "2024-02-05T11:20:00Z",
      "publishedAt": null
    }
  ],
  "pagination": {
    "page": 1,
    "perPage": 20,
    "total": 45,
    "totalPages": 3
  }
}

Get Workflow by ID

Retrieve a specific workflow by its unique identifier.

GET /v2/workflows/{id}

Path Parameters

Parameter	Type	Description
`id`	string	Workflow unique identifier

Response

{
  "id": "wf_01HQ3K5X7Y8Z9ABCDEFGHIJK",
  "name": "KYC Verification Flow",
  "alias": "kyc-verification",
  "version": "v1",
  "status": "active",
  "description": "Automated KYC verification for new borrowers",
  "inputSchema": {
    "type": "object",
    "properties": {
      "borrowerId": { "type": "string" },
      "documentType": { "type": "string", "enum": ["passport", "national_id", "driver_license"] },
      "countryCode": { "type": "string" }
    },
    "required": ["borrowerId", "documentType"]
  },
  "tasks": [
    {
      "id": "task_001",
      "type": "http-request",
      "name": "Fetch Borrower Data",
      "config": { }
    }
  ],
  "edges": [
    {
      "source": "start",
      "target": "task_001"
    }
  ],
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-20T14:45:00Z",
  "publishedAt": "2024-01-20T14:45:00Z"
}

Create Workflow

Create a new workflow definition.

POST /v2/workflows

Request Body

{
  "name": "Document Verification",
  "alias": "doc-verification",
  "description": "Validates uploaded documents against external sources",
  "inputSchema": {
    "type": "object",
    "properties": {
      "borrowerId": { "type": "string" },
      "documentUrl": { "type": "string", "format": "uri" }
    },
    "required": ["borrowerId", "documentUrl"]
  },
  "tasks": [],
  "edges": []
}

Response

{
  "id": "wf_01HQ3K5X7Y8Z9ABCDEFGHIJM",
  "name": "Document Verification",
  "alias": "doc-verification",
  "version": "v1",
  "status": "draft",
  "description": "Validates uploaded documents against external sources",
  "createdAt": "2024-02-10T16:00:00Z",
  "updatedAt": "2024-02-10T16:00:00Z",
  "publishedAt": null
}

Update Workflow

Update an existing workflow. Only draft workflows can be modified directly.

PUT /v2/workflows/{id}

Path Parameters

Parameter	Type	Description
`id`	string	Workflow unique identifier

Request Body

{
  "name": "Document Verification v2",
  "description": "Enhanced document validation with OCR support",
  "inputSchema": {
    "type": "object",
    "properties": {
      "borrowerId": { "type": "string" },
      "documentUrl": { "type": "string", "format": "uri" },
      "extractText": { "type": "boolean", "default": false }
    },
    "required": ["borrowerId", "documentUrl"]
  },
  "tasks": [
    {
      "id": "task_001",
      "type": "http-request",
      "name": "Download Document",
      "config": { }
    }
  ],
  "edges": [
    {
      "source": "start",
      "target": "task_001"
    }
  ]
}

Delete Workflow

Permanently delete a workflow. Only draft workflows can be deleted.

DELETE /v2/workflows/{id}

This action cannot be undone. Active workflows must be archived first before deletion.

Path Parameters

Parameter	Type	Description
`id`	string	Workflow unique identifier

Response

HTTP/1.1 204 No Content

Publish Draft

Publish a draft workflow to make it active and executable.

POST /v2/workflows/{id}/publish

Path Parameters

Parameter	Type	Description
`id`	string	Workflow unique identifier

Response

{
  "id": "wf_01HQ3K5X7Y8Z9ABCDEFGHIJM",
  "status": "active",
  "version": "v1",
  "publishedAt": "2024-02-10T18:30:00Z"
}

Create Draft from Active

Create a new draft version from an active workflow for editing.

POST /v2/workflows/{id}/create-draft

Path Parameters

Parameter	Type	Description
`id`	string	Active workflow identifier

Response

{
  "id": "wf_01HQ3K5X7Y8Z9ABCDEFGHIJN",
  "name": "KYC Verification Flow",
  "alias": "kyc-verification",
  "version": "v2",
  "status": "draft",
  "parentVersion": "v1",
  "createdAt": "2024-02-15T09:00:00Z"
}

Archive Workflow

Archive an active workflow. Archived workflows cannot be executed but are retained for audit purposes.

POST /v2/workflows/{id}/archive

Path Parameters

Parameter	Type	Description
`id`	string	Workflow unique identifier

Response

{
  "id": "wf_01HQ3K5X7Y8Z9ABCDEFGHIJK",
  "status": "archived",
  "archivedAt": "2024-03-01T12:00:00Z"
}

Execution Endpoints

These endpoints use the V1 API for executing workflows and retrieving execution results.

Execute Workflow

Execute a workflow synchronously or asynchronously.

POST /v1/workflows/{alias}/{version}/execute

Path Parameters

Parameter	Type	Description
`alias`	string	Workflow alias
`version`	string	Workflow version (e.g., `v1`, `v2`)

Request Body

The request body must conform to the workflow's input schema.

curl --request POST \
  --url https://bc.altscore.ai/v1/workflows/kyc-verification/v1/execute \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "borrowerId": "brw_01HQ3K5X7Y8Z9ABCDEFGHIJK",
    "documentType": "passport",
    "countryCode": "MX"
  }'

Synchronous Response

For synchronous workflows, the response includes the complete execution result:

{
  "isSuccess": true,
  "statusCode": 200,
  "executionId": "exec_01HQ3K5X7Y8Z9ABCDEFGHIJK",
  "output": {
    "verified": true,
    "score": 850,
    "decision": "approved",
    "fields": {
      "fullName": "Juan Garcia Lopez",
      "dateOfBirth": "1985-03-15",
      "documentNumber": "ABC123456"
    }
  },
  "customOutput": {
    "riskCategory": "low",
    "recommendedLimit": 50000
  },
  "attachments": [
    {
      "url": "https://storage.altscore.ai/reports/exec_01HQ3K5X7Y8Z9ABCDEFGHIJK.pdf",
      "fileExtension": "pdf",
      "metadata": {
        "type": "verification_report"
      }
    }
  ],
  "notes": ["Document verified against government database"],
  "notices": [],
  "errorMessage": null
}

Asynchronous Response

For asynchronous workflows, the response returns immediately with an execution ID:

{
  "executionId": "exec_01HQ3K5X7Y8Z9ABCDEFGHIJK",
  "status": "pending",
  "createdAt": "2024-02-10T18:45:00Z"
}

Get Execution Output

Retrieve the output of a completed execution.

GET /v1/executions/{execution_id}/output

Path Parameters

Parameter	Type	Description
`execution_id`	string	Execution unique identifier

Response

{
  "isSuccess": true,
  "statusCode": 200,
  "output": {
    "verified": true,
    "score": 850,
    "decision": "approved"
  },
  "customOutput": {
    "riskCategory": "low"
  },
  "attachments": [],
  "notes": [],
  "notices": [],
  "errorMessage": null
}

Get Execution Status

Check the current status of an execution.

GET /v1/executions/{execution_id}/status

Path Parameters

Parameter	Type	Description
`execution_id`	string	Execution unique identifier

curl --request GET \
  --url https://bc.altscore.ai/v1/executions/exec_01HQ3K5X7Y8Z9ABCDEFGHIJK/status \
  --header 'Authorization: Bearer {token}'

Response

{
  "executionId": "exec_01HQ3K5X7Y8Z9ABCDEFGHIJK",
  "status": "completed",
  "startedAt": "2024-02-10T18:45:00Z",
  "completedAt": "2024-02-10T18:45:32Z",
  "duration": 32000,
  "tasksCompleted": 8,
  "tasksFailed": 0
}

Execution Status Values

Status	Description
`pending`	Execution queued, not yet started
`running`	Execution in progress
`completed`	Execution finished successfully
`failed`	Execution terminated with errors
`cancelled`	Execution was manually cancelled
`timeout`	Execution exceeded time limit

Batch Execution Endpoints

Execute workflows for multiple subjects in a single batch operation.

Execute Batch

Start a batch execution for multiple items.

POST /v1/workflows/{alias}/{version}/execute-batch

Path Parameters

Parameter	Type	Description
`alias`	string	Workflow alias
`version`	string	Workflow version

Complete Batch Processing Walkthrough

This example demonstrates the full batch processing flow: generating a pre-signed URL, uploading your input file, executing the batch, polling for completion, and retrieving results.

Step 1: Generate Pre-Signed URL for File Upload

# Generate upload URL
curl --request POST \
  --url https://bc.altscore.ai/v1/stores/packages/commands/attachments/generate-upload-signed-url \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "fileName": "borrowers-batch.xlsx"
  }'

Response:

{
  "signedUrl": "https://storage.googleapis.com/...",
  "fileName": "9ad44ab7-30a9-400e-a741-44c008817e84.xlsx",
  "attachmentId": "9ad44ab7-30a9-400e-a741-44c008817e84",
  "contentType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
}

Step 2: Upload Your File

# Upload the file to the pre-signed URL
curl -X PUT \
  --url "https://storage.googleapis.com/..." \
  --header 'Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' \
  --data-binary @/path/to/borrowers-batch.xlsx

Step 3: Execute the Batch

curl --request POST \
  --url https://bc.altscore.ai/v1/workflows/kyc-verification/v1/execute-batch \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "label": "Q1 2024 KYC Refresh",
    "description": "Quarterly KYC verification for active borrowers",
    "attachmentFileNames": [
      "9ad44ab7-30a9-400e-a741-44c008817e84.xlsx"
    ],
    "workflowInput": {
      "items": [],
      "customInput": {},
      "rawPackageIds": []
    }
  }'

Step 4: Poll for Completion

# Check batch status
curl --request GET \
  --url https://bc.altscore.ai/v1/execution-batches/{batch_id} \
  --header 'Authorization: Bearer {token}'

Step 5: Retrieve Results

# Get the output package ID from the batch response
# Then retrieve the package attachments
curl --request GET \
  --url https://bc.altscore.ai/v1/stores/packages/{output_package_id}/attachments \
  --header 'Authorization: Bearer {token}'

Handling Partial Failures

If some items fail during processing, the batch still completes but reports failures:

if completed_batch.state.batch_items_executions_summary.failed > 0:
    print(f"Warning: {completed_batch.state.batch_items_executions_summary.failed} items failed")
 
    # Retry only failed items
    retry_result = alt_client.borrower_central.execution_batches.retry(
        batch_id=batch_id,
        retry_mode="failed_items",
        use_previous_inputs=True
    )

Request Body Reference

{
  "label": "Q1 2024 KYC Refresh",
  "description": "Quarterly KYC verification for active borrowers",
  "attachmentFileNames": [
    "9ad44ab7-30a9-400e-a741-44c008817e84.xlsx"
  ],
  "workflowInput": {
    "items": [
      { "borrowerId": "brw_001", "documentType": "passport" },
      { "borrowerId": "brw_002", "documentType": "national_id" },
      { "borrowerId": "brw_003", "documentType": "driver_license" }
    ],
    "customInput": {},
    "rawPackageIds": []
  }
}

Response

{
  "executionBatchId": "batch_01HQ3K5X7Y8Z9ABCDEFGHIJK",
  "workflowId": "wf_01HQ3K5X7Y8Z9ABCDEFGHIJK",
  "workflowAlias": "kyc-verification",
  "workflowVersion": "v1",
  "executedAt": "2024-02-10T19:00:00Z"
}

Get Batch Status

Retrieve the current status and progress of a batch execution.

GET /v1/execution-batches/{batch_id}

Path Parameters

Parameter	Type	Description
`batch_id`	string	Batch execution identifier

Response

{
  "executionBatchId": "batch_01HQ3K5X7Y8Z9ABCDEFGHIJK",
  "workflowId": "wf_01HQ3K5X7Y8Z9ABCDEFGHIJK",
  "workflowAlias": "kyc-verification",
  "workflowVersion": "v1",
  "label": "Q1 2024 KYC Refresh",
  "status": "processing",
  "state": {
    "batchItemsExecutionsSummary": {
      "total": 150,
      "completed": 87,
      "failed": 3,
      "pending": 60,
      "unsuccessfulSources": 2
    }
  },
  "outputs": {
    "wBatchPreProcessingOutput": {
      "result": "success",
      "validatedItemsCount": 150
    },
    "wBatchPostProcessingOutput": {
      "processedOutputPackageId": null
    }
  },
  "createdAt": "2024-02-10T19:00:00Z",
  "updatedAt": "2024-02-10T19:15:00Z"
}

Batch Status Values

Status	Description
`pending`	Batch created, waiting to be processed
`pre_processing`	Validating input data
`pre_processing_complete`	Input validated, ready to execute
`pre_processing_failed`	Input validation failed
`processing`	Executing workflow for each item
`post_processing`	Generating output files
`post_processing_failed`	Output generation failed
`complete`	Batch finished successfully
`paused`	Batch execution paused
`cancelled`	Batch execution cancelled

Retry Failed Batch

Retry a failed batch phase or failed items.

POST /v1/execution-batches/{batch_id}/retry

Path Parameters

Parameter	Type	Description
`batch_id`	string	Batch execution identifier

Request Body

{
  "retryMode": "failed_items",
  "usePreviousInputs": true,
  "attachmentFileNames": [],
  "workflowInput": {
    "items": [],
    "customInput": {},
    "rawPackageIds": []
  }
}

Retry Modes

Mode	Description
`pre_processing`	Retry input validation phase
`post_processing`	Retry output generation phase
`failed_items`	Retry only items that failed during processing
`unsuccessful_sources_items`	Retry items with data source failures
`failed_and_unsuccessful_sources_items`	Retry both failed and unsuccessful source items

Scheduling Endpoints

Configure recurring workflow executions.

Configure Schedule

Set up a recurring schedule for workflow execution.

POST /v1/workflows/commands/configure-schedules

Request Body

{
  "workflowId": "wf_01HQ3K5X7Y8Z9ABCDEFGHIJK",
  "schedule": {
    "cron": "0 8 * * 1-5",
    "utcDeltaHours": -5
  },
  "scheduleBatch": {
    "cron": "0 6 * * 0",
    "utcDeltaHours": -5
  }
}

Field	Description
`schedule`	Configuration for single-item execution schedule
`scheduleBatch`	Configuration for batch execution schedule
`cron`	Cron expression defining the schedule
`utcDeltaHours`	Timezone offset from UTC

The example configures single executions at 8:00 AM (UTC-5) on weekdays and batch executions at 6:00 AM (UTC-5) on Sundays.

Response

{
  "workflowId": "wf_01HQ3K5X7Y8Z9ABCDEFGHIJK",
  "schedule": {
    "cron": "0 8 * * 1-5",
    "utcDeltaHours": -5,
    "nextRunAt": "2024-02-12T13:00:00Z"
  },
  "scheduleBatch": {
    "cron": "0 6 * * 0",
    "utcDeltaHours": -5,
    "nextRunAt": "2024-02-18T11:00:00Z"
  }
}

Delete Schedule

Remove a workflow's execution schedule.

POST /v1/workflows/commands/delete-schedules

Request Body

{
  "workflowId": "wf_01HQ3K5X7Y8Z9ABCDEFGHIJK",
  "schedule": true,
  "scheduleBatch": true
}

Field	Type	Description
`schedule`	boolean	Delete single-item schedule if `true`
`scheduleBatch`	boolean	Delete batch schedule if `true`

Response

{
  "workflowId": "wf_01HQ3K5X7Y8Z9ABCDEFGHIJK",
  "schedulesDeleted": ["schedule", "scheduleBatch"]
}

Error Handling

All API errors follow a consistent response format.

Error Response Format

{
  "code": "VALIDATION_ERROR",
  "message": "Request validation failed",
  "details": [
    {
      "field": "inputSchema.properties.borrowerId",
      "message": "Required field is missing"
    }
  ],
  "errorSubCode": "MISSING_REQUIRED_FIELD",
  "requestId": "req_01HQ3K5X7Y8Z9ABCDEFGHIJK"
}

Common Error Codes

HTTP Status	Code	Description
400	`VALIDATION_ERROR`	Request body or parameters are invalid
401	`UNAUTHORIZED`	Missing or invalid authentication token
403	`FORBIDDEN`	Insufficient permissions for the operation
404	`NOT_FOUND`	Requested resource does not exist
409	`CONFLICT`	Resource state conflict (e.g., publishing already active workflow)
422	`UNPROCESSABLE_ENTITY`	Request understood but cannot be processed
429	`RATE_LIMITED`	Too many requests, please retry later
500	`INTERNAL_ERROR`	Unexpected server error
503	`SERVICE_UNAVAILABLE`	Service temporarily unavailable

Error Sub-Codes

Sub-Code	Description
`MISSING_REQUIRED_FIELD`	Required field not provided
`INVALID_FIELD_TYPE`	Field value has incorrect type
`INVALID_WORKFLOW_STATUS`	Operation not allowed for current workflow status
`EXECUTION_TIMEOUT`	Workflow execution exceeded time limit
`EXTERNAL_SERVICE_ERROR`	External service call failed
`INPUT_SCHEMA_MISMATCH`	Execution input does not match workflow schema
`CIRCULAR_DEPENDENCY`	Workflow contains circular task dependencies

Handling Errors

async function executeWorkflow(alias, version, input) {
  try {
    const response = await fetch(
      `https://bc.altscore.ai/v1/workflows/${alias}/${version}/execute`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${token}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(input)
      }
    )
 
    if (!response.ok) {
      const error = await response.json()
 
      if (error.errorSubCode === 'INPUT_SCHEMA_MISMATCH') {
        console.error('Input validation failed:', error.details)
      } else if (response.status === 429) {
        // Implement retry with exponential backoff
        await delay(error.retryAfter || 1000)
        return executeWorkflow(alias, version, input)
      }
 
      throw new Error(`API Error: ${error.code} - ${error.message}`)
    }
 
    return await response.json()
  } catch (err) {
    console.error('Workflow execution failed:', err)
    throw err
  }
}

Rate Limits

API requests are subject to rate limiting to ensure fair usage.

Endpoint Category	Rate Limit
Workflow Management	100 requests/minute
Single Execution	50 requests/minute
Batch Execution	10 requests/minute
Status Polling	200 requests/minute

When rate limited, the API returns a 429 status code with a Retry-After header indicating when to retry.

On this page