Service lifecycle - KarmaCheck

This page is a Draft and subject to change.

Each service ordered on a case is represented in the API as case data — a single record per service with its own status. A case’s overall status is a roll-up of the statuses of all of its case data records. While the case lifecycle describes how a case moves through onboarding, processing, and adjudication at a high level, each underlying service runs its own lifecycle in parallel. The states a service can be in, the substates it surfaces while pending, and the terminal status it lands in all depend on the service’s type, category, and subcategory. This page describes the service-level lifecycle for each service category, and clarifies the nuances that customers should account for when integrating with the platform.

Service-level status model

A case data record has two status fields that, together, describe its current state:

Status (statusId) — the primary state of the service. The full enumeration is documented in Case data statuses. A service starts in pending and progresses to a terminal status when it completes.
Pending status (pendingStatusId) — an optional sub-state. It is most commonly set while status = pending to communicate what stage of processing the service is in (for example, drug screening scheduled, sent to lab, awaiting medical review). It may also remain set on a terminal status to communicate why the service ended in that state (for example, consider + pending-status-no-show).

Whenever either field changes, the platform emits a casedata.statuschange webhook. Integrations that need fine-grained progress reporting should subscribe to this event and inspect both fields together rather than only statusId.

Statuses

Note: even when a service reaches a terminal status, it may later be reopened and transition back to pending in certain situations (for example, contested results, corrected source data, or manual reprocessing).

Status applicability matrix

The following matrix summarizes which terminal statuses are reachable by each category. Use this to validate that your integration handles the right set of outcomes per service.

Note: The status names and service type/category names shown in the tables above are the human-friendly names; the canonical status IDs and service type/category IDs used in the API are documented in detail on the Case data statuses page and Service type/categories page. Be sure to use the IDs when processing API responses and interacting with the API.

Pending Status applicablity matrix

While statusId remains pending, the pendingStatusId field communicates where in the workflow a service is — for example, pending-status-scheduled when an OHS appointment has been booked, or drugtest-sent when a specimen has been shipped to the lab. Long-running services (especially OHS Drug Screening, TB testing, and Vaccination) progress almost entirely through changes to pendingStatusId while statusId stays pending, so consumers that only watch statusId will miss most of the lifecycle.

Notes:

See Pending status for the complete enumeration of pending statuses.
If a service type/category/subcategory does not appear in the Pending Status applicablity matrix above, it means that it does not have any pending substates.
The service type/category names shown in the Pending Status applicability matrix above are human-friendly names; the canonical service type/category IDs used in the API are documented in detail on the Service type/categories page. Be sure to use the IDs when processing API responses and interacting with the API.

Integration guidance

Subscribe to casedata.statuschange. Long-running services (especially OHS Drug, TB skin test, Vaccination) communicate progress almost entirely through pendingStatusId while statusId remains pending. Polling statusId alone will miss most of the lifecycle.
Treat (statusId, pendingStatusId) as a tuple. A terminal consider carries different meaning when paired with drugtest-expired versus pending-status-no-show versus a real positive lab result. The pending substate is preserved on terminal records for exactly this reason.
Use the right “passed” terminal per category. Criminal/MVR/IDV pass with clear. Verification, Professional License, and most OHS services pass with acknowledge. Payment passes with complete. A single statusId === 'clear' check is not portable across all services.
Account for non-monotonic transitions. A service can move backwards (for example, pending-status-scheduled → pending-status-canceled → pending-status-requested) and a terminal status can be re-opened to pending if a result is contested or new information arrives. Build for idempotent processing of casedata.statuschange events.
not_found is not a failure. It means the source could not produce a record. Treat it as a distinct outcome from consider in your adjudication flow — many customers route not_found to manual review rather than auto-decline.
If you are going to generate a Custom Report for a service (or set of services), do so only once the service(s) has reached a terminal status.

Lifecycles by service category

The following sections describe the lifecycle for each category. Substates listed in parentheses are pending substates that can accompany pending (or, where noted, a terminal status).

Identity Verification (`service-cat-idv`)

Includes SSN trace, SSN validation, CBSV, IDV document/liveness, Death Master, and social media services. Most identity services are “instant” and return a terminal status quickly with no pending substate.

pending → clear
        ↘ consider
        ↘ not_found
        ↘ canceled

