Integration journey · Step 4 of 5

Integration best practices

Patterns that keep a production integration reliable, efficient and compliant.

A first call proves connectivity. A production integration has to stay reliable under load, keep its credentials valid without manual intervention, and make efficient use of the API. This step covers the patterns Neterium recommends, all of which are implemented out of the box in the SDK.

Limits, header names and exact parameters depend on your environment and are documented in the API reference on the Neterium Portal. The principles below apply regardless of the values.

Authentication

Keep secrets out of the code. API credentials and tokens belong in a secrets manager or environment configuration, never in source control or in logs.
One token, many calls. Request a token once and reuse it for all calls until it is close to expiry. Requesting a new token for every screening call adds latency and load for no benefit.
Separate identities per environment. Sandbox and production credentials are distinct; make sure a deployment can never mix them.
Least privilege. Use dedicated credentials per integrating application so that access can be revoked or rotated independently.

Token refresh

The access token obtained in step 3 is valid for one hour. The same response also carries a refresh token, valid for twelve hours, which lets you obtain a new access token without sending the credentials again. Your application must renew tokens without interrupting screening. Two renewal modes exist and can be combined:

Proactive renewal — tokens are refreshed just before they expire, based on the expiry returned with the token. Screening calls never see an expired token.
Lazy renewal — tokens are checked and renewed only when required, typically when a call is rejected as unauthorised. Simpler, at the cost of one failed call per expiry.

Refresh the access tokenbash

curl -X POST "https://connect-to-neterium.cloud/demo/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=$REFRESH_TOKEN" \
  -d "client_id=api"

Renewal strategypseudo-code

tokens = requestToken(username, password)      # access token: 1 h, refresh token: 12 h

before each API call:                            # proactive renewal
  if tokens.accessExpiresAt - now < safetyMargin:
    tokens = refreshToken(tokens.refreshToken)

on HTTP 401:                                     # lazy renewal
  tokens = refreshToken(tokens.refreshToken)
  retry the call once

if the refresh token has expired:
  tokens = requestToken(username, password)

Whichever mode you choose, make token handling a single shared component: concurrent threads or workers should never each request their own token.

Batching

Screening requests can carry several records or transactions at once. Batching reduces the number of HTTP round trips and lets the screening platform process records efficiently.

Choose the batch size deliberately. The number of records per request is configurable; larger batches mean fewer calls but longer individual responses. Start with a moderate size and tune from measurements.
Keep your own identifiers. Give every record a stable identifier so that results, which come back one per record, can be reconciled with your source data.
Handle partial outcomes. A batch can contain both clean records and hits: route each result individually to the right downstream process.
Batch by use case. Real-time transaction screening usually favours small batches or single transactions; periodic customer re-screening favours large batches.

Batch of three recordsjson

{
  "records": [
    { "id": "customer-00042", "type": "individual", "name": "Jane Example" },
    { "id": "customer-00043", "type": "entity", "name": "Example Trading Ltd" },
    { "id": "customer-00044", "type": "individual", "name": "John Sample" }
  ]
}

Throttling

Throttling controls the rate at which API requests are sent to the screening platform, ensuring controlled, stable and compliant usage of the API, especially during bulk operations such as an initial customer base screening or a list update re-screening.

Respect the agreed rate. Send requests at a controlled pace rather than in uncontrolled bursts. A queue with a fixed number of concurrent workers is a simple and effective model.
Back off on rejection. When the platform signals that the rate is exceeded, slow down and retry with an increasing delay instead of retrying immediately.
Measure. Collect operational data such as response times, throughput and error rates. The SDK's throttling component uses these metrics to adapt the request rate automatically.
Separate real-time from bulk traffic. Do not let a bulk re-screening starve the real-time transaction flow: give them distinct queues or rate budgets.

Re-applying decisions

During ongoing monitoring, the same customer is screened again and again. Without care, every run produces the same alerts for hits that analysts have already reviewed. Each hit in the response carries a checksum computed from the matched watchlist profile:

Store the checksum together with the analyst's decision the first time a hit is reviewed.
On later runs, compare the checksum of each new hit with the stored ones. If it matches, re-apply the previous decision automatically; if not, the watchlist entry has changed and a new review is needed.

This pattern, known as delta screening, is implemented by the SDK's hit handler component and dramatically reduces alert volumes on recurring screening. The next step shows where to find these components and the rest of the reference documentation.

Looking for a hosted alternative to implementing all of this yourself? The Integration Hub and the Portal take these concerns on for you.

PreviousGetting started with the API Next stepIntegration tools