Status: Private preview. The public API ships Q3 2026. Founding-50 customers can request early credentials by emailing [email protected] with their use case. The shape below is the planned public API; specifics may shift before GA.

Base URL + Authentication

All API requests will be made against:

https://api.prevaylos.com/v1

Authentication is via Bearer token in the Authorization header:

Authorization: Bearer pvy_live_<your-api-key>

API keys are scoped at creation time. Available scopes:

orders:read — list and read orders
orders:write — create, update, cancel orders
carriers:read — list carriers
carriers:write — onboard, update, suspend carriers
accounting:read — read invoices, payments, GL
accounting:write — create/void invoices, record payments
webhooks:manage — create, update, delete webhook endpoints

Resource: Orders

Create order

POST /v1/orders
Content-Type: application/json
Authorization: Bearer pvy_live_<key>

{
  "customer_id": "cus_4kJsD...",
  "pickup": {
    "address1": "100 Main St",
    "city": "Detroit",
    "state": "MI",
    "zip": "48226"
  },
  "delivery": {
    "address1": "500 Peachtree St",
    "city": "Atlanta",
    "state": "GA",
    "zip": "30308"
  },
  "vehicles": [
    { "vin": "1G1ZD5ST6JF111111", "year": 2018, "make": "Chevrolet", "model": "Malibu" }
  ],
  "ready_date": "2026-05-15",
  "delivery_window_days": 5
}

List orders

GET /v1/orders?status=in_transit&limit=50

Response:
{
  "data": [
    { "id": "ord_8kJsD...", "status": "in_transit", "vehicles": [...], ... }
  ],
  "has_more": true,
  "next_cursor": "ord_4kJsD..."
}

Resource: Carriers

Onboard carrier

POST /v1/carriers
{
  "mc_number": "0000001",
  "dot_number": "0000001",
  "contact_name": "Sample Owner",
  "contact_email": "[email protected]",
  "phone": "+15555550100"
}

Response: {
  "id": "car_xYz...",
  "status": "pending_vetting",
  "safer_pull_status": "queued"
}

SAFER vetting runs asynchronously. Subscribe to the carrier.vetted webhook to know when it's complete.

Rate limits

Default rate limits are 100 requests/minute per API key, with burst capacity of 200 requests in 10 seconds. Rate limit headers on every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1714560000

Hitting a 429 means back off and retry with exponential backoff. The Retry-After header indicates seconds until the next safe request.

Errors

Errors follow a standard shape:

{
  "error": {
    "type": "validation_error",
    "code": "missing_required_field",
    "message": "The 'customer_id' field is required.",
    "param": "customer_id",
    "request_id": "req_8kJsD..."
  }
}

Always include the request_id when contacting support — it's the fastest way to investigate a specific failed call.

Versioning + stability

Once the API is GA (Q3 2026), Prevayl follows a date-based versioning policy: a new API version is published whenever a breaking change ships. Older versions remain supported for at least 12 months. The current version is fixed by API key — to upgrade, generate a new key with the new version pinned.

Webhooks — subscribe to events instead of polling
Zapier Integration — no-code automation if you don't want to write API code

REST API.