Reachable status	Typical meaning
`pending`	Identity check submitted to the vendor.
`clear`	Identity confirmed; no discrepancies. Terminal.
`consider`	Discrepancy detected (failed liveness, SSN mismatch, etc.). Terminal.
`not_found`	No matching record could be located (rare; specific to SSN/DMF-style services). Terminal.
`canceled`	Service was not performed. Terminal.

Criminal Check (`service-cat-criminal`)

Includes county, state, federal, and national criminal searches, civil searches, sex offender registries, FACIS, and global watchlists. These services typically run against multiple jurisdictions and can take several days to complete but do not use pending substates.

pending → clear
        ↘ consider
        ↘ canceled

Reachable status	Typical meaning
`pending`	Search is in progress, including any per-jurisdiction sub-searches.
`clear`	No actionable records were found in any searched jurisdiction. Terminal.
`consider`	One or more jurisdictions returned records that require customer adjudication. Terminal.
`canceled`	Search was not performed. Terminal.

Note on multi-jurisdiction searches. County, state, and federal criminal searches may run against multiple jurisdictions. Each jurisdiction has its own sub-status (clear, consider, pending, canceled) inside the case data details payload, but the top-level statusId is the authoritative roll-up that customers should adjudicate against. Records that are still being reviewed internally before being released to the customer will keep the top-level statusId at pending until review completes.

Criminal searches do not use not_found — a search that returns no records is clear, not not_found.

Motor Vehicle Record Check (`service-cat-mvr`)

pending → clear
        ↘ consider
        ↘ not_found
        ↘ canceled

Reachable status	Typical meaning
`pending`	DMV query in progress.
`clear`	Driving record returned; no actionable violations. Terminal.
`consider`	Violations or restrictions on the record require review. Terminal.
`not_found`	License number could not be matched in the DMV system. Terminal.
`canceled`	Service was not performed. Terminal.

Verification (`service-cat-verification`)

Includes employment and education verification services. These services typically involve outreach to a third party and can have a longer pending lifecycle but do not have pending substates.

pending → acknowledge
        ↘ consider
        ↘ not_found
        ↘ canceled

Reachable status	Typical meaning
`pending`	Verification request submitted; awaiting response from the verifier or institution.
`acknowledge`	Verification confirmed positively — credential matches what the candidate provided. Terminal.
`consider`	Verifier responded but information differs from what the candidate provided. Terminal.
`not_found`	The institution or employer could not be reached, or the candidate’s record could not be located. Terminal.
`canceled`	Verification was not performed. Terminal.

For verification services, acknowledge — not clear — is the canonical “passed” terminal. Customers building credential validity checks should treat acknowledge and consider (with reviewer-approved discrepancies) as the valid terminals.

Professional License (`service-cat-pro-lic`)

Professional License and Certification verification services do not use pending substates.

pending → acknowledge
        ↘ consider
        ↘ not_found
        ↘ canceled

Reachable status	Typical meaning
`pending`	License lookup in progress.
`acknowledge`	License located, in good standing, and matches candidate-provided data. Terminal.
`consider`	License is expired, suspended, has disciplinary action, or shows a discrepancy. Terminal.
`not_found`	License could not be located with the issuing authority. Terminal.
`canceled`	Service was not performed. Terminal.

As with Verification, acknowledge is the canonical “passed” terminal for Professional License services.

Occupational Health Screening (`service-cat-ohs`)

OHS services share the same case data status model, but each subcategory has its own full lifecycle shape and is documented with a standalone diagram below.

Common OHS patterns across subcategories:

Services start in pending and usually progress through one or more pending substates before reaching a terminal status.
Most OHS subcategories use the pending-status-* scheduling family, while Drug Screening uses the drugtest-* pending substate family.
Terminal outcomes vary by subcategory (for example, acknowledge, clear, consider, not_found, canceled).
A terminal consider may carry pending-status-no-show or pending-status-refusal, and a terminal canceled may carry pending-status-not-performed.

The subsections below describe what is unique about each OHS subcategory.

Physical (`service-subcat-physical`)

Includes DOT physicals, fit-for-duty exams, and respirator clearance.

