Orders

POST /api/vendor/v1/orders orders background checks for one driver. Send multipart/form-data (at most 32 MB in all) with an Idempotency-Key header.

Place an order

curl -X POST https://api-demo-safety.spotter.ai/api/vendor/v1/orders \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: 9d4e1f0a-2b6c-4c8e-a1f3-7e5d2c9b8a60" \
  -F first_name=Jane \
  -F last_name=Doe \
  -F date_of_birth=1985-04-12 \
  -F license_number=D1234567 \
  -F license_state=TX \
  -F mc_number=MC-123456 \
  -F services=mvr,psp,cdlis,driver_reviews \
  -F ssn=DRIVER_SSN \
  -F driver_consent_confirmed=true \
  -F consent_obtained_at=2026-10-14T15:04:05-05:00 \
  -F consent_version=CONSENT_VERSION \
  -F cdl_image=@cdl-front.jpg

Fields

Field	Required	Notes
`first_name`, `last_name`	Yes	Also `middle_name` and `name_suffix`, optional.
`date_of_birth`	Yes	`YYYY-MM-DD`.
`license_number`	Yes
`license_state`	Yes	The two-letter state code. Optional: `class_type`, `issue_date`, `expiration_date`.
`mc_number`	Yes	The carrier's MC (or MX / FF) docket number. It's shown on your invoice.
`cdl_image`	Yes	The front of the CDL; `cdl_image_back` is optional. image/jpeg, image/png, image/webp, image/heic, application/pdf, at most 15 MB each.
`driver_consent_confirmed`	Yes	Must be `true`: you confirm you have the driver's consent.
`consent_obtained_at`	Yes	When you collected consent, with a timezone.
`consent_version`	Yes	The consent wording version: `vendor-2026-10-v1`.
`services`	No	Comma-separated, for example `mvr,psp`. Without it, every service enabled for your account runs.
`ssn`	With CDLIS	The driver's full SSN. Required with CDLIS and refused without it. Never returned, logged or shown, and erased once CDLIS has finished.
`external_reference`	No	Your own reference, returned with the order.

The answer

202 with the order: each service starts as processing, and is billed on your monthly invoice at the price in effect when the order was placed (responses carry no prices or totals). Poll poll.url every 30 seconds (the Retry-After header) until final is true; see Results and files.

An order not finished 48 hours after it was placed is closed: every unfinished service fails with timed_out, except one still held for identity_review, which fails with identity_unverified. A result that arrives later never reopens it.

Idempotency

Every order needs an Idempotency-Key: a value you choose, unique per order (a UUID, say), printable ASCII, at most 64 characters. Retrying with the same key and the same body answers with the order already placed (Idempotent-Replayed: true) and orders nothing again. The same key with a different body is 409 idempotency_conflict.

Refusals

Nothing is created or billed when an order is refused.

Code	Status	When
`validation_error`	400	A field is missing or wrong; see `fields`.
`service_not_enabled`	403	A service isn't enabled for your account.
`idempotency_conflict`	409	The key was used for a different order (`error.order_id`).
`in_progress`	409	An order with this key is still being placed; retry after `Retry-After`.
`mvr_state_unavailable`	422	MVR can't be ordered for the license state; `fields.license_state` says why.
`price_unavailable`	503	A service can't be priced right now.

You can place 10 orders a minute per account, replays included.