POST

Order background checks for a driver

POST/api/vendor/v1/orders

Orders the services in services (or, without it, every service enabled for the vendor) for one driver. Each service is billed on your monthly invoice at the price in effect when the order was placed. The answer is 202 with the order and its services; poll the order every 30 seconds (Retry-After) until it is final.

Send multipart/form-data, at most 32 MB in all. The CDL images may be JPEG, PNG, WEBP, HEIC or PDF, at most 15 MB each; the type is read from the file's bytes, and a PDF is stored as its first page.

Every order needs an Idempotency-Key. Retrying with the same key and the same body (from any of the vendor's API keys) answers with the order already placed, marked Idempotent-Replayed: true, and orders nothing again; the same key with a different body is 409 idempotency_conflict. The key belongs to the vendor and never expires.

Nothing is created or billed when an order is refused. MVR is refused (422 mvr_state_unavailable) for a license state it can't be pulled for through the vendor API (a state that needs the carrier's own access code or credentials, MVR switched off, a manual pull, no price); a Driver Reviews-only order for that state is fine.

The ssn is accepted only with CDLIS and is required with it. It is never returned, logged or shown anywhere, and it is erased once CDLIS has finished.

10 orders a minute per vendor, replays included.

Authorization

X-API-Keystringrequired
The environment's prefix (snt_test_ on this server; GET /me returns the environment), 8 characters, _, then the secret. Shown once, when the key is created in the Sentinel Developers portal. A key works only against the server that issued it.

Headers

Idempotency-Keystringat most 64 charactersrequired
A value of your choosing, unique per order (a UUID, say): printable ASCII, at most 64 characters.

Request body

multipart/form-datarequired

first_namestringrequired
last_namestringrequired
middle_namestring
name_suffixstring
date_of_birthstring · daterequired
YYYY-MM-DD.
license_numberstringrequired
license_statestringrequired
The two-letter state code.
class_typestring
The license class (A, B, C...).
issue_datestring · date
expiration_datestring · date
mc_numberstringrequired
The carrier's MC (or MX / FF) docket number, for example MC-123456. You are responsible for sending the right one. It is stored on the order and shown on your invoice; the carrier doesn't need to be a Sentinel customer.
servicesstring
Comma-separated, for example mvr,psp. Without it, every service enabled for your account runs.
ssnstring
The driver's full SSN, digits with optional dashes or spaces. Required with CDLIS, refused without it.
external_referencestringat most 255 characters
Your own reference for the order, returned with it.
driver_consent_confirmedbooleanrequired
Must be true. You confirm that you have the driver's consent.
consent_obtained_atstring · date-timerequired
When you collected the driver's consent, with a timezone.
consent_versionstringrequired
The version of the consent wording you collected it under. This server accepts vendor-2026-10-v1.
cdl_imagefilerequired
The front of the CDL.
cdl_image_backfile
The back of the CDL (optional).

Responses

200A replay of an order that is already final (Idempotent-Replayed: true).
- Idempotent-Replayedheader · string
  true when the answer is an order already placed with this Idempotency-Key.
- Locationheader · string
  The order's address, to poll.
- Cache-Controlheader · string
  no-store: order results are never cached.
- order_idstring · uuidrequired
- statusstringrequired
  under_review while any service is held for Sentinel staff, processing while any service runs, then completed, failed or partially_completed.
  One of: processing, under_review, completed, partially_completed, failed
- finalbooleanrequired
  True once every service is completed or failed.
- safety_scoreobject | nullrequired
  Null for an order without MVR or PSP, before the score is calculated, and while the order or its MVR is under review.
  ShowHide 5 fields
  scoreintegerrequired
  From 0 to 100.
  gradestring | nullrequired
  risk_levelstring | nullrequired
  reports_usedarray of stringrequired
  calculated_atstring · date-time | nullrequired
- environmentstringrequired
  One of: sandbox, live
- mc_numberstringrequired
  The MC number sent with the order, normalised.
