Bermuda Commercial Bank RESTful Open Banking API Implementation (v1)

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Retrieves a paginated list of background jobs for the authenticated client. This endpoint:

• Returns only active jobs (status: Pending or InProgress)
• Completed, failed, or cancelled jobs are not included in this list
• Provides job status information including progress summaries
• Supports pagination for efficient handling of large job datasets

Job Status Information

Each job entry includes:

• JobId: Unique identifier for the batch job
• JobStatus: Current status (Pending, InProgress, Completed, CompletedWithErrors, Cancelled)
  • Pending: Job has been created and is waiting to be processed
  • InProgress: Job is currently being processed
  • Completed: Job has completed successfully with no errors
  • CompletedWithErrors: Job has completed but some items failed during processing
  • Cancelled: Job has been cancelled and will not be processed further
• EventType: Type of status event (typically "job.status")
• Summary: Progress statistics (Total, Completed, Failed counts)

Pagination

This endpoint uses simple numeric pagination:

• pageStart: 1-based index of the first record to return (default: 1)
• pageSize: Number of records to return (default: 100, maximum: 1000)
• Total Pages: Calculate using Math.ceil(total_size / page_size) from response metadata

Content Negotiation

Clients must use the HTTP Accept header to indicate the desired response format:

• Set Accept: application/json for JSON responses (default)
• Set Accept: text/csv for CSV responses If the Accept header is omitted, application/json is assumed.

Base URL

All API requests use the versioned base URL:

https://api.bcb.bm/v1/jobs

Sample Request in JavaScript

async function getAllBackgroundJobs(pageStart = 1, pageSize = 50) {
  try {
    // Build URL with pagination parameters
    let url = 'https://api.bcb.bm/v1/jobs';
    const params = new URLSearchParams();
    
    params.append('pageStart', pageStart.toString());
    params.append('pageSize', pageSize.toString());
    
    url += '?' + params.toString();

    const response = await fetch(url, {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      }
    });

    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`Background jobs retrieval failed: ${JSON.stringify(errorData)}`);
    }

    // Parse JSON response
    const result = await response.json();

    // Access pagination info
    const pagination = result.meta.pagination;
    console.log(`Page: ${pagination.page_start}, Size: ${pagination.page_size}, Total: ${pagination.total_size}`);

    // Process background jobs
    result.data.forEach((job, index) => {
      console.log(`Job ${index + 1}:`);
      console.log(`  Job ID: ${job.jobId}`);
      console.log(`  Status: ${job.jobStatus}`);
      console.log(`  Event Type: ${job.eventType}`);
      console.log(`  Summary:`);
      console.log(`    Total: ${job.summary.total}`);
      console.log(`    Completed: ${job.summary.completed}`);
      console.log(`    Failed: ${job.summary.failed}`);
      console.log('---');
    });

    return result;
  } catch (error) {
    console.error('Failed to retrieve background jobs:', error.message);
    throw error;
  }
}

// Example usage:

// Get first 50 jobs
getAllBackgroundJobs(1, 50);

// Get next page
getAllBackgroundJobs(2, 50);

// Get all jobs with default pagination
getAllBackgroundJobs();

Retrieves the current status and progress information for a specific background job. This endpoint:

• Returns detailed status information for the specified job
• Provides real-time progress statistics (total, completed, failed counts)
• Shows current job status (Pending, InProgress, Completed, Failed, Cancelled)
• Includes event type information for status tracking

Job Status Information

The response includes:

• JobId: Unique identifier for the batch job
• JobStatus: Current status (Pending, InProgress, Completed, CompletedWithErrors, Cancelled)
  • Pending: Job has been created and is waiting to be processed
  • InProgress: Job is currently being processed
  • Completed: Job has completed successfully with no errors
  • CompletedWithErrors: Job has completed but some items failed during processing
  • Cancelled: Job has been cancelled and will not be processed further
• EventType: Type of status event (typically "job.status")
• Summary: Progress statistics (Total, Completed, Failed counts)

Callback Notifications

When a job reaches a completed state (Completed or CompletedWithErrors), the system automatically sends a callback notification to the callbackUrl provided during job creation (if specified). This callback allows you to receive real-time notifications without polling the status endpoint.

Sample Callback Payload:

