Developer Docs

INTEGRO API

Integrate digital protection directly into your applications with our RESTful API. Breach checks, identity scans, risk scoring, and more.

Base URL https://integro.finendar.com/api/v1/

Get Started Free

Quick Start

Get up and running with the INTEGRO API in under 5 minutes.

Create an Account

Subscribe to an API Plan

Head to API Access in your dashboard and choose a plan (Starter, Professional, or Enterprise).

Generate an API Key

Generate your API key from the API Access page. Keys start with intg_ and are shown only once — save it securely.

Make Your First Request

Test your key with the health endpoint below.

cURL

curl -X GET https://integro.finendar.com/api/v1/health/ \
  -H "Authorization: Bearer intg_your_api_key_here"

Response

{
  "status": "ok",
  "api_version": "v1",
  "authenticated": true,
  "user": "your_username",
  "timestamp": "2026-02-17T12:00:00Z"
}
                        

Authentication

All API requests must include your API key in the Authorization header using the Bearer scheme.

Header Format

Authorization: Bearer intg_your_api_key_here

Language Examples

Python

import requests

API_KEY = "intg_your_api_key_here"
BASE_URL = "https://integro.finendar.com/api/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.get(f"{BASE_URL}/health/", headers=headers)
print(response.json())

JavaScript

const API_KEY = "intg_your_api_key_here";
const BASE_URL = "https://integro.finendar.com/api/v1";

const response = await fetch(`${BASE_URL}/health/`, {
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json"
  }
});

const data = await response.json();
console.log(data);

PHP

$apiKey = "intg_your_api_key_here";
$baseUrl = "https://integro.finendar.com/api/v1";

$ch = curl_init("$baseUrl/health/");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer $apiKey",
    "Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($response);

Security Notice

Never expose your API key in client-side code, public repositories, or browser requests. Always make API calls from your server backend. If a key is compromised, revoke it immediately from your API dashboard.

Rate Limits

Rate limits are enforced per API key and vary by plan. When you exceed the limit, the API returns 429 Too Many Requests.

Plan	Requests / Minute	Requests / Month
Starter	10	1,000
Professional	60	10,000
Enterprise	300	Unlimited

Rate Limit Headers

Every response includes rate limit information:

Response Headers

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1708174800
Retry-After: 45          (only on 429 responses)
                        

Monthly usage resets on your billing date. Check current usage via the /usage/ endpoint.

Error Handling

All errors return a consistent JSON structure:

Error Response

{
  "error": "Human-readable error message",
  "code": "error_code",
  "details": { }
}
                        

Code	Error Code	Description
400	`validation_error`	Invalid request body or parameters
401	`authentication_error`	Missing, invalid, or expired API key
403	`limit_exceeded`	Plan limit reached (identities, scans, etc.)
404	`not_found`	Resource does not exist
429	`rate_limited`	Too many requests — slow down
500	`internal_error`	Server error — try again later

Retry Strategy

For 429 and 5xx errors, implement exponential backoff starting at 1 second, doubling each retry, up to 5 attempts.

Python — Retry Example

import time, requests

def api_request(url, headers, max_retries=5):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code == 429:
            wait = int(response.headers.get("Retry-After", 2 ** attempt))
            print(f"Rate limited. Retrying in {wait}s...")
            time.sleep(wait)
            continue
        return response
    raise Exception("Max retries exceeded")

Health Check

GET /api/v1/health/

Verify API connectivity and validate your authentication credentials.

200 OK

{
  "status": "ok",
  "api_version": "v1",
  "authenticated": true,
  "user": "johndoe",
  "timestamp": "2026-02-17T12:00:00Z"
}
                            

Breach Check

POST /api/v1/breach-check/

Check an email address or username against known data breaches. Returns matched breaches with severity ratings.

Request Body

Parameter	Type	Required	Description
email	string	conditional	Email to check. Required if `username` not provided.
username	string	conditional	Username to check. Required if `email` not provided.

cURL Example

curl -X POST https://integro.finendar.com/api/v1/breach-check/ \
  -H "Authorization: Bearer intg_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

200 OK

