NexaScreen API

Order drug and alcohol tests for your drivers from your own system, track their progress, and download results and custody forms as soon as they are available.

The API lets your system:

• Create a test case for a driver working for a motor carrier.
• List and look up the test cases you have created.
• Download the result and the chain-of-custody form (CCF) as PDFs.
• Receive webhook notifications when a test case changes or its result is ready.

Base URL

All endpoints below are relative to:

https://api.nexascreen.com/v1

Available endpoints

Integration overview

A complete integration follows these steps:

1. Get your credentials. Your testing provider issues you an API key. If you want webhook notifications, send them the HTTPS URL of your receiving endpoint; they will give you a signing secret for it.
2. Create a test case with POST /test-cases, identifying the driver by license number and state and the company by USDOT number. Save the id from the response; you need it for every later call.
3. Wait for the result. Listen for the test_case.result_added webhook, or poll GET /test-cases/{id}/result until result is no longer null.
4. Download the result from GET /test-cases/{id}/result. The result PDF and the CCF PDF are included as base64 strings.

Authentication

Authenticate every request by sending your API key as a Bearer token in the Authorization header. Requests without a valid key are rejected with 401 Unauthorized.

Authorization: Bearer YOUR_API_KEY

Each key is enabled for specific endpoints. If a request returns 403 with This API key is not permitted to use this endpoint, ask your provider to enable that endpoint for your key.

Requests & responses

• All requests must use HTTPS.
• Request bodies are JSON. Send Content-Type: application/json.
• All responses are JSON, encoded as UTF-8.
• Dates are YYYY-MM-DD strings. Timestamps (createdAt, updatedAt, …AddedAt) are ISO 8601 in UTC, for example 2026-09-20T14:03:11.000Z.
• Fields with no value are returned as null. Optional fields that don't apply, such as otherReason, are left out.
• IDs are UUID strings. Treat them as opaque values and don't parse them.

Errors

The API uses standard HTTP status codes. A 2xx code means success. Any other code means an error, and the body has an error field with a readable message:

{
  "error": "reason must be one of: pre-employment, post-accident, reasonable-suspicion, follow-up, random, return-to-duty, other"
}

Rate limits

Each API key can make up to 100 requests per minute. Every response includes headers showing how much of the limit is left:

RateLimit-Policy: 100;w=60
RateLimit: limit=100, remaining=87, reset=42

reset is the number of seconds until the window resets. Requests over the limit get 429 Too Many Requests with a Retry-After header. To stay under the limit, use webhooks instead of frequent polling.

The test case object

A test case is one drug or alcohol test ordered for a driver. Its result is retrieved separately from /test-cases/{id}/result.

Driver and company details (name, license, contact information) are never returned in responses. Use driverExternalId and clientExternalId to match test cases to records in your own system.

Create a test case

Orders a new test for a driver. You don't need any IDs from our system. The driver is matched by license number + license state and the company by USDOT number. If no match exists, the driver or company is created automatically, and the driver is linked to the company.

Body parameters

Example request

curl -X POST https://api.nexascreen.com/v1/test-cases \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "driver": {
      "externalId": "partner-driver-4821",
      "firstName": "Jane",
      "lastName": "Doe",
      "licenseNumber": "D1234567",
      "licenseState": "TX",
      "phoneNumber": "+15125550123",
      "email": "jane.doe@example.com"
    },
    "client": {
      "externalId": "partner-company-102",
      "companyName": "Acme Trucking LLC",
      "usdot": "1234567",
      "email": "compliance@acmetrucking.com",
      "phoneNumber": "+15125550199",
      "contactPerson": "John Smith"
    },
    "type": "urine",
    "reason": "pre-employment",
    "orderDate": "2026-09-18",
    "zipCode": "90210"
  }'

const response = await fetch("https://api.nexascreen.com/v1/test-cases", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    driver: {
      externalId: "partner-driver-4821",
      firstName: "Jane",
      lastName: "Doe",
      licenseNumber: "D1234567",
      licenseState: "TX",
      phoneNumber: "+15125550123",
    },
    client: {
      externalId: "partner-company-102",
      companyName: "Acme Trucking LLC",
      usdot: "1234567",
      email: "compliance@acmetrucking.com",
      phoneNumber: "+15125550199",
      contactPerson: "John Smith",
    },
    type: "urine",
    reason: "other",
    otherReason: "Annual company policy test",
    orderDate: "2026-09-18",
    zipCode: "90210",
  }),
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`Create failed (${response.status}): ${error}`);
}
const testCase = await response.json(); // save testCase.id

Response — 201 Created

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "created",
  "type": "urine",
  "reason": "pre-employment",
  "orderDate": "2026-09-18"
}

otherReason is included in the response when reason is other.

Common errors

List test cases

Returns the test cases on your account, newest first, one page at a time.

Query parameters

Example request

curl "https://api.nexascreen.com/v1/test-cases?page=1&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response — 200 OK

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "driverExternalId": "partner-driver-4821",
      "clientExternalId": "partner-company-102",
      "type": "urine",
      "reason": "pre-employment",
      "orderDate": "2026-09-18",
      "createdAt": "2026-09-17T14:03:11.000Z",
      "updatedAt": "2026-09-17T14:03:11.000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "limit": 20,
    "totalPages": 1
  }
}

data is an array of test case objects. To read every page, keep increasing page until it equals pagination.totalPages.

Retrieve a test case

Returns one test case by its id.

Path parameters

Example request