{
  "eventType": "job.completed",
  "jobId": "badabb89-8cdb-4d3d-aaf0-c714f487f1bc",
  "jobStatus": "Completed",
  "summary": {
    "total": 1,
    "completed": 1,
    "failed": 0
  }
}

Message Signing

Callback notifications are signed. When your client configuration enables response signing, callbacks use the asymmetric option (RSA-PSS + SHA-256) and include Bcb-Signature, Bcb-Timestamp, Bcb-Nonce, and Bcb-Signature-Version (e.g., rsa-v1). If asymmetry is not configured, callbacks use the HMAC option with your Message Signing Secret and no Bcb-Signature-Version header. See the Message Signing guide for verification steps.

Content Negotiation

Clients must use the HTTP Accept header to indicate the desired response format:

• Set Accept: application/json for JSON responses (default)
• Set Accept: text/csv for CSV responses If the Accept header is omitted, application/json is assumed.

Base URL

All API requests use the versioned base URL:

https://api.bcb.bm/v1/jobs/{jobId}

Sample Request in JavaScript

async function getJobStatus(jobId) {
  try {
    const url = `https://api.bcb.bm/v1/jobs/${jobId}`;

    const response = await fetch(url, {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      }
    });

    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`Job status retrieval failed: ${JSON.stringify(errorData)}`);
    }

    // Parse JSON response
    const jobStatus = await response.json();

    // Display job information
    console.log('Job Status:');
    console.log(`  Job ID: ${jobStatus.jobId}`);
    console.log(`  Status: ${jobStatus.jobStatus}`);
    console.log(`  Event Type: ${jobStatus.eventType}`);
    console.log(`  Progress Summary:`);
    console.log(`    Total Items: ${jobStatus.summary.total}`);
    console.log(`    Completed: ${jobStatus.summary.completed}`);
    console.log(`    Failed: ${jobStatus.summary.failed}`);
    console.log(`    Progress: ${((jobStatus.summary.completed / jobStatus.summary.total) * 100).toFixed(1)}%`);

    return jobStatus;
  } catch (error) {
    console.error('Failed to retrieve job status:', error.message);
    throw error;
  }
}

// Example usage:

// Get status for a specific job
getJobStatus('550e8400-e29b-41d4-a716-446655440001');

Cancels a background job and stops processing of all pending and in-progress items. This endpoint:

• Cancels the specified job if it's in a cancellable state
• Stops processing of all pending and in-progress items within the job
• Marks cancelled items with appropriate error messages
• Returns the updated job status after cancellation
• Provides immediate feedback on cancellation success

Cancellation Rules

A job can only be cancelled if it's in one of these states:

• Pending: Job has been created but not yet started processing
• InProgress: Job is currently being processed

Jobs in these states cannot be cancelled:

• Completed: Job has already finished successfully
• CompletedWithErrors: Job has finished with some failures
• Cancelled: Job has already been cancelled

What Happens During Cancellation

1. Job Status Update: The job status is changed to "Cancelled"
2. Item Cancellation: All pending and in-progress items are marked as "Cancelled"
3. Error Messages: Cancelled items receive the error message "Job was cancelled by user request"
4. Counter Updates: Job completion counters are recalculated from the database
5. Immediate Effect: Processing stops immediately for all affected items

Content Negotiation

Clients must use the HTTP Accept header to indicate the desired response format:

• Set Accept: application/json for JSON responses (default)
• Set Accept: text/csv for CSV responses If the Accept header is omitted, application/json is assumed.

Base URL

All API requests use the versioned base URL:

https://api.bcb.bm/v1/jobs/{jobId}

Idempotency

The API supports idempotency through the optional Idempotency-Key header:

• If no idempotency key is provided, the request is processed normally (duplicates are possible)
• If a valid UUID idempotency key is provided, the system stores the key and associates it with the batch job
• If the same idempotency key is received again, the system returns the previously stored response
• Idempotency keys are user-specific - different users with the same keys don't share cached responses
• The idempotency key must be a valid UUID format (e.g., "123e4567-e89b-12d3-a456-426614174000")

Sample Request in JavaScript