pending → pending (substates) → acknowledge | clear
                   |            ↘ consider
                   |            ↘ canceled
                   |
                   ↓
        ↕ pending-status-requested       (scheduling invite sent to candidate)
        ↕ pending-status-scheduled       (clinic appointment booked)
        ↕ pending-status-rescheduled     (appointment moved to a new time)
        ↕ pending-status-canceled        (appointment canceled; may reschedule)
        ↕ pending-status-pending         (clinic processing results)
        ↕ pending-status-partial         (some results returned, others outstanding)
        ↕ pending-status-medical-review  (where applicable)
        ↕ pending-status-no-show         (candidate did not attend appointment)
        ↕ pending-status-refusal         (candidate refused the exam)
        ↕ pending-status-not-performed   (service was not run)

acknowledge is used when a physical is affirmatively pass/fit (e.g., DOT physical fit-for-duty). clear may be used for portion-style sub-exams that have a simple pass/fail. consider indicates findings the customer needs to review (including no-show or refusal, surfaced via the pending substate).

Tuberculosis (`service-subcat-tb`)

TB tests have two distinct lifecycle shapes depending on the test type:

pending → pending (substates) → acknowledge | clear
                   |            ↘ consider
                   |            ↘ canceled
                   |
                   ↓
        ↕ pending-status-requested       (scheduling invite sent to candidate)
        ↕ pending-status-scheduled       (clinic appointment booked)
        ↕ pending-status-rescheduled     (appointment moved to a new time)
        ↕ pending-status-canceled        (appointment canceled; may reschedule)
        ↕ pending-status-pending         (clinic processing results)
        ↕ pending-status-partial         (some results returned, others outstanding)
        ↕ pending-status-medical-review  (blood/chest X-ray where applicable)
        ↕ pending-status-suspended       (PPD only: waiting for TB read)
        ↕ pending-status-no-show         (candidate did not attend appointment)
        ↕ pending-status-not-performed   (service was not run)

TB skin test (PPD) is a two-visit test. After placement, the case data transitions to pending / pending-status-suspended (“Waiting for TB Read”) while the candidate returns 48–72 hours later for the read. Final terminal is acknowledge (negative read), consider (positive/equivocal), or canceled.
TB blood (QuantiFERON, T-Spot) and TB chest X-ray follow the standard OHS scheduling preamble and produce acknowledge / consider / clear / canceled without pending-status-suspended.

Titer (`service-subcat-titer`)

pending → pending (substates) → acknowledge
                   |            ↘ consider
                   |            ↘ not_found
                   |            ↘ canceled
                   |
                   ↓
        ↕ pending-status-requested       (scheduling invite sent to candidate)
        ↕ pending-status-scheduled       (clinic appointment booked)
        ↕ pending-status-rescheduled     (appointment moved to a new time)
        ↕ pending-status-canceled        (appointment canceled; may reschedule)
        ↕ pending-status-pending         (clinic processing results)
        ↕ pending-status-partial         (some titer results returned, others outstanding)
        ↕ pending-status-medical-review  (where applicable)
        ↕ pending-status-no-show         (candidate did not attend appointment)
        ↕ pending-status-not-performed   (service was not run)

acknowledge indicates an immune titer. consider indicates a non-immune or equivocal result and typically triggers a follow-up vaccination order. not_found is rare and indicates the specimen could not be processed.

Vaccination (`service-subcat-vacc`)

Vaccination services may require multiple doses spread over weeks or months. Between doses, the case data may surface a partial-style state:

pending → pending (substates) → acknowledge
                   |            ↘ consider
                   |            ↘ canceled
                   |
                   ↓
        ↕ pending-status-requested       (scheduling invite sent to candidate)
        ↕ pending-status-scheduled       (clinic appointment booked)
        ↕ pending-status-rescheduled     (appointment moved to a new time)
        ↕ pending-status-canceled        (appointment canceled; may reschedule)
        ↕ pending-status-pending         (clinic processing results)
        ↕ pending-status-partial         (intermediate doses recorded; series incomplete)
        ↕ pending-status-medical-review  (where applicable)
        ↕ pending-status-no-show         (candidate did not attend appointment)
        ↕ pending-status-refusal         (candidate refused the vaccination)
        ↕ pending-status-not-performed   (service was not run)

Integrations that surface vaccination progress to customers should treat pending / pending-status-partial as a long-lived intermediate state and only consider the service finalized when it transitions out of pending.

