Skip to documentation
SANCTIONS GATEWAYCustosHUB Developer docs API reference
Back to portal
THE CUSTOSHUB API

Screen with confidence.
Build with clarity.

Bring sanctions screening into your workflow. One API for individuals, organizations, and vessels, with evidence you can review.

Make your first request Explore the reference
SUPPORTED LISTSOFAC SDNConsolidatedUNUKEU
01 / QUICK START

From API key to first result

Send a JSON request from your backend. Start with a name, then add the identity details you have.

  1. 1

    Create your API key

    Sign in to the CustosHUB portal and open API Keys. Store your key as an environment variable on your server.

  2. 2

    Send a screening request

    Call POST /api/v1/screen with X-API-Key. The examples use CUSTOSHUB_API_KEY and select all five lists explicitly.

  3. 3

    Review the evidence

    Read status, search_complete, and each candidate’s reason_code. Keep the request_id for tracing.

Keep your key on your backend. The examples read your key from a server-side environment variable. Do not include it in browser code.

02 / AUTHENTICATION

A key in every screening request

Pass your client API key in the request header. The public status and metadata endpoints do not require it.

HEADERX-API-Key: <your-api-key>

Use Content-Type: application/json for JSON requests. For a CSV upload, let your HTTP client set the multipart content type and boundary.

Manage keys and view account audit history in the portal. Account-management endpoints require a signed-in portal session; a screening API key does not replace that session.

03 / API REFERENCE

The endpoints you need

Choose an endpoint to see its parameters, request body, response schema, and a copyable example. Definitions come from this server’s OpenAPI schema.

Loading the current request and response definitions…

04 / SCREENING RESULTS

Turn a response into a review

HTTP 200 means the request completed. The JSON status describes the screening outcome.

exact

Strong identity-data correspondence. Review the listed record and supporting evidence.

potential_match

Substantial correspondence with incomplete or conflicting details. Further review is needed.

possible_match

Limited, ambiguous, or identifier-based evidence. Read the reason before deciding.

clear

No alert-worthy candidate in the completed search. Check the selected lists and data freshness.

incomplete_search

The search could not complete as required. Read search_notes; do not treat this as Clear.

A score is similarity, not a probability. Classifications use name, birth-date, identifier, and other evidence. min_score is not a universal cutoff for review alerts.

What about the legacy “match” status?

The separate legacy SQL screening engine can return match. Treat it as a review alert. The main file-store service uses the classifications above.

05 / RELIABLE INTEGRATIONS

Plan for volume and retries

One item, one unit

A batch consumes one quota unit per item. The default maximum is 100 items per batch; your server’s configuration may differ.

Read the quota headers

Use X-RateLimit-Remaining and X-RateLimit-Month-Remaining to track capacity. On 429, honor Retry-After.

Allow time to screen

The examples allow 60 seconds. Select a timeout appropriate for your workload, particularly for batches. A client timeout does not prove processing stopped.

Retry deliberately

A repeated POST may consume quota again. X-Request-ID provides tracing; it is not an idempotency key.

06 / TROUBLESHOOTING

Know what to check next

HTTPWhat it meansNext step
400 / 422Invalid requestCheck the response detail, field names, and input format.
401Missing or invalid credentialsCheck X-API-Key. Portal endpoints require a session.
403API key disabledCheck the key’s status in the portal.
404Resource not foundCheck the endpoint and resource ID.
429Rate or monthly limit reachedRead Retry-After and the quota headers.
5xxServer, gateway, or timeout failureKeep the response and request ID; use bounded retries.

Trace a request from your application

Send a unique X-Request-ID, or retain the value returned by the API in its response header and JSON. When investigating missing audit history, compare the request ID and the key/account used by the integration.