GET /apiv2/screening/

Read a screening order in any state. Reading is free and can be repeated as often as you like.

This is the version 2 contract. It replaces GET /apiv2/aml/{order_id}, which keeps working.

Endpoint URL

GET https://netts.io/apiv2/screening/{client_order_id}

Request Headers

Header	Required	Description
X-API-KEY	Yes	Your API key from the Netts dashboard

Path Parameters

Parameter	Type	Description
client_order_id	string	The identifier returned when the order was created: A followed by 14 hexadecimal characters

Query Parameters

Parameter	Type	Default	Description
format	string	json	Representation of the result. json is the only accepted value

The representation is a property of the request, not of the order. In version 1 it was fixed when the order was created, so a check ordered as JSON could never be read any other way.

There is one representation, and it is JSON. The parameter is kept so that adding a second one later is not a breaking change; today any other value returns 4001. A report is a rendering of data you already have in full, and rendering it yourself gives you your own branding, your own language and your own layout. See Reports.

Example Requests

cURL

curl https://netts.io/apiv2/screening/A90D21F68C9AEA2 \
  -H "X-API-KEY: your_api_key"

Python — poll until the check is finished

import time
import requests

headers = {"X-API-KEY": "your_api_key"}
url = "https://netts.io/apiv2/screening/A90D21F68C9AEA2"

while True:
    body = requests.get(url, headers=headers).json()
    status = body["order"]["status"]
    if status in ("completed", "failed", "skipped"):
        break
    time.sleep(2)

print(status, body["risk"]["level"], body["risk"]["score"])

Response

200 OK with the same body as POST /apiv2/screening, in every state of the order. The field set does not depend on the state: blocks that have no data yet are filled with nulls and empty lists rather than left out.

Responses carrying a screening result are sent with Cache-Control: private, no-store.

A check that is not finished

{
  "schema_version": 2,
  "order": {
    "client_order_id": "A90D21F68C9AEA2",
    "status": "pending",
    "api_version": "v2",
    "cache_hit": false,
    "created_at": "2026-09-13T08:14:29.614988Z",
    "started_at": null,
    "completed_at": null
  },
  "request": { "address": "YOUR_ADDRESS_HERE", "network": "trx", "provider": "elliptic" },
  "billing": {
    "charged": true, "price_usdt": "0.98", "base_amount": "2.882421",
    "markup_amount": "0", "charged_amount": "2.882421", "charged_currency": "TRX",
    "exchange_rate": "0.33999200", "payment_status": "pending"
  },
  "precheck": { "activity_checked": true, "activity_status": "active", "source": "tron-address-checker" },
  "check": {
    "provider": "elliptic", "provider_check_id": null, "checked_at": null,
    "status": "pending", "provider_status": null
  },
  "risk": {
    "score": null, "scale": { "min": 0, "max": 10 }, "level": "none",
    "level_source": "computed", "provider_level": null, "policy": "netts-risk-v1",
    "by_direction": { "source": null, "destination": null }
  },
  "sanctions": null,
  "exposure": [],
  "rules": [],
  "entities": [],
  "primary_entity": null,
  "sanctioned_entities": [],
  "wallet": { "inflow_usd": null, "outflow_usd": null },
  "provider_data": { }
}

An address with no activity

An address that has never been used on the blockchain is not sent to the provider and is not charged. The order exists, so the result can be read:

{
  "order": {
    "client_order_id": "AC4F9BC45A79323",
    "status": "skipped",
    "started_at": null,
    "completed_at": null,
    "reason": "address_inactive"
  },
  "billing": { "charged": false, "charged_amount": "0", "payment_status": "not_charged" },
  "precheck": { "activity_checked": true, "activity_status": "inactive", "source": "tron-address-checker" },
  "check": { "status": "not_performed", "provider_check_id": null, "checked_at": null }
}

Only the blocks that change are shown here; the rest are present with nulls and empty lists as always.

Errors

The format is RFC 9457, Content-Type: application/problem+json. The full code list is on the POST page.

Code	HTTP	When
4003	400	The identifier is not A plus 14 hexadecimal characters
4040	404	No such order
4010 / 4011	401	No API key, or a key or IP that is not accepted

An order belonging to another account answers 404, not 403. Otherwise the response code alone would confirm that somebody else's identifier exists.

{
  "type": "https://doc.netts.io/api/v2/errors/order-not-found",
  "title": "Order not found",
  "status": 404,
  "detail": "Order not found",
  "instance": "/apiv2/screening/AFFFFFFFFFFFFFF",
  "code": 4040
}

Rate Limits

Shared with every other AML path: 5 requests per second, 150 per minute. Polling costs nothing but counts towards the limit — two seconds between polls is plenty.

See Also

• POST /apiv2/screening — order a check
• GET /apiv2/screening/history — many checks at once, in the short form