Drug Screening (`service-subcat-drug`)

Drug screenings use the drug-specific pending substates rather than the generic OHS ones:

pending → pending (substates) → clear
                   |            ↘ consider
                   |            ↘ canceled
                   |
                   ↓
        ↕ drugtest-appointment-requested  (scheduling invite sent to candidate)
        ↕ drugtest-appointment-scheduled  (collection appointment booked)
        ↕ drugtest-appointment-change     (collection appointment rescheduled)
        ↕ drugtest-appointment-canceled   (collection appointment canceled; may reschedule)
        ↕ drugtest-pending                (Pending Custody & Control Form after collection)
        ↕ drugtest-sent                   (specimen sent to lab)
        ↕ drugtest-received               (specimen received at lab)
        ↕ drugtest-review                 (Medical Review Officer review)
        ↕ pending-status-no-show          (candidate did not attend collection appointment)
        ↕ pending-status-refusal          (candidate refused to provide specimen)
        ↕ pending-status-not-performed    (service was not run)

A terminal consider may carry drugtest-expired, pending-status-no-show, or pending-status-refusal to explain the outcome. Drug screenings do not use acknowledge or not_found.

Document Processing (`service-cat-document-processing`)

Document Processing services do not use pending substates.

pending → complete
        ↘ consider
        ↘ canceled

Reachable status	Typical meaning
`pending`	Document extraction/processing is in progress.
`complete`	Processing finished successfully with no additional review required. Terminal.
`consider`	Processing completed but extracted output requires review or follow-up. Terminal.
`canceled`	Service was not performed. Terminal.

Payment (`service-cat-payment`)

Payment services do not use pending substates and have no pass/fail interpretation.

pending → complete
        ↘ canceled

Reachable status	Typical meaning
`pending`	Payment authorization in progress.
`complete`	Payment captured successfully. Terminal.
`canceled`	Payment was not attempted or was voided. Terminal.

Shipment (`service-type-shipment`)

Shipment services do not use pending substates and have no pass/fail interpretation.

pending → complete
        ↘ canceled

Reachable status	Typical meaning
`pending`	Shipment workflow is in progress.
`complete`	Shipment workflow completed successfully. Terminal.
`canceled`	Shipment was not performed or was voided. Terminal.

Legal (`service-type-legal`)

Legal services are consent/authorization workflows and do not use pending substates and have no pass/fail interpretation.

pending → acknowledge

Reachable status	Typical meaning
`pending`	Candidate legal authorization/disclosure flow is in progress.
`acknowledge`	Candidate completed the legal authorization/disclosure flow. Terminal.

​Service-level status model

​Statuses

​Status applicability matrix

​Pending Status applicablity matrix

​Integration guidance

​Lifecycles by service category

​Identity Verification (service-cat-idv)

​Criminal Check (service-cat-criminal)

​Motor Vehicle Record Check (service-cat-mvr)

​Verification (service-cat-verification)

​Professional License (service-cat-pro-lic)

​Occupational Health Screening (service-cat-ohs)

​Physical (service-subcat-physical)

​Tuberculosis (service-subcat-tb)

​Titer (service-subcat-titer)

​Vaccination (service-subcat-vacc)

​Drug Screening (service-subcat-drug)

​Document Processing (service-cat-document-processing)

​Payment (service-cat-payment)

​Shipment (service-type-shipment)

​Legal (service-type-legal)

​Related references

Service-level status model

Statuses

Status applicability matrix

Pending Status applicablity matrix

Integration guidance

Lifecycles by service category

Identity Verification (`service-cat-idv`)

Criminal Check (`service-cat-criminal`)

Motor Vehicle Record Check (`service-cat-mvr`)

Verification (`service-cat-verification`)

Professional License (`service-cat-pro-lic`)

Occupational Health Screening (`service-cat-ohs`)

Physical (`service-subcat-physical`)

Tuberculosis (`service-subcat-tb`)

Titer (`service-subcat-titer`)

Vaccination (`service-subcat-vacc`)

Drug Screening (`service-subcat-drug`)

Document Processing (`service-cat-document-processing`)

Payment (`service-cat-payment`)

Shipment (`service-type-shipment`)

Legal (`service-type-legal`)

Related references