Immolo — Developers

Quickstart

Make your first assessment in 3 steps. You'll need your API key from the dashboard.

1. Get your API key

After your account is approved, find your key in the dashboard under API Keys. It starts with fm_live_

2. Connect a bank account

Use the Mastercard Open Banking Connect widget to let your applicant link their bank. You'll receive a customer_id on success — pass this as the bank_token.

3. Run your first assessment

CURL

curl -X POST https://api.immolo.co/v1/assess \
  -H "Authorization: Bearer fm_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "applicant_id": "usr_123",
    "bank_token": "mc_ob_xxxx",
    "applicant_name": "Maria Santos"
  }'

Authentication

All API requests must include your API key as a Bearer token in the Authorization header.

HEADER
Authorization: Bearer fm_live_your_key_here

Keep your key secret. Never expose it in frontend code or public repos. Use environment variables.

API Reference

POST /v1/assess

Run a full credit assessment for an applicant. Fetches bank data, enriches transactions, computes the Immolo Score, and returns a decision.

Parameter	Type	Required	Description
applicant_id	string	required	Your internal ID for the applicant
bank_token	string	required	Mastercard OB customer ID from Connect widget
applicant_name	string	optional	Full name for the assessment record
months_history	integer	optional	Months of history to analyze. Default: 24, max: 36

GET /v1/assess/:id

Retrieve a completed assessment by ID. Returns the full score, decision, and narrative.

GET /v1/assess

List all assessments for your account. Supports pagination via page and limit query params.

Code examples

CURL

curl -X POST https://api.immolo.co/v1/assess \
  -H "Authorization: Bearer fm_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"applicant_id":"usr_123","bank_token":"mc_ob_xxxx"}'

NODE.JS

const response = await fetch('https://api.immolo.co/v1/assess', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.IMMOLO_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    applicant_id: 'usr_123',
    bank_token: 'mc_ob_xxxx',
    applicant_name: 'Maria Santos'
  })
});
 
const result = await response.json();
console.log(result.immolo_score); // 847
console.log(result.decision);  // "approve"

PYTHON

import requests, os
 
response = requests.post(
  "https://api.immolo.co/v1/assess",
  headers={
    "Authorization": f"Bearer {os.environ['IMMOLO_API_KEY']}",
    "Content-Type": "application/json"
  },
  json={
    "applicant_id": "usr_123",
    "bank_token": "mc_ob_xxxx",
    "applicant_name": "Maria Santos"
  }
)
 
result = response.json()
print(result["immolo_score"])  # 847
print(result["decision"])   # approve

Errors

Immolo uses standard HTTP status codes. All errors return a JSON body with an error and message field.

Code	Meaning
200	Assessment completed successfully
400	Validation error — check your request body
401	Missing or invalid API key
404	Assessment not found
500	Assessment pipeline failed — check error message

Build with Immolo