curl https://api.nexascreen.com/v1/test-cases/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response — 200 OK

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "driverExternalId": "partner-driver-4821",
  "clientExternalId": "partner-company-102",
  "type": "urine",
  "reason": "other",
  "otherReason": "Annual company policy test",
  "orderDate": "2026-09-18",
  "createdAt": "2026-09-17T14:03:11.000Z",
  "updatedAt": "2026-09-18T09:12:40.000Z"
}

Returns 404 with {"error": "Test case not found"} if the id doesn't exist on your account.

Retrieve a result

Returns the result of a test case and its chain-of-custody form (CCF), with both documents included as PDF files. Fields stay null until the information is available, so this endpoint also works for checking progress.

Path parameters

Example request

curl https://api.nexascreen.com/v1/test-cases/a1b2c3d4-e5f6-7890-abcd-ef1234567890/result \
  -H "Authorization: Bearer YOUR_API_KEY"

Response — 200 OK

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "result": "negative",
  "resultDate": "2026-09-22",
  "resultAddedAt": "2026-09-22T16:40:02.000Z",
  "resultPdf": "JVBERi0xLjQKJc...",
  "ccfNumber": "ABC123",
  "ccfAddedAt": "2026-09-18T14:03:11.000Z",
  "ccfForm": "JVBERi0xLjQKJc..."
}

Response fields

Saving the PDFs

const fs = require("fs");

const res = await fetch(`https://api.nexascreen.com/v1/test-cases/${id}/result`, {
  headers: { Authorization: `Bearer ${process.env.API_KEY}` },
});
const result = await res.json();

if (result.resultPdf) {
  fs.writeFileSync(`result-${id}.pdf`, Buffer.from(result.resultPdf, "base64"));
}
if (result.ccfForm) {
  fs.writeFileSync(`ccf-${id}.pdf`, Buffer.from(result.ccfForm, "base64"));
}

Webhooks

Webhooks notify your system when something happens to a test case, so you don't need to poll. When an event happens, we send an HTTPS POST request to the endpoint URL you registered with your provider.

Payloads are deliberately small: they say what changed, not the full data. When you receive an event, read resourceId and fetch the latest state from the API, for example GET /test-cases/{id}/result after test_case.result_added.

Setting up your endpoint

1. Expose a public HTTPS URL that accepts POST requests with a JSON body.
2. Send that URL to your provider. They register it and give you its signing secret. Store the secret securely; it is shown only once.
3. Verify the signature of every request before you trust it.
4. Respond with any 2xx status within 10 seconds. Do slow work, such as downloading PDFs, after you respond.

Event types

Payload

{
  "event": "test_case.result_added",
  "tenantId": "8f14e45f-ceea-467e-b7f1-9f0a3d2c1b45",
  "resourceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "resourceType": "test_case",
  "timestamp": "2026-09-22T16:40:02.000Z"
}

Request headers

Verifying signatures

Every request is signed with your endpoint's signing secret, so you can confirm it came from us and wasn't changed. To verify a request:

1. Read the header X-Webhook-Signature and split it into t (timestamp) and v1 (signature).
2. Build the signed string: {t}.{raw request body}. Use the raw body exactly as received, before parsing it as JSON.
3. Compute an HMAC-SHA256 of that string, using your signing secret as the key, and hex-encode it.
4. Compare it with v1 using a constant-time comparison.
5. Reject the request if t is more than 5 minutes away from your current time. This prevents replay attacks.

const crypto = require("crypto");
const express = require("express");

const app = express();
const SIGNING_SECRET = process.env.WEBHOOK_SIGNING_SECRET;
const TOLERANCE_SECONDS = 300;

function isValidSignature(header, rawBody) {
  if (!header) return false;
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const timestamp = Number(parts.t);
  if (!timestamp || !parts.v1) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > TOLERANCE_SECONDS) return false;

  const expected = crypto
    .createHmac("sha256", SIGNING_SECRET)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");
  const received = Buffer.from(parts.v1, "hex");
  const computed = Buffer.from(expected, "hex");
  return received.length === computed.length && crypto.timingSafeEqual(received, computed);
}

// Use the raw body: re-serialized JSON will not match the signature.
app.post("/webhooks/testing", express.raw({ type: "application/json" }), (req, res) => {
  const rawBody = req.body.toString("utf8");
  if (!isValidSignature(req.get("X-Webhook-Signature"), rawBody)) {
    return res.status(400).send("Invalid signature");
  }

  const event = JSON.parse(rawBody);
  res.sendStatus(200); // acknowledge first, then process

  // e.g. queue a job: fetch GET /test-cases/{event.resourceId}/result
});

import hashlib, hmac, time

def is_valid_signature(header: str, raw_body: bytes, secret: str, tolerance: int = 300) -> bool:
    try:
        parts = dict(p.split("=", 1) for p in header.split(","))
        timestamp = int(parts["t"])
        received = parts["v1"]
    except (AttributeError, KeyError, ValueError):
        return False
    if abs(time.time() - timestamp) > tolerance:
        return False
    signed = f"{timestamp}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(received, expected)

Delivery & retries

A delivery succeeds when your endpoint responds with a 2xx status within 10 seconds. Any other status, a timeout or a connection error counts as a failure, and the delivery is retried on this schedule:

If all six attempts fail, the event is not sent again. You can still get the current state at any time from the API.

Best practices

• Handle duplicates. The same event can arrive more than once. Store X-Webhook-Event-ID and ignore events you have already processed.
• Don't rely on order. Events can arrive out of order. Always fetch the current state from the API rather than relying on the event sequence.
• Respond quickly. Return 2xx right away and do the processing in the background.
• Reconcile periodically. As a safety net, use GET /test-cases now and then to catch any events you missed.

Reference

Test types

Allowed values for type.

Test reasons

Allowed values for reason.

Result values

Possible values for result.