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

This API is not authenticated.

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 "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.blacklisthub.io/v1/api-keys"
);

const headers = {
    "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

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 "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 = {
    "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

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 "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 = {
    "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

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 "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.blacklisthub.io/v1/api-keys/1"
);

const headers = {
    "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

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   integer     

The API key ID. Example: 1

Endpoints

Register Company

Register a new company account. The account will be inactive until approved by an administrator.

Example request:
curl --request POST \
    "https://api.blacklisthub.io/v1/auth/register" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"Estafeta Express\",
    \"email\": \"contact@estafeta.com\",
    \"password\": \"password123\",
    \"country_code\": \"ay\",
    \"currency\": \"kcm\"
}"

const url = new URL(
    "https://api.blacklisthub.io/v1/auth/register"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "name": "Estafeta Express",
    "email": "contact@estafeta.com",
    "password": "password123",
    "country_code": "ay",
    "currency": "kcm"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (201, Success):


{
    "success": true,
    "status": 201,
    "message": "Company registered successfully. Waiting for admin activation.",
    "data": {
        "company": {
            "id": 1,
            "name": "Estafeta Express",
            "email": "contact@estafeta.com",
            "is_active": false
        }
    }
}

Example response (422, Validation Error):


{
    "success": false,
    "status": 422,
    "message": "Validation failed",
    "data": {
        "errors": {
            "email": [
                "The email has already been taken."
            ]
        }
    }
}

Request      

POST v1/auth/register

Headers

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

name   string     

The company name. Example: Estafeta Express

email   string     

The company email. Example: contact@estafeta.com

password   string     

The password (minimum 8 characters). Example: password123

country_code   string     

Must be 2 characters. Example: ay

currency   string  optional    

Must be 3 characters. Example: kcm

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 "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.blacklisthub.io/v1/auth/logout"
);

const headers = {
    "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

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 "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.blacklisthub.io/v1/categories"
);

const headers = {
    "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

Content-Type        

Example: application/json

Accept        

Example: application/json

GET v1/fraud-types

Example request:
curl --request GET \
    --get "https://api.blacklisthub.io/v1/fraud-types" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.blacklisthub.io/v1/fraud-types"
);

const headers = {
    "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
 

{
    "success": false,
    "status": 401,
    "message": "Authentication required. Provide either Bearer Token or X-API-Key header",
    "data": []
}

Request      

GET v1/fraud-types

Headers

Content-Type        

Example: application/json

Accept        

Example: application/json

Get Supported Countries

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 "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.blacklisthub.io/v1/countries"
);

const headers = {
    "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

Content-Type        

Example: application/json

Accept        

Example: application/json

Get Country Details

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 "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.blacklisthub.io/v1/countries/MX"
);

const headers = {
    "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

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

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 "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.blacklisthub.io/v1/currencies"
);

const headers = {
    "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

Content-Type        

Example: application/json

Accept        

Example: application/json

Convert Currency

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 "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 = {
    "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

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

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 "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"category_id\": 1,
    \"name\": \"Fernando García\",
    \"email\": \"fernando@gmail.com\",
    \"phone\": \"3331234567\",
    \"ip_address\": \"192.168.1.100\",
    \"tax_id\": \"l\",
    \"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 = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "category_id": 1,
    "name": "Fernando García",
    "email": "fernando@gmail.com",
    "phone": "3331234567",
    "ip_address": "192.168.1.100",
    "tax_id": "l",
    "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

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

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: l

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 "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"clients\": [
        \"architecto\"
    ]
}"

const url = new URL(
    "https://api.blacklisthub.io/v1/blacklist/bulk"
);

const headers = {
    "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

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

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: d

tax_id   string  optional    

Must not be greater than 50 characters. Example: l

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

List Blacklisted Clients

requires authentication

Get paginated list of all blacklisted clients. Results are ordered by number of reports (most reported first).

Example request:
curl --request GET \
    --get "https://api.blacklisthub.io/v1/blacklist?per_page=15&category_id=1&page=1" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.blacklisthub.io/v1/blacklist"
);

const params = {
    "per_page": "15",
    "category_id": "1",
    "page": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "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": "Clients retrieved successfully",
    "data": {
        "current_page": 1,
        "data": [
            {
                "id": 1,
                "name": "Fernando García",
                "email": "fernando@gmail.com",
                "phone": "3331234567",
                "reports_count": 3,
                "category": {
                    "id": 1,
                    "name": "Shipping & Logistics"
                }
            }
        ],
        "per_page": 15,
        "total": 50
    }
}

Request      

GET v1/blacklist

Headers

Content-Type        

Example: application/json

Accept        

Example: application/json

Query Parameters

per_page   integer  optional    

Number of results per page. Example: 15

category_id   integer  optional    

Filter by category ID. Example: 1

page   integer  optional    

Page number. Example: 1

requires authentication

Search for clients using multiple criteria. All parameters are optional and can be combined.

