Introduction
API documentation for the Blacklist reporting system. This API allows companies to report and search for clients in a shared blacklist across multiple business categories.
Welcome to the Blacklist API documentation.
This API allows companies to:
- Register and authenticate
- Report clients to a shared blacklist
- Search for clients across all reports
- View statistics and insights
All endpoints (except registration) require authentication via Bearer token.
Authenticating requests
To authenticate requests, include an Authorization header with the value "Bearer your-token-here".
All authenticated endpoints are marked with a requires authentication badge in the documentation below.
Get a token from POST /v1/auth/login and send it as Authorization: Bearer <token>.
Alternatively, authenticate with an API key: send X-API-Key: blh_... instead of the Authorization header. Manage your keys under /v1/api-keys.
BlacklistHub is invite-only: there is no public sign-up. Companies are created by a superadmin.
API Keys Management
APIs for managing company API keys. Companies can create, list, update, and delete their own API keys.
List API keys
requires authentication
Get all API keys for the authenticated company.
Example request:
curl --request GET \
--get "https://api.blacklisthub.io/v1/api-keys" \
--header "Authorization: Bearer your-token-here" \
--header "Content-Type: application/json" \
--header "Accept: application/json"const url = new URL(
"https://api.blacklisthub.io/v1/api-keys"
);
const headers = {
"Authorization": "Bearer your-token-here",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());Example response (200):
{
"success": true,
"status": 200,
"message": "API keys retrieved successfully",
"data": [
{
"id": 1,
"company_id": 1,
"name": "Production Server",
"key_prefix": "blh_AYpbX24Ypo32...",
"is_active": true,
"last_used_at": "2025-12-06T18:45:00.000000Z",
"created_at": "2025-12-06T18:00:00.000000Z",
"updated_at": "2025-12-06T18:45:00.000000Z"
}
]
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Create API key
requires authentication
Create a new API key for the authenticated company. The plain key is returned only once.
Example request:
curl --request POST \
"https://api.blacklisthub.io/v1/api-keys" \
--header "Authorization: Bearer your-token-here" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"name\": \"Production Server\"
}"
const url = new URL(
"https://api.blacklisthub.io/v1/api-keys"
);
const headers = {
"Authorization": "Bearer your-token-here",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"name": "Production Server"
};
fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
}).then(response => response.json());Example response (201):
{
"success": true,
"status": 201,
"message": "API key created successfully",
"data": {
"api_key": {
"id": 1,
"company_id": 1,
"name": "Production Server",
"key_prefix": "blh_AYpbX24Ypo32...",
"is_active": true,
"last_used_at": null,
"created_at": "2025-12-06T18:45:00.000000Z",
"updated_at": "2025-12-06T18:45:00.000000Z"
},
"plain_key": "blh_AYpbX24Ypo32HlIMocKVb1OCPxdvKBtfiSMg304Ffceb40c2a1b2c3",
"warning": "Store this API key securely. It will not be shown again."
}
}
Example response (400):
{
"success": false,
"status": 400,
"message": "Maximum number of API keys reached (10)",
"data": {}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Update API key
requires authentication
Update an API key's name or active status.
Example request:
curl --request PUT \
"https://api.blacklisthub.io/v1/api-keys/1" \
--header "Authorization: Bearer your-token-here" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"name\": \"Updated Name\",
\"is_active\": false
}"
const url = new URL(
"https://api.blacklisthub.io/v1/api-keys/1"
);
const headers = {
"Authorization": "Bearer your-token-here",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"name": "Updated Name",
"is_active": false
};
fetch(url, {
method: "PUT",
headers,
body: JSON.stringify(body),
}).then(response => response.json());Example response (200):
{
"success": true,
"status": 200,
"message": "API key updated successfully",
"data": {
"id": 1,
"company_id": 1,
"name": "Updated Name",
"key_prefix": "blh_AYpbX24Ypo32...",
"is_active": false,
"last_used_at": "2025-12-06T18:45:00.000000Z",
"created_at": "2025-12-06T18:00:00.000000Z",
"updated_at": "2025-12-06T19:00:00.000000Z"
}
}
Example response (404):
{
"success": false,
"status": 404,
"message": "API key not found",
"data": {}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Delete API key
requires authentication
Permanently delete an API key. This action cannot be undone.
Example request:
curl --request DELETE \
"https://api.blacklisthub.io/v1/api-keys/1" \
--header "Authorization: Bearer your-token-here" \
--header "Content-Type: application/json" \
--header "Accept: application/json"const url = new URL(
"https://api.blacklisthub.io/v1/api-keys/1"
);
const headers = {
"Authorization": "Bearer your-token-here",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "DELETE",
headers,
}).then(response => response.json());Example response (200):
{
"success": true,
"status": 200,
"message": "API key deleted successfully",
"data": null
}
Example response (404):
{
"success": false,
"status": 404,
"message": "API key not found",
"data": {}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Endpoints
Submit Lead Form (public)
Public endpoint for the marketing site's "contact / request access" form. Emails the sales inbox (LEADS_NOTIFICATION_EMAIL) via the configured mailer (Amazon SES SMTP). No authentication — protect with rate limiting.
Example request:
curl --request POST \
"https://api.blacklisthub.io/v1/leads" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"company\": \"Paquetería S.A. de C.V.\",
\"email\": \"nombre@empresa.com\",
\"country\": \"México\",
\"monthly_volume\": \"1,000 - 5,000\",
\"message\": \"Nos interesa integrar la API.\"
}"
const url = new URL(
"https://api.blacklisthub.io/v1/leads"
);
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"company": "Paquetería S.A. de C.V.",
"email": "nombre@empresa.com",
"country": "México",
"monthly_volume": "1,000 - 5,000",
"message": "Nos interesa integrar la API."
};
fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
}).then(response => response.json());Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Company Login
Authenticate a company and receive an access token. The company must be activated by an administrator first.
Example request:
curl --request POST \
"https://api.blacklisthub.io/v1/auth/login" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"email\": \"contact@estafeta.com\",
\"password\": \"password123\"
}"
const url = new URL(
"https://api.blacklisthub.io/v1/auth/login"
);
const headers = {
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"email": "contact@estafeta.com",
"password": "password123"
};
fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
}).then(response => response.json());Example response (200, Success):
{
"success": true,
"status": 200,
"message": "Login successful",
"data": {
"company": {
"id": 1,
"name": "Estafeta Express",
"email": "contact@estafeta.com"
},
"token": "XyZ9aB3cD4eF5gH6iJ7kL8mN9oP0qR1sT2uV3wX4yZ5aB6cD7eF8gH9iJ0kL1mN2"
}
}
Example response (401, Invalid Credentials):
{
"success": false,
"status": 401,
"message": "Invalid credentials",
"data": []
}
Example response (403, Not Activated):
{
"success": false,
"status": 403,
"message": "Company not activated yet. Please wait for admin approval.",
"data": []
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Company Logout
requires authentication
Logout and invalidate the current access token.
Example request:
curl --request POST \
"https://api.blacklisthub.io/v1/auth/logout" \
--header "Authorization: Bearer your-token-here" \
--header "Content-Type: application/json" \
--header "Accept: application/json"const url = new URL(
"https://api.blacklisthub.io/v1/auth/logout"
);
const headers = {
"Authorization": "Bearer your-token-here",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "POST",
headers,
}).then(response => response.json());Example response (200, Success):
{
"success": true,
"status": 200,
"message": "Logout successful",
"data": []
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
List Categories
requires authentication
Get all available business categories for blacklist reporting.
Example request:
curl --request GET \
--get "https://api.blacklisthub.io/v1/categories" \
--header "Authorization: Bearer your-token-here" \
--header "Content-Type: application/json" \
--header "Accept: application/json"const url = new URL(
"https://api.blacklisthub.io/v1/categories"
);
const headers = {
"Authorization": "Bearer your-token-here",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());Example response (200, Success):
{
"success": true,
"status": 200,
"message": "Categories retrieved successfully",
"data": [
{
"id": 1,
"name": "Shipping & Logistics",
"slug": "shipping-logistics",
"description": "Shipping companies, courier services, freight"
},
{
"id": 2,
"name": "E-commerce",
"slug": "e-commerce",
"description": "Online stores, marketplaces, retail"
}
]
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
List Fraud Types
requires authentication
The active fraud types you can attach to a report via fraud_type_id.
Managed by superadmins, so treat the list as a catalogue to read, not a
fixed enum to hard-code.
Example request:
curl --request GET \
--get "https://api.blacklisthub.io/v1/fraud-types" \
--header "Authorization: Bearer your-token-here" \
--header "Content-Type: application/json" \
--header "Accept: application/json"const url = new URL(
"https://api.blacklisthub.io/v1/fraud-types"
);
const headers = {
"Authorization": "Bearer your-token-here",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());Example response (200, Success):
{
"success": true,
"status": 200,
"message": "Fraud types retrieved successfully",
"data": [
{
"id": 1,
"name": "Non Payment",
"slug": "non-payment",
"is_active": true
}
]
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Get Supported Countries
requires authentication
Get list of all supported countries with their currencies and tax ID labels. Useful for populating country selection dropdowns in UIs.
Example request:
curl --request GET \
--get "https://api.blacklisthub.io/v1/countries" \
--header "Authorization: Bearer your-token-here" \
--header "Content-Type: application/json" \
--header "Accept: application/json"const url = new URL(
"https://api.blacklisthub.io/v1/countries"
);
const headers = {
"Authorization": "Bearer your-token-here",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());Example response (200, Success):
{
"success": true,
"status": 200,
"message": "Countries retrieved successfully",
"data": {
"countries": [
{
"code": "MX",
"name": "Mexico",
"currency": "MXN",
"tax_id": "RFC"
},
{
"code": "US",
"name": "United States",
"currency": "USD",
"tax_id": "SSN/EIN"
}
],
"total": 17
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Get Country Details
requires authentication
Get detailed information about a specific country including currency and tax ID format.
Example request:
curl --request GET \
--get "https://api.blacklisthub.io/v1/countries/MX" \
--header "Authorization: Bearer your-token-here" \
--header "Content-Type: application/json" \
--header "Accept: application/json"const url = new URL(
"https://api.blacklisthub.io/v1/countries/MX"
);
const headers = {
"Authorization": "Bearer your-token-here",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());Example response (200, Success):
{
"success": true,
"status": 200,
"message": "Country details retrieved successfully",
"data": {
"country": {
"code": "MX",
"name": "Mexico",
"currency": "MXN",
"tax_id": "RFC",
"currency_details": {
"code": "MXN",
"name": "Mexican Peso",
"symbol": "$"
}
}
}
}
Example response (404, Country Not Found):
{
"success": false,
"status": 404,
"message": "Country not found",
"data": []
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Get Supported Currencies
requires authentication
Get list of all supported currencies with their codes, names, and symbols. Useful for populating currency selection dropdowns in UIs.
Example request:
curl --request GET \
--get "https://api.blacklisthub.io/v1/currencies" \
--header "Authorization: Bearer your-token-here" \
--header "Content-Type: application/json" \
--header "Accept: application/json"const url = new URL(
"https://api.blacklisthub.io/v1/currencies"
);
const headers = {
"Authorization": "Bearer your-token-here",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());Example response (200, Success):
{
"success": true,
"status": 200,
"message": "Currencies retrieved successfully",
"data": {
"currencies": [
{
"code": "USD",
"name": "US Dollar",
"symbol": "$"
},
{
"code": "MXN",
"name": "Mexican Peso",
"symbol": "$"
},
{
"code": "EUR",
"name": "Euro",
"symbol": "€"
}
],
"total": 15
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Convert Currency
requires authentication
Convert an amount from one currency to another using current exchange rates.
Example request:
curl --request GET \
--get "https://api.blacklisthub.io/v1/currency/convert?amount=1000&from=MXN&to=USD" \
--header "Authorization: Bearer your-token-here" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"amount\": 27,
\"from\": \"ngz\",
\"to\": \"miy\"
}"
const url = new URL(
"https://api.blacklisthub.io/v1/currency/convert"
);
const params = {
"amount": "1000",
"from": "MXN",
"to": "USD",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Authorization": "Bearer your-token-here",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"amount": 27,
"from": "ngz",
"to": "miy"
};
fetch(url, {
method: "GET",
headers,
body: JSON.stringify(body),
}).then(response => response.json());Example response (200, Success):
{
"success": true,
"status": 200,
"message": "Currency converted successfully",
"data": {
"original": {
"amount": 1000,
"currency": "MXN",
"formatted": "$1,000.00"
},
"converted": {
"amount": 59,
"currency": "USD",
"formatted": "$59.00"
},
"exchange_rate": 0.059
}
}
Example response (422, Validation Error):
{
"success": false,
"status": 422,
"message": "Validation failed",
"data": {
"errors": {
"amount": [
"The amount field is required."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Verify Identity
requires authentication
Fast registration-time check: given an email and/or phone, returns an aggregated risk verdict WITHOUT exposing which companies reported the person, their debt amounts, or their private notes.
Example request:
curl --request POST \
"https://api.blacklisthub.io/v1/verify" \
--header "Authorization: Bearer your-token-here" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"email\": \"fernando@gmail.com\",
\"phone\": \"3331234567\",
\"country_code\": \"MX\"
}"
const url = new URL(
"https://api.blacklisthub.io/v1/verify"
);
const headers = {
"Authorization": "Bearer your-token-here",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"email": "fernando@gmail.com",
"phone": "3331234567",
"country_code": "MX"
};
fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
}).then(response => response.json());Example response (200, Reported):
{
"success": true,
"status": 200,
"message": "Verification completed",
"data": {
"found": true,
"client_id": "9f1c2a80-4c9e-4a1e-9b0e-5f6a7b8c9d01",
"matched_on": [
"phone"
],
"trust_score": 40,
"risk_level": "HIGH",
"recommendation": "Require upfront payment or secured transaction",
"report_summary": {
"total_reports": 4,
"distinct_companies": 3,
"fraud_types_count": 2,
"first_reported_at": "2025-11-01T00:00:00.000000Z",
"last_reported_at": "2026-04-20T00:00:00.000000Z"
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Bulk Verify Identities
requires authentication
Check many identities in a single request (e.g. a batch of pending registrations). Returns one verdict per item, in order.
Example request:
curl --request POST \
"https://api.blacklisthub.io/v1/verify/bulk" \
--header "Authorization: Bearer your-token-here" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"items\": [
\"architecto\"
]
}"
const url = new URL(
"https://api.blacklisthub.io/v1/verify/bulk"
);
const headers = {
"Authorization": "Bearer your-token-here",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"items": [
"architecto"
]
};
fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
}).then(response => response.json());Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Report Client
requires authentication
Report a single client to the blacklist. If the client already exists, your company will be added to their report list.
Example request:
curl --request POST \
"https://api.blacklisthub.io/v1/blacklist" \
--header "Authorization: Bearer your-token-here" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"category_id\": 1,
\"name\": \"Fernando García\",
\"company_name\": \"Acme Corp\",
\"email\": \"fernando@gmail.com\",
\"phone\": \"3331234567\",
\"ip_address\": \"192.168.1.100\",
\"tax_id\": \"j\",
\"address\": \"Av. Principal 123\",
\"city\": \"Guadalajara\",
\"state\": \"Jalisco\",
\"country_code\": \"zm\",
\"currency\": \"iyv\",
\"postal_code\": \"44100\",
\"debt_amount\": 5000,
\"incident_date\": \"2024-11-15\",
\"fraud_type_id\": 1,
\"additional_info\": \"No pagó 3 envíos\",
\"rfc_tax_id\": \"GACF850101ABC\",
\"country\": \"Mexico\"
}"
const url = new URL(
"https://api.blacklisthub.io/v1/blacklist"
);
const headers = {
"Authorization": "Bearer your-token-here",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"category_id": 1,
"name": "Fernando García",
"company_name": "Acme Corp",
"email": "fernando@gmail.com",
"phone": "3331234567",
"ip_address": "192.168.1.100",
"tax_id": "j",
"address": "Av. Principal 123",
"city": "Guadalajara",
"state": "Jalisco",
"country_code": "zm",
"currency": "iyv",
"postal_code": "44100",
"debt_amount": 5000,
"incident_date": "2024-11-15",
"fraud_type_id": 1,
"additional_info": "No pagó 3 envíos",
"rfc_tax_id": "GACF850101ABC",
"country": "Mexico"
};
fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
}).then(response => response.json());Example response (201, Success):
{
"success": true,
"status": 201,
"message": "Client reported successfully",
"data": {
"client": {
"id": 1,
"category_id": 1,
"name": "Fernando García",
"email": "fernando@gmail.com",
"phone": "3331234567",
"reports_count": 1
}
}
}
Example response (409, Already Reported):
{
"success": false,
"status": 409,
"message": "Your company has already reported this client",
"data": []
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Bulk Report Clients
requires authentication
Report multiple clients in a single request.
Example request:
curl --request POST \
"https://api.blacklisthub.io/v1/blacklist/bulk" \
--header "Authorization: Bearer your-token-here" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"clients\": [
\"architecto\"
]
}"
const url = new URL(
"https://api.blacklisthub.io/v1/blacklist/bulk"
);
const headers = {
"Authorization": "Bearer your-token-here",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"clients": [
"architecto"
]
};
fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
}).then(response => response.json());Example response (200, Success):
{
"success": true,
"status": 200,
"message": "Bulk operation completed",
"data": {
"success": [
{
"id": 1,
"name": "Juan Pérez",
"email": "juan@hotmail.com"
},
{
"id": 2,
"name": "María López",
"email": "maria@yahoo.com"
}
],
"errors": []
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
My Reported Clients
requires authentication
The clients YOUR company has reported, together with the moderation status of your own report, so you can follow them up or withdraw them.
This is the only listing endpoint in the API. The network-wide blacklist is deliberately not enumerable: to learn about anyone else you must supply their identity to /v1/verify or /v1/blacklist/search.
Free: it returns your own data and does not count against your quota.
Example request:
curl --request GET \
--get "https://api.blacklisthub.io/v1/blacklist/mine?per_page=15&page=1" \
--header "Authorization: Bearer your-token-here" \
--header "Content-Type: application/json" \
--header "Accept: application/json"const url = new URL(
"https://api.blacklisthub.io/v1/blacklist/mine"
);
const params = {
"per_page": "15",
"page": "1",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Authorization": "Bearer your-token-here",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());Example response (200, Success):
{
"success": true,
"status": 200,
"message": "Your reported clients retrieved successfully",
"data": {
"current_page": 1,
"data": [
{
"id": "9f1c2a80-4c9e-4a1e-9b0e-5f6a7b8c9d01",
"name": "Fernando García",
"email": "fernando@gmail.com",
"trust_score": 45,
"risk_level": "HIGH"
}
],
"per_page": 15,
"total": 3
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Look Up a Client
requires authentication
Exact-identity lookup: you must supply the email, phone or tax ID of the person you are checking. There is no way to browse, filter or page through the network's clients — the blacklist is not enumerable.
Matching is done on the NORMALIZED identity within the jurisdiction, so "333 123 4567" and "+52 333 123 4567" find the same person. Returns at most one client. A person whose only reports are still pending moderation reads as not found.
Counts as one billable lookup against your plan.
Example request:
curl --request GET \
--get "https://api.blacklisthub.io/v1/blacklist/search?email=fernando%40gmail.com&phone=3331234567&tax_id=GACF850101ABC&country_code=MX" \
--header "Authorization: Bearer your-token-here" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"email\": \"gbailey@example.net\",
\"phone\": \"m\",
\"tax_id\": \"i\",
\"country_code\": \"yv\"
}"
const url = new URL(
"https://api.blacklisthub.io/v1/blacklist/search"
);
const params = {
"email": "fernando@gmail.com",
"phone": "3331234567",
"tax_id": "GACF850101ABC",
"country_code": "MX",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Authorization": "Bearer your-token-here",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"email": "gbailey@example.net",
"phone": "m",
"tax_id": "i",
"country_code": "yv"
};
fetch(url, {
method: "GET",
headers,
body: JSON.stringify(body),
}).then(response => response.json());Example response (200, Match found):
{
"success": true,
"status": 200,
"message": "Match found",
"data": {
"found": true,
"client": {
"id": "9f1c2a80-4c9e-4a1e-9b0e-5f6a7b8c9d01",
"name": "Fernando García",
"email": "fernando@gmail.com",
"trust_score": 45,
"risk_level": "HIGH"
}
}
}
Example response (200, No match):
{
"success": true,
"status": 200,
"message": "No match found",
"data": {
"found": false,
"client": null
}
}
Example response (422, No identity supplied):
{
"success": false,
"status": 422,
"message": "Validation failed",
"data": {
"errors": {
"email": [
"The email field is required when none of phone / tax id are present."
]
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Get Client Details
requires authentication
Full record of a client you have already located through /v1/verify or /v1/blacklist/search. Addressed by the client's public UUID; sequential internal ids are never accepted, so this endpoint cannot be walked.
Third-party reporters stay anonymous: other companies' debt amounts and notes are replaced by placeholders. Counts as one billable lookup.
Example request:
curl --request GET \
--get "https://api.blacklisthub.io/v1/blacklist/9f1c2a80-4c9e-4a1e-9b0e-5f6a7b8c9d01?country_code=MX" \
--header "Authorization: Bearer your-token-here" \
--header "Content-Type: application/json" \
--header "Accept: application/json"const url = new URL(
"https://api.blacklisthub.io/v1/blacklist/9f1c2a80-4c9e-4a1e-9b0e-5f6a7b8c9d01"
);
const params = {
"country_code": "MX",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Authorization": "Bearer your-token-here",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());Example response (200, Success):
{
"success": true,
"status": 200,
"message": "Client retrieved successfully",
"data": {
"client": {
"id": "9f1c2a80-4c9e-4a1e-9b0e-5f6a7b8c9d01",
"name": "Fernando García",
"email": "fernando@gmail.com",
"reports_count": 2,
"blacklist_reports": [
{
"is_yours": false,
"company": {
"name": "Confidential partner"
},
"fraud_type": {
"name": "Non Payment"
},
"debt_amount": null,
"additional_info": null
}
]
}
}
}
Example response (404, Unknown or out of jurisdiction):
{
"success": false,
"status": 404,
"message": "Endpoint no encontrado.",
"data": {}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Update Own Report
requires authentication
A company updates ONLY its own report for a client (debt, fraud type, notes...). It cannot touch the shared client identity. Recalculates the trust score.
Example request:
curl --request PUT \
"https://api.blacklisthub.io/v1/blacklist/9f1c2a80-4c9e-4a1e-9b0e-5f6a7b8c9d01/report" \
--header "Authorization: Bearer your-token-here" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"debt_amount\": 27,
\"currency\": \"ngz\",
\"incident_date\": \"2026-09-03T01:01:56\",
\"additional_info\": \"architecto\"
}"
const url = new URL(
"https://api.blacklisthub.io/v1/blacklist/9f1c2a80-4c9e-4a1e-9b0e-5f6a7b8c9d01/report"
);
const headers = {
"Authorization": "Bearer your-token-here",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"debt_amount": 27,
"currency": "ngz",
"incident_date": "2026-09-03T01:01:56",
"additional_info": "architecto"
};
fetch(url, {
method: "PUT",
headers,
body: JSON.stringify(body),
}).then(response => response.json());Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Withdraw Own Report
requires authentication
A company retracts its own report (e.g. the debt was paid). The report is marked withdrawn and soft-deleted, so it no longer counts toward the score.
Example request:
curl --request DELETE \
"https://api.blacklisthub.io/v1/blacklist/9f1c2a80-4c9e-4a1e-9b0e-5f6a7b8c9d01/report" \
--header "Authorization: Bearer your-token-here" \
--header "Content-Type: application/json" \
--header "Accept: application/json"const url = new URL(
"https://api.blacklisthub.io/v1/blacklist/9f1c2a80-4c9e-4a1e-9b0e-5f6a7b8c9d01/report"
);
const headers = {
"Authorization": "Bearer your-token-here",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "DELETE",
headers,
}).then(response => response.json());Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Open a Dispute
requires authentication
Flag a blacklisted client as wrongly/unfairly listed. Creates a PENDING dispute for admin review. Provides a recourse against defamation claims.
Example request:
curl --request POST \
"https://api.blacklisthub.io/v1/blacklist/9f1c2a80-4c9e-4a1e-9b0e-5f6a7b8c9d01/dispute" \
--header "Authorization: Bearer your-token-here" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"reason\": \"El cliente sí pagó, adjunto comprobante.\",
\"evidence_url\": \"https:\\/\\/files.example.com\\/comprobante.pdf\"
}"
const url = new URL(
"https://api.blacklisthub.io/v1/blacklist/9f1c2a80-4c9e-4a1e-9b0e-5f6a7b8c9d01/dispute"
);
const headers = {
"Authorization": "Bearer your-token-here",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"reason": "El cliente sí pagó, adjunto comprobante.",
"evidence_url": "https:\/\/files.example.com\/comprobante.pdf"
};
fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
}).then(response => response.json());Example response (201, Created):
{
"success": true,
"status": 201,
"message": "Dispute submitted for review",
"data": {
"dispute": {
"id": 1,
"status": "pending"
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Get Statistics
requires authentication
Aggregated statistics about the network and your company's own activity. Deliberately contains NO rows about identifiable people: counts, totals and distributions only.
Example request:
curl --request GET \
--get "https://api.blacklisthub.io/v1/stats?category_id=1" \
--header "Authorization: Bearer your-token-here" \
--header "Content-Type: application/json" \
--header "Accept: application/json"const url = new URL(
"https://api.blacklisthub.io/v1/stats"
);
const params = {
"category_id": "1",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Authorization": "Bearer your-token-here",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());Example response (200, Success):
{
"success": true,
"status": 200,
"message": "Statistics retrieved successfully",
"data": {
"total_blacklisted_clients": 150,
"total_reports": 200,
"total_active_companies": 25,
"clients_by_category": [],
"company_stats": {
"total_reports": 10,
"unique_clients_reported": 8
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
My Usage
requires authentication
Your current plan and how many billable lookups you have consumed today and this month. Billable lookups are: verify, each item of a bulk verify, blacklist search, client detail and trust analysis.
This endpoint is free and does not count against your quota.
Example request:
curl --request GET \
--get "https://api.blacklisthub.io/v1/usage" \
--header "Authorization: Bearer your-token-here" \
--header "Content-Type: application/json" \
--header "Accept: application/json"const url = new URL(
"https://api.blacklisthub.io/v1/usage"
);
const headers = {
"Authorization": "Bearer your-token-here",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());Example response (200, Success):
{
"success": true,
"status": 200,
"message": "Usage retrieved successfully",
"data": {
"plan": {
"slug": "free",
"name": "Free",
"price": "0.00",
"currency": "USD"
},
"enforced": true,
"daily": {
"limit": 50,
"used": 8,
"remaining": 42,
"resets_at": "2026-09-03T00:00:00-06:00"
},
"monthly": {
"limit": 1000,
"used": 120,
"remaining": 880,
"resets_at": "2026-10-01T00:00:00-06:00"
}
}
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Trust Analysis
requires authentication
Full risk breakdown for a client you have already located through /v1/verify or /v1/blacklist/search. Addressed by the client's public UUID; internal ids are never accepted.
Counts as one billable lookup against your plan.
Example request:
curl --request GET \
--get "https://api.blacklisthub.io/v1/trust-analysis/9f1c2a80-4c9e-4a1e-9b0e-5f6a7b8c9d01" \
--header "Authorization: Bearer your-token-here" \
--header "Content-Type: application/json" \
--header "Accept: application/json"const url = new URL(
"https://api.blacklisthub.io/v1/trust-analysis/9f1c2a80-4c9e-4a1e-9b0e-5f6a7b8c9d01"
);
const headers = {
"Authorization": "Bearer your-token-here",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());Example response (401):
Show headers
cache-control: no-cache, private
content-type: application/json
x-ratelimit-limit: 120
x-ratelimit-remaining: 119
access-control-allow-origin: *
{
"success": false,
"status": 401,
"message": "Invalid credentials",
"data": []
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.