☰Documentation
How to integrate with the ParcelShield API. Start with the quick start, then the conventions every endpoint follows, so you can learn one and know the rest. Each API's reference, with its parameters, response schema and downloadable OpenAPI definition, is on the APIs page.
Quick start
1. Exchange your client ID and secret (issued by ParcelShield) for an access token:
curl -s -X POST "https://parcelshield.auth0.com/oauth/token" \
-H "Content-Type: application/json" \
-d '{"grant_type":"client_credentials","client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET","audience":"urn:parcelshield:public-api"}'
The response's access_token is valid for the number of seconds in expires_in (24 hours). Cache it and reuse it for every call; fetch a new one shortly before it expires, or when a call returns 401.
2. Call the API with the token:
curl "https://publicapi.parcelshield.com/v1/temperature-alerts?minLevel=SevereHot&pageSize=50" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
curl "https://publicapi.parcelshield.com/v1/risk-levels?granularity=zip3" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Without a date, 5-Day Risk returns tomorrow (UTC); pass date=yyyy-MM-dd for any day in the published horizon (meta.horizon).
Each API's reference page, under APIs, lists the typed query parameters and the response schema, and Download definition gives you the OpenAPI file to import into Postman or Insomnia. The conventions below cover authentication, errors, rate limits and usage.
API groups
The APIs page groups every API by what it returns. All of them use the same access token and follow the same conventions.
Data
Global environmental-risk data: Temperature Alerts and 5-Day Risk. No account identity is needed beyond your client credentials, and every client sees the same data.
Shipping
Account-scoped shipping APIs, such as shipment recommendations, that act on your own account's data. Access is authorized per account, so you only ever see and act on your own account. Shipping APIs appear on the APIs page as they become available.
Conventions
Authentication
Every request carries an Auth0 access token in the Authorization header as a Bearer token. Tokens are issued with the client-credentials grant for audience urn:parcelshield:public-api and must carry the product's scope (for example read:five-day-risk). ParcelShield issues your client ID and delivers the client secret through a one-time secure link; keep the secret in your secret manager, never in source code or a web page. Access tokens last 24 hours: cache and reuse them rather than requesting one per call.
Request tracing
Every response includes an X-Request-Id header. Include this id when contacting support and we can trace your exact request end to end.
Versioning
The version is in the path (e.g. /v1/...). A published version's contract never changes in a breaking way; breaking changes ship as a new version, and existing versions keep working. When a version is scheduled for retirement we announce it in advance.
Errors
Errors are returned as RFC 9457 problem+json with type, title, status and requestId, plus detail where there is more to say (for example which parameter was invalid). 400 = invalid query parameters; 401 = missing, invalid or expired token, or the token lacks the product's scope; 403 = the token is valid but its API account is missing or invalid; 404 = no such resource; 429 = rate limit exceeded; 502 or 503 = an upstream data source is unavailable, retry later.
Rate limits
Limits apply per API account and per product: all of your applications and credentials share one limit for each product. When you exceed it you receive HTTP 429 with a Retry-After header (seconds). Honor Retry-After with backoff rather than retrying immediately. There is no monthly cap.
Usage
Usage is charged per successful API request, as recorded by ParcelShield's gateway. Requests with recorded errors are excluded. Each successful retry counts separately.
Requests and responses
Send POST bodies as application/json. Responses are JSON with camelCase fields. Timestamps are UTC ISO-8601. List responses include a generatedAt indicating data freshness.
Every successful response uses the same envelope: a data field holding the result, and a meta field holding information about the response. data is the resource for single-item responses, or an array for collections. meta always includes generatedAt (when the data was produced); paginated lists also include total, page, pageSize, and hasMore.
Example — a page of Temperature Alerts:
{
"data": [
{ "zip": "75001", "temperatureLevel": "SevereHot" }
],
"meta": {
"generatedAt": "2026-09-24T13:22:41Z",
"window": { "hours": 48 }, "granularity": "zip5",
"total": 12529, "page": 1, "pageSize": 50,
"hasMore": true
}
}
Errors are the exception: they are returned as problem+json (see Errors above) and are never wrapped in data/meta. Every error also includes a requestId matching the X-Request-Id response header, so you can quote it in a support request.