Example request:
curl --request GET \
    --get "https://api.blacklisthub.io/v1/blacklist/search?email=fernando&phone=333&name=Garc%C3%ADa&rfc_tax_id=GACF&category_id=1&fraud_type_id=1&per_page=15" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.blacklisthub.io/v1/blacklist/search"
);

const params = {
    "email": "fernando",
    "phone": "333",
    "name": "García",
    "rfc_tax_id": "GACF",
    "category_id": "1",
    "fraud_type_id": "1",
    "per_page": "15",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "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": "Search completed successfully",
    "data": {
        "current_page": 1,
        "data": [
            {
                "id": 1,
                "name": "Fernando García",
                "email": "fernando@gmail.com",
                "phone": "3331234567",
                "reports_count": 2
            }
        ]
    }
}

Get Client Details

requires authentication

Get detailed information about a specific blacklisted client, including all companies that reported them.

Example request:
curl --request GET \
    --get "https://api.blacklisthub.io/v1/blacklist/1" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.blacklisthub.io/v1/blacklist/1"
);

const headers = {
    "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": 1,
            "name": "Fernando García",
            "email": "fernando@gmail.com",
            "reports_count": 2,
            "blacklist_reports": [
                {
                    "company": {
                        "name": "Estafeta Express"
                    },
                    "fraud_type": {
                        "name": "Non Payment"
                    },
                    "debt_amount": "5000.00",
                    "additional_info": "No pagó 3 envíos"
                }
            ]
        }
    }
}

Request      

GET v1/blacklist/{id}

Headers

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   integer     

The client ID. Example: 1

Update Client

requires authentication

Update blacklisted client information. Only companies that reported this client can update it.

Example request:
curl --request PUT \
    "https://api.blacklisthub.io/v1/blacklist/1" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"category_id\": 1,
    \"name\": \"Fernando García López\",
    \"email\": \"fernando.new@gmail.com\",
    \"phone\": \"3331234567\",
    \"ip_address\": \"y\",
    \"tax_id\": \"v\",
    \"address\": \"architecto\",
    \"city\": \"n\",
    \"state\": \"g\",
    \"country_code\": \"zm\",
    \"currency\": \"iyv\",
    \"postal_code\": \"dljnikhwaykcmyuw\"
}"

const url = new URL(
    "https://api.blacklisthub.io/v1/blacklist/1"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "category_id": 1,
    "name": "Fernando García López",
    "email": "fernando.new@gmail.com",
    "phone": "3331234567",
    "ip_address": "y",
    "tax_id": "v",
    "address": "architecto",
    "city": "n",
    "state": "g",
    "country_code": "zm",
    "currency": "iyv",
    "postal_code": "dljnikhwaykcmyuw"
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (200, Success):


{
    "success": true,
    "status": 200,
    "message": "Client updated successfully",
    "data": {
        "client": {
            "id": 1,
            "name": "Fernando García López",
            "email": "fernando.new@gmail.com"
        }
    }
}

Example response (403, Unauthorized):


{
    "success": false,
    "status": 403,
    "message": "Unauthorized to update this client",
    "data": []
}

Request      

PUT v1/blacklist/{id}

Headers

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   integer     

The client ID. Example: 1

Body Parameters

category_id   integer  optional    

Category ID. Example: 1

name   string  optional    

Client full name. Example: Fernando García López

email   string  optional    

Client email. Example: fernando.new@gmail.com

phone   string  optional    

Client phone. Example: 3331234567

ip_address   string  optional    

Must not be greater than 45 characters. Example: y

tax_id   string  optional    

Must not be greater than 50 characters. Example: v

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

DELETE v1/blacklist/{id}

Example request:
curl --request DELETE \
    "https://api.blacklisthub.io/v1/blacklist/architecto" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.blacklisthub.io/v1/blacklist/architecto"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());

Request      

DELETE v1/blacklist/{id}

Headers

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   string     

The ID of the blacklist. Example: architecto

Get Statistics

requires authentication

Get general statistics about blacklisted clients and your company's activity.

Example request:
curl --request GET \
    --get "https://api.blacklisthub.io/v1/stats?category_id=1" \
    --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 = {
    "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,
        "top_reported_clients": [],
        "clients_by_category": [],
        "company_stats": {
            "total_reports": 10,
            "unique_clients_reported": 8
        }
    }
}

Request      

GET v1/stats

Headers

Content-Type        

Example: application/json

Accept        

Example: application/json

Query Parameters

category_id   integer  optional    

Filter statistics by category. Example: 1

GET v1/trust-analysis/{id}

Example request:
curl --request GET \
    --get "https://api.blacklisthub.io/v1/trust-analysis/architecto" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.blacklisthub.io/v1/trust-analysis/architecto"
);

const headers = {
    "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
 

{
    "success": false,
    "status": 401,
    "message": "Authentication required. Provide either Bearer Token or X-API-Key header",
    "data": []
}

Request      

GET v1/trust-analysis/{id}

Headers

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   string     

The ID of the trust analysi. Example: architecto