SureLoadr API

Base URL

https://www.sureloadr.com/api/v1

Authentication

Every request must include your secret API key as a Bearer token in the Authorization header. Generate and manage keys in your dashboard: API-only accounts have a Keys tab, and every other plan with API access finds them under Settings → API Keys. Your key is shown once at creation — store it securely and never expose it in client-side code.

Authorization: Bearer sk_live_your_api_key

Keys come in two kinds, chosen when you create one. A live key (sk_live_…) returns real reports and is billable. A test key (sk_test_…) returns fixed sample companies from the sandbox and is never billed. An account can hold one of each, revoked independently.

Endpoints

curl https://www.sureloadr.com/api/v1/carrier/1234567 \
  -H "Authorization: Bearer sk_live_your_api_key"

curl https://www.sureloadr.com/api/v1/broker/MC123456 \
  -H "Authorization: Bearer sk_live_your_api_key"

curl "https://www.sureloadr.com/api/v1/search?q=blue%20ridge&type=broker" \
  -H "Authorization: Bearer sk_live_your_api_key"

curl -X POST https://www.sureloadr.com/api/v1/reports/batch \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"type":"broker","ids":["MC123456","MC234567"],"view":"summary"}'

Response shapes

Both endpoints accept an optional view parameter. full is the default, so an existing integration needs no change.

curl "https://www.sureloadr.com/api/v1/broker/MC123456?view=summary" \
  -H "Authorization: Bearer sk_live_your_api_key"

An unrecognized view value returns 400 rather than quietly falling back, so a typo surfaces on the first call instead of in your parser.

{
  "data": {
    "subjectType": "broker",
    "subjectKey": "MC123456",
    "name": "EXAMPLE LOGISTICS LLC",
    "mc": "MC123456",
    "dot": "7654321",
    "location": "COLUMBUS, OH",
    "active": true,
    "score": 82,
    "band": "Moderate (70-84)",
    "notice": null,
    "warnings": [ /* same as above */ ],
    "stats": {
      "avgDaysToPay": 34,
      "reporterCount": 1240,
      "evidenceCount": 88300,
      "nonPaymentReports": 0
    }
  }
}

Score history

Neither view includes score history unless you ask for it. Add include=history to either view to get history: twelve weekly points, each with week, score and, for brokers, avgDaysToPay. Leave it off if you store results and build your own trend, since the response is smaller and faster without it. An unrecognized include value returns 400.

curl "https://www.sureloadr.com/api/v1/broker/MC123456?include=history"   -H "Authorization: Bearer sk_live_your_api_key"

When several companies match

Use the MC number or USDOT number for a broker, and the DOT number for a carrier. Those are unique identifiers and return a single report — they are what an integration should store and send. Send a broker's MC with its MC prefix (MC123456, not 123456): a bare number on /broker is matched as a USDOT number first, and only falls back to an MC when no USDOT number matches.

One registration, one report per product. FMCSA records broker authority and carrier authority separately on the same MC/DOT, and each call returns at most one report — never two. Read data.subjectType to know which one you got. A company that holds both authorities (J. B. Hunt, MC135797 / DOT 80806, for example) has a Broker Credit Report at /v1/broker/MC135797 and a separate Carrier Risk Analysis at /v1/carrier/MC135797; they score different things and each is its own billable call. A registration whose broker authority is inactive but which operates as an active motor carrier is a carrier: /v1/broker/<that MC> returns its Carrier Risk Analysis with subjectType: "carrier", and there is no broker report for it. Search hits and matches entries carry a subjectType for the same reason.

A company name will often match several companies. When more than one matches, the response is 200 with a matches array and no data key:

{
  "matches": [
    {
      "subjectKey": "MC015600",
      "name": "EXAMPLE RIDGE LOGISTICS LLC",
      "dba": null,
      "mc": "MC015600",
      "dot": "1234567",
      "location": "DALLAS, TX",
      "active": true
    },
    { /* … */ }
  ],
  "matchCount": 2,
  "truncated": false
}

Each entry is identity only — no score. Pick the one you want and call again with its subjectKey. truncated: true means more than twelve companies matched and the list was cut short, so narrow the query.

A bare number can be ambiguous too: some dockets exist in both zero-padded and unpadded form, so 15600 may match two records where MC015600 matches one.

An ambiguous response is never billed — no report was returned.

Sandbox and test keys

A test key (sk_test_…) serves a fixed set of sample companies and never reads real data. Live scores are recalculated nightly, so a test asserting a real company's score will eventually fail for reasons that have nothing to do with your code. The sandbox companies never change.

Every one is fictitious. Any other id returns 404, and MC99999999 and 90009999 are guaranteed to stay missing so you can test error handling. Sandbox calls are never billed, and a test key cannot reach real data any more than a live key can reach the sandbox.

Example (JavaScript)

const res = await fetch(
  "https://www.sureloadr.com/api/v1/broker/123456",
  { headers: { Authorization: "Bearer sk_live_your_api_key" } }
);
const { data } = await res.json();
console.log(data.name, data.score, data.band);

Example response

Successful responses return HTTP 200 with a top-level data object:

{
  "data": {
    "subjectType": "broker",
    "subjectKey": "MC123456",
    "name": "EXAMPLE LOGISTICS LLC",
    "dba": null,
    "mc": "MC123456",
    "dot": "7654321",
    "location": "COLUMBUS, OH",
    "active": true,
    "score": 82,
    "band": "Moderate (70-84)",
    "warnings": [
      {
        "kind": "no_buy",
        "severity": "high",
        "text": "One or more factoring companies have placed this broker on a no-buy list."
      }
    ],
    "stats": {
      "avgDaysToPay": 34,
      "reporterCount": 1240,
      "evidenceCount": 88300,
      "nonPaymentReports": 0
    },
    "sections": [ /* authority, payment experiences, contact, etc. */ ],
    "aging": { /* monthly receivables aging */ }
  }
}

Field reference

A broker report carries only broker fields and a carrier report carries only carrier fields. Read subjectType to know which you have. A field that does apply can still be null when we have no data for it, and that means unknown, never “checked and clear”.

Band values are Low (85-100), Moderate (70-84), High (51-69) and Extreme (<51).

Rate limits

Requests are limited per account, not per key — creating a second key does not raise your ceiling. The default is 60 per minute; your account may be set higher or lower. Exceeding it returns HTTP 429, and the message states the limit that actually applies to you.

A batch spends one unit of that budget per company rather than one per request, because the limit exists to bound work and not HTTP calls. A batch larger than your remaining budget for the current minute is refused with 429 before any report is built, and the message says how many you have left — so you are never charged for a batch that was only half served.

/search carries its own separate allowance of 20 per minute, counted apart from report calls, so free lookups cannot exhaust the budget you need for reports.

An account may also carry a monthly ceiling on billable calls as a runaway guard. Reaching it returns HTTP 402 until the next month. Need a higher limit? Contact us.

Errors

Errors return the appropriate HTTP status with a JSON { "error": "…" } body.

Not yet available

These are planned and are not live. They are listed so you know what is coming, not so you can build against them — calling any of them today returns 404.

• GET /alerts — changes since a timestamp
• Webhooks — pushed alerts when a monitored company changes

Frequently asked questions