Skip to content
Developers
GET

One of your orders

GET/api/vendor/v1/orders/{order_id}

The order as it is now: the same object POST /orders answered, with each service's status, its report link or result once it is completed, and the Safety Score. 202 (with Retry-After) while it runs, 200 once it is final. Another account's order answers 404, exactly like an id that does not exist.

A service is processing, under_review (held for Sentinel staff), completed or failed; reason says why when it is not plainly processing or completed. The whole order is under_review while its MVR names a different person than the one ordered for: nothing is served until staff release it. An order not finished 48 hours after it was placed is closed: every unfinished service fails with timed_out (identity_unverified for one held for that review), and a result that arrives later never reopens it.

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.

Path parameters

  • order_idstring · uuidrequired

Responses

  • 200The order, final.
    • 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.

      Show 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
      Show 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.

        Show 2 fields
        • foundbooleanrequired

          False when no review of the driver was found.

        • reviewsarray of objectrequired
          Show 3 fields
          • ratingnumber | nullrequired
          • textstring | nullrequired
          • datestring · date | nullrequired
    • created_atstring · date-timerequired
    • pollobjectrequired
      Show 2 fields
      • urlstringrequired
      • after_secondsintegerrequired
  • 202The order, still running.
    • Retry-Afterheader · integer

      Seconds to wait before trying again.

    • 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.

      Show 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
      Show 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.

        Show 2 fields
        • foundbooleanrequired

          False when no review of the driver was found.

        • reviewsarray of objectrequired
          Show 3 fields
          • ratingnumber | nullrequired
          • textstring | nullrequired
          • datestring · date | nullrequired
    • created_atstring · date-timerequired
    • pollobjectrequired
      Show 2 fields
      • urlstringrequired
      • after_secondsintegerrequired
  • 401invalid_api_key or api_key_expired.
    • WWW-Authenticateheader · string
    • errorobjectrequired
      Show 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.
    • errorobjectrequired
      Show 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.

  • 404not_found.
    • errorobjectrequired
      Show 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
      Show 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.
    • Retry-Afterheader · integer

      Seconds to wait before trying again.

    • errorobjectrequired
      Show 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 https://api-demo-safety.spotter.ai/api/vendor/v1/orders/3f2b9c1e-7a4d-4e8b-9c61-5d0a8e2f4b17 \
  -H "X-API-Key: YOUR_API_KEY"
{
  "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
  }
}