GET /api/vendor/v1/orders/{order_id} answers the order as it is now: 202 while it runs, 200 once it's final. Another account's order answers 404, like one that doesn't exist.
Statuses
Each service has its own status: processing, under_review (held for Sentinel staff), completed or failed. reason says why when it isn't plainly processing or completed.
reason | Status | Meaning |
|---|---|---|
report_unavailable | processing | The report is finished but its file isn't available right now. |
identity_review | under_review | The MVR names a different person; 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 couldn't complete the check. |
no_record | failed | The provider has no record of this driver. 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. |
The order's own status is under_review while any service is held, processing while any runs, then completed, failed or partially_completed. final is true once every service is completed or failed.
Report files
MVR, PSP and CDLIS come back as PDFs. Once the service is completed, its file_url points to GET /api/vendor/v1/orders/{order_id}/files/{service}; download it with your API key. The CDLIS report never shows the SSN.
curl --fail-with-body https://api-demo-safety.spotter.ai/api/vendor/v1/orders/3f2b9c1e-7a4d-4e8b-9c61-5d0a8e2f4b17/files/mvr \
-H "X-API-Key: YOUR_API_KEY" \
-OJDriver Reviews
Driver Reviews comes back in the service's result: found (false when no review was found) and reviews, each with rating, text and date. Reviews are matched on the exact name and date of birth, and never include the reviewer, the reviewing carrier or any record id.
Safety Score
safety_score is on the order when it includes MVR or PSP: score (0 to 100), grade, risk_level, reports_used and calculated_at. It's null before the score is calculated and while the order or its MVR is under review.
Listing orders
GET /api/vendor/v1/orders lists your orders, newest first. Filter with status, created_after, created_before and external_reference; set page_size and follow next_cursor until it's null. The list can lag GET /orders/{order_id} by about a minute.