Getting Started with Rose API

Getting Started

Base URL

https://public.api.axleruns.com/api/v1/

Authentication

Obtain API Key

Please obtain an API key and set it in the X-API-Key header.

Go to the Settings menu, and navigate to the API KEYS tab, and click on the "Generate Key" Button.

Include your API key in the request header:

X-API-Key: your-api-key-here

Content Type

All requests must use application/json

Core Concepts

Data Relationships

The system works with three interconnected data types:

Entities: Your customers (individuals or businesses)
Transactions: Financial activities
Alerts: Suspicious activity flags referencing transactions and entities

The detailed data model is described in API Reference.

Here's how they connect:

Each transaction must reference at least one entity (sender, receiver, or both)
Alerts reference one or more transactions and the entities involved
Entities can appear across multiple transactions and alerts

Upload Sequence

Due to validation dependencies, you need to upload data in this specific order:

Entities → Upload your customer data first
Transactions → Upload transaction data (references entities)
Alerts → Upload alerts last (references both transactions and entities)

Working with Entities

Upload Entities

Upload your customer data directly via API. Maximum 500 entities per request.

Endpoint: POST /api/v1/transaction-monitoring/entities

Request Body:

{
  "entities": [
    {
      "entity_id": "cust-12345",
      "name": "John Smith",
      "type": "individual",
      "risk_score": 25,
      "country": "US"
    }
  ]
}

Response:

{
  "success": true,
  "processed": 1,
  "errors": []
}

Entity Requirements

entity_id: Your unique identifier for this customer
name: Customer name
type: Either "individual" or "business"
Additional fields as per your data model

Working with Transactions

Upload Process

Transactions follow a two-step process due to potentially large data volumes:

Get a pre-signed upload URL
Upload your transaction file to that URL

Step 1: Get Upload URL

Endpoint: POST /api/v1/transaction-monitoring/transactions/upload-via-url

Request:

{
  "filename": "transactions_2024_01.json",
  "content_type": "application/json"
}

Response:

{
  "upload_url": "https://...",
  "expires_at": "2028-09-15T10:00:00Z"
}

Step 2: Upload File

curl -X PUT \
  "your-upload-url-here" \
  -H "Content-Type: application/json" \
  -d @transactions.json

Transaction Data Format

Your transaction file should contain an array of transaction objects:

[
  {
    "transaction_id": "txn-001",
    "type": "deposit",    
    "event_time": "2024-01-10T14:30:00Z",
    "amount": "1500.00",
    "amount_currency": "USD",
    "sender": {
      "entity_id": "cust-12345",      
      "asset_out": {
        "amount": "1500.00",
        "currency_id": 840,
        "currency_type": "fiat",        
      }
    },
    "receiver": {
      "entity_id": "cust-67890"
    }   
  }
]

Key Transaction Fields

Required:

transaction_id: Your unique transaction identifier
amount: Transaction amount (decimal)
amount_currency: Currency code (see currency reference endpoints)

Conditional Requirements:

For crypto deposits: receiver_blockchain_addresses or sender_blockchain_addresses is required
When specifying currency: Both sent_currency and sent_currency_type must be provided together
sender_id and sender_name are mutually exclusive (use one or the other). Use sender_id when you are referencing an entity from prior API calls. Use sender_name when the transaction counterparty is not defined in your system, like a merchant name.
receiver_id and receiver_name are mutually exclusive (use one or the other). Use receiver_id when you are referencing an entity from prior API calls. Use receiver_name when the transaction counterparty is not defined in your system, like a merchant name.

Currency Handling

You'll need to use our numeric currency codes. Get the full list from:

Crypto: GET /api/v1/crypto/crypto-assets
Fiat: GET /api/v1/crypto/fiat-currencies
Chains: GET /api/v1/crypto/crypto-chains

Example response:

{
  "items": [
    {"id": 840, "symbol": "USD", "name": "US Dollar"},
    {"id": 978, "symbol": "EUR", "name": "Euro"}
  ],
  "total": 150,
  "page": 1
}

Working with Alerts

Upload Alerts

Submit alerts with optional execution trigger. Maximum 100 alerts per request.

Endpoint: POST /api/v1/transaction-monitoring/alerts

Request:

{
  "alerts": [
    {
      "alert_id": "alert-001",
      "entity_ids": ["cust-12345"],
      "flagged_transaction_ids": ["txn-001", "txn-002"],
      "alert_type": "unusual_activity",
      "severity": "high",
      "created_at": "2024-01-10T15:00:00Z"
    }
  ],
  "trigger_execution": true
}

Response:

{
  "success": true,
  "processed": 1,
  "execution_triggered": true
}

Alert Requirements

Must reference valid entity IDs and transaction IDs
At least one transaction must be flagged
Setting trigger_execution: true will immediately process the alerts. If set to false, alerts can be triggered via the UI or by Axle personnel.

Retrieving Results

Get Investigation Details

After processing, retrieve detailed risk assessments:

Endpoint: GET /api/v1/transaction-monitoring/investigation/{investigation_id}

Response:

{
  "investigation_id": "inv-12345",
  "status": "completed",
  "risk_score": 75,
  "risk_factors": [...],
  "recommendations": [...]
}

Submit Feedback

Provide feedback on investigation outcomes:

Endpoint: POST /api/v1/transaction-monitoring/rose-alert-feedback/

Request:

{
  "feedbacks": [
    {
      "investigation_id": "inv-12345",
      "status": "confirmed_suspicious",
      "analyst_notes": "Confirmed money laundering pattern"
    }
  ]
}

Error Handling

The API uses standard HTTP status codes:

200: Success
400: Bad request (check your parameters)
401: Authentication failed
422: Validation error (check data format)
500: Server error (retry with exponential backoff)

Error responses include details:

{
  "error": "validation_error",
  "message": "Invalid entity_id format",
  "details": {
    "field": "entity_id",
    "value": "invalid-id"
  }
}

Best Practices

Batch Operations: Use maximum batch sizes to reduce API calls
Error Recovery: Implement retry logic with exponential backoff
Webhooks: Set up webhook endpoints to receive processing notifications
Data Validation: Validate data locally before submission to avoid errors
Idempotency: Use consistent IDs to prevent duplicate submissions

Testing

Start with small data sets to verify your integration:

Upload 2-3 test entities
Upload 5-10 test transactions
Create 1-2 test alerts
Verify the investigation results