API Access

What is the TradeLasso API?

The TradeLasso REST API allows you to programmatically access all TradeLasso features from your own applications. Build custom integrations, automate screening workflows, and embed compliance checks directly into your systems.

Common use cases include:

• Screening customers during account creation or checkout
• Automating vendor onboarding with compliance checks
• Integrating screening into your CRM, ERP, or custom applications
• Building internal compliance dashboards and reporting tools
• Bulk screening large datasets programmatically

Getting started

1. Generate an API key

To use the API, you'll need an API key. Generate one in Dashboard → Settings → API Keys:

1. Click "Create API Key"
2. Give your key a descriptive name (e.g., "Production App", "Dev Environment")
3. Copy the key immediately — it won't be shown again
4. Store the key securely (use environment variables, never commit to source control)

2. Make your first request

All API requests require authentication via the Authorization header:

curl https://api.tradelasso.com/v1/screen \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Smith",
    "country": "US"
  }'

3. Handle the response

Successful responses return JSON with a 200 status code:

{
  "id": "scr_abc123",
  "status": "completed",
  "entity": {
    "name": "John Smith",
    "country": "US"
  },
  "result": {
    "match_count": 0,
    "status": "no_match",
    "lists_searched": ["OFAC SDN", "BIS Entity List"]
  },
  "created_at": "2026-05-05T18:30:00Z"
}

API endpoints

Screening

• POST /v1/screen — Screen a single entity
• GET /v1/screenings/:id — Retrieve screening results
• GET /v1/screenings — List all screenings (paginated)

Batch screening

• POST /v1/batch — Create a batch screening job
• GET /v1/batch/:id — Get batch job status and results
• GET /v1/batch — List all batch jobs

Saved profiles

• POST /v1/profiles — Save an entity profile
• GET /v1/profiles/:id — Retrieve a saved profile
• GET /v1/profiles — List all saved profiles
• PUT /v1/profiles/:id — Update a profile
• DELETE /v1/profiles/:id — Delete a profile

Watchlist monitoring (Advanced/Complete)

• POST /v1/monitors — Create a watchlist monitor
• GET /v1/monitors/:id — Get monitor details
• POST /v1/monitors/:id/entities — Add entities to a monitor
• GET /v1/monitors/:id/alerts — Get monitoring alerts

Compliance documents (Advanced/Complete)

• POST /v1/certificates — Generate a compliance certificate
• GET /v1/certificates/:id — Download a certificate
• POST /v1/reports — Generate a PDF compliance report

Authentication

All API requests must include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

If authentication fails, you'll receive a 401 Unauthorized response.

Rate limits

API rate limits vary by plan:

Rate limits are per API key. If you exceed your limit, you'll receive a 429 Too Many Requests response with a Retry-After header.

Error handling

The API uses standard HTTP status codes:

• 200 — Success
• 400 — Bad request (invalid parameters)
• 401 — Unauthorized (invalid or missing API key)
• 403 — Forbidden (feature not available on your plan)
• 404 — Not found
• 429 — Rate limit exceeded
• 500 — Internal server error

Error response format

{
  "error": {
    "code": "invalid_parameter",
    "message": "The 'country' field must be a valid ISO 3166-1 alpha-2 code",
    "param": "country"
  }
}

Example: Screening workflow

Here's a complete example of screening an entity and handling the results:

Node.js

const axios = require('axios');

async function screenEntity(name, country) {
  try {
    const response = await axios.post(
      'https://api.tradelasso.com/v1/screen',
      { name, country },
      {
        headers: {
          'Authorization': `Bearer ${process.env.TRADELASSO_API_KEY}`,
          'Content-Type': 'application/json'
        }
      }
    );
    
    const { result } = response.data;
    
    if (result.status === 'no_match') {
      console.log('✓ No matches found - safe to proceed');
      return { approved: true };
    } else {
      console.log(`⚠ Found ${result.match_count} potential matches`);
      return { approved: false, matches: result.matches };
    }
  } catch (error) {
    if (error.response?.status === 429) {
      console.error('Rate limit exceeded - retry after', error.response.headers['retry-after']);
    } else {
      console.error('Screening failed:', error.message);
    }
    throw error;
  }
}

// Usage
screenEntity('John Smith', 'US')
  .then(result => console.log(result))
  .catch(err => console.error(err));

Python

import requests
import os

def screen_entity(name, country):
    response = requests.post(
        'https://api.tradelasso.com/v1/screen',
        json={'name': name, 'country': country},
        headers={
            'Authorization': f'Bearer {os.environ["TRADELASSO_API_KEY"]}',
            'Content-Type': 'application/json'
        }
    )
    
    if response.status_code == 429:
        retry_after = response.headers.get('Retry-After')
        raise Exception(f'Rate limit exceeded - retry after {retry_after}s')
    
    response.raise_for_status()
    result = response.json()['result']
    
    if result['status'] == 'no_match':
        print('✓ No matches found - safe to proceed')
        return {'approved': True}
    else:
        print(f'⚠ Found {result["match_count"]} potential matches')
        return {'approved': False, 'matches': result['matches']}

# Usage
result = screen_entity('John Smith', 'US')
print(result)

Best practices

• Use environment variables — Never hardcode API keys in your source code
• Implement retry logic — Handle rate limits with exponential backoff
• Cache results — Don't re-screen the same entity multiple times in a short period
• Use batch endpoints — For screening multiple entities, use batch endpoints instead of individual requests
• Handle errors gracefully — Always check status codes and handle errors appropriately
• Monitor usage — Track your API usage in Usage & Limits
• Rotate keys regularly — Generate new API keys periodically for security

API key management

Manage your API keys in Dashboard → Settings → API Keys:

• Create keys — Generate new API keys for different environments or applications
• Name keys — Use descriptive names to identify where each key is used
• View usage — See request counts and last used date for each key
• Revoke keys — Immediately disable compromised or unused keys
• Monitor activity — Track which keys are making requests

Full API reference

For complete API documentation including all endpoints, parameters, and response schemas, visit our interactive API reference:

api.tradelasso.com/docs →

Related documentation

• Webhooks & Integrations — Push data to your systems
• Batch Screening — Screen multiple entities
• Plan Limits & Usage — View your API limits