{
  "checked": "user@example.com",
  "total_breaches": 3,
  "breaches": [
    {
      "source": "ExampleCorp",
      "title": "ExampleCorp Data Breach 2024",
      "date": "2024-03-15",
      "data_types": ["email", "password_hash", "name"],
      "severity": "high",
      "description": "Database exposed via misconfigured server"
    }
  ],
  "risk_level": "medium",
  "checked_at": "2026-02-17T12:05:00Z"
}
                            

Identities

GET /api/v1/identities/

List all active identities associated with your account.

200 OK

{
  "count": 2,
  "identities": [
    {
      "id": "a1b2c3d4-...",
      "name": "Personal",
      "identity_type": "personal",
      "full_name": "John Doe",
      "emails": ["john@example.com"],
      "usernames": ["johnd"],
      "phones": ["+1234567890"],
      "is_primary": true,
      "is_active": true,
      "last_scanned": "2026-02-15T10:00:00Z",
      "created_at": "2026-01-10T08:30:00Z"
    }
  ]
}
                            

POST /api/v1/identities/

Create a new identity to monitor. Subject to your plan's identity limit.

Request Body

Parameter	Type	Required	Description
name	string	required	Label for this identity
identity_type	string	optional	`personal`, `professional`, `business`, `alias`, or `other`
full_name	string	optional	Full name for the identity
emails	array	optional	List of email addresses
usernames	array	optional	List of usernames
phones	array	optional	List of phone numbers
is_primary	boolean	optional	Set as primary identity (default: false)

cURL Example

curl -X POST https://integro.finendar.com/api/v1/identities/ \
  -H "Authorization: Bearer intg_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Work Identity",
    "identity_type": "professional",
    "full_name": "John Doe",
    "emails": ["john@company.com"],
    "usernames": ["johndoe_work"]
  }'

GET DELETE /api/v1/identities/{identity_id}/

GET retrieves identity details. DELETE deactivates the identity (soft delete, returns 204).

Parameter	Type	In	Description
identity_id	UUID	Path	The identity's unique identifier

Scans

POST /api/v1/scans/

Initiate a new security scan on an identity. Consumes a scan from your plan or deducts from your wallet balance.

Request Body

Parameter	Type	Required	Description
identity_id	UUID	required	Identity to scan
scan_type	string	optional	`quick`, `full`, `deep`, `breach`, or `social`. Default: `quick`
callback_url	string	optional	Webhook URL for scan completion (Professional+ plans)

cURL Example

curl -X POST https://integro.finendar.com/api/v1/scans/ \
  -H "Authorization: Bearer intg_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"identity_id": "a1b2c3d4-...", "scan_type": "full"}'

201 Created

{
  "scan_id": "e5f6g7h8-...",
  "status": "pending",
  "progress": 0,
  "scan_type": "full",
  "scan_source": "plan",
  "identity": "a1b2c3d4-...",
  "created_at": "2026-02-17T12:10:00Z"
}
                            

GET /api/v1/scans/{scan_id}/

Get the current status and summary of a scan. Poll this endpoint to track progress.

200 OK

{
  "scan_id": "e5f6g7h8-...",
  "status": "completed",
  "progress": 100,
  "scan_type": "full",
  "current_task": null,
  "findings_count": 12,
  "critical_count": 1,
  "high_count": 3,
  "medium_count": 5,
  "low_count": 3,
  "created_at": "2026-02-17T12:10:00Z",
  "started_at": "2026-02-17T12:10:02Z",
  "completed_at": "2026-02-17T12:12:45Z"
}
                            

GET /api/v1/scans/{scan_id}/findings/

Retrieve all findings from a completed scan. Supports filtering and pagination.

Query Parameters

Parameter	Type	Description
severity	string	Filter: `critical`, `high`, `medium`, `low`
category	string	Filter: `breach`, `exposure`, `dark_web`, `social`, `credential`
page	integer	Page number (default: 1, 25 results per page)

200 OK