- external_referencestring | nullrequired
- servicesarray of objectrequired
  ShowHide 7 fields
  servicestringrequired
  One of: mvr, psp, cdlis, driver_reviews
  statusstringrequired
  Extensible: a later version may add values. Treat a value you don't know as not final until final says so. (Whether a result is billed is on the Billing page, not here.)
  Known values: processing, under_review, completed, failed
  reasonstring | nullrequired
  Extensible: a later version adds reasons; show an unknown one as is.
  
  report_unavailable (processing): the report is finished but its file is not available right now; Sentinel staff are alerted.
  
  identity_review (under_review): the MVR names a different person than the one ordered for. The whole order is held until staff release it.
  
  manual_review (under_review): the MVR needs Sentinel staff before its report can be served.
  
  report_review (under_review): the report needs Sentinel staff before it can be served.
  
  provider_failed (failed): the provider or Sentinel could not complete the check.
  
  no_record (failed): the provider answered that it has no record of this driver (an MVR every provider of the state answered so for; a PSP FMCSA has no record for). Billed as NO_HIT.
  
  no_report (failed): the provider finished without a report.
  
  timed_out (failed): not finished by the order's deadline.
  
  identity_unverified (failed): still held for identity_review at the deadline.
  
  record_deleted (failed): the order's data was deleted on request.
  
  Known values: report_unavailable, identity_review, manual_review, report_review, provider_failed, no_record, no_report, timed_out, identity_unverified, record_deleted
  statestring | nullrequired
  The license state of the MVR (MVR only).
  completed_atstring · date-time | nullrequired
  file_urlstring | nullrequired
  The report PDF (MVR, PSP, CDLIS), once the service is completed. Download it with your API key. A link from the list can briefly answer 404 after the file becomes unavailable.
  resultobject | nullrequired
  Driver Reviews only, once it is completed.
  ShowHide 2 fields
  foundbooleanrequired
  False when no review of the driver was found.
  reviewsarray of objectrequired
  ShowHide 3 fields
  ratingnumber | nullrequired
  textstring | nullrequired
  datestring · date | nullrequired
- created_atstring · date-timerequired
- pollobjectrequired
  ShowHide 2 fields
  urlstringrequired
  after_secondsintegerrequired
202The order is accepted, or a replay of one that is still running (Idempotent-Replayed: true). A newly accepted order can already be final (final: true), for example when every check answers at once; poll it while final is false.
- Retry-Afterheader · integer
  Only while the order is not final: seconds to wait before polling it.
- Locationheader · string
  The order's address, to poll.
- Idempotent-Replayedheader · string
  true when the answer is an order already placed with this Idempotency-Key.
- Cache-Controlheader · string
  no-store: order results are never cached.
- order_idstring · uuidrequired
- statusstringrequired
  under_review while any service is held for Sentinel staff, processing while any service runs, then completed, failed or partially_completed.
  One of: processing, under_review, completed, partially_completed, failed
- finalbooleanrequired
  True once every service is completed or failed.
- safety_scoreobject | nullrequired
  Null for an order without MVR or PSP, before the score is calculated, and while the order or its MVR is under review.
  ShowHide 5 fields
  scoreintegerrequired
  From 0 to 100.
  gradestring | nullrequired
  risk_levelstring | nullrequired
  reports_usedarray of stringrequired
  calculated_atstring · date-time | nullrequired
- environmentstringrequired
  One of: sandbox, live
- mc_numberstringrequired
  The MC number sent with the order, normalised.
