Home → Blog

You need a reliable way to look up a trucking carrier by DOT number and surface core attributes like legal name, status, safety rating, and driver count. By the end of this post, you will be able to call the FreightPulse Carrier Lookup API from curl and JavaScript, handle the response envelope, and ship a guest-access integration that supports up to 100 requests per IP per day without an API key.

What you can build and how guest access works

This guide focuses on a carrier lookup workflow: users enter a DOT number, your service calls the FreightPulse endpoint, and you display the carrier’s identity and basic profile. You can launch immediately with guest access, which allows 100 requests per IP per day without a key, and later switch to authenticated requests using the documented header.

Guest access lets you prototype quickly, but you should cache results and budget calls to stay within the 100 requests/day/IP limit. When you are ready to move beyond guest limits, create a key via the registration flow: Register.

Endpoint and authentication

Carrier search uses a single query parameter and returns a standard response envelope. Key details:

• HTTP method: GET
• URL: https://freightpulsehq.com/api/v1/carriers?q=54283 (replace q with your search value)
• Auth: header X-API-Key: YOUR_API_KEY (omit this header for guest usage; guest is limited to 100 requests/day per IP)
• Envelope: the API returns an object with success and data fields

Plan for multiple results in data.results, and select the best match for your UI. If you need additional query forms or advanced filters beyond the q parameter, refer to the Documentation.

Quickstart: curl request (copy-paste)

Use the authenticated request below during development, or omit the X-API-Key header to rely on guest access within the daily IP quota.

curl -H "X-API-Key: YOUR_API_KEY" "https://freightpulsehq.com/api/v1/carriers?q=54283"

Response format and fields you will use

The API returns a consistent success/data envelope with a results array. Here is the official sample response:

{
    "success": true,
    "data": {
        "type": "trucking",
        "query": "54283",
        "results": [
            {
                "dot_number": 54283,
                "legal_name": "SWIFT TRANSPORTATION COMPANY OF ARIZONA LLC",
                "status": "active",
                "safety_rating": "S",
                "drivers": 12883,
                "address": {
                    "city": "Phoenix",
                    "state": "AZ",
                    "country": "US"
                }
            }
        ]
    }
}

Field usage in a carrier profile UI:

• data.type: category of the entity (here, trucking). Useful for routing or display logic.
• data.query: echo of your search term; log it with the match for traceability.
• data.results: array of candidate matches. Expect one or more; select the entry that matches your DOT number.
• results[].dot_number: the carrier’s DOT identifier.
• results[].legal_name: the carrier’s registered legal name.
• results[].status: operational status string.
• results[].safety_rating: concise rating code; render alongside status for compliance checks.
• results[].drivers: integer count of drivers. Use as-is; it represents a headcount.
• results[].address: city/state/country fields to show carrier location.

JavaScript example: fetch and parse

The snippet below queries the same endpoint, reads the standard envelope, and extracts a minimal carrier card. Replace YOUR_API_KEY with your key for authenticated usage, or remove the header to operate in guest mode within the IP quota.

async function lookupCarrier(dotNumber) {
const url = `https://freightpulsehq.com/api/v1/carriers?q=${encodeURIComponent(dotNumber)}`;
const res = await fetch(url, {
headers: {
// For guest mode within 100 requests/day/IP, you may omit this header entirely.
"X-API-Key": "YOUR_API_KEY"
},
// Avoid caching issues during development; adjust for production as needed.
cache: "no-store"
});

if (!res.ok) {
throw new Error(`HTTP ${res.status} when calling ${url}`);
}

const body = await res.json();

if (!body || body.success !== true || !body.data || !Array.isArray(body.data.results)) {
throw new Error("Unexpected API response shape");
}

// Choose the first result. In production, verify it matches the DOT input.
const first = body.data.results[0];
if (!first) {
return null; // No matches found
}

// Construct a minimal carrier card for your UI.
return {
dotNumber: first.dot_number,
legalName: first.legal_name,
status: first.status,
safetyRating: first.safety_rating,
drivers: first.drivers,
location: [first.address?.city, first.address?.state, first.address?.country].filter(Boolean).join(", "),
sourceType: body.data.type,
queryEcho: body.data.query
};
}

// Example usage:
lookupCarrier(54283)
.then(card => {
if (!card) {
console.log("No carrier found");
return;
}
console.log("Carrier:", card);
})
.catch(err => {
console.error("Lookup failed:", err);
});

Designing the integration: quotas, caching, and UX

Guest access allows 100 requests per day per IP without an API key. To avoid quota surprises, debounce input-driven searches and only call the API after the user confirms the DOT number. Cache responses for DOT numbers you have already resolved to reduce duplicate calls.

Because the response arrives in a consistent envelope, centralize parsing and validation. Treat data.results as potentially multi-valued and ensure your UI can either display the first result or prompt the user to confirm the correct match if you choose to show multiple options.

If you operate in environments where many users share an egress IP (for example, an office or proxy), monitor request counts and switch to authenticated usage with your own key to decouple from shared-IP limits. For server-side integrations, set sensible network timeouts and surface useful error messages when an upstream failure or malformed response occurs.

Notes on related data: port congestion

If you later expand beyond carrier lookup into port context, FreightPulse port congestion metrics come from IMF PortWatch and are lagged by approximately 6–7 days. They are computed as a 7-day average relative to a 90-day baseline and are not live AIS wait times.

Keep this distinction clear in your UX and labeling. Do not present lagged congestion metrics as real-time data; a simple badge or tooltip can prevent user confusion.

Testing and observability

Create a repeatable test that queries a known DOT number so you can verify parsing and UI rendering after depoyments. The official fixture for DOT 54283 is a good baseline: it exercises identity, status, safety rating, driver count, and address fields in one response.

Log the following per request to speed up debugging: timestamp, remote IP (if relevant to guest quotas), query value (q), HTTP status, and whether your call was guest or authenticated. Store a compact preview of the first result, such as dot_number and legal_name, for quick verification without persisting full payloads longer than necessary.

Error handling and edge cases

• No results: data.results may be an empty array. Handle this as a normal user-visible “not found” state.
• Multiple results: if more than one candidate appears, decide on a deterministic selection rule (e.g., exact DOT match) rather than assuming the first item is correct in every context.
• Transport errors: network failures or 5xx responses should surface a retryable error. Exponential backoff helps, but respect daily guest limits.
• Malformed payloads: verify success === true and that data and data.results exist before indexing. Fail fast with a clear message if the envelope is missing.

FAQ

How do I use the API without a key?
Omit the X-API-Key header. Guest requests are capped at 100 per day per IP. For higher or predictable throughput, add a key and send it via X-API-Key: YOUR_API_KEY.

What should I pass to the q parameter?
Pass the DOT number you want to look up, as shown in the examples. For additional query modes, see the Documentation.

Is the response real-time?
Carrier identity fields are returned as-is from the service. If you also work with FreightPulse port congestion metrics, note those are lagged by ~6–7 days from IMF PortWatch and are not live AIS wait times.

How should I handle multiple results?
Inspect data.results and choose based on your criteria. For DOT lookups, prefer the exact dot_number match. If your UX supports it, present a short list for user confirmation.

Can I cache results?
Yes. Cache by the DOT number you queried. This reduces duplicate calls and helps you stay within guest limits. Invalidate or refresh on a schedule that fits your product requirements.