MENU navbar-image

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:

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"
        }
    ]
}
 

Request      

GET v1/api-keys

Headers

Authorization        

Example: Bearer your-token-here

Content-Type        

Example: application/json

Accept        

Example: application/json

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": {}
}
 

Request      

POST v1/api-keys

Headers

Authorization        

Example: Bearer your-token-here

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

name   string     

Descriptive name for the API key. Example: Production Server

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": {}
}
 

Request      

PUT v1/api-keys/{id}

Headers

Authorization        

Example: Bearer your-token-here

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   integer     

The API key ID. Example: 1

Body Parameters

name   string  optional    

optional New name for the API key. Example: Updated Name

is_active   boolean  optional    

optional Active status. Example: false

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": {}
}
 

Request      

DELETE v1/api-keys/{id}

Headers

Authorization        

Example: Bearer your-token-here

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   integer     

The API key ID. Example: 1

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());

Request      

POST v1/leads

Headers

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

company   string     

Company name. Example: Paquetería S.A. de C.V.

email   string     

Corporate email. Example: nombre@empresa.com

country   string     

Country. Example: México

monthly_volume   string     

Monthly shipping volume range. Example: 1,000 - 5,000

message   string  optional    

Optional message. Example: Nos interesa integrar la API.

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": []
}
 

Request      

POST v1/auth/login

Headers

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

email   string     

The company email. Example: contact@estafeta.com

password   string     

The password. Example: password123

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": []
}
 

Request      

POST v1/auth/logout

Headers

Authorization        

Example: Bearer your-token-here

Content-Type        

Example: application/json

Accept        

Example: application/json

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"
        }
    ]
}
 

Request      

GET v1/categories

Headers

Authorization        

Example: Bearer your-token-here

Content-Type        

Example: application/json

Accept        

Example: application/json

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
        }
    ]
}
 

Request      

GET v1/fraud-types

Headers

Authorization        

Example: Bearer your-token-here

Content-Type        

Example: application/json

Accept        

Example: application/json

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
    }
}
 

Request      

GET v1/countries

Headers

Authorization        

Example: Bearer your-token-here

Content-Type        

Example: application/json

Accept        

Example: application/json

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": []
}
 

Request      

GET v1/countries/{code}

Headers

Authorization        

Example: Bearer your-token-here

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

code   string     

The country code (ISO 3166-1 alpha-2). Example: MX

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
    }
}
 

Request      

GET v1/currencies

Headers

Authorization        

Example: Bearer your-token-here

Content-Type        

Example: application/json

Accept        

Example: application/json

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."
            ]
        }
    }
}
 

Request      

GET v1/currency/convert

Headers

Authorization        

Example: Bearer your-token-here

Content-Type        

Example: application/json

Accept        

Example: application/json

Query Parameters

amount   number     

The amount to convert. Example: 1000

from   string     

Source currency code (ISO 4217). Example: MXN

to   string     

Target currency code (ISO 4217). Example: USD

Body Parameters

amount   number     

Must be at least 0. Example: 27

from   string     

Must be 3 characters. Example: ngz

to   string     

Must be 3 characters. Example: miy

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"
        }
    }
}
 

Request      

POST v1/verify

Headers

Authorization        

Example: Bearer your-token-here

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

email   string  optional    

Client email to check. Example: fernando@gmail.com

phone   string  optional    

Client phone to check. Example: 3331234567

country_code   string  optional    

Jurisdiction (defaults to your company's). Example: MX

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());

Request      

POST v1/verify/bulk

Headers

Authorization        

Example: Bearer your-token-here

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

items   string[]     

Array of identities to verify (max 100).

email   string  optional    

Client email. Example: juan@hotmail.com

phone   string  optional    

Client phone. Example: 3339876543

country_code   string  optional    

Jurisdiction. Example: MX

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": []
}
 

Request      

POST v1/blacklist

Headers

Authorization        

Example: Bearer your-token-here

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

category_id   integer     

The business category ID. Example: 1

name   string     

Client full name. Example: Fernando García

company_name   string  optional    

Company name where client works (optional). Example: Acme Corp

email   string     

Client email address. Example: fernando@gmail.com

phone   string     

Client phone number. Example: 3331234567

ip_address   string  optional    

Client IP address. Example: 192.168.1.100

tax_id   string  optional    

Must not be greater than 50 characters. Example: j

address   string  optional    

Client address. Example: Av. Principal 123

city   string  optional    

Client city. Example: Guadalajara

state   string  optional    

Client state/province. Example: Jalisco

country_code   string  optional    

Must be 2 characters. Example: zm

currency   string  optional    

Must be 3 characters. Example: iyv

postal_code   string  optional    