- external_referencestring | nullrequired
- servicesarray of objectrequired
  ShowHide 7 fields
  servicestringrequired
  One of: mvr, psp, cdlis, driver_reviews
  statusstringrequired
  Extensible: a later version may add values. Treat a value you don't know as not final until final says so. (Whether a result is billed is on the Billing page, not here.)
  Known values: processing, under_review, completed, failed
  reasonstring | nullrequired
  Extensible: a later version adds reasons; show an unknown one as is.
  
  report_unavailable (processing): the report is finished but its file is not available right now; Sentinel staff are alerted.
  
  identity_review (under_review): the MVR names a different person than the one ordered for. The whole order is held until staff release it.
  
  manual_review (under_review): the MVR needs Sentinel staff before its report can be served.
  
  report_review (under_review): the report needs Sentinel staff before it can be served.
  
  provider_failed (failed): the provider or Sentinel could not complete the check.
  
  no_record (failed): the provider answered that it has no record of this driver (an MVR every provider of the state answered so for; a PSP FMCSA has no record for). Billed as NO_HIT.
  
  no_report (failed): the provider finished without a report.
  
  timed_out (failed): not finished by the order's deadline.
  
  identity_unverified (failed): still held for identity_review at the deadline.
  
  record_deleted (failed): the order's data was deleted on request.
  
  Known values: report_unavailable, identity_review, manual_review, report_review, provider_failed, no_record, no_report, timed_out, identity_unverified, record_deleted
  statestring | nullrequired
  The license state of the MVR (MVR only).
  completed_atstring · date-time | nullrequired
  file_urlstring | nullrequired
  The report PDF (MVR, PSP, CDLIS), once the service is completed. Download it with your API key. A link from the list can briefly answer 404 after the file becomes unavailable.
  resultobject | nullrequired
  Driver Reviews only, once it is completed.
  ShowHide 2 fields
  foundbooleanrequired
  False when no review of the driver was found.
  reviewsarray of objectrequired
  ShowHide 3 fields
  ratingnumber | nullrequired
  textstring | nullrequired
  datestring · date | nullrequired
- created_atstring · date-timerequired
- pollobjectrequired
  ShowHide 2 fields
  urlstringrequired
  after_secondsintegerrequired
400validation_error: see fields, one list of messages per field.
- errorobjectrequired
  ShowHide 4 fields
  order_idstring · uuid
  idempotency_conflict only: the order the key already belongs to.
  codestringrequired
  
  validation_error (400): the request is not valid; see fields.
  
  invalid_api_key (401): no key, a malformed, unknown or revoked key, or a key this server did not issue.
  
  api_key_expired (401): the key is past its 90 days. Create a new one.
  
  account_not_approved (403): staff have not approved the account yet.
  
  account_suspended (403): the account is suspended. Results can still be read; new orders are refused.
  
  service_not_enabled (403): an order names a service that is not enabled for the account (or none is).
  
  permission_denied (403): any other refusal.
  
  not_found (404): no such path or object. Any unknown path under /api/vendor/ answers this, with or without a key; so does an order that is not yours (exactly like one that does not exist) and a report that can't be downloaded now.
  
  method_not_allowed (405).
  
  idempotency_conflict (409): the Idempotency-Key was already used for a different order (error.order_id).
  
  in_progress (409): an order with this Idempotency-Key is still being placed; see Retry-After.
  
  payload_too_large (413): the request body or an image is too large.
  
  unsupported_media_type (415): the request body or an image has the wrong type.
  
  mvr_state_unavailable (422): MVR can't be ordered for the license state through the vendor API.
  
  rate_limited (429): see Retry-After. Also answered, instead of 401, after more than 100 failed keys from one address or 10 on one key in 10 minutes.
  
  internal_error (500).
  
  rate_limit_unavailable (503): try again shortly.
  
  price_unavailable (503): a service can't be priced right now.
  
  request_failed: any other error, with its HTTP status.
  
  One of: validation_error, invalid_api_key, api_key_expired, account_not_approved, account_suspended, service_not_enabled, permission_denied, not_found, method_not_allowed, idempotency_conflict, in_progress, payload_too_large, unsupported_media_type, mvr_state_unavailable, rate_limited, internal_error, rate_limit_unavailable, price_unavailable, request_failed
  messagestringrequired
  For people; may change. Use code in your code.
  fieldsobject | nullrequired
  Per-field messages, for validation errors.