async function cancelJob(jobId) {
  try {
    const url = `https://api.bcb.bm/v1/jobs/${jobId}`;

    const response = await fetch(url, {
      method: 'DELETE',
      headers: {
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      }
    });

    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`Job cancellation failed: ${JSON.stringify(errorData)}`);
    }

    // Parse JSON response
    const jobStatus = await response.json();

    // Display cancellation result
    console.log('Job Cancellation Result:');
    console.log(`  Job ID: ${jobStatus.jobId}`);
    console.log(`  Status: ${jobStatus.jobStatus}`);
    console.log(`  Event Type: ${jobStatus.eventType}`);
    console.log(`  Final Summary:`);
    console.log(`    Total Items: ${jobStatus.summary.total}`);
    console.log(`    Completed: ${jobStatus.summary.completed}`);
    console.log(`    Failed: ${jobStatus.summary.failed}`);
    console.log(`    Cancelled: ${jobStatus.summary.total - jobStatus.summary.completed - jobStatus.summary.failed}`);

    return jobStatus;
  } catch (error) {
    console.error('Failed to cancel job:', error.message);
    throw error;
  }
}

// Example usage:

// Cancel a specific job
cancelJob('550e8400-e29b-41d4-a716-446655440001');

Retrieves the detailed results for a specific background job. This endpoint:

• Returns paginated results for all items processed in the job
• Provides detailed information about each item's processing outcome
• Shows processing status, attempts, HTTP responses, and error details
• Includes original payload and result data for auditing
• Supports pagination for efficient handling of large result sets

Job Results Information

Each result entry includes:

• Id: Internal numeric identifier for this item result
• JobId: Identifier of the parent batch job
• ExternalItemId: Client-supplied item identifier from the original batch
• PayloadJson: Original request payload serialized as JSON
• Status: Current processing status (Pending, InProgress, Completed, Failed, Cancelled)
• Attempt: Number of processing attempts made for this item
• HttpStatusCode: HTTP status code returned by the target endpoint
• ResultJson: Response payload from the target endpoint (if successful)
• ErrorMessage: Error details (if processing failed)

Pagination

This endpoint uses simple numeric pagination:

• pageStart: 1-based index of the first record to return (default: 1)
• pageSize: Number of records to return (default: 100, maximum: 1000)
• Total Pages: Calculate using Math.ceil(total_size / page_size) from response metadata

Content Negotiation

Clients must use the HTTP Accept header to indicate the desired response format:

• Set Accept: application/json for JSON responses (default)
• Set Accept: text/csv for CSV responses If the Accept header is omitted, application/json is assumed.

Base URL

All API requests use the versioned base URL:

https://api.bcb.bm/v1/jobs/{jobId}/results

Sample Request in JavaScript

async function getJobResults(jobId, pageStart = 1, pageSize = 50) {
  try {
    const url = `https://api.bcb.bm/v1/jobs/${jobId}/results`;
    const params = new URLSearchParams();
    
    params.append('pageStart', pageStart.toString());
    params.append('pageSize', pageSize.toString());
    
    const fullUrl = url + '?' + params.toString();

    const response = await fetch(fullUrl, {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      }
    });

    if (!response.ok) {
      const errorData = await response.json();
      throw new Error(`Job results retrieval failed: ${JSON.stringify(errorData)}`);
    }

    // Parse JSON response
    const result = await response.json();

    // Access pagination info
    const pagination = result.meta.pagination;
    console.log(`Page: ${pagination.page_start}, Size: ${pagination.page_size}, Total: ${pagination.total_size}`);

    // Process job results
    result.data.forEach((item, index) => {
      console.log(`Result ${index + 1}:`);
      console.log(`  Item ID: ${item.externalItemId}`);
      console.log(`  Status: ${item.status}`);
      console.log(`  Attempts: ${item.attempt}`);
      console.log(`  HTTP Status: ${item.httpStatusCode}`);
      
      if (item.errorMessage) {
        console.log(`  Error: ${item.errorMessage}`);
      }
      
      if (item.resultJson) {
        console.log(`  Result: ${item.resultJson}`);
      }
      
      console.log('---');
    });

    return result;
  } catch (error) {
    console.error('Failed to retrieve job results:', error.message);
    throw error;
  }
}

// Example usage:

// Get first 50 results for a job
getJobResults('550e8400-e29b-41d4-a716-446655440001', 1, 50);

// Get next page of results
getJobResults('550e8400-e29b-41d4-a716-446655440001', 2, 50);

// Get all results with default pagination
getJobResults('550e8400-e29b-41d4-a716-446655440001');