Client postal code. Example: 44100

debt_amount   number  optional    

Amount owed (if applicable). Example: 5000

incident_date   date  optional    

Date of the incident. Example: 2024-11-15

fraud_type_id   integer  optional    

Fraud type ID (see GET /v1/fraud-types). Example: 1

additional_info   string  optional    

Additional notes or comments. Example: No pagó 3 envíos

rfc_tax_id   string  optional    

Client RFC/Tax ID. Example: GACF850101ABC

country   string  optional    

Client country. Example: Mexico

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": []
    }
}
 

Request      

POST v1/blacklist/bulk

Headers

Authorization        

Example: Bearer your-token-here

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

clients   string[]     

Array of clients to report.

category_id   integer     

The business category ID. Example: 1

name   string     

Client full name. Example: Juan Pérez

company_name   string  optional    

Company name where client works (optional). Example: Acme Corp

email   string     

Client email address. Example: juan@hotmail.com

phone   string     

Client phone number. Example: 3339876543

ip_address   string  optional    

Must not be greater than 45 characters. Example: l

tax_id   string  optional    

Must not be greater than 50 characters. Example: j

address   string  optional    

Example: architecto

city   string  optional    

Must not be greater than 100 characters. Example: n

state   string  optional    

Must not be greater than 100 characters. Example: g

country_code   string  optional    

Must be 2 characters. Example: zm

currency   string  optional    

Must be 3 characters. Example: iyv

postal_code   string  optional    

Must not be greater than 20 characters. Example: dljnikhwaykcmyuw

debt_amount   number  optional    

Amount owed. Example: 2500

incident_date   date  optional    

Date of incident. Example: 2024-10-20

fraud_type_id   integer  optional    

Fraud type ID. Example: 1

additional_info   string  optional    

Additional notes. Example: No pagó 5 paquetes

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
    }
}
 

Request      

GET v1/blacklist/mine

Headers

Authorization        

Example: Bearer your-token-here

Content-Type        

Example: application/json

Accept        

Example: application/json

Query Parameters

per_page   integer  optional    

Results per page. Example: 15

page   integer  optional    

Page number. Example: 1

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."
            ]
        }
    }
}
 

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": {}
}
 

Request      

GET v1/blacklist/{publicId}

Headers

Authorization        

Example: Bearer your-token-here

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

publicId   string     

Public UUID of the client. Example: 9f1c2a80-4c9e-4a1e-9b0e-5f6a7b8c9d01

Query Parameters

country_code   string  optional    

Jurisdiction (defaults to your company's). Example: MX

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());

Request      

PUT v1/blacklist/{publicId}/report

Headers

Authorization        

Example: Bearer your-token-here

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

publicId   string     

Public UUID of the client. Example: 9f1c2a80-4c9e-4a1e-9b0e-5f6a7b8c9d01

Body Parameters

debt_amount   number  optional    

Must be at least 0. Example: 27

currency   string  optional    

Must be 3 characters. Example: ngz

incident_date   string  optional    

Must be a valid date. Example: 2026-09-03T01:01:56

fraud_type_id   string  optional    

The id of an existing record in the fraud_types table.

additional_info   string  optional    

Example: architecto

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());

Request      

DELETE v1/blacklist/{publicId}/report

Headers

Authorization        

Example: Bearer your-token-here

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

publicId   string     

Public UUID of the client. Example: 9f1c2a80-4c9e-4a1e-9b0e-5f6a7b8c9d01

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"
        }
    }
}
 

Request      

POST v1/blacklist/{publicId}/dispute

Headers

Authorization        

Example: Bearer your-token-here

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

publicId   string     

Public UUID of the client. Example: 9f1c2a80-4c9e-4a1e-9b0e-5f6a7b8c9d01

Body Parameters

reason   string     

Why the listing is disputed. Example: El cliente sí pagó, adjunto comprobante.

evidence_url   string  optional    

Link to supporting evidence. Example: https://files.example.com/comprobante.pdf

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
        }
    }
}
 

Request      

GET v1/stats

Headers

Authorization        

Example: Bearer your-token-here

Content-Type        

Example: application/json

Accept        

Example: application/json

Query Parameters

category_id   integer  optional    

Filter statistics by category. Example: 1

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"
        }
    }
}
 

Request      

GET v1/usage

Headers

Authorization        

Example: Bearer your-token-here

Content-Type        

Example: application/json

Accept        

Example: application/json

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": []
}
 

Request      

GET v1/trust-analysis/{publicId}

Headers

Authorization        

Example: Bearer your-token-here

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

publicId   string     

Public UUID of the client. Example: 9f1c2a80-4c9e-4a1e-9b0e-5f6a7b8c9d01