401invalid_api_key or api_key_expired.
- WWW-Authenticateheader · string
- errorobjectrequired
  ShowHide 4 fields
  order_idstring · uuid
  idempotency_conflict only: the order the key already belongs to.
  codestringrequired
  
  validation_error (400): the request is not valid; see fields.
  
  invalid_api_key (401): no key, a malformed, unknown or revoked key, or a key this server did not issue.
  
  api_key_expired (401): the key is past its 90 days. Create a new one.
  
  account_not_approved (403): staff have not approved the account yet.
  
  account_suspended (403): the account is suspended. Results can still be read; new orders are refused.
  
  service_not_enabled (403): an order names a service that is not enabled for the account (or none is).
  
  permission_denied (403): any other refusal.
  
  not_found (404): no such path or object. Any unknown path under /api/vendor/ answers this, with or without a key; so does an order that is not yours (exactly like one that does not exist) and a report that can't be downloaded now.
  
  method_not_allowed (405).
  
  idempotency_conflict (409): the Idempotency-Key was already used for a different order (error.order_id).
  
  in_progress (409): an order with this Idempotency-Key is still being placed; see Retry-After.
  
  payload_too_large (413): the request body or an image is too large.
  
  unsupported_media_type (415): the request body or an image has the wrong type.
  
  mvr_state_unavailable (422): MVR can't be ordered for the license state through the vendor API.
  
  rate_limited (429): see Retry-After. Also answered, instead of 401, after more than 100 failed keys from one address or 10 on one key in 10 minutes.
  
  internal_error (500).
  
  rate_limit_unavailable (503): try again shortly.
  
  price_unavailable (503): a service can't be priced right now.
  
  request_failed: any other error, with its HTTP status.
  
  One of: validation_error, invalid_api_key, api_key_expired, account_not_approved, account_suspended, service_not_enabled, permission_denied, not_found, method_not_allowed, idempotency_conflict, in_progress, payload_too_large, unsupported_media_type, mvr_state_unavailable, rate_limited, internal_error, rate_limit_unavailable, price_unavailable, request_failed
  messagestringrequired
  For people; may change. Use code in your code.
  fieldsobject | nullrequired
  Per-field messages, for validation errors.
403account_not_approved, account_suspended or service_not_enabled.
- errorobjectrequired
  ShowHide 4 fields
  order_idstring · uuid
  idempotency_conflict only: the order the key already belongs to.
  codestringrequired
  
  validation_error (400): the request is not valid; see fields.
  
  invalid_api_key (401): no key, a malformed, unknown or revoked key, or a key this server did not issue.
  
  api_key_expired (401): the key is past its 90 days. Create a new one.
  
  account_not_approved (403): staff have not approved the account yet.
  
  account_suspended (403): the account is suspended. Results can still be read; new orders are refused.
  
  service_not_enabled (403): an order names a service that is not enabled for the account (or none is).
  
  permission_denied (403): any other refusal.
  
  not_found (404): no such path or object. Any unknown path under /api/vendor/ answers this, with or without a key; so does an order that is not yours (exactly like one that does not exist) and a report that can't be downloaded now.
  
  method_not_allowed (405).
  
  idempotency_conflict (409): the Idempotency-Key was already used for a different order (error.order_id).
  
  in_progress (409): an order with this Idempotency-Key is still being placed; see Retry-After.
  
  payload_too_large (413): the request body or an image is too large.
  
  unsupported_media_type (415): the request body or an image has the wrong type.
  
  mvr_state_unavailable (422): MVR can't be ordered for the license state through the vendor API.
  
  rate_limited (429): see Retry-After. Also answered, instead of 401, after more than 100 failed keys from one address or 10 on one key in 10 minutes.
  
  internal_error (500).
  
  rate_limit_unavailable (503): try again shortly.
  
  price_unavailable (503): a service can't be priced right now.
  
  request_failed: any other error, with its HTTP status.
  
  One of: validation_error, invalid_api_key, api_key_expired, account_not_approved, account_suspended, service_not_enabled, permission_denied, not_found, method_not_allowed, idempotency_conflict, in_progress, payload_too_large, unsupported_media_type, mvr_state_unavailable, rate_limited, internal_error, rate_limit_unavailable, price_unavailable, request_failed
  messagestringrequired
  For people; may change. Use code in your code.
  fieldsobject | nullrequired
  Per-field messages, for validation errors.
409idempotency_conflict (the key was used for a different body; error.order_id names that order) or in_progress (an order with this key is still being placed; retry after Retry-After).
- Retry-Afterheader · integer
  in_progress only: seconds to wait before retrying with the same key.