{
  "scan_id": "e5f6g7h8-...",
  "total_findings": 12,
  "page": 1,
  "per_page": 25,
  "findings": [
    {
      "id": "f1g2h3i4-...",
      "title": "Email found in data breach",
      "description": "Your email was found in the ExampleCorp breach",
      "severity": "high",
      "category": "breach",
      "status": "open",
      "source": "ExampleCorp Breach Database",
      "remediation_steps": [
        "Change your password immediately",
        "Enable two-factor authentication"
      ],
      "created_at": "2026-02-17T12:12:30Z"
    }
  ]
}
                            

Risk Score

GET /api/v1/risk-score/

Get your overall risk score (0–100) with category breakdowns and actionable recommendations.

Query Parameters

Parameter	Type	Description
identity_id	UUID	Optional. Score for a specific identity. Omit for account-wide score.

200 OK

{
  "overall_score": 42,
  "risk_level": "medium",
  "trend": "improving",
  "categories": {
    "breach": 65,
    "exposure": 30,
    "password": 45,
    "social": 20,
    "dark_web": 50
  },
  "recommendations": [
    "Change compromised passwords found in recent breaches",
    "Enable 2FA on accounts with high-severity findings",
    "Remove personal data from 3 data broker sites"
  ],
  "last_calculated": "2026-02-17T06:00:00Z"
}
                            

Usage Stats

GET /api/v1/usage/

Get your current API usage statistics, including requests used, limits, and subscription status.

200 OK

{
  "plan": "professional",
  "requests_used": 2847,
  "requests_limit": 10000,
  "requests_remaining": 7153,
  "rate_limit_per_minute": 60,
  "usage_reset_date": "2026-03-16",
  "subscription_expires": "2026-03-16T00:00:00Z",
  "is_active": true
}
                            

API Plans

Choose the API plan that matches your usage needs.

Starter

$29.99/mo

1,000 requests/month

10 req/min rate limit

Breach Check • Risk Score • Basic Support

Professional

$79.99/mo

10,000 requests/month

60 req/min rate limit

+ Full OSINT Scan • Webhooks • Priority Support

Enterprise

$199.99/mo

Unlimited requests

300 req/min rate limit

+ Custom Integrations • SLA • Dedicated Support

Status Codes

Code	Meaning
200	Success — request processed
201	Created — resource created successfully
204	No Content — resource deleted successfully
400	Bad Request — invalid parameters
401	Unauthorized — missing or invalid API key
403	Forbidden — plan limit exceeded or insufficient permissions
404	Not Found — resource doesn't exist
429	Too Many Requests — rate limit exceeded
500	Internal Server Error — please retry

SDKs & Libraries

Official client libraries to help you integrate faster.

Python

pip install integro-python

Node.js

npm install @integro/node

PHP

composer require integro/php-sdk

Python SDK — Quick Example

from integro import IntegroClient

client = IntegroClient("intg_your_api_key")

# Check an email for breaches
result = client.breach_check(email="user@example.com")
print(f"Found {result.total_breaches} breaches")

# Initiate a full scan
scan = client.scans.create(
    identity_id="a1b2c3d4-...",
    scan_type="full"
)

# Wait for completion
scan.wait_until_complete()
print(f"Found {scan.findings_count} findings")

Webhooks

Receive real-time notifications when events occur. Available on Professional and Enterprise plans.

Supported Events

Event	Description
scan.completed	A scan has finished processing
finding.new	A new finding was detected
alert.triggered	An alert condition was met
breach.detected	Your identity appeared in a new breach

Webhook Payload

POST to your callback URL

{
  "event": "scan.completed",
  "timestamp": "2026-02-17T12:12:45Z",
  "data": {
    "scan_id": "e5f6g7h8-...",
    "identity_id": "a1b2c3d4-...",
    "status": "completed",
    "findings_count": 12,
    "critical_count": 1
  },
  "signature": "sha256=abc123..."
}
                        

Verification

Always verify the signature header using your webhook secret before processing payloads. This prevents spoofed requests.

Changelog

Feb 2026

New

API v1 Launch — Initial release with breach check, identity management, scanning, risk scoring, and webhook support.

Feb 2026

New

Python, Node.js, and PHP SDKs — Official client libraries published.

Coming

Planned

Batch Breach Check — Check up to 100 emails in a single request.

Coming

Planned

Dark Web Monitoring API — Programmatic access to real-time dark web alerts.