- errorobjectrequired
  ShowHide 4 fields
  order_idstring · uuid
  idempotency_conflict only: the order the key already belongs to.
  codestringrequired
  
  validation_error (400): the request is not valid; see fields.
  
  invalid_api_key (401): no key, a malformed, unknown or revoked key, or a key this server did not issue.
  
  api_key_expired (401): the key is past its 90 days. Create a new one.
  
  account_not_approved (403): staff have not approved the account yet.
  
  account_suspended (403): the account is suspended. Results can still be read; new orders are refused.
  
  service_not_enabled (403): an order names a service that is not enabled for the account (or none is).
  
  permission_denied (403): any other refusal.
  
  not_found (404): no such path or object. Any unknown path under /api/vendor/ answers this, with or without a key; so does an order that is not yours (exactly like one that does not exist) and a report that can't be downloaded now.
  
  method_not_allowed (405).
  
  idempotency_conflict (409): the Idempotency-Key was already used for a different order (error.order_id).
  
  in_progress (409): an order with this Idempotency-Key is still being placed; see Retry-After.
  
  payload_too_large (413): the request body or an image is too large.
  
  unsupported_media_type (415): the request body or an image has the wrong type.
  
  mvr_state_unavailable (422): MVR can't be ordered for the license state through the vendor API.
  
  rate_limited (429): see Retry-After. Also answered, instead of 401, after more than 100 failed keys from one address or 10 on one key in 10 minutes.
  
  internal_error (500).
  
  rate_limit_unavailable (503): try again shortly.
  
  price_unavailable (503): a service can't be priced right now.
  
  request_failed: any other error, with its HTTP status.
  
  One of: validation_error, invalid_api_key, api_key_expired, account_not_approved, account_suspended, service_not_enabled, permission_denied, not_found, method_not_allowed, idempotency_conflict, in_progress, payload_too_large, unsupported_media_type, mvr_state_unavailable, rate_limited, internal_error, rate_limit_unavailable, price_unavailable, request_failed
  messagestringrequired
  For people; may change. Use code in your code.
  fieldsobject | nullrequired
  Per-field messages, for validation errors.
413payload_too_large: the body or an image is too large.
- errorobjectrequired
  ShowHide 4 fields
  order_idstring · uuid
  idempotency_conflict only: the order the key already belongs to.
  codestringrequired
  
  validation_error (400): the request is not valid; see fields.
  
  invalid_api_key (401): no key, a malformed, unknown or revoked key, or a key this server did not issue.
  
  api_key_expired (401): the key is past its 90 days. Create a new one.
  
  account_not_approved (403): staff have not approved the account yet.
  
  account_suspended (403): the account is suspended. Results can still be read; new orders are refused.
  
  service_not_enabled (403): an order names a service that is not enabled for the account (or none is).
  
  permission_denied (403): any other refusal.
  
  not_found (404): no such path or object. Any unknown path under /api/vendor/ answers this, with or without a key; so does an order that is not yours (exactly like one that does not exist) and a report that can't be downloaded now.
  
  method_not_allowed (405).
  
  idempotency_conflict (409): the Idempotency-Key was already used for a different order (error.order_id).
  
  in_progress (409): an order with this Idempotency-Key is still being placed; see Retry-After.
  
  payload_too_large (413): the request body or an image is too large.
  
  unsupported_media_type (415): the request body or an image has the wrong type.
  
  mvr_state_unavailable (422): MVR can't be ordered for the license state through the vendor API.
  
  rate_limited (429): see Retry-After. Also answered, instead of 401, after more than 100 failed keys from one address or 10 on one key in 10 minutes.
  
  internal_error (500).
  
  rate_limit_unavailable (503): try again shortly.
  
  price_unavailable (503): a service can't be priced right now.
  
  request_failed: any other error, with its HTTP status.
  
  One of: validation_error, invalid_api_key, api_key_expired, account_not_approved, account_suspended, service_not_enabled, permission_denied, not_found, method_not_allowed, idempotency_conflict, in_progress, payload_too_large, unsupported_media_type, mvr_state_unavailable, rate_limited, internal_error, rate_limit_unavailable, price_unavailable, request_failed
  messagestringrequired
  For people; may change. Use code in your code.
  fieldsobject | nullrequired
  Per-field messages, for validation errors.
415unsupported_media_type: the body is not multipart/form-data, or an image is not one of the accepted types.
- errorobjectrequired
  ShowHide 4 fields
  order_idstring · uuid
  idempotency_conflict only: the order the key already belongs to.
  codestringrequired
  
  validation_error (400): the request is not valid; see fields.
  
  invalid_api_key (401): no key, a malformed, unknown or revoked key, or a key this server did not issue.
  
  api_key_expired (401): the key is past its 90 days. Create a new one.
  
  account_not_approved (403): staff have not approved the account yet.
  
  account_suspended (403): the account is suspended. Results can still be read; new orders are refused.
  
  service_not_enabled (403): an order names a service that is not enabled for the account (or none is).
  
  permission_denied (403): any other refusal.
  
  not_found (404): no such path or object. Any unknown path under /api/vendor/ answers this, with or without a key; so does an order that is not yours (exactly like one that does not exist) and a report that can't be downloaded now.
  
  method_not_allowed (405).
  
  idempotency_conflict (409): the Idempotency-Key was already used for a different order (error.order_id).
  
  in_progress (409): an order with this Idempotency-Key is still being placed; see Retry-After.
  
  payload_too_large (413): the request body or an image is too large.
  
  unsupported_media_type (415): the request body or an image has the wrong type.
  
  mvr_state_unavailable (422): MVR can't be ordered for the license state through the vendor API.
  
  rate_limited (429): see Retry-After. Also answered, instead of 401, after more than 100 failed keys from one address or 10 on one key in 10 minutes.
  
  internal_error (500).
  
  rate_limit_unavailable (503): try again shortly.
  
  price_unavailable (503): a service can't be priced right now.
  
  request_failed: any other error, with its HTTP status.
  
  One of: validation_error, invalid_api_key, api_key_expired, account_not_approved, account_suspended, service_not_enabled, permission_denied, not_found, method_not_allowed, idempotency_conflict, in_progress, payload_too_large, unsupported_media_type, mvr_state_unavailable, rate_limited, internal_error, rate_limit_unavailable, price_unavailable, request_failed
  messagestringrequired
  For people; may change. Use code in your code.
  fieldsobject | nullrequired
  Per-field messages, for validation errors.
422mvr_state_unavailable: MVR can't be ordered for the license state; fields.license_state says why.
- errorobjectrequired
  ShowHide 4 fields
  order_idstring · uuid
  idempotency_conflict only: the order the key already belongs to.
  codestringrequired
  
  validation_error (400): the request is not valid; see fields.
  
  invalid_api_key (401): no key, a malformed, unknown or revoked key, or a key this server did not issue.
  
  api_key_expired (401): the key is past its 90 days. Create a new one.
  
  account_not_approved (403): staff have not approved the account yet.
  
  account_suspended (403): the account is suspended. Results can still be read; new orders are refused.
  
  service_not_enabled (403): an order names a service that is not enabled for the account (or none is).
  
  permission_denied (403): any other refusal.
  
  not_found (404): no such path or object. Any unknown path under /api/vendor/ answers this, with or without a key; so does an order that is not yours (exactly like one that does not exist) and a report that can't be downloaded now.
  
  method_not_allowed (405).
  
  idempotency_conflict (409): the Idempotency-Key was already used for a different order (error.order_id).
  
  in_progress (409): an order with this Idempotency-Key is still being placed; see Retry-After.
  
  payload_too_large (413): the request body or an image is too large.
  
  unsupported_media_type (415): the request body or an image has the wrong type.
  
  mvr_state_unavailable (422): MVR can't be ordered for the license state through the vendor API.
  
  rate_limited (429): see Retry-After. Also answered, instead of 401, after more than 100 failed keys from one address or 10 on one key in 10 minutes.
  
  internal_error (500).
  
  rate_limit_unavailable (503): try again shortly.
  
  price_unavailable (503): a service can't be priced right now.
  
  request_failed: any other error, with its HTTP status.
  
  One of: validation_error, invalid_api_key, api_key_expired, account_not_approved, account_suspended, service_not_enabled, permission_denied, not_found, method_not_allowed, idempotency_conflict, in_progress, payload_too_large, unsupported_media_type, mvr_state_unavailable, rate_limited, internal_error, rate_limit_unavailable, price_unavailable, request_failed
  messagestringrequired
  For people; may change. Use code in your code.
  fieldsobject | nullrequired
  Per-field messages, for validation errors.
429rate_limited. 120 reads and 10 orders a minute per vendor, across all of its keys.
- Retry-Afterheader · integer
  Seconds to wait before trying again.
- errorobjectrequired
  ShowHide 4 fields
  order_idstring · uuid
  idempotency_conflict only: the order the key already belongs to.
  codestringrequired
  
  validation_error (400): the request is not valid; see fields.
  
  invalid_api_key (401): no key, a malformed, unknown or revoked key, or a key this server did not issue.
  
  api_key_expired (401): the key is past its 90 days. Create a new one.
  
  account_not_approved (403): staff have not approved the account yet.
  
  account_suspended (403): the account is suspended. Results can still be read; new orders are refused.
  
  service_not_enabled (403): an order names a service that is not enabled for the account (or none is).
  
  permission_denied (403): any other refusal.
  
  not_found (404): no such path or object. Any unknown path under /api/vendor/ answers this, with or without a key; so does an order that is not yours (exactly like one that does not exist) and a report that can't be downloaded now.
  
  method_not_allowed (405).
  
  idempotency_conflict (409): the Idempotency-Key was already used for a different order (error.order_id).
  
  in_progress (409): an order with this Idempotency-Key is still being placed; see Retry-After.
  
  payload_too_large (413): the request body or an image is too large.
  
  unsupported_media_type (415): the request body or an image has the wrong type.
  
  mvr_state_unavailable (422): MVR can't be ordered for the license state through the vendor API.
  
  rate_limited (429): see Retry-After. Also answered, instead of 401, after more than 100 failed keys from one address or 10 on one key in 10 minutes.
  
  internal_error (500).
  
  rate_limit_unavailable (503): try again shortly.
  
  price_unavailable (503): a service can't be priced right now.
  
  request_failed: any other error, with its HTTP status.
  
  One of: validation_error, invalid_api_key, api_key_expired, account_not_approved, account_suspended, service_not_enabled, permission_denied, not_found, method_not_allowed, idempotency_conflict, in_progress, payload_too_large, unsupported_media_type, mvr_state_unavailable, rate_limited, internal_error, rate_limit_unavailable, price_unavailable, request_failed
  messagestringrequired
  For people; may change. Use code in your code.
  fieldsobject | nullrequired
  Per-field messages, for validation errors.
503rate_limit_unavailable (see Retry-After) or price_unavailable (a service has no price right now).
- Retry-Afterheader · integer
  rate_limit_unavailable only: seconds to wait before trying again.
- errorobjectrequired
  ShowHide 4 fields
  order_idstring · uuid
  idempotency_conflict only: the order the key already belongs to.
  codestringrequired
  
  validation_error (400): the request is not valid; see fields.
  
  invalid_api_key (401): no key, a malformed, unknown or revoked key, or a key this server did not issue.
  
  api_key_expired (401): the key is past its 90 days. Create a new one.
  
  account_not_approved (403): staff have not approved the account yet.
  
  account_suspended (403): the account is suspended. Results can still be read; new orders are refused.
  
  service_not_enabled (403): an order names a service that is not enabled for the account (or none is).
  
  permission_denied (403): any other refusal.
  
  not_found (404): no such path or object. Any unknown path under /api/vendor/ answers this, with or without a key; so does an order that is not yours (exactly like one that does not exist) and a report that can't be downloaded now.
  
  method_not_allowed (405).
  
  idempotency_conflict (409): the Idempotency-Key was already used for a different order (error.order_id).
  
  in_progress (409): an order with this Idempotency-Key is still being placed; see Retry-After.
  
  payload_too_large (413): the request body or an image is too large.
  
  unsupported_media_type (415): the request body or an image has the wrong type.
  
  mvr_state_unavailable (422): MVR can't be ordered for the license state through the vendor API.
  
  rate_limited (429): see Retry-After. Also answered, instead of 401, after more than 100 failed keys from one address or 10 on one key in 10 minutes.
  
  internal_error (500).
  
  rate_limit_unavailable (503): try again shortly.
  
  price_unavailable (503): a service can't be priced right now.
  
  request_failed: any other error, with its HTTP status.
  
  One of: validation_error, invalid_api_key, api_key_expired, account_not_approved, account_suspended, service_not_enabled, permission_denied, not_found, method_not_allowed, idempotency_conflict, in_progress, payload_too_large, unsupported_media_type, mvr_state_unavailable, rate_limited, internal_error, rate_limit_unavailable, price_unavailable, request_failed
  messagestringrequired
  For people; may change. Use code in your code.
  fieldsobject | nullrequired
  Per-field messages, for validation errors.

curl -X POST https://api-demo-safety.spotter.ai/api/vendor/v1/orders \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: string" \
  -F first_name=string \
  -F last_name=string \
  -F date_of_birth=2026-10-14 \
  -F license_number=string \
  -F license_state=string \
  -F mc_number=string \
  -F driver_consent_confirmed=true \
  -F consent_obtained_at=2026-10-14T15:04:05Z \
  -F consent_version=string \
  -F services=mvr,psp,cdlis,driver_reviews \
  -F ssn=DRIVER_SSN \
  -F cdl_image=@cdl-front.jpg

import { readFile } from "node:fs/promises";

const form = new FormData();
form.append("first_name", "string");
form.append("last_name", "string");
form.append("date_of_birth", "2026-10-14");
form.append("license_number", "string");
form.append("license_state", "string");
form.append("mc_number", "string");
form.append("driver_consent_confirmed", "true");
form.append("consent_obtained_at", "2026-10-14T15:04:05Z");
form.append("consent_version", "string");
form.append("services", "mvr,psp,cdlis,driver_reviews");
form.append("ssn", "DRIVER_SSN");
form.append("cdl_image", new Blob([await readFile("cdl-front.jpg")]), "cdl-front.jpg");

const res = await fetch("https://api-demo-safety.spotter.ai/api/vendor/v1/orders", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Idempotency-Key": "string" },
  body: form,
});
const data = await res.json();

import requests

res = requests.post(
    "https://api-demo-safety.spotter.ai/api/vendor/v1/orders",
    headers={"X-API-Key": "YOUR_API_KEY", "Idempotency-Key": "string"},
    data={"first_name": "string", "last_name": "string", "date_of_birth": "2026-10-14", "license_number": "string", "license_state": "string", "mc_number": "string", "driver_consent_confirmed": "true", "consent_obtained_at": "2026-10-14T15:04:05Z", "consent_version": "string", "services": "mvr,psp,cdlis,driver_reviews", "ssn": "DRIVER_SSN"},
    files={"cdl_image": open("cdl-front.jpg", "rb")},
)
data = res.json()

{
  "order_id": "3f2b9c1e-7a4d-4e8b-9c61-5d0a8e2f4b17",
  "status": "processing",
  "final": true,
  "safety_score": {
    "score": 0,
    "grade": "string",
    "risk_level": "string",
    "reports_used": [
      "mvr"
    ],
    "calculated_at": "2026-10-14T15:04:05Z"
  },
  "environment": "sandbox",
  "mc_number": "string",
  "external_reference": "string",
  "services": [
    {
      "service": "mvr",
      "status": "processing",
      "reason": "report_unavailable",
      "state": "string",
      "completed_at": "2026-10-14T15:04:05Z",
      "file_url": "string",
      "result": {
        "found": true,
        "reviews": [
          {
            "rating": 0,
            "text": "string",
            "date": "2026-10-14"
          }
        ]
      }
    }
  ],
  "created_at": "2026-10-14T15:04:05Z",
  "poll": {
    "url": "string",
    "after_seconds": 0
  }
}