# Authenticate API client Source: https://developer.karmacheck.com/api-reference/authentication/authenticate-api-client /background-check-api/api-reference/openapi.json post /auth/api Authenticates an API client with KarmaCheck so that they can access the KarmaCheck system. # Cancel a case Source: https://developer.karmacheck.com/api-reference/cancel-a-case /background-check-api/api-reference/openapi.json post /case/id/{caseId}/cancel # Cancel Case Service Source: https://developer.karmacheck.com/api-reference/cancel-case-service /background-check-api/api-reference/openapi.json post /case/id/{caseId}/services/cancel # Acknowledge Canada Disclosure Source: https://developer.karmacheck.com/api-reference/candidate-onboarding/acknowledge-canada-disclosure /background-check-api/api-reference/openapi.json post /case/id/{caseId}/canadadisclosure/{language} Submits acknowledgement of a Canada Disclosure document for tracking and auditing purposes. This action creates a case data record with the provided information. The system records the acknowledgment and generates a downloadable PDF file of the acknowledged disclosure. # Acknowledge Custom Disclosure Source: https://developer.karmacheck.com/api-reference/candidate-onboarding/acknowledge-custom-disclosure /background-check-api/api-reference/openapi.json post /case/id/{caseId}/customdisclosure/{language} Submits acknowledgement of a Custom Disclosure document for tracking and auditing purposes. This action creates a case data record with the provided information. The system records the acknowledgment and generates a downloadable PDF file of the acknowledged disclosure. # Acknowledge E-Signature Source: https://developer.karmacheck.com/api-reference/candidate-onboarding/acknowledge-e-signature /background-check-api/api-reference/openapi.json post /case/id/{caseId}/esig/{language} Submits acknowledgement of the e-Signature for tracking and auditing purposes. This action creates a case data record with the provided information. The system records the acknowledgment and generates a PDF file of the e-Signature document, which includes the candidate's acknowledgment and is available for download. # Acknowledge FCRA Source: https://developer.karmacheck.com/api-reference/candidate-onboarding/acknowledge-fcra /background-check-api/api-reference/openapi.json post /case/id/{caseId}/fcra/{language} Submits acknowledgement of the FCRA for tracking and auditing purposes. This action creates a case data record with the provided information. The system records the acknowledgment and generates a downloadable PDF file of the acknowledged FCRA document. # Acknowledge International Disclosure Source: https://developer.karmacheck.com/api-reference/candidate-onboarding/acknowledge-international-disclosure /background-check-api/api-reference/openapi.json post /case/id/{caseId}/intldisclosure/{language} Submits acknowledgement of an International Disclosure document for tracking and auditing purposes. This action creates a case data record with the provided information. The system records the acknowledgment and generates a downloadable PDF file of the acknowledged disclosure. # Acknowledge location-specific disclosures Source: https://developer.karmacheck.com/api-reference/candidate-onboarding/acknowledge-location-specific-disclosures /background-check-api/api-reference/openapi.json put /case/id/{caseId}/{disclosureType}/{language} Submits acknowledgement of location-specific disclosures for tracking and auditing purposes. This action creates a case data record with the provided information. The system records the acknowledgment and generates a downloadable PDF file of the acknowledged disclosures. # Create candidate by proxy for invitation Source: https://developer.karmacheck.com/api-reference/candidate-onboarding/create-candidate-by-proxy-for-invitation /background-check-api/api-reference/openapi.json post /invitation/candidate/create Creates the candidate object in KarmaCheck on behalf of the candidate so that there can be pre-population of PII before the candidate accepts an invitation and enters the system. The candidate will be directed to onboard the associated case via the one-time token link that will be provided by the API partner. This API marks the candidate object as not secured in the KarmaCheck system, which results in the candidate being prompted to set a password when the onboarding of the case begins. After this call is complete, the candidate will be associated with the specific `caseId` that was attached to the invitation. The `caseId` will be used for saving all further case data, such as authorizations and acknowledgements. This assumes that a candidate will need to sign up with KarmaCheck before being able to continue to accept the invitation. # Create testimony for case Source: https://developer.karmacheck.com/api-reference/candidate-onboarding/create-testimony-for-case /background-check-api/api-reference/openapi.json post /testimony/create/case/id/{caseId} Stores personally identifiable information (PII) on a candidate in KarmaCheck. Only one piece of PII can be included in a single piece of testimony. Testimony is owned by the candidate, and can be attached to a case. When testimony is attached to a case, a separate case testimony record is created, which then becomes part of the case. # Detach testimony from case Source: https://developer.karmacheck.com/api-reference/candidate-onboarding/detach-testimony-from-case /background-check-api/api-reference/openapi.json delete /testimony/id/{testimonyId}/detach/case/id/{caseId} Removes previously attached testimony from a case. If the testimony is not attached to the supplied case, then calling this endpoint generates an error with 404. If the case has finished onboarding, then this call will fail with 403. If the testimony has not been attached to any other case, then detaching will result in deletion of the testimony from the system. # Get Canada Disclosure Source: https://developer.karmacheck.com/api-reference/candidate-onboarding/get-canada-disclosure /background-check-api/api-reference/openapi.json get /case/id/{caseId}/canadadisclosure/{language} Retrieves a Canada Disclosure document to present to the candidate so that the candidate can acknowledge and continue the onboarding process. If the candidate has already acknowledged the disclosure, the response will indicate this and provide a valid `caseDataId` so that the details of the previous acknowledgement can be retrieved. This can also be used to determine whether the candidate can skip this specific disclosure step if they leave and then continue their onboarding later or on another device, for example. # Get candidate for invitation Source: https://developer.karmacheck.com/api-reference/candidate-onboarding/get-candidate-for-invitation /background-check-api/api-reference/openapi.json get /candidate/invitation/token/{invitationToken} Retrieves the candidate information associated with an invitation. # Get countries Source: https://developer.karmacheck.com/api-reference/candidate-onboarding/get-countries /background-check-api/api-reference/openapi.json get /candidate/countries Fetches the list of countries and their respective ISO 3166 codes to use for creating testimony with proper codes. # Get Custom Disclosure Source: https://developer.karmacheck.com/api-reference/candidate-onboarding/get-custom-disclosure /background-check-api/api-reference/openapi.json get /case/id/{caseId}/customdisclosure/{language} Retrieves a Custom Disclosure document to present to the candidate so that the candidate can acknowledge and continue the onboarding process. If the candidate has already acknowledged the disclosure, the response will indicate this and provide a valid `caseDataId` so that the details of the previous acknowledgement can be retrieved. This can also be used to determine whether the candidate can skip this specific disclosure step if they leave and then continue their onboarding later or on another device, for example. # Get E-Signature Source: https://developer.karmacheck.com/api-reference/candidate-onboarding/get-e-signature /background-check-api/api-reference/openapi.json get /case/id/{caseId}/esig/{language} Retrieves an e-Signature consent document and form that can be presented to and acknowledged by the candidate as part of the onboarding process. If the candidate has already acknowledged it, the response will indicate this as well as provide the `caseDataId` of the acknowledgement, which can be used to retrieve details. These can be used to determine whether the candidate can skip this step if they leave and then continue their onboarding later or on another device, for example. The e-Signature document can be customized. If a customer-specific version doesn't exist, a default one will be returned. # Get FCRA Source: https://developer.karmacheck.com/api-reference/candidate-onboarding/get-fcra /background-check-api/api-reference/openapi.json get /case/id/{caseId}/fcra/{language} Retrieves a Fair Credit Reporting Act (FCRA) consent document and form that can be presented to and acknowledged by the candidate as part of the onboarding process. If the candidate has already acknowledged it, the response will indicate this as well as provide the `caseDataId` of the acknowledgement, which can be used to retrieve details. These can be used to determine whether the candidate can skip this step if they leave and then continue their onboarding later or on another device, for example. The FCRA document can be customized. If a customer-specific version doesn't exist, a default one will be returned. # Get International Disclosure Source: https://developer.karmacheck.com/api-reference/candidate-onboarding/get-international-disclosure /background-check-api/api-reference/openapi.json get /case/id/{caseId}/intldisclosure/{language} Retrieves an International Disclosure document to present to the candidate so that the candidate can acknowledge and continue the onboarding process. If the candidate has already acknowledged the disclosure, the response will indicate this and provide a valid `caseDataId` so that the details of the previous acknowledgement can be retrieved. This can also be used to determine whether the candidate can skip this specific disclosure step if they leave and then continue their onboarding later or on another device, for example. # Get invitation for case ID Source: https://developer.karmacheck.com/api-reference/candidate-onboarding/get-invitation-for-case-id /background-check-api/api-reference/openapi.json get /invitation/case/{caseId} Retrieves the invitation associated with a case. # Get legal acknowledgement status Source: https://developer.karmacheck.com/api-reference/candidate-onboarding/get-legal-acknowledgement-status /background-check-api/api-reference/openapi.json get /case/id/{caseId}/legal/status/{legalType} Retrieves the candidate acknowledgment status of the specified legal document for the case. This can be used to determine whether the candidate can skip acknowledging that legal document if they leave and then continue their onboarding later or on another device, for example. # Get one-time token link Source: https://developer.karmacheck.com/api-reference/candidate-onboarding/get-one-time-token-link /background-check-api/api-reference/openapi.json get /case/id/{caseId}/candidate/id/{candidateId}/url Retrieves a one-time token (OTT) URL to give to a candidate so that they can complete onboarding for a case. The returned URL contains a token, ensuring that the candidate secures their account before proceeding with onboarding. This endpoint is typically called when a candidate has been newly integrated into KarmaCheck by a partner. This is so that testimony can be presented on behalf of the candidate for a case before onboarding begins. The URL is designed to ensure that the onboarding process includes a step where the candidate can secure their account before continuing. **Note:** To properly redirect the candidate to the provided invitation context to commence their background check, append the full invitation link to the end of the returned OTT URL as a `redirect_url` query parameter. For example: - `https://my.karmacheck.com/ott/{ott}?redirect_url=/invite/{invitationToken}` - `https://my.karmacheck.com/ott/{ott}?redirect_url=https://my.karmacheck.com/invite/{invitationToken}` # Get secure image by ID Source: https://developer.karmacheck.com/api-reference/candidate-onboarding/get-secure-image-by-id /background-check-api/api-reference/openapi.json get /candidate/secureimage/id/{secureImageId} Retrieves a secure image by its identifier. # Get testimony for case Source: https://developer.karmacheck.com/api-reference/candidate-onboarding/get-testimony-for-case /background-check-api/api-reference/openapi.json get /testimony/case/{caseId} Retrieves the testimony attached to a case. # Refresh invitation for case Source: https://developer.karmacheck.com/api-reference/candidate-onboarding/refresh-invitation-for-case /background-check-api/api-reference/openapi.json put /case/id/{caseId}/action/refreshinvite Refreshes the expiration date for an existing invitation. When an onboarding invitation is generated, the candidate has 14 days (the default expiration period) to begin and complete their onboarding, or else the link in their invitation email becomes invalid. As long as the invitation is refreshed during the 14-day period, enough time will be added so that the candidate has 14 days to complete onboarding. For example, if only 1 day remains, 13 days will be added. If 12 days still remain, only 2 days will be added. Note that for your cases that don't rely on the candidate to onboard, such as those that use the customer PII entry feature, you'll never need to call this API. # Request location-specific disclosures Source: https://developer.karmacheck.com/api-reference/candidate-onboarding/request-location-specific-disclosures /background-check-api/api-reference/openapi.json post /case/id/{caseId}/{disclosureType}/{language} Retrieves location-specific disclosure documents and forms that can be presented to and acknowledged by the candidate as part of the onboarding process. # Resend case invitation Source: https://developer.karmacheck.com/api-reference/candidate-onboarding/resend-case-invitation /background-check-api/api-reference/openapi.json post /case/id/{caseId}/action/resendinvite Resends the invitation email for a case. Note that a case can have only one active invitation at a time, and resending the invite actually creates and sends a new invitation with a new ID. This means that the link in an old invitation email will stop working, so make sure to update any references to the old invitation in order to use the new one. # Update candidate for case Source: https://developer.karmacheck.com/api-reference/candidate-onboarding/update-candidate-for-case /background-check-api/api-reference/openapi.json post /candidate/id/{candidateId}/update/case/id/{caseId} Sets modifiable data for a candidate. # Update testimony for case Source: https://developer.karmacheck.com/api-reference/candidate-onboarding/update-testimony-for-case /background-check-api/api-reference/openapi.json post /testimony/id/{testimonyId}/update/case/id/{caseId} Updates testimony associated with a case. # Add to order Source: https://developer.karmacheck.com/api-reference/cases/add-to-order /background-check-api/api-reference/openapi.json post /case/id/{caseId}/add/services Adds the requested services to the existing ordered case. The requested services must be part of the package for the case. The authentication token must be for the group that the case is owned by. # Archive case Source: https://developer.karmacheck.com/api-reference/cases/archive-case /background-check-api/api-reference/openapi.json post /case/archive/{caseId} Archives a case so that it no longer appears in the KarmaCheck dashboard. # Begin processing case Source: https://developer.karmacheck.com/api-reference/cases/begin-processing-case /background-check-api/api-reference/openapi.json put /case/id/{caseId}/action/beginprocessing Begins the processing of screenings for a case. This endpoint must be called when the onboarding of a case is complete, unless you are: - Sending invitation emails to the candidate so they can onboard. - Using the customer-provided PII flow to [create the case](paths/~1case~1create/post). In these instances, the case will begin processing as soon as the candidate information has been provided. # Cancel case data search Source: https://developer.karmacheck.com/api-reference/cases/cancel-case-data-search /background-check-api/api-reference/openapi.json post /case/data/id/{caseDataId}/search/id/{searchId}/cancel Endpoint to cancel individual case data search records. Currently supports cancelling education and employment searches. # Create case Source: https://developer.karmacheck.com/api-reference/cases/create-case /background-check-api/api-reference/openapi.json post /case/create Orders a background check report and opens a case for tracking. The new case includes references to the package. Depending on the values entered in the request, the case goes through one of two flows: - **Candidate onboarding flow:** The new case will have an initial status of **Pending** and a secondary status of **Waiting for Authorization**. An invitation is emailed to the candidate, who is required to provide their personally identifiable information (PII) via the invitation email. - **Customer-provided PII flow:** All PII for the candidate is provided in the request body. Setting `autoProcess` to true initiates a case for the candidate and immediately begins processing. ### API Integration - Attributing a case to a specific user To provide additional insight for API integrations the Create Case API supports an optional header that allows an API customer to provide additional information about the end user that is initiating the API call through their integration. This optional header is only ever used if the API call has a valid authentication token. The optional header is `karmacheck-on-behalf-of` and the value that should be provided is an email address. When the `karmacheck-on-behalf-of` header contains an email address, the server will validate the email address provided, and if valid, the user associated with the email address will be recorded in the KarmaCheck system as the user that created the associated case. When validating the email address that is provided for this header: - if there is no user in the KarmaCheck system, then the value will simply be ignored and the case creation will be attributed to the authenticated API token itself. - if there is a user in the KarmaCheck system associated with the email address, but that user does not have the proper access to create a case for the package (or is not a user that is directly associated with the calling company) that is being requested then the API call will fail with a result that indicates that the user is not authorized to make that call. This error will occur even though the API token itself may be allowed to make the call but, because of the conflict, the call will be rejected. ### Restrictions The following restrictions exist when creating a case. Be sure to adhere to these restrictions when selecting a package or excluding services from the order (via `excludeServices`). #### Criminal and identity screening restrictions - SSN Trace is required when a County, State, or Federal Criminal Search is being ordered. - Cannot order Identity Verification and Identity And Liveliness Verification at the same time. - International Identity Verification cannot be ordered without other international screenings. - Must choose between US criminal screenings or international criminal screenings. - Must include International Identity Verification if Canadian Criminal Record Check or International Criminal Record Check is included. #### OHS and drug screening restrictions - Cannot order more than one type of TB test. - Cannot order DOT and non-DOT drug screenings in the same order. - Cannot order more than one non-DOT drug screening. - Only one urine drug screening can be selected for any order. - Cannot order both vaccine and titer for the same immunization type. This applies for each of the following immunization types: Varicella, Hepatitis A, Hepatitis B, and MMR. - OSHA Respirator/Fit to Wear Questionnaire is required when Respirator/Mask Fit Testing - Qualitative or Respirator/Mask Fit Testing - Quantitative is being ordered. - OHS and drug screenings are US-only and cannot be ordered with Canadian or international screenings. # Download legal doc for case data Source: https://developer.karmacheck.com/api-reference/cases/download-legal-doc-for-case-data /background-check-api/api-reference/openapi.json get /case/id/{caseId}/data/{serviceId}/pdf/download Downloads the PDF document for the legal service requested for a case. Legal checks are the various required authorizations collected from a candidate when they authorize a background check (e-signature, FCRA, and disclosures). # Download pre-adverse action document Source: https://developer.karmacheck.com/api-reference/cases/download-pre-adverse-action-document /background-check-api/api-reference/openapi.json get /case/id/{caseId}/preadverse/{type}/pdf/download Downloads the PDF file for the pre-adverse action notice or the case report that was active at the time of the pre-adverse action. # Find jurisdictions Source: https://developer.karmacheck.com/api-reference/cases/find-jurisdictions /background-check-api/api-reference/openapi.json post /jurisdiction/find/all Retrieves a list of relevant county and federal district jurisdictions based on a set of city/county/state combinations. This list is needed when ordering a case, as it ensures that the case is ordered with the correct list of jurisdictions. # Get active cases Source: https://developer.karmacheck.com/api-reference/cases/get-active-cases /background-check-api/api-reference/openapi.json get /case/list Retrieves all active cases for the `groupProfileId` on the token used. The response includes summary-level information with IDs for accessing details using other endpoints. The cases are listed in descending order by `crStamp`. If any `crStamp` values are identical, the cases are then sorted by `caseStatusId`, followed by `caseSecondaryStatusId`. # Get all cases Source: https://developer.karmacheck.com/api-reference/cases/get-all-cases /background-check-api/api-reference/openapi.json get /case/list/all Retrieves all cases (both active and archived) for the `groupProfileId` on the token used. The response includes summary-level information with IDs for accessing details using other endpoints. The cases are listed in descending order by `crStamp`. If any `crStamp` values are identical, the cases are then sorted by `caseStatusId`, followed by `caseSecondaryStatusId`. # Get all services for case Source: https://developer.karmacheck.com/api-reference/cases/get-all-services-for-case /background-check-api/api-reference/openapi.json get /case/id/{caseId}/services Retrieves a list of all services ordered for a case. # Get candidate info for case Source: https://developer.karmacheck.com/api-reference/cases/get-candidate-info-for-case /background-check-api/api-reference/openapi.json get /candidate/info/case/id/{caseId} Retrieves information about the candidate associated with the case. # Get case Source: https://developer.karmacheck.com/api-reference/cases/get-case /background-check-api/api-reference/openapi.json get /case/id/{caseId} Retrieves the details of a case by its ID. The response includes summary-level information with IDs for accessing details using other endpoints. # Get case configuration Source: https://developer.karmacheck.com/api-reference/cases/get-case-configuration /background-check-api/api-reference/openapi.json get /config/case/id/{caseId} Returns the service configurations and contact information for a case. For information on how to create or update configuration options for a case, see [Create case](paths/~1case~1create/post) or [Add to order](paths/~1case~1id~1{caseId}~1add~1services/post). # Get case data by case ID Source: https://developer.karmacheck.com/api-reference/cases/get-case-data-by-case-id /background-check-api/api-reference/openapi.json get /case/id/{caseId}/data/{serviceTypeId} Gets the details associated with services ordered and processed for a case. # Get custom report download URL Source: https://developer.karmacheck.com/api-reference/cases/get-custom-report-download-url /background-check-api/api-reference/openapi.json post /case/id/{caseId}/report/pdf/download/url Returns a URL to download a PDF report for one or more case screenings (in other words, case data). # Get full report download URL Source: https://developer.karmacheck.com/api-reference/cases/get-full-report-download-url /background-check-api/api-reference/openapi.json get /case/id/{caseId}/report/pdf/download/url Returns a URL to download a PDF report for the entire case and available attachments. # Get legal doc for case data Source: https://developer.karmacheck.com/api-reference/cases/get-legal-doc-for-case-data /background-check-api/api-reference/openapi.json get /case/id/{caseId}/data/{serviceId}/pdf Returns inline the PDF document for the legal service requested for a case. Legal checks are the various required authorizations collected from a candidate when they authorize a background check (e-signature, FCRA, and disclosures). # Get pre-adverse action document Source: https://developer.karmacheck.com/api-reference/cases/get-pre-adverse-action-document /background-check-api/api-reference/openapi.json get /case/id/{caseId}/preadverse/{type}/pdf Returns inline the PDF file for the pre-adverse action notice or the case report that was active at the time of the pre-adverse action. # Get services for case Source: https://developer.karmacheck.com/api-reference/cases/get-services-for-case /background-check-api/api-reference/openapi.json get /case/id/{caseId}/services/{serviceType} Retrieves a list of services ordered for a case. The list includes services of only one of the following types: - **`idv`:** Identity verification services ordered for the case. - **`legal`:** Legal checks ordered for the case. Legal checks are the various required authorizations collected from a candidate when they authorize a background check (e-signature, FCRA, and disclosures). - **`payment`:** Payment services ordered for the case. - **`screenings`:** Screenings ordered for the case. - **`shipment`:** Shipments ordered for the case. # Place case Source: https://developer.karmacheck.com/api-reference/cases/place-case /background-check-api/api-reference/openapi.json put /case/id/{caseId}/action/place Sets the status of a case to Placed in the system. Internally, the API sets the case's status to `Adjudicated` and its result to `Placed`. The secondary status, if any, gets reset. # Pre-adverse action for case Source: https://developer.karmacheck.com/api-reference/cases/pre-adverse-action-for-case /background-check-api/api-reference/openapi.json post /case/id/{caseId}/action/preadverse Begins the adverse action process for a case by putting the case into the Pre-Adverse Action status. This also sends a pre-adverse action notice to the candidate by email, which can also be downloaded from both the customer and candidate dashboards. # Unarchive case Source: https://developer.karmacheck.com/api-reference/cases/unarchive-case /background-check-api/api-reference/openapi.json post /case/unarchive/{caseId} Unarchives a case so that it reappears in the KarmaCheck dashboard. This operation reverses a previous archive operation on the case. # Get all enabled services for package Source: https://developer.karmacheck.com/api-reference/packages/get-all-enabled-services-for-package /background-check-api/api-reference/openapi.json get /package/id/{packageId}/services Retrieves a list of all enabled services for a package. # Get package Source: https://developer.karmacheck.com/api-reference/packages/get-package /background-check-api/api-reference/openapi.json get /package/min/id/{packageId} Retrieves the identifier and the name of a specific package. # Get package list Source: https://developer.karmacheck.com/api-reference/packages/get-package-list /background-check-api/api-reference/openapi.json get /package/min/list Retrieves a list of enabled packages for the user to order new reports/cases. This list includes the identifier and the name of each package, sorted alphabetically by name. # Get services for package Source: https://developer.karmacheck.com/api-reference/packages/get-services-for-package /background-check-api/api-reference/openapi.json get /package/id/{packageId}/services/{serviceType} Retrieves a list of enabled services for a package. The list includes services of only one of the following types: - **`idv`:** Identity verification services in the package. - **`legal`:** Legal checks in the package. Legal checks are the various required authorizations collected from a candidate when they authorize a background check (e-signature, FCRA, and disclosures). - **`payment`:** Payment services in the package. - **`screenings`:** Screenings in the package. # Create secure document records Source: https://developer.karmacheck.com/api-reference/secure-documents/create-secure-document-records /background-check-api/api-reference/openapi.json post /document/secure/create Creates secure document records in the KarmaCheck system and associates uploaded documents with an existing case. This is step 3 of 3 when adding documents to KarmaCheck. At this stage, you should have successfully uploaded your documents via the URLs obtained from the [Generate secure document upload URLs](paths/~1document~1secure~1upload/post) API call. The uploaded documents are unavailable for use in KarmaCheck until they are associated with a case in this third step. Document associations are identified by sending access grants. If your token does not have access to associate a document with a specific entity, a 403 Forbidden response will be returned. In addition to associating a document with an existing case, you can call this API to create candidate disclosure and authorization document records before a case is created. When [creating a case](paths/~1case~1create/post), you can send the newly created document IDs to associate these documents with the case and the candidate. Note that this association is allowed only when the document type is a candidate disclosure or authorization. # Generate secure document upload URLs Source: https://developer.karmacheck.com/api-reference/secure-documents/generate-secure-document-upload-urls /background-check-api/api-reference/openapi.json post /document/secure/upload Generates short-lived URLs that can be used to upload one or more secure documents to the KarmaCheck system. This API call is step 1 of 3 when adding a document to the system and linking it to a case. The returned URLs expire after 1 hour. If an attempt to use an expired URL occurs, the server responds with a 403 HTTP status code. # Get secure document download URL Source: https://developer.karmacheck.com/api-reference/secure-documents/get-secure-document-download-url /background-check-api/api-reference/openapi.json get /document/secure/id/{secureDocumentId}/download/url Gets a URL from KarmaCheck, which can then be used to download a secure document. The URL will be valid for only 60 minutes, but once the download begins, the download can take as long as needed. The URL can also be reused as many times as needed during the 60-minute validity period. # Get secure document list Source: https://developer.karmacheck.com/api-reference/secure-documents/get-secure-document-list /background-check-api/api-reference/openapi.json get /document/secure/list/case/id/{caseId} Returns a list of the secure documents associated with a case. # Get secure document MIME types Source: https://developer.karmacheck.com/api-reference/secure-documents/get-secure-document-mime-types /background-check-api/api-reference/openapi.json get /document/secure/mimetypes Gets acceptable MIME types for secure documents. # Get secure document type list Source: https://developer.karmacheck.com/api-reference/secure-documents/get-secure-document-type-list /background-check-api/api-reference/openapi.json get /document/secure/type/list Returns a list of objects representing all secure document types in KarmaCheck. Among other uses, it enables population of the supported document types in a list that users can select from and associate with the document that they are uploading. # Get all CPLCs Source: https://developer.karmacheck.com/api-reference/services/get-all-cplcs /background-check-api/api-reference/openapi.json get /service/cplc/list/all Retrieves the list of all professional licenses and certifications, including ones that are disabled for verification. # Get CPLC full definition Source: https://developer.karmacheck.com/api-reference/services/get-cplc-full-definition /background-check-api/api-reference/openapi.json get /service/cplc/id/{cplcId} Returns an object describing a specific professional license or certification. # Get CPLC full definitions for case Source: https://developer.karmacheck.com/api-reference/services/get-cplc-full-definitions-for-case /background-check-api/api-reference/openapi.json get /service/cplc/case/id/{caseId} Retrieves a list of definitions for all the professional licenses and certifications that were provided to a case as testimony. This is used when rendering Professional License and Certification testimony by associating the testimony data with the definition. # Get CPLCs Source: https://developer.karmacheck.com/api-reference/services/get-cplcs /background-check-api/api-reference/openapi.json get /service/cplc/list Retrieves the list of supported professional licenses and certifications that are enabled for verification. # Get mask list Source: https://developer.karmacheck.com/api-reference/services/get-mask-list /background-check-api/api-reference/openapi.json get /shipment/mask/list Retrieves a list of masks for the user to order new shipment. # Get users by group profile Source: https://developer.karmacheck.com/api-reference/users/get-users-by-group-profile /background-check-api/api-reference/openapi.json get /company/user/list Gets the users for every group within the company that the authenticated user belongs to. If the `groupProfileId` query parameter is included, the endpoint retrieves users associated with only the specified group. # Search Verification Book Source: https://developer.karmacheck.com/api-reference/verification-book/search-verification-book /background-check-api/api-reference/openapi.json post /vbook/search Search for Verification Book entries. Results will be returned by matching against the name and aliases of book items. # Candidate-provided PII flow Source: https://developer.karmacheck.com/background-check-api/guides/candidate-provided-pii-flow Step-by-step guide for ordering a background check using the candidate-provided PII flow. This guide will help you get started with the KarmaCheck API by walking you through a typical workflow for a background check. With this workflow, a background check on a candidate begins running after the candidate provides their personally identifiable information (PII) and authorizes the background check. By the end of this guide, you'll know how to: 1. Authenticate with KarmaCheck. 2. Order a background check report by sending an onboarding invitation to a candidate. 3. Get updates about the ordered background check (also known as a *case*). 4. Generate a PDF report of the background check. ## Before you begin * Ensure that you have the following sandbox credentials to gain access to the KarmaCheck API: * An API key * A client access token The method for obtaining these credentials varies depending on whether you're a [customer](/background-check-api/overview/customer-integration) or a [partner](/background-check-api/overview/partner-integration). * Email invites to candidates get sent to the KarmaCheck sandbox account instead of the email address that you enter for a candidate. If you want to run through the entire workflow in this guide, you'll need the email invite to enter PII as a candidate. To receive these emails, [contact KarmaCheck](mailto:customersuccess@karmacheck.com) to set up email forwarding. ## Step 1: Authenticate with KarmaCheck Call the authentication endpoint to retrieve an authentication token. Replace `API_KEY` and `CLIENT_ACCESS_TOKEN` with your credentials: ```bash theme={null} curl --request POST \ --url https://api-stage.karmacheck.io/auth/api \ --header 'Content-Type: application/json' \ --data '{ "apiKey": "API_KEY", "clientAccessToken": "CLIENT_ACCESS_TOKEN" }' ``` The response body displays your authentication token in the `token` field. ## Step 2: Order a report With an authentication token, you can now make API calls to order a background check for a specific group. ### Step 2a: Get available packages Call the `GET /package/min/list` endpoint to get a list of packages available for background checks: ```bash theme={null} curl --request GET \ --url https://api-stage.karmacheck.io/package/min/list \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer AUTHENTICATION_TOKEN' ``` The response body displays a list of packages with the unique ID of each package in an `id` field. Find the package with the name `Basic Test Package` and note its ID. This package consists of services that support simulated results, enabling you to test the full workflow from start to finish. To learn more about screenings that support simulated results, see [Simulated services](/background-check-api/overview/api/environments#simulated-services). ### Step 2b: Create a case Call the `POST /case/create` endpoint to order a background check on a candidate. Replace all placeholder values: * **`AUTHENTICATION_TOKEN`:** Your authentication token * **`PACKAGE_ID`:** The ID of the package retrieved in the previous step * **`POSTBACK_URL`:** The URL for receiving webhook event notifications when the status of the case changes. Remove the `postbackUrl` field if you don't want to test webhooks. * **`EMAIL`:** The candidate's email address * **`GIVEN_NAME`:** The candidate's first name * **`FAMILY_NAME`:** The candidate's last name The `postbackUrl` property is for *testing purposes only* and supports only [case status change](/background-check-api/reference/webhooks/events/case-status-change) events. To configure webhooks for your production environment, or to test all available webhook events, you must contact KarmaCheck to subscribe to webhook events. ```bash theme={null} curl --request POST \ --url https://api-stage.karmacheck.io/case/create \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer AUTHENTICATION_TOKEN' \ --data '{ "packageId": "PACKAGE_ID", "postbackUrl": "POSTBACK_URL", "email": "EMAIL", "givenName": "GIVEN_NAME", "familyName": "FAMILY_NAME" }' ``` Note the ID of the ordered background check in the `caseId` field returned by the endpoint. You'll need this value in subsequent API calls. ## Step 3: Complete candidate onboarding To begin processing the background check, you need to complete the following steps as a candidate: 1. Access the email invitation forwarded to you, and click **Get Started Now** to begin the KarmaCheck candidate onboarding process. 2. Follow the prompts to provide candidate data and authorize the background check. Enter **111-22-3333** as the candidate's Social Security number. ## Step 4: (Optional) Receive status updates If you provided a webhook URL to receive case status updates, a POST request is sent to the webhook endpoint any time the status of the case changes. The following is an example of a webhook payload: ```json theme={null} { "messageId": "e123e0d6-12fc-d45b-abc1-dddd5cd2a028", "event": "case.statuschange", "apiTrackingCode": null, "apiTrackingUser": null, "username": null, "password": null, "eventObject": { "id": "d1234567-1234-1d23-b12b-5582d748c7c6", "crStamp": "2024-06-20T23:07:16.000Z", "crUserId": "abc29350-12f3-4d85-9df1-9a73f14d9d17", "caseTypeId": "cde61186-4f22-45f4-9e19-429061365bce", "caseType": "Background Check", "caseStatusId": "d894b8a0-937e-46b1-8799-15bad611844f", "caseStatus": "Pending", "secondaryCaseStatusId": "8e0c9756-a42f-4a7d-b8e2-412a0f6b9dea", "secondaryStatus": "Waiting for Authorization", "resultType": "Open", "modStamp": "2024-06-20T23:07:16.000Z", "candidateId": null, "candidateEmail": null, "candidateGivenName": null, "candidateFamilyName": null, "packageId": "d04dece1-1ea5-43fc-2832-231a5d23a08b", "packageName": "Basic Test Package", "packageCompanyName": null, "billingReferenceId": "d04dece1-1ea5-43fc-2832-231a5d23a08b", "groupProfileId": "fd0546e4-ac27-4c96-bb22-06ae7e372fd2", "resultTypeId": "8c94f0d9-57c9-4c7b-be95-5ec309cff330", "caseInvitationId": "d1234a8a-dd12-1e3d-98e6-5ff7eb9f7f0a", "invitationStatusId": "3f5e6898-6641-4685-8ee0-1363b7e10c98", "invitationStatusName": "pending", "invitationGivenName": "Kim", "invitationFamilyName": "Smith", "companyId": "dde1eafd-232b-39e8-dff4-f1be061eba2c", "companyName": "Example Company", "companyCommonName": null, "companyLogo": null, "archived": 0, "serviceGroupId": "b3582ef5-72b7-4e48-9973-858464f01141", "invitationEmail": "kim.smith@example.com", "isMinorCandidate": 0, "hasParentalConsent": 0, "groupName": "Default", "adverseActionId": null, "adverseActionStatusName": null, "adverseActionStatusId": null, "orderedStamp": "2024-06-20T23:07:16.000Z", "beginOnboardingStamp": null, "completedOnboardingStamp": null, "beginProcessingStamp": null, "completedInitialProcessingStamp": null, "completedLatestProcessingStamp": null } } ``` Your webhook endpoint should respond with an HTTP status code of 2\_xx\_ to indicate that the call was processed successfully. If a response status other than a 2\_xx\_ is received, KarmaCheck will attempt to resend the webhook after a delay. See the [webhooks overview](/background-check-api/reference/webhooks/webhooks-overview) for more details on webhooks and how to handle events. If you don't have your webhook set up, send a GET request to the `GET /case/id/{caseId}` endpoint to retrieve the details of your case. ## Step 5: Get report results After the case is complete, call the `GET /case/id/{caseId}/report/pdf/download/url` endpoint to get a PDF of the report. Replace `CASE_ID` with the ID from Step 2b and `AUTHENTICATION_TOKEN` with your token: ```bash theme={null} curl --request GET \ --url https://api-stage.karmacheck.io/case/id/CASE_ID/report/pdf/download/url \ --header 'Accept: text/html' \ --header 'Authorization: Bearer AUTHENTICATION_TOKEN' ``` A successful request returns the URL at which you can view and download the report. Congratulations! You've now run an end-to-end workflow using the KarmaCheck API. # Customer-provided PII flow Source: https://developer.karmacheck.com/background-check-api/guides/customer-provided-pii-flow Step-by-step guide for ordering a background check by providing the candidate's PII directly. This tutorial will help you get started with the KarmaCheck API by walking you through a typical workflow for a background check. With this workflow, a background check on a candidate begins running after you order the background check. By the end of this tutorial, you'll know how to: 1. Authenticate with KarmaCheck. 2. Order a background check report by providing a candidate's personally identifiable information (PII). 3. Get updates about the ordered background check (also known as a *case*). ## Before you begin * Ensure that you have the following sandbox credentials to gain access to the KarmaCheck API: * An API key * A client access token The method for obtaining these credentials varies depending on whether you're a [customer](/background-check-api/overview/customer-integration) or a [partner](/background-check-api/overview/partner-integration). * Email notifications to candidates get sent to the KarmaCheck sandbox account instead of the email address that you enter for a candidate. If you want to receive these emails, [contact KarmaCheck](mailto:customersuccess@karmacheck.com) to set up email forwarding. ## Step 1: Authenticate with KarmaCheck Call the authentication endpoint to retrieve an authentication token. Replace `API_KEY` and `CLIENT_ACCESS_TOKEN` with your credentials: ```bash theme={null} curl --request POST \ --url https://api-stage.karmacheck.io/auth/api \ --header 'Content-Type: application/json' \ --data '{ "apiKey": "API_KEY", "clientAccessToken": "CLIENT_ACCESS_TOKEN" }' ``` The response body displays your authentication token in the `token` field. ## Step 2: Order a report With an authentication token, you can now make API calls to order a background check for a specific group. ### Step 2a: Get available packages Call the `GET /package/min/list` endpoint to get a list of packages available for background checks: ```bash theme={null} curl --request GET \ --url https://api-stage.karmacheck.io/package/min/list \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer AUTHENTICATION_TOKEN' ``` The response body displays a list of packages with the unique ID of each package in an `id` field. Find the package with the name `Advanced Test Package` and note its ID. ### Step 2b: Get services in the package Call the `GET /package/id/{packageId}/services` endpoint to retrieve the list of services included in the Advanced Test Package: ```bash theme={null} curl --request GET \ --url https://api-stage.karmacheck.io/package/id/PACKAGE_ID/services \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer AUTHENTICATION_TOKEN' ``` A successful request returns a list of services with the unique ID of each service in a `serviceId` field. Note the IDs of the services named `Federal Criminal Search` and `Employment Verification` — you'll need these when ordering the background check. ### Step 2c: Find jurisdictions The Advanced Test Package includes the Federal Criminal Search (District) service, so you need to find the correct federal district jurisdictions. Call the `POST /jurisdiction/find/all` endpoint: ```bash theme={null} curl --request POST \ --url https://api-stage.karmacheck.io/jurisdiction/find/all \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer AUTHENTICATION_TOKEN' \ --data '{ "counties": [ { "city": "Brooklyn", "county": "Kings", "state": "NY" }, { "city": "Manhattan", "county": "New York", "state": "NY" } ] }' ``` A successful request returns a list of jurisdictions. Note the names of jurisdictions with `federal-district` as the jurisdiction type — you'll need these when ordering the background check. ### Step 2d: Create a case Call the `POST /case/create` endpoint to order a background check. The request below includes the minimally required data plus jurisdiction and employment order data for the Advanced Test Package: The `postbackUrl` property is for *testing purposes only* and supports only [case status change](/background-check-api/reference/webhooks/events/case-status-change) events. To configure webhooks for your production environment, or to test all available webhook events, you must contact KarmaCheck to subscribe to webhook events. ```bash theme={null} curl --request POST \ --url https://api-stage.karmacheck.io/case/create \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer AUTHENTICATION_TOKEN' \ --data '{ "packageId": "PACKAGE_ID", "email": "EMAIL", "givenName": "GIVEN_NAME", "familyName": "FAMILY_NAME", "postbackUrl": "POSTBACK_URL", "autoProcess": true, "candidateConsentProvided": true, "orderData": [ { "caseOrderDataTypeId": "codt-govt-id", "metadata": { "govtId": "111-22-3333" } }, { "caseOrderDataTypeId": "codt-dob", "metadata": { "dob": "1985-05-15" } }, { "caseOrderDataTypeId": "codt-current-candidate-address", "metadata": { "address1": "1 Main Street", "address2": "Unit 179", "city": "Brooklyn", "state": "NY", "postalCode": "11201", "country": "US" } }, { "caseOrderDataTypeId": "codt-address", "metadata": { "city": "Brooklyn", "county": "Kings", "state": "NY", "autoProcessJurisdictions": false } }, { "caseOrderDataTypeId": "codt-address", "metadata": { "city": "Manhattan", "county": "New York", "state": "NY", "autoProcessJurisdictions": false } }, { "caseOrderDataTypeId": "codt-jurisdiction-fed-district", "serviceId": "FEDERAL_CRIMINAL_SEARCH_ID", "metadata": { "district": "New York Eastern District Court" } }, { "caseOrderDataTypeId": "codt-jurisdiction-fed-district", "serviceId": "FEDERAL_CRIMINAL_SEARCH_ID", "metadata": { "district": "New York Southern District Court" } }, { "caseOrderDataTypeId": "codt-employment", "serviceId": "EMPLOYMENT_VERIFICATION_ID", "metadata": { "employer": "Example Organization", "position": "Nurse", "city": "Brooklyn", "state": "NY", "country": "US", "monthBegin": "November", "yearBegin": "2004", "current": false, "monthEnd": "November", "yearEnd": "2018", "contact": { "website": "www.example.com", "email": "hr@example.com", "phone": "800-555-0167" }, "okToContact": true } }, { "caseOrderDataTypeId": "codt-employment", "serviceId": "EMPLOYMENT_VERIFICATION_ID", "metadata": { "employer": "Example Organization 2", "position": "Nurse", "city": "Manhattan", "state": "NY", "country": "US", "monthBegin": "November", "yearBegin": "2018", "current": true, "contact": { "website": "www.example.com", "email": "admin@example.com", "phone": "800-555-0172" }, "okToContact": true } } ] }' ``` Replace `FEDERAL_CRIMINAL_SEARCH_ID` and `EMPLOYMENT_VERIFICATION_ID` with the service IDs retrieved in Step 2b. A successful request returns the ID of the ordered background check in the `caseId` field. Congratulations! You've initiated a background check using the KarmaCheck API. For a full explanation of the `orderData` array and all supported types, see [Provide order data](/background-check-api/guides/order-data). ## Step 3: (Optional) Receive status updates If you provided a webhook URL to receive case status updates, a POST request is sent to the webhook endpoint any time the status of the case changes. The following is an example of a webhook payload: ```json theme={null} { "messageId": "e123e0d8-22dd-d45b-abc1-dddd5cd2a028", "event": "case.statuschange", "apiTrackingCode": null, "apiTrackingUser": null, "username": null, "password": null, "eventObject": { "id": "12345678-2e75-4ba7-abcde-06741f65df3e", "crStamp": "2024-06-20T23:16:14.000Z", "caseStatus": "Pending", "secondaryCaseStatusId": null, "secondaryStatus": null, "resultType": "Open", "candidateEmail": "john.smith@example.com", "candidateGivenName": "John", "candidateFamilyName": "Smith", "packageName": "Advanced Test Package", "groupName": "Default", "orderedStamp": "2024-06-20T23:16:14.000Z", "completedOnboardingStamp": "2024-06-20T23:16:15.000Z", "beginProcessingStamp": "2024-06-20T23:16:16.000Z" } } ``` Your webhook endpoint should respond with an HTTP status code of 2*xx* to indicate that the call was processed successfully. If a response status other than a 2*xx* is received, KarmaCheck will attempt to resend the webhook after a delay. See the [webhooks overview](/background-check-api/reference/webhooks/webhooks-overview) for more details on webhooks and how to handle events. If you don't have your webhook set up, send a GET request to the `GET /case/id/{caseId}` endpoint to retrieve the details of your case. # Document processing flow Source: https://developer.karmacheck.com/background-check-api/guides/document-processing-flow Walk through a complete document processing order: upload documents, create an order, retrieve results, and handle webhook updates. This guide walks you through a typical workflow for a document processing order. With this workflow, document processing begins running after you upload documents to the KarmaCheck system and create the order. By the end of this guide, you'll know how to: 1. Authenticate with KarmaCheck. 2. Upload documents and create a secure document record for each one. 3. Order document processing by providing the candidate's name, email, and order data with the secure document record IDs. 4. Retrieve document processing results and receive status updates. ## Before you begin Ensure that you have the following sandbox credentials: * An API key * A client access token How you obtain these credentials depends on whether you're a [customer](/background-check-api/overview/customer-integration) or a [partner](/background-check-api/overview/partner-integration). ## Step 1: Authenticate with KarmaCheck Call `POST /auth/api` to retrieve an authentication token. Replace `API_KEY` and `CLIENT_ACCESS_TOKEN` with your credentials: ```bash theme={null} curl -X POST https://api-stage.karmacheck.io/auth/api \ -H "Content-Type: application/json" \ -d '{ "apiKey": "API_KEY", "clientAccessToken": "CLIENT_ACCESS_TOKEN" }' ``` The response body contains your authentication token in the `token` field. Use this as `Bearer AUTHENTICATION_TOKEN` in all subsequent requests. ## Step 2: Order document processing ### Step 2a: Upload your documents to KarmaCheck This step references the full [Upload documents](/background-check-api/guides/upload-documents) guide. The key flow is: 1. **Request upload URLs** — Call `POST /document/secure/upload` to generate a secure, time-limited upload URL and `fileKey` for each document. 2. **Upload documents** — Upload each file directly to the returned URL using an HTTP `PUT` request with the correct `Content-Type`. 3. **Create secure document records** — Call `POST /document/secure/create` with the `fileKey`, `documentTypeId`, and `originalFileName`. At this point you will not yet have a `caseId`. When no order exists yet, **omit the `accessGrants` object** from the request. 4. **Note the `secureDocumentId`** returned for each document — you'll pass these when creating the order. For request examples, supported MIME types, and error handling, see [Upload documents](/background-check-api/guides/upload-documents). ### Step 2b: Get available packages Call `GET /package/min/list` to get a list of available packages: ```bash theme={null} curl https://api-stage.karmacheck.io/package/min/list \ -H "Authorization: Bearer AUTHENTICATION_TOKEN" ``` Find the package named **Intelligent Document Processing** and note its `id`. ### Step 2c: Get services in the package Call `GET /package/id/{packageId}/services` to retrieve the services included in the package: ```bash theme={null} curl https://api-stage.karmacheck.io/package/id/PACKAGE_ID/services \ -H "Authorization: Bearer AUTHENTICATION_TOKEN" ``` Note the `serviceId` of the **Document Processing** service (`service-intelligent-document-process`). You'll need this when providing order data. ### Step 2d: Create a document processing order Call `POST /case/create` to order document processing. Because a document processing order is not a background-check screening, no candidate PII order data is required — the package ID and the candidate's name and email in the request body are sufficient. The `orderData` array only needs one `codt-idp` entry per document: ```bash theme={null} curl -X POST https://api-stage.karmacheck.io/case/create \ -H "Content-Type: application/json" \ -H "Authorization: Bearer AUTHENTICATION_TOKEN" \ -d '{ "packageId": "PACKAGE_ID", "email": "candidate@example.com", "givenName": "Jane", "familyName": "Smith", "postbackUrl": "POSTBACK_URL", "autoProcess": true, "candidateConsentProvided": true, "disableOptions": 7, "orderData": [ { "caseOrderDataTypeId": "codt-idp", "serviceId": "service-intelligent-document-process", "metadata": { "documentTypeId": "unclassified", "fileName": "testfile1.pdf", "secureDocumentId": "SECURE_DOCUMENT_ID_1" } }, { "caseOrderDataTypeId": "codt-idp", "serviceId": "service-intelligent-document-process", "metadata": { "documentTypeId": "unclassified", "fileName": "testfile2.pdf", "secureDocumentId": "SECURE_DOCUMENT_ID_2" } } ] }' ``` **`orderData` fields:** | Field | Description | | - | - | | `codt-idp` / `documentTypeId` | Document type. Always use `unclassified` for Document Processing. | | `codt-idp` / `fileName` | The file name as provided when uploading the document. | | `codt-idp` / `secureDocumentId` | The ID returned after creating the secure document record. | | `codt-govt-id` / `govtId` | Optional. Candidate's SSN in `xxx-xx-xxxx` format. Use `111-22-3333` for sandbox testing. | | `codt-dob` / `dob` | Optional. Candidate's date of birth in `yyyy-mm-dd` format. | | `codt-current-candidate-address` | Optional. Candidate's current address (`address1`, `city`, `state`, `postalCode`, `country`). | Candidate PII order data such as `codt-govt-id`, `codt-dob`, and `codt-current-candidate-address` is not required when the order contains only the Document Processing service and can be omitted. Set `disableOptions` to `7` to suppress KarmaCheck's candidate and customer notification emails for a document processing order. Because document processing is not a background-check screening, candidates should not receive the standard screening invitation or status-update emails. `disableOptions` is a bitmask that combines candidate invitation (`1`), candidate status updates (`2`), and customer notifications (`4`); a value of `7` disables all three. Omit the field or set it to `0` to keep notifications enabled. `postbackUrl` is for testing purposes only and supports only `case.statuschange` events. To configure webhooks for production, contact KarmaCheck to subscribe to webhook events. A successful response returns the `caseId` of the order. Note this value — you'll use it to retrieve results. ## Step 3: Retrieve document processing results Call `GET /case/id/{caseId}/data/{serviceTypeId}` using `service-type-document-processing` as the `serviceTypeId`: ```bash theme={null} curl https://api-stage.karmacheck.io/case/id/CASE_ID/data/service-type-document-processing \ -H "Authorization: Bearer AUTHENTICATION_TOKEN" ``` The response returns a list of case data objects — one per document ordered. Key response fields: | Field | Description | | - | - | | `status` / `statusDisplayName` | Current processing status (e.g. `complete`). | | `detailsObject.documentTypeId` | The document type IDP classified the document as. See [IDP document type](/background-check-api/reference/idp-document-type) for all possible values. | | `detailsObject.classificationData` | Document classification results including `type` (see [IDP document type](/background-check-api/reference/idp-document-type)) and `confidence` score. | | `detailsObject.value` | Extracted data keyed by field name (e.g. `issueDate`, `dateOfBirth`). | | `detailsObject.metadata` | OCR confidence scores and citation polygons for each extracted field. | **Example response:** ```json theme={null} { "data": [ { "id": "1777e943-7feb-42a9-aa35-2b73f781e4a8", "caseId": "8558c68f-5d39-4867-af25-57abeb047c5c", "serviceId": "service-intelligent-document-process", "serviceName": "Document Processing", "statusId": "case-data-status-complete", "status": "complete", "statusDisplayName": "Complete", "detailsObject": { "fileName": "US_PASSPORT-example.pdf", "documentTypeId": "us-passport", "secureDocumentId": "d17e3813-94e1-4717-8d92-df5e935af005", "documentExpirationDate": "2032-08-24 00:00:00", "classificationData": { "id": "classification_usC", "type": "us-passport", "confidence": 1 }, "value": { "issueDate": "2022-08-27", "dateOfBirth": "1990-09-25", "candidateName": "Avery Ellis", "expirationDate": "2032-08-24" } } } ] } ``` ## Step 4: Receive status updates (optional) If you provided a `postbackUrl` when creating the order, KarmaCheck sends a `POST` request to that URL whenever the order status changes. Example webhook payload: ```json theme={null} { "messageId": "e123e0d8-22dd-d45b-abc1-dddd5cd2a028", "event": "case.statuschange", "apiTrackingCode": null, "apiTrackingUser": null, "username": null, "password": null, "eventObject": { "id": "12345678-2e75-4ba7-abcde-06741f65df3e", "caseStatus": "Pending", "secondaryStatus": null, "resultType": "Open", "candidateEmail": "jane.smith@example.com", "candidateGivenName": "Jane", "candidateFamilyName": "Smith", "packageName": "Intelligent Document Processing" } } ``` Respond with an HTTP `2xx` status to confirm receipt. If KarmaCheck does not receive a `2xx` response, it will retry the delivery after a delay. See the [webhooks overview](/background-check-api/reference/webhooks/webhooks-overview) for more details. If you don't have a webhook set up, poll `GET /case/id/{caseId}` to retrieve the current status of the order. # Getting started with MCP Source: https://developer.karmacheck.com/background-check-api/guides/mcp-get-started-guide How to configure and use KarmaCheck's MCP server with Claude Desktop and Cursor. Get started with KarmaCheck's MCP server using this guide — it covers prerequisites, authenticating the MCP server, configuring Claude Desktop and Cursor, trying starter prompts (including test SSNs), and the path to production. If anything's unclear or you need a hand, reach out to us at [mcp@karmacheck.com](mailto:mcp@karmacheck.com). ## Setup prerequisites ### Authenticating the MCP server See the [authentication page](/background-check-api/overview/api/authentication) for details on how to retrieve the authentication token for KarmaCheck's MCP server. The JWT token generated using the combination of your API key and client secret will be used to authenticate your connection to the MCP server. The subsequent steps will show you how this authentication token is used. ## Get setup on Claude Desktop ### Prerequisites You will need to install the following dependencies before progressing with this section: * Claude Desktop * Node.js Version 22+ ### Steps to setup the KarmaCheck MCP server 1. Open Claude Desktop — the free tier should work for this guide, though you may experience some rate limiting. 2. Go to **Settings → Developer → Edit Config**. 3. Insert the following into the `claude_desktop_config.json`. Replace `` with your JWT token (see the [authentication](#authenticating-the-mcp-server) section for details): ```json theme={null} { "mcpServers": { "karmacheck-dev": { "command": "npx", "args": [ "-y", "mcp-remote", "https://mcp-stage.karmacheck.io", "--header", "Authorization:${AUTH_HEADER}" ], "env": { "AUTH_HEADER": "Bearer " } } } } ``` 4. Quit and restart Claude Desktop. 5. Get started using the [Starter prompts](#starter-prompts-for-using-karmacheck-via-mcp). ## Get setup on Cursor ### Prerequisites You will need to install the following dependencies before progressing with this section: * Cursor IDE * Node.js Version 22+ ### Steps to setup the KarmaCheck MCP server 1. Open Cursor. 2. Navigate to **Cursor → Settings → Cursor Settings**. 3. Click on **Tools & Integrations → Add Custom MCP**. 4. Insert the following into the `mcp.json` file. Replace `` with your JWT token: ```json theme={null} { "mcpServers": { "karmacheck-dev": { "command": "npx", "args": [ "-y", "mcp-remote", "https://mcp-stage.karmacheck.io", "--header", "Authorization:${AUTH_HEADER}" ], "env": { "AUTH_HEADER": "Bearer " } } } } ``` 5. You should see the KarmaCheck MCP server and the associated tools under the MCP Tools section within "Tools & Integrations". 6. Get started using the [Starter prompts](#starter-prompts-for-using-karmacheck-via-mcp). ## Starter prompts for using KarmaCheck via MCP ### Test emails & SSNs All order-specific emails in your sandbox account are automatically sent to the default email address on your account (the one you used to sign up). This includes any emails sent to test candidate addresses. In our system, email addresses act as the unique identifier for candidates, so each order must use a unique email address. A simple way to achieve this is by appending a date and timestamp to a test email, for example: `test+20250808T1530@test.com`. For testing purposes during onboarding: * Use SSN **111-22-3333** to generate all CLEAR/COMPLETE results. * Use SSN **333-22-1111** to generate NEEDS REVIEW results. * All other SSNs will be blocked in the sandbox environment. ### Create a case Creating a case requires the candidate's **First Name**, **Last Name**, and **Email Address**. If any of these details are missing, KarmaCheck will prompt you to provide them. **Example prompts:** ``` Verify the identity, motor vehicle records, and criminal background of Jane Doe (jane.doe@email.com), who is applying for a Senior Driving Instructor position, using KarmaCheck. ``` ``` Run a nationwide criminal background search on Jane Doe, whose email address is jane.doe@email.com, using KarmaCheck. ``` ``` Create a case for John Smith at john.smith@email.com and only run a Motor Vehicle Records check. ``` ``` Verify the identity, motor vehicle records, and criminal background for Emily Johnson (emily.johnson@email.com) applying as a Delivery Driver. ``` ``` Verify the criminal background of a candidate named Michael applying as a Chauffeur. ``` *KarmaCheck will prompt you to provide the last name and email to create the case.* ### Get the status of all cases in your dashboard **Example prompts:** ``` Provide a list of all candidate cases that require candidate action. ``` ``` Provide a list of all candidate cases that require candidate action. For each case, draft a personalized email prompting the candidate to complete the necessary steps to move their case forward. ``` ``` Show me all candidate cases where background checks are delayed due to missing candidate actions. ``` ``` List all candidate cases that are waiting on the candidate, and suggest the next actions to resolve each case. ``` ### Get details on a specific case When testing in the sandbox environment, make sure to complete the candidate onboarding process first. This will generate cases in various stages of completion, allowing you to fully test prompts and workflows. **Example prompts:** ``` What's going on with John Smith's case? ``` ``` Provide a detailed status update on Emily Johnson's case, including any pending actions or completed checks. ``` ``` Has the Motor Vehicle Records check been completed for Michael Lee's case? ``` ``` What is preventing Sarah Brown's case from moving forward, and what actions are required? ``` ``` Show me the timeline of all activities for David Wilson's case. ``` ### Monitoring use case You can monitor candidate records on a recurring basis to ensure compliance and up-to-date checks. Monitoring prompts can be **resource intensive**, so use them thoughtfully with a clear timeframe. **Example prompts:** ``` Run a Motor Vehicle Records (MVR) check on all candidates who have not had an MVR check in the past 7 days using KarmaCheck. ``` ``` Run a Motor Vehicle Records (MVR) check on all candidates who have not been checked in the last 30 days. ``` ``` Identify all candidates who have not had a Motor Vehicle Records check in the past 14 days and run new checks for them. ``` ``` List all candidates overdue for a Motor Vehicle Records check based on a 60-day cycle, and initiate new checks for each. ``` ## Ready for production? 1. **Request production access** — Join the [MCP production waitlist](https://contact.karmacheck.com/mcp-production-wl). You'll be the first to know when production MCP accounts become available. 2. **Credentialing & contracting** — Your organization will complete contracting and credentialing to ensure you're approved to run background checks in compliance with applicable regulations. 3. **Unlock full services** — Once approved, you'll gain access to the full suite of KarmaCheck screenings and services in production. Since background checks involve PII and, at times, PHI, we strongly recommend using enterprise-grade LLMs with secure tool-calling capabilities to ensure data protection and compliance. Examples include GPT-5 (ChatGPT Enterprise or Azure OpenAI), Anthropic Claude Opus/Sonnet (via Amazon Bedrock), Amazon Nova Pro/Lite, Cohere Command R+, and Google Gemini 1.5 Pro (via Vertex AI). # Provide order data Source: https://developer.karmacheck.com/background-check-api/guides/order-data Reference for all supported orderData types when creating a case or adding to an order. When you're creating a case using the customer-provided PII flow, or adding to an existing order, you'll need to provide the necessary candidate data. This data is sent in an `orderData` array of objects with the following properties: | Property | Type | Required | Description | | - | - | - | - | | `caseOrderDataTypeId` | `string` | `Required` | The type of candidate data to include in the order. See the [Case order data types](#case-order-data-types) table for the possible types. | | `serviceId` | `string` | — | The service for which the data is being provided. Required for certain case order data types. | | `metadata` | `object` | `Required` | The candidate data. The exact properties are specific to each case order data type. | The types of order data to include depend on the services that are being ordered. For a background check, at a minimum, the candidate's government ID, date of birth, and current address need to be included as order data for a case: ```json theme={null} { "orderData": [ { "caseOrderDataTypeId": "codt-govt-id", "metadata": { "govtId": "111-22-3333" } }, { "caseOrderDataTypeId": "codt-dob", "metadata": { "dob": "1983-05-17" } }, { "caseOrderDataTypeId": "codt-current-candidate-address", "metadata": { "address1": "100 Main St", "address2": "Unit 2", "city": "New York", "state": "NY", "postalCode": "10016", "country": "US" } } ] } ``` The following sections describe each supported type of order data. ## Case order data types | Case order data type | ID | Required? | | - | - | - | | **Government ID** | codt-govt-id | Yes, except when the order contains only the Document Processing service. See [Government ID](#government-id) for more details. | | **Date of birth** | codt-dob | Yes, except when the order contains only the Document Processing service. See [Date of birth](#date-of-birth) for more details. | | **Current candidate address** | codt-current-candidate-address | Yes, except when the order contains only the Document Processing service. See [Current candidate address](#current-candidate-address) for more details. | | **Health screening scheduling address** | codt-ohs-scheduling-address | Conditionally. See [Health screening scheduling address](#health-screening-scheduling-address) for services that require this type of order data. | | **Education records** | codt-education | Conditionally. See [Education](#education) for services that require this type of order data. | | **Employment records** | codt-employment | Conditionally. See [Employment](#employment) for services that require this type of order data. | | **Motor vehicle record (MVR)** | codt-mvr | Conditionally. See [Motor vehicle record](#motor-vehicle-record) for services that require this type of order data. | | **Alternative names for a candidate** | codt-alias | No. See [Aliases](#aliases) for services that support this type of order data. | | **Jurisdiction address** | codt-address | No. See [Jurisdictions](#jurisdictions) for services that support this type of order data. | | **County jurisdiction** | codt-jurisdiction-county | No. See [Jurisdictions](#jurisdictions) for services that support this type of order data. | | **Federal district jurisdiction** | codt-jurisdiction-fed-district | No. See [Jurisdictions](#jurisdictions) for services that support this type of order data. | | **State jurisdiction** | codt-jurisdiction-state | No. See [Jurisdictions](#jurisdictions) for services that support this type of order data. | | **Professional license and certification** | codt-cplc | Conditionally. See [Professional license and certification](#professional-license-and-certification) for services that require this type of order data. | | **Shipments** | codt-shipment | Conditionally. See [Shipments](#shipments) for services that require this type of order data. | | **Drug reason for test** | codt-drug-reason-for-test | No. See [Drug reason for test](#drug-reason-for-test) for services that support this type of order data. | | **Drug testing authority** | codt-drug-testing-authority | No. See [Drug testing authority](#drug-testing-authority) for services that support this type of order data. | ## Case order data structures Below are details and examples of each type of order data. ### Government ID The candidate's government ID is required in order data, unless the order contains only the Document Processing service. ```json theme={null} { "orderData": [ { "caseOrderDataTypeId": "codt-govt-id", "metadata": { "govtId": "111-22-333" } } ] } ``` **`metadata` properties:** `govtId` (string) — The candidate's Social Security number in the format *xxx*-*xx*-*xxxx*. For testing purposes, use **111-22-3333**. ### Date of birth The candidate's birthdate is required in order data, unless the order contains only the Document Processing service. ```json theme={null} { "orderData": [ { "caseOrderDataTypeId": "codt-dob", "metadata": { "dob": "1983-05-17" } } ] } ``` **`metadata` properties:** `dob` (string) — The candidate's birthdate in the format *yyyy*-*mm*-*dd*. ### Current candidate address The candidate's current address is required in order data, unless the order contains only the Document Processing service. ```json theme={null} { "orderData": [ { "caseOrderDataTypeId": "codt-current-candidate-address", "metadata": { "address1": "100 Main St", "address2": "Unit 2", "city": "New York", "state": "NY", "postalCode": "10016", "country": "US" } } ] } ``` **`metadata` properties:** `address1`, `address2`, `city`, `state` (two-letter abbreviation), `postalCode`, `country` (two-letter abbreviation). ### Health screening scheduling address If an occupational health or drug screening is being ordered, you must provide an address that can be used for finding nearby clinics to fulfill the screening. | Service category | ID | | - | - | | Occupational health screening | service-cat-ohs | All OHS and drug screening services share the same `serviceCategoryId` (`service-cat-ohs`). If you're running logic to determine if you need to include the `codt-ohs-scheduling-address` order data, you should use the `serviceCategoryId` in your conditional logic. ```json theme={null} { "orderData": [ { "caseOrderDataTypeId": "codt-ohs-scheduling-address", "metadata": { "address1": "100 Main St", "address2": "Unit 2", "city": "New York", "state": "NY", "postalCode": "10016", "country": "US" } } ] } ``` ### Education If Education Verification is being ordered, you must provide at least one education order data item. | Service | ID | | - | - | | Education Verification | 85307784-1f84-471a-8596-c8ea088c3a62 | ```json theme={null} { "orderData": [ { "caseOrderDataTypeId": "codt-education", "serviceId": "85307784-1f84-471a-8596-c8ea088c3a62", "metadata": { "institution": "Example University", "educationType": "College", "educationTypeDescription": "", "degree": "Bachelor of Science", "major": "Nursing", "city": "Manchester", "state": "NH", "country": "US", "monthBegin": "August", "yearBegin": "2000", "current": false, "monthEnd": "May", "yearEnd": "2004", "nameIfDifferentFlag": false, "nameIfDifferent": "", "contact": { "website": "exampleuniversity.edu", "email": "admin@exampleuniversity.edu", "phone": "800-555-0123" } } } ] } ``` ### Employment If an employment verification service is being ordered, you must provide at least one employment order data item. | Service | ID | | - | - | | Employment Verification | 9ac65633-b4c4-4062-875c-3556db9d2a08 | | Employment Income Verification | service-employment-income | ```json theme={null} { "orderData": [ { "caseOrderDataTypeId": "codt-employment", "serviceId": "9ac65633-b4c4-4062-875c-3556db9d2a08", "metadata": { "employer": "Example Organization", "position": "Nurse", "city": "Manchester", "state": "NH", "country": "US", "monthBegin": "December", "yearBegin": "2004", "current": false, "monthEnd": "December", "yearEnd": "2018", "contact": { "website": "www.example.com", "email": "hr@example.com", "phone": "800-555-0147" }, "okToContact": true } } ] } ``` **`metadata` properties:** `employer`, `position`, `city`, `state`, `country`, `monthBegin`, `yearBegin`, `current` (boolean), `monthEnd`, `yearEnd`, `contact.website`, `contact.email`, `contact.phone`, `okToContact` (boolean), `staffingAgency` (optional, max 100 characters). ### Motor vehicle record If a Motor Vehicle Report is being ordered, you must provide at least one MVR order data item. | Service | ID | | - | - | | Motor Vehicle Report | 9a1aa5db-1292-423e-a17c-4a7ab380de58 | ```json theme={null} { "orderData": [ { "caseOrderDataTypeId": "codt-mvr", "serviceId": "9a1aa5db-1292-423e-a17c-4a7ab380de58", "metadata": { "state": "NH", "licenseNumber": "NHL12345678", "firstNameIfDifferent": "", "middleInitialIfDifferent": "", "lastNameIfDifferent": "" } } ] } ``` ### Aliases Alias order data is never required. This data is optional if you're ordering one of the services that support aliases: | Service | ID | | - | - | | FACIS | 2c6bbd00-dce3-4ecd-ae91-b0f3dab268f7 | | Global Watchlist Search | c3080270-3e83-4eb2-a2a9-e5964645f8c5 | | National Criminal Search | d8e3dbdb-c2d7-4787-9736-86fffab74da4 | | Federal Criminal Search | ee774b82-a411-4e2b-a38f-c0641bd836e7 | | State Criminal Court Search | c407f6dd-523e-4627-a4d9-8f52d30ee744 | | State Criminal Database Search | d9381240-6230-40ec-9e11-35703e8041bc | | County Criminal Search | fa226cb7-1214-4cdf-9296-6120a7376926 | When providing alias order data, you must do the following: 1. Include a master list of aliases for the candidate — one `codt-alias` item for each alias. 2. Include one `codt-alias` item for each service that you want verified using the alias. `serviceId` must be specified for these items. ```json theme={null} { "orderData": [ { "caseOrderDataTypeId": "codt-alias", "metadata": { "givenName": "Bill", "middleName": "", "familyName": "Moore" } }, { "caseOrderDataTypeId": "codt-alias", "metadata": { "givenName": "Will", "middleName": "", "familyName": "Moore" } }, { "caseOrderDataTypeId": "codt-alias", "serviceId": "fa226cb7-1214-4cdf-9296-6120a7376926", "metadata": { "givenName": "Bill", "middleName": "", "familyName": "Moore" } }, { "caseOrderDataTypeId": "codt-alias", "serviceId": "fa226cb7-1214-4cdf-9296-6120a7376926", "metadata": { "givenName": "Will", "middleName": "", "familyName": "Moore" } } ] } ``` ### Jurisdictions Jurisdiction order data is never required. This data is optional if you're ordering one of the jurisdiction-based services: | Service | ID | | - | - | | County Criminal Search | fa226cb7-1214-4cdf-9296-6120a7376926 | | Federal Criminal Search | ee774b82-a411-4e2b-a38f-c0641bd836e7 | | State Criminal Database Search | d9381240-6230-40ec-9e11-35703e8041bc | | State Criminal Court Search | c407f6dd-523e-4627-a4d9-8f52d30ee744 | The results of an SSN Trace will inform which jurisdictions to be searched. As a result, the final list of jurisdictions might be larger than the list that is provided as order data. When providing jurisdiction order data, you must do the following: 1. Provide one or more addresses to derive the list of specific jurisdictions: ```json theme={null} { "orderData": [ { "caseOrderDataTypeId": "codt-address", "metadata": { "city": "Manchester", "state": "NH", "county": "Hillsborough", "autoProcessJurisdictions": false } } ] } ``` 2. If `autoProcessJurisdictions` is set to false (or omitted), specify the jurisdictions for each relevant search type: **County jurisdictions:** ```json theme={null} { "orderData": [ { "caseOrderDataTypeId": "codt-jurisdiction-county", "serviceId": "fa226cb7-1214-4cdf-9296-6120a7376926", "metadata": { "state": "NH", "county": "HILLSBOROUGH" } } ] } ``` **Federal district jurisdictions:** ```json theme={null} { "orderData": [ { "caseOrderDataTypeId": "codt-jurisdiction-fed-district", "serviceId": "ee774b82-a411-4e2b-a38f-c0641bd836e7", "metadata": { "district": "New Hampshire District Court" } } ] } ``` **State jurisdictions:** ```json theme={null} { "orderData": [ { "caseOrderDataTypeId": "codt-jurisdiction-state", "serviceId": "c407f6dd-523e-4627-a4d9-8f52d30ee744", "metadata": { "state": "NH" } } ] } ``` Use the `POST /jurisdiction/find/all` endpoint to help populate the specific jurisdiction order data. Setting `autoProcessJurisdictions` to true skips the need to specify individual jurisdiction items. ### Professional license and certification If a Professional License and Certification verification (CPLC) is being ordered, you must provide at least one CPLC order data item. | Service | ID | | - | - | | Professional License and Certification | service-cplc | To get the required fields for a specific license or certification: 1. Send a GET request to `GET /service/cplc/list` to retrieve all supported CPLCs and get the `cplcId`. 2. Send a GET request to `GET /service/cplc/id/{cplcId}` to retrieve the required fields for that `cplcId`. ```json theme={null} { "orderData": [ { "caseOrderDataTypeId": "codt-cplc", "serviceId": "service-cplc", "metadata": { "cplcId": "e9a5f173-a9cc-4dc7-91a0-25d5586b3d50", "fields": [ { "fieldId": "licenseNumber", "value": "LN123456" }, { "fieldId": "firstName", "value": "William" }, { "fieldId": "lastName", "value": "Moore" }, { "fieldId": "state", "value": "NH" } ] } } ] } ``` ### Shipments If a shipment service is being ordered, you must provide at least one shipment order data item regardless of PII flow. If you don't include the order data when creating a case, the service will be excluded from the case order. | Service | ID | | - | - | | Mask Shipment | service-mask-shipment | To get the masks available for shipment: 1. Send a GET request to `GET /shipment/mask/list` to retrieve a list of masks. 2. In the returned `list` array, get the `sku` for a specific mask. Only masks with `inStock` as true can be ordered. Attempting to order an out-of-stock mask results in a 422 response. ```json theme={null} { "orderData": [ { "caseOrderDataTypeId": "codt-shipment", "serviceId": "service-mask-shipment", "metadata": { "recipientName": "William Moore", "address1": "100 Main St", "address2": "Unit 2", "addressType": "home", "addressSource": "homeAddress", "city": "New York", "state": "NY", "postalCode": "10016", "shippingMethod": "2-3 Business Days", "maskType": "3M 8210" } } ] } ``` ### Drug reason for test If a DOT drug screening is being ordered, you can optionally provide a reason for test. If omitted, the default value of `pre-employment` is used. | Service category | ID | | - | - | | Occupational health screening | service-cat-ohs | | Service sub-category | ID | | - | - | | Drug test | service-subcat-drug | Supported `reasonForTest` values: | Value | Description | | - | - | | **`pre-employment`** | Pre-employment screening (default). | | **`followup`** | Follow-up screening. | | **`post-accident`** | Post-accident screening. | | **`return-to-duty`** | Return-to-duty screening. | ```json theme={null} { "orderData": [ { "caseOrderDataTypeId": "codt-drug-reason-for-test", "metadata": { "reasonForTest": "pre-employment" } } ] } ``` ### Drug testing authority If a DOT drug screening is being ordered, you can optionally provide the regulatory authority under which the test is being conducted. If omitted, the default value of `fmcsa` is used. | Service category | ID | | - | - | | Occupational health screening | service-cat-ohs | | Service sub-category | ID | | - | - | | Drug test | service-subcat-drug | Supported `testingAuthority` values: | Value | Description | | - | - | | **`fmcsa`** | Federal Motor Carrier Safety Administration (default). | | **`faa`** | Federal Aviation Administration. | | **`fra`** | Federal Railroad Administration. | | **`fta`** | Federal Transit Administration. | | **`phmsa`** | Pipeline and Hazardous Materials Safety Administration. | | **`uscg`** | United States Coast Guard. | ```json theme={null} { "orderData": [ { "caseOrderDataTypeId": "codt-drug-testing-authority", "metadata": { "testingAuthority": "fmcsa" } } ] } ``` ### Document Processing If document processing is being ordered, you must provide one `codt-idp` order data item per document to be processed. If you don't provide order data for a document, it will not be included in the processing order. If the order contains only the Document Processing service, no other order data is required — the package ID and the candidate's name and email in the request body are sufficient. | Service | ID | | - | - | | Document Processing | service-intelligent-document-process | **`metadata` properties:** | Property | Description | | - | - | | `documentTypeId` | Document type identifier. Always use `unclassified` for Document Processing. | | `fileName` | The file name as provided when uploading the document. | | `secureDocumentId` | The secure document ID returned after creating the secure document record. | ```json theme={null} { "orderData": [ { "caseOrderDataTypeId": "codt-idp", "serviceId": "service-intelligent-document-process", "metadata": { "documentTypeId": "unclassified", "fileName": "testfile1.pdf", "secureDocumentId": "e9a5f173-a9cc-4dc7-91a0-25d5586b3d50" } } ] } ``` See the [Document processing flow guide](/background-check-api/guides/document-processing-flow) for a full walkthrough of uploading documents and creating a document processing order. # Upload documents for a case Source: https://developer.karmacheck.com/background-check-api/guides/upload-documents How to securely upload candidate disclosure and authorization documents and associate them with a case. KarmaCheck supports the ability for providing candidate disclosure and authorization document records by way of a secure file upload. These uploaded files can be associated with a case, either an existing case or a case that you're going to create. This guide assumes that you already obtained API access to a group in KarmaCheck. The steps to securely upload, store, and make appropriate associations with a case are as follows: 1. Request a secure URL for each document to store. 2. Upload the files to KarmaCheck using the returned URLs from step 1. 3. Create the proper association for the successfully uploaded files in step 2. ## Step 1: Request document upload URLs To upload any documents and associate them with a case, you need to first generate a URL for each document. Replace `AUTHENTICATION_TOKEN` with your token and adjust the body values: * **`mimeType`:** The MIME type of the document you will upload. If you're uploading a non-PDF file, replace `application/pdf` with the correct MIME type. To retrieve a list of supported MIME types, send a GET request to `GET /document/secure/mimetypes`. * **`documentTypeId`:** The type of document you will upload. Candidate disclosures and authorizations are the only supported document type to associate with a case. If uploading more than one document, add an additional object containing `mimeType` and `documentTypeId` to the `files` array for each additional document. ```bash theme={null} curl --request POST \ --url https://api-stage.karmacheck.io/document/secure/upload \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer AUTHENTICATION_TOKEN' \ --data '{ "files": [ { "mimeType": "application/pdf", "documentTypeId": "candidate-disclosures-and-authorizations" } ] }' ``` A successful request returns the following: * **`url`:** A URL for each document that you'll upload in the next step. Note that each returned URL expires after 1 hour. * **`fileKey`:** A unique key for referencing your document in KarmaCheck. You'll need this key in Step 3. ## Step 2: Upload documents You can now upload your documents directly to KarmaCheck using the URLs provided in the response from Step 1: ```shell theme={null} curl --request PUT 'UPLOAD_URL' \ --header 'Content-Type: MIME_TYPE' \ --data 'PATH_TO_DOCUMENT' ``` Replace the following in your request: * **`UPLOAD_URL`:** The URL returned in step 1 * **`MIME_TYPE`:** The MIME type of the document you're uploading. This should match the MIME type you entered in Step 1. * **`PATH_TO_DOCUMENT`:** The path to the document you're uploading Note the following: * If you're uploading more than one document, make sure to keep track of which URL you're uploading each document to. * If you attempt to use an expired URL, the server responds with a 403 HTTP status code. If you have additional issues with uploading your documents, see [Troubleshooting](https://docs.aws.amazon.com/AmazonS3/latest/userguide/troubleshooting.html) in the Amazon S3 documentation. ## Step 3: Create secure document records Finally, create a secure document record for each document you just uploaded. If you don't complete this step, the documents uploaded in Step 2 are unavailable for use in KarmaCheck, as they are not associated with any case. Replace `AUTHENTICATION_TOKEN` with your token and adjust the body values: * **`fileKey`:** The key returned in Step 1. If uploading more than one document, enter the key that corresponds with the URL to which you uploaded the document. * **`documentTypeId`:** The type of document uploaded — `candidate-disclosures-and-authorizations` * **`originalFileName`:** The file name for the uploaded document, including the file extension. * **`caseId`:** The ID of an existing case to associate the document with. If the case hasn't been created yet, remove the `accessGrants` object from the request body. ```bash theme={null} curl --request POST \ --url https://api-stage.karmacheck.io/document/secure/create \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer AUTHENTICATION_TOKEN' \ --data '{ "list": [ { "fileKey": "1daa3c43-ea4e-4d66-9330-0cbd197feee6", "documentTypeId": "candidate-disclosures-and-authorizations", "originalFileName": "example_document.pdf" } ], "accessGrants": { "caseId": "22e88848-17d1-4946-bbac-18d44f381ca7" } }' ``` A successful request returns a `secureDocumentId` for each document. If the documents are to be associated with a new case, you can send the newly created secure document IDs from this API call to the call for creating a case. Doing this will associate these documents with the case and the candidate. # API basics Source: https://developer.karmacheck.com/background-check-api/overview/api/api-overview An overview of the KarmaCheck REST API structure, endpoints, and request headers. The KarmaCheck API is a background check service that follows REST conventions. The API provides resources and actions at specified HTTPS endpoints, uses standard HTTP methods and response codes, and accepts and returns JSON in requests and responses. You have multiple options for testing the KarmaCheck API: * Try out each endpoint in the interactive [API reference](/api-reference/authentication/authenticate-api-client) documentation. * Export the OpenAPI Specification file from the API reference documentation and import the file into an API client, such as Postman. All API requests must be made over HTTPS. Calls made over plain HTTP or without valid authentication will be refused. ## Endpoints A KarmaCheck endpoint consists of the following: * **The base URL:** The production API is hosted at `https://api.karmacheck.io`. For sandbox testing, the base URL is `https://api-stage.karmacheck.io`. * **A resource path:** The API is organized around resources (such as cases, packages, or secure documents) that you can retrieve, create, or update. When applicable, a specific resource is referenced by its unique identifier. ## Request headers HTTP request headers store authentication data and information about the request and response formats: * **Authentication:** Every API request must include a valid authentication token that authorizes access to a group's data. See [Authentication](/background-check-api/overview/api/authentication) for details on how to obtain an authentication token. * **Request format:** Requests that include body data are submitted in JSON format. This is specified by sending the header `Content-Type: application/json`. * **Response format:** Most responses are returned in JSON format. This is specified by sending the header `Accept: application/json`. The header `Accept: text/html` is used for endpoints that return data in plain text format, such as the URL of a report for download. # Authentication Source: https://developer.karmacheck.com/background-check-api/overview/api/authentication How to obtain and use a JWT to authenticate KarmaCheck API requests. All API requests must be authenticated with a token in the form of a [JSON Web Token](https://jwt.io/) (JWT). The KarmaCheck API uses a [Bearer authentication scheme](https://swagger.io/docs/specification/authentication/bearer-authentication/), which should be used only over HTTPS. ## Create an authentication token To create an authentication token, you need to first contact KarmaCheck to [enable API access](/background-check-api/overview/customer-integration#enable-api-access). KarmaCheck will issue you an API key and one or more client access tokens. Each client access token gives access to a specific group within a company in the KarmaCheck system. With the API key and a client access token, call the `POST /auth/api` endpoint to retrieve an authentication token: ```bash theme={null} curl --request POST \ --url https://api-stage.karmacheck.io/auth/api \ --header 'Content-Type: application/json' \ --data '{ "apiKey": "API_KEY", "clientAccessToken": "CLIENT_ACCESS_TOKEN" }' ``` Replace `API_KEY` and `CLIENT_ACCESS_TOKEN` with your credentials. The response will contain your authentication token in the `token` field. Note the following regarding KarmaCheck authentication tokens: * Authentication tokens do not expire. However, tokens can be invalidated in order to revoke access to other API calls. * Anyone with access to your authentication token can access your KarmaCheck data. Store these tokens as securely as possible and avoid placing them in shared codebases. ## Authenticate an API request For all requests to the KarmaCheck API, set the `Authorization` header with the value `Bearer AUTHENTICATION_TOKEN`, replacing `AUTHENTICATION_TOKEN` with the authentication token that you created. Do *not* attempt to pass the authentication token in the query string (in other words, the URL). ```bash theme={null} curl --request GET \ --url https://api-stage.karmacheck.io/case/list \ --header 'Accept: application/json' \ --header 'Authorization: Bearer AUTHENTICATION_TOKEN' ``` # Environments Source: https://developer.karmacheck.com/background-check-api/overview/api/environments Staging and production environments, test SSNs, and simulated services for the KarmaCheck API. The KarmaCheck API supports two environments: staging and production. You can use the staging environment as a sandbox to test all available KarmaCheck functionality without affecting your live data. To access a KarmaCheck environment, contact your KarmaCheck account manager to obtain your API credentials. ## URLs | Environment | API base URL | KarmaCheck dashboard URL | | - | - | - | | **Staging** | `https://api-stage.karmacheck.io` | `https://app-stage.karmacheck.com` | | **Production** | `https://api.karmacheck.io` | `https://app.karmacheck.com` | ## Testing considerations The KarmaCheck sandbox and production environments provide simulated data for testing your integrations and service flows. Note the following scenarios and limitations when testing in these environments. ### Sandbox limitations When testing in the sandbox, all email notifications to candidates, such as invitations for candidates to initiate onboarding, are blocked from being sent to external email addresses. Instead, these emails are directed to a shared internal email inbox. If you'd like to receive copies of these emails, contact us to set up email forwarding. ### Predefined SSNs KarmaCheck supports usage of the following Social Security numbers (SSNs) to return either clean or unfavorable service results on the candidate: * **111-22-3333:** Use this SSN for certain services to be returned as cleared. * **333-22-1111:** Use this SSN for certain services to be returned with results or records that require review. See the next section for a list of applicable services. ### Simulated services KarmaCheck simulates results for a number of services after completion of candidate onboarding or PII entry during case ordering. These simulations lead to a case data completion status (in other words, the service is clear or needs review) for each service. All KarmaCheck environments generate simulated results for the following services, listed by service category: #### Identity verification | Service | Status | Test data required | | - | - | - | | **SSN Trace** | `clear` | SSN: 111-22-3333 | | **International Identity Verification** | `acknowledge` | Any data | #### Criminal check | Service | Status | Test data required | | - | - | - | | **OIG Exclusions Search** | `clear` | Any data | | **National Criminal Search** | `clear` | SSN: 111-22-3333 | | **Global Watchlist Search** | `clear` | SSN: 111-22-3333 | | **Sex Offender Search** | `clear` | SSN: 111-22-3333 | | **International Criminal Record Check** | `clear` | Name: Andrew McLeod; Date of birth: March 4, 1987 | | **International Criminal Record Check** | `consider` | Name: Andrew McLeod; Date of birth: any date other than March 4, 1987 | | **Canadian Criminal Record Check** | `clear` | Any data, except the name Will Nettke | | **Canadian Criminal Record Check** | `consider` | Name: Will Nettke | #### Motor vehicle record check | Service | Status | Test data required | | - | - | - | | **Motor Vehicle Report** | `acknowledge` | SSN: 111-22-3333 | | **Canadian Motor Vehicle Record Check** | `clear` | Any data, except driver's licenses issued in British Columbia | | **Canadian Motor Vehicle Record Check** | `consider` | Driver's license issued in British Columbia | #### Occupational health screening | Service | Status | Test data required | | - | - | - | | **Any physical screening** (except Lab - CBC With Differential; Audiogram Annual/Baseline supports `acknowledge` only) | `acknowledge` | SSN: 111-22-3333 | | **Any physical screening** (except Lab - CBC With Differential; Audiogram Annual/Baseline supports `acknowledge` only) | `consider` | SSN: 333-22-1111 | | **Any drug screening** | `clear` | SSN: 111-22-3333 | | **Any drug screening** | `consider` | SSN: 333-22-1111 | | **Any TB test** | `acknowledge` | SSN: 111-22-3333 | | **Any TB test** | `consider` | SSN: 333-22-1111 | | **Any immunization** (except Hepatitis B Surface Antigen Titer; Hepatitis C Titer) | `acknowledge` | SSN: 111-22-3333 | | **Any immunization** (except Hepatitis B Surface Antigen Titer; Hepatitis C Titer) | `consider` | SSN: 333-22-1111 | | **Hepatitis C Titer** | `acknowledge` | SSN: 333-22-1111 | | **Hepatitis C Titer** | `consider` | SSN: 111-22-3333 | #### Professional license and certification | Service | Status | Test data required | | - | - | - | | **CNM (APRN) Verification** | `consider` | Any fictitious license | | **CNP (APRN) Verification** | `consider` | Any fictitious license | | **CNS (APRN) Verification** | `consider` | Any fictitious license | | **CRNA (APRN) Verification** | `consider` | Any fictitious license | | **PN Verification** | `consider` | Any fictitious license | | **RN Verification** | `consider` | Any fictitious license | All other screenings remain in a pending status. # Status codes and errors Source: https://developer.karmacheck.com/background-check-api/overview/api/errors HTTP status codes used by the KarmaCheck API and the structure of error responses. The KarmaCheck API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, a 2*xx* status code indicates success, a 4*xx* status code indicates an error based on the information provided, and a 5*xx* status code indicates an error with KarmaCheck servers. ## HTTP status codes | Code | Title | Description | | - | - | - | | **200** | OK | The request was successful. | | **400** | Bad Request | The request couldn't be processed. This might be due to issues in the request body. | | **403** | Forbidden | The user doesn't have permissions to access the requested resource. | | **404** | Not Found | The resource path doesn't exist. This might be due to an invalid resource ID that was provided. | | **409** | Conflict | The request conflicts with the resource's current state. | | **422** | Unprocessable Entity | The request contains data that fails validation rules or business rules. | | **500** | Internal Server Error | A problem occurred on KarmaCheck's end. | ## Errors Errors are returned as JSON-based messages. Most 4*xx* responses include an error message that briefly explains the error, which can be handled programmatically. The following sections provide examples of different types of error responses. ### 400 Bad Request Your request body has one of the following issues: * A required field is missing. * A field contains the wrong format or data type. For example, you want to find relevant jurisdictions for a county, but didn't provide the state: ```json theme={null} { "message": [ "counties.0.state must be a string" ], "error": "Bad Request", "statusCode": 400 } ``` ### 403 Forbidden You don't have permission to access a specific resource: ```json theme={null} { "message": "You do not have access to documents for case e074241e-36e8-444b-bf55-bb4dad6d3f3d", "error": "Forbidden", "statusCode": 403 } ``` ### 404 Not Found The resource (for example, a case) associated with the ID provided in the path parameter doesn't exist: ```json theme={null} Invalid case ``` ### 409 Conflict A request to create a case includes an email address associated with a candidate who is already the subject of an existing case within the same group: ```json theme={null} { "httpStatus": "CONFLICT", "cases": [ { "existingCaseId": "afe52932-7c0d-4233-93f9-ce6ee3d0bede", "existingCaseCrStamp": "2024-05-30T00:02:12.000+00:00", "existingCasePackageId": "d04defe1-1ea5-43fc-1832-231a5d23a08b", "existingCasePackageName": "Basic Check", "existingCaseStatusId": "d894b8a0-937e-46b1-8799-15bad611844f", "existingCaseStatus": "Pending", "modStamp": "2024-05-31T00:02:17.000+00:00" } ] } ``` To create a new case associated with the same candidate, resend the request with `orderOverride` in the request body. Depending on the value provided (`add` or `replace`), a successful request results in one of the following: * The new case is created in addition to the existing case. * The existing case is archived, and the new case is created. ### 422 Unprocessable Entity The request contains data that fails validation. For example, a request to create a case using the PII entry flow is missing required candidate information: ```json theme={null} Requested package requires candidate phone number ``` The request doesn't align with business logic. For example, you can't resend the invitation associated with a case if a candidate has already begun the onboarding process: ```json theme={null} { "message": "Case has already started", "error": "Unprocessable Entity", "statusCode": 422 } ``` # Case lifecycle Source: https://developer.karmacheck.com/background-check-api/overview/case-lifecycle How a case moves through its states, from ordering through adjudication. Every case goes through multiple states within its lifecycle. The following diagram depicts the overall status of a case as it moves through its lifecycle. A diagram of the lifecycle of a case. ## Case statuses A combination of the following case attributes determines the overall status, or the state, of a case: * **Primary status:** Every case has a primary status that describes the status of a case at a high level. * **Secondary status:** In certain scenarios, a case has a secondary status that provides additional information about its status. * **Adverse action status:** An adverse action flow can be initiated after a case reaches a primary status of `Complete`. When this occurs, an adverse action status is associated with the case. * **Result type:** The result type of a case indicates the outcome of the background check. A case remains open until a decision is made to place the candidate or initiate an adverse action. The following tables describe the different states that a case can be in, and the corresponding statuses and result type that determine its overall status. See [Case-level result and statuses](/background-check-api/reference/case-status) for the system-defined IDs of all the possible statuses and result types. ### Onboarding and processing | Overall status | Description | Primary status | Secondary status | Adverse action status | Result type | Final state? | | - | - | - | - | - | - | - | | **Invitation sent** | A case was ordered, and an invitation was sent to the candidate. | `Pending` | `Waiting for Authorization` | `null` | `Open` | No | | **Authorization in progress** | **Candidate-provided PII flow:** The candidate started onboarding. **Customer-provided PII flow:** A case was ordered, and the system is verifying the input data. | `Pending` | `Authorization in Progress` | `null` | `Open` | No | | **Processing screenings** | The processing of screenings is in progress. The case remains in this state until all screenings are complete. | `Pending` | `null` | `null` | `Open` | No | | **Waiting for parental consent** | The processing of screenings is on hold until parental consent is provided on behalf of the minor candidate, who is under the age of 18. | `Blocked` | `Waiting for Parental Consent` | `null` | `Open` | No | | **Verifying candidate input** | The candidate-provided PII differs from existing candidate data in the system. The case cannot proceed until it's reviewed by KarmaCheck Support. | `Blocked` | `Verifying Candidate Input` | `null` | `Open` | No | | **Reviewing order** | The customer-provided PII differs from existing candidate data in the system. The case cannot proceed until it's reviewed by KarmaCheck Support. | `Blocked` | `Reviewing Order` | `null` | `Open` | No | | **Blocked** | An unexpected issue occurred. Processing is blocked until KarmaCheck Support can review the case. | `Blocked` | `null` | `null` | `Open` | No | | **Canceled** | The case is canceled. This occurs when the case gets replaced with a new case, or when the case gets archived while in a secondary status of `Waiting for Authorization`, `Authorization in Progress`, or a primary status of `Blocked`. | `Adjudicated` | `Canceled` | `null` | `Open` | Yes, unless KarmaCheck is explicitly asked to reopen the case | ### Processing complete The "Processing complete" state is a rollup (aggregate) status, determined by the terminal status of all services or screenings ordered on the case. For details on individual service lifecycles and terminal statuses, see the [Service Lifecycle](./service-lifecycle) page. | Overall status | Description | Primary status | Secondary status | Adverse action status | Result type | Final state? | | - | - | - | - | - | - | - | | **Needs review** | Processing is complete, and at least one screening requires customer review. | `Complete` | `Consider` | `null` or `Cancel` | `Open` | Yes, unless adverse action is initiated or another screening is added to the case | | **Clear** | Processing is complete, and all screenings are clear. | `Complete` | `null` | `null` | `Open` | Yes, unless adverse action is initiated or another screening is added to the case | ### Adjudicated results | Overall status | Description | Primary status | Secondary status | Adverse action status | Result type | Final state? | | - | - | - | - | - | - | - | | **Placed** | The candidate meets the hiring criteria. | `Adjudicated` | `null` | `null` or `Cancel` | `Placed` | Yes, unless another screening is added to the case | | **Pre-adverse action** | The adverse action flow was initiated on the case, which previously had a result of `Open` and a primary status of `Complete`. The candidate will receive a pre-adverse action letter. | `Complete` | `Consider` or `null` | `Pre-Adverse` | `Pre-Adverse Action` | No | | **Dispute adverse action** | The candidate disputed the adverse action. | `Complete` | `Consider` or `null` | `Dispute` | `Dispute Adverse Action` | No | | **Adverse action** | The final phase of the adverse action flow was initiated. | `Adjudicated` | `null` | `Post` | `Adverse Action` | Yes, but the case can be taken out of adverse action if a mistake was made | ## Status changes Due to the fluid nature of background checks, a case can cycle through different states more than once. A case that reaches the end of a typical lifecycle could still be subject to change, so your system should account for potential state reversals. For example, a case with a `Placed` result can transition to `Open` with a secondary status of `Consider` (in other words, an overall status of **Needs review**). This might occur after the discovery of information that affects the initial adjudication decision. # Changelog Source: https://developer.karmacheck.com/background-check-api/overview/changelog Recent changes to the KarmaCheck API, in reverse chronological order. * Updated the `DetailsDrug` and `DetailsOHS` schemas to list only the properties returned to API clients for drug and occupational health screenings. Clinic, lab, and medical review officer (MRO) properties are unchanged. * Candidate PII order data (`codt-govt-id`, `codt-dob`, and `codt-current-candidate-address`) is no longer required on `POST /case/create` when the order contains only the Document Processing service (`service-intelligent-document-process`). Only the package ID and the candidate's name and email are needed, plus one `codt-idp` order data item per document. See the [Document processing flow guide](/background-check-api/guides/document-processing-flow) for details. * Added `authorization` as a supported contact type to `orderConfig.contacts` on `POST /case/create` and `POST /case/id/{caseId}/add/services`. See [Order configuration](/background-check-api/reference/order-configuration) for details. * Added support for `codt-drug-reason-for-test` and `codt-drug-testing-authority` order data types for DOT drug screenings on `POST /case/create` and `POST /case/id/{caseId}/add/services`. See [Provide order data](/background-check-api/guides/order-data) for details. * Added support for Intelligent Document Processing with the new `service-intelligent-document-process` service. See the [Document processing flow guide](/background-check-api/guides/document-processing-flow) for more detail. * Added support for order data `CaseOrderDataOHSServiceSubstitutions`. This new type can be optionally supplied on `POST /case/create` and `POST /case/id/{caseId}/add/services`. * Added the `POST /case/data/id/{caseDataId}/search/id/{searchId}/cancel` endpoint to cancel individual case data search records. * Updated `DetailsEmployment` and `DetailsEducation` to include a `searchId` field. * Added an optional `fileFormat` property to `DocumentCreateRecords`. This allows the property to be supplied on `POST /document/secure/create`. * Added support to search the verification book via `POST /vbook/search`. * Added an optional `secureDocumentIds` property to `CaseOrderDataEmployment`, `CaseOrderDataEducation`, and `CaseOrderDataCPLC`. This allows the property to be supplied on `POST /case/create` and `POST /case/id/{caseId}/add/services`. * Validation added to name fields for create case, aliases, and update candidate info endpoints. These fields are now restricted to only letters, numbers and the following special characters: Hyphen (`-`), Apostrophe (`'`), Comma (`,`), Period (`.`), and Underscore (`_`). This applies to `CreateCase` and `CaseOrderDataAlias`. * Added an optional `staffingAgency` property (100 character max) to `CaseOrderDataEmployment`, `TestimonyEmployment`, and `TestimonyEmploymentCreate`. This allows this property to be supplied on `POST /case/create`, `POST /case/id/{caseId}/add/services`, `POST /testimony/create/case/id/{caseId}`, and `PUT /testimony/id/{testimonyId}/update/case/id/{caseId}`. * Added the `jurisdictions` array to county criminal search details in the response of `GET /case/id/{caseId}/data/{serviceTypeId}`. * Added support for shipment order data to `POST /case/create` and `POST /case/id/{caseId}/add/services`. * Added the `GET /shipment/mask/list` endpoint to retrieve a list of masks for shipment. * Added the `GET /company/user/list` endpoint to retrieve users by groups within a company. * Added support for Professional License and Certification order data to `POST /case/create` (customer-provided PII) and `POST /case/id/{caseId}/add/services`. * Added `statusId` to each individual record within employment verification details and education verification details in `GET /case/id/{caseId}/data/{serviceTypeId}`. * Added endpoints to request and acknowledge custom dynamic disclosures. # Customer integration Source: https://developer.karmacheck.com/background-check-api/overview/customer-integration How to enable KarmaCheck API access as a customer. As a KarmaCheck customer, you have access to the KarmaCheck API and the user dashboard. Integrating with the API gives you the ability to programmatically order background checks and receive results of those background checks. ## Enable API access To gain access to the KarmaCheck API, contact [KarmaCheck Customer Success](mailto:customersuccess@karmacheck.com) to request the following: 1. **An API key** that allows your company to access the KarmaCheck system 2. **A client access token** that gives access to a specific group in your company The combination of the API key and the client access token enables you to authenticate with the KarmaCheck system in a specific environment (either sandbox or production) and perform API calls for the group that's associated with the client access token. If you have multiple groups within KarmaCheck, you'll need a client access token for each group. ## Optional: Set up webhooks You have the option to set up webhooks if you want to receive status updates on ordered background checks. To receive webhook event calls, provide KarmaCheck with the URL where you want to receive webhook event notifications. See [Subscriptions](/background-check-api/reference/webhooks/webhooks-overview#subscriptions) for details about configuring webhooks. # Glossary Source: https://developer.karmacheck.com/background-check-api/overview/glossary Definitions of terms used throughout the KarmaCheck developer documentation. This page defines terms that are used throughout the KarmaCheck developer documentation. These terms are ordered so that each definition builds on a previous one. ### Candidate An individual who is the target of a background check. ### Service An individual service that's performed on a candidate as part of a larger background check. KarmaCheck supports multiple types of services, many of which are referred to as *screenings*. ### Package A group of services to execute on a candidate for a complete background check. ### Case An ordered background check. A case is an active instance of a package, and links a candidate to the package. When a case is complete, a report will be made available for that case. ### Case data The information for a specific service of an ordered case. Case data will exist for each service of the ordered case. ### Order data The information supplied at the time of ordering a background check or adding additional services after the background check was ordered. ### Onboarding The process that a candidate goes through to approve the running of a case and provide any necessary personally identifiable information (PII). The KarmaCheck onboarding process collects the information required to execute the services of the ordered case, presents the candidate with the appropriate disclosures, and gathers all necessary approvals and signatures to allow the execution of the case to move forward. ### Invitation Token-based access for a candidate to initiate the onboarding process of an ordered background check. ### Company A KarmaCheck customer that's ordering background checks. ### Group A virtual division within a company for grouping access to candidates, available packages, and running checks. This division is used to control access among multiple users of the company as well as to organize the company's accounting by group. ### Customer 1. A KarmaCheck customer that uses the KarmaCheck API to order background checks for their own company. Such customers are a primary audience for the KarmaCheck developer documentation. 2. A KarmaCheck customer that uses their own KarmaCheck account to log in to the KarmaCheck dashboard to order background checks. 3. A KarmaCheck customer that enables a partner to use the KarmaCheck API to order background checks on their behalf. ### Partner A KarmaCheck partner enabled by a mutual customer to order background checks on the company's behalf. A partner must register with KarmaCheck and obtain one or more client access tokens from the mutual customer. ### API key A unique key that enables programmatic access to KarmaCheck. An API key is issued in two scenarios: * For a customer who is building an integration with their own system for their own access. * For a vendor who is building a solution for their customers. This vendor is referred to as a *partner*. ### Client access token A unique token provided to a customer, enabling them to programmatically access and manage cases for a specific group in their company. The customer can also provide the token to an API partner if they want that partner to access their cases on their behalf. # Introduction Source: https://developer.karmacheck.com/background-check-api/overview/introduction An overview of the KarmaCheck API and its integration scenarios. KarmaCheck provides an API-first platform for ordering and tracking background checks, credential verifications, and occupational health screenings. With the KarmaCheck API, you can: * Submit orders that consist of various screenings, ranging from one to many. * Track the state of an order throughout its lifecycle. * Review the overall results of a background check, as well as the details of individual screenings. * Adjudicate a completed background check. * Receive data asynchronously through the webhook infrastructure. ## Who is the API for? The KarmaCheck API enables businesses to seamlessly integrate background checks into their applications and services. Whether you're building your own integrations or extending offerings to your customers, KarmaCheck makes it easy to order and manage a range of services. * **For customers:** Use the KarmaCheck API to integrate and automate your background check processes. Accessing the API simply requires [obtaining your API credentials](/background-check-api/overview/customer-integration) from your KarmaCheck account manager. * **For partners:** Enhance your applicant tracking system (ATS), customer relationship management (CRM), or any recruitment platform by integrating with KarmaCheck's background check capabilities. To access the API, reach out to an account manager to [register as a KarmaCheck partner](/background-check-api/overview/partner-integration), and have our mutual customers request API access on your behalf. ## Common integration scenarios The workflows for ordering KarmaCheck services and onboarding candidates are flexible and customizable. The following table describes the different ways you can order and initiate a background check on a candidate. | Integration scenario | Description | Try out the workflow | | - | - | - | | **Candidate-provided PII flow** | Invite the candidate to participate in the KarmaCheck-hosted candidate onboarding process. The candidate will receive an invitation email from KarmaCheck to access a KarmaCheck candidate dashboard, where they can enter their personally identifiable information (PII) and authorize the check. The background check is initiated after the candidate completes this process. | See [Candidate-provided PII flow](/background-check-api/guides/candidate-provided-pii-flow) for details on how to order a background check. | | **Customer-provided PII flow** | Initiate a background check by providing the candidate's PII and other required data during check ordering. This requires confirmation that you gathered consent from the candidate to begin running a background check. | See [Customer-provided PII flow](/background-check-api/guides/customer-provided-pii-flow) for details on how to order and initiate a background check. | | **Custom candidate onboarding** | Build your own candidate onboarding experience instead of using the KarmaCheck-hosted candidate onboarding process. | Contact [KarmaCheck Customer Success](mailto:customersuccess@karmacheck.com) for guidance on this type of integration. | ## Next steps * Review the [glossary](/background-check-api/overview/glossary) for a better understanding of KarmaCheck concepts. * Gain an [overview](/background-check-api/overview/api/api-overview) of the KarmaCheck API. # Partner integration Source: https://developer.karmacheck.com/background-check-api/overview/partner-integration How to register as a KarmaCheck API partner and access the system on behalf of mutual customers. API partners can access the KarmaCheck system on behalf of mutual customers, allowing them to order and receive the results of background checks. Enabling integration with KarmaCheck as an API partner requires two steps: ## Step 1: Partner registration Register with [KarmaCheck Customer Success](mailto:customersuccess@karmacheck.com) as an API partner: 1. **Request an API key** from KarmaCheck that allows you to gain access to the KarmaCheck system. 2. **Request a client access token** for a sandbox demo company on the KarmaCheck sandbox server. 3. **(Optional) Supply KarmaCheck with a URL** where you want to receive webhook event calls. See [Subscriptions](/background-check-api/reference/webhooks/webhooks-overview#subscriptions) for details about configuring webhooks. ## Step 2: Customer access When a mutual customer wants to access the KarmaCheck system through the partnership, they will: 1. Request a client access token for each of their company groups from KarmaCheck. 2. Provide you with one or more client access tokens. The combination of your API key and the customer-provided client access token enables you to authenticate in the KarmaCheck system and perform API calls on behalf of the specific client company and group associated with the client access token. # Service lifecycle Source: https://developer.karmacheck.com/background-check-api/overview/service-lifecycle How an individual service (case data) moves through its states, and how the lifecycle differs by service type, category, and subcategory. This page is a Draft and subject to change. Each [service](/background-check-api/reference/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](/background-check-api/overview/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](/background-check-api/reference/service-type). 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](/background-check-api/reference/case-data-status). 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](/background-check-api/reference/webhooks/events/case-data-status-change). Integrations that need fine-grained progress reporting should subscribe to this event and inspect both fields together rather than only `statusId`. ### Statuses | Status | Terminal | Meaning | Notes | | - | - | - | - | | 
`pending`
| No | In progress — service processing has started but not yet completed. | All services start here; progress is typically reflected in `pendingStatusId`, see the [Pending substates](#pending-substates) section below for details. | | 
`clear`
| Yes | Done and good — no findings or discrepancies. | Used for record-search services that return no actionable hits. | | 
`consider`
| Yes | Done and needs review — findings exist that the customer must adjudicate. | The most common non-clean terminal across all screening services. | | 
`acknowledge`
| Yes | Done positive — affirmative confirmation. | Used by services that verify a credential or fitness (Verification, Professional License, OHS Titer/Vaccination/Physical). | | 
`not_found`
| Yes | Unable to verify — the source could not be reached, or no matching record exists. | Used by Verification, Professional License, MVR, and some Identity Verification services. | | 
`complete`
| Yes | Done without prejudice — no pass/fail interpretation. | Used by Payment, Shipment, and Document Processing services. | | 
`canceled`
| Yes | Service was not performed. | Possible on any service. | | 
`error`
| No | Processing encountered an unexpected error. | Transitional in practice; can return to `pending` once error is resolved by the system or KarmaCheck customer support intervention. | **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. | Status | IDV | Criminal | MVR | Verification | Pro License | OHS Physical | OHS TB | OHS Titer | OHS Vacc | OHS Drug | Document Processing | Payment | Shipment | Legal | | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | | 
`pending`
| ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | 
`clear`
| ✓ | ✓ | ✓ | | | ✓ | ✓ | | | ✓ | | | | | | 
`complete`
| | | | | | | | | | | ✓ | ✓ | ✓ | | | 
`acknowledge`
| | | | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | | | ✓ | | 
`consider`
| ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | | | 
`not_found`
| ✓ | | ✓ | ✓ | ✓ | | | | | | | | | | | 
`canceled`
| ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | | 
`error`
| ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | **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](/background-check-api/reference/case-data-status) page and [Service type/categories](/background-check-api/reference/service-type) 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. | Pending substate (pendingStatusId) | Verification | Pro License | OHS Physical | OHS TB | OHS Titer | OHS Vacc | OHS Drug | | - | - | - | - | - | - | - | - | | 
`pending-status-not-performed`
| ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | 
`pending-status-requested`
| | | ✓ | ✓ | ✓ | ✓ | | | 
`pending-status-scheduled`
| | | ✓ | ✓ | ✓ | ✓ | | | 
`pending-status-rescheduled`
| | | ✓ | ✓ | ✓ | ✓ | | | 
`pending-status-canceled`
| | | ✓ | ✓ | ✓ | ✓ | | | 
`pending-status-pending`
| | | ✓ | ✓ | ✓ | ✓ | | | 
`pending-status-partial`
| | | ✓ | ✓ | ✓ | ✓ | | | 
`pending-status-medical-review`
| | | ✓ | ✓ | ✓ | ✓ | | | 
`pending-status-suspended`
| | | | ✓ | | | | | 
`pending-status-no-show`
| | | ✓ | ✓ | ✓ | ✓ | ✓ | | 
`pending-status-refusal`
| | | ✓ | | | ✓ | ✓ | | 
`drugtest-*`
| | | | | | | ✓ | **Notes:** * See [Pending status](/background-check-api/reference/case-data-status#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](/background-check-api/reference/service-type) 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](/background-check-api/reference/reporting/generate-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. ```text theme={null} 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: ```text theme={null} 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`) ```text theme={null} 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: ```text theme={null} 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: ```text theme={null} 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.** | ## Related references * [Case lifecycle](/background-check-api/overview/case-lifecycle) * [Case-level result and statuses](/background-check-api/reference/case-status) * [Case data statuses](/background-check-api/reference/case-data-status) * [Service type and categories](/background-check-api/reference/service-type) * [Invitation status](/background-check-api/reference/invitation-status) * [`casedata.statuschange` webhook](/background-check-api/reference/webhooks/events/case-data-status-change) # Case data statuses Source: https://developer.karmacheck.com/background-check-api/reference/case-data-status System-defined IDs for all case data (service-level) statuses and pending statuses. Each service within an ordered case is represented by case data. The case data includes one or more statuses reflecting the current state of that service. ## Status The following table lists the possible statuses for case data. The status and its ID appear respectively as `status` and `statusId` in the response body of API endpoints like [`GET /case/id/{caseId}/data/{serviceTypeId}`](/api-reference/cases/get-case-data-by-case-id). | *status* | *statusId* | Description | | - | - | - | | **acknowledge** | 1a8490cb-084d-4209-bf2f-d46e41d760d6 | Done positive | | **clear** | e086eea7-e4b7-4c74-ac04-4c3b51c23a33 | Done and good | | **consider** | f657c777-c38d-489b-ac26-dd9bf0a88724 | Done and needs review | | **not\_found** | 96e0420a-4396-4bd1-9b54-447f00eb3ed8 | Unable to verify | | **canceled** | 3d726502-d2e2-4d10-859b-8a218f22086d | Not performed | | **complete** | case-data-status-complete | Done without prejudice | | **pending** | 8f29e0de-10f2-4c84-8379-16c6eb7cdf64 | In progress | | **error** | case-data-status-error | Error during processing | > **Note:** Some `statusId` values are GUIDs, while others are human-readable identifiers. The GUID-based IDs are legacy values from the original statuses introduced before we adopted human-readable IDs. To preserve backward compatibility, those original GUID-based status IDs were not changed and we have no plans to change them. ## Pending status The following table lists the possible pending statuses for certain case data. The pending status and its ID appear respectively as `pendingStatus` and `pendingStatusId` in the response body of API endpoints like [`GET /case/id/{caseId}/data/{serviceTypeId}`](/api-reference/cases/get-case-data-by-case-id). | Case data pending status | ID | Description | | - | - | - | | **Drug Test Appointment Scheduled** | drugtest-appointment-scheduled | Applies to drug screenings | | **Drug Test Appointment Change** | drugtest-appointment-change | Applies to drug screenings | | **Drug Test Appointment Canceled** | drugtest-appointment-canceled | Applies to drug screenings | | **Drug Test Appointment Requested** | drugtest-appointment-requested | Applies to drug screenings | | **Drug Test Sent to Lab** | drugtest-sent | Applies to drug screenings | | **Drug Test Received at Lab** | drugtest-received | Applies to drug screenings | | **Drug Test In Review** | drugtest-review | Applies to drug screenings | | **Drug Test Pending** | drugtest-pending | Applies to drug screenings | | **Drug Test Expired** | drugtest-expired | Applies to drug screenings | | **Appointment Scheduled** | pending-status-scheduled | Applies to OHS services | | **Appointment Rescheduled** | pending-status-rescheduled | Applies to OHS services | | **Appointment Canceled** | pending-status-canceled | Applies to OHS services | | **Appointment Requested** | pending-status-requested | Applies to OHS services | | **Pending (Processing)** | pending-status-pending | Applies to OHS services | | **Appointment No Show** | pending-status-no-show | Applies to OHS services | | **Partial Results (Processing)** | pending-status-partial | Applies to OHS services | | **Refusal to Test** | pending-status-refusal | Applies to OHS services | | **Suspended (Waiting for TB Read)** | pending-status-suspended | Applies to OHS services | | **Medical Review** | pending-status-medical-review | Applies to OHS services | | **Not Performed** | pending-status-not-performed | Applies to any service | | **Order In Progress** | pending-status-order-in-progress | Applies to OHS services | | **Cancel In Progress** | pending-status-cancel-in-progress | Applies to OHS services | | **Auth Packet Created** | pending-status-clinic-auth-created | Applies to OHS services | | **Auth Packet Sent** | pending-status-clinic-auth-sent | Applies to OHS services | | **Follow Up Required** | pending-status-followup-required | Applies to drug screenings | | **Awaiting Documentation** | pending-status-missing-document | Applies to OHS services | # Case-level result and statuses Source: https://developer.karmacheck.com/background-check-api/reference/case-status System-defined IDs for all case result types, primary statuses, secondary statuses, and adverse action statuses. After a case is created, it goes through multiple result types and statuses. ## Result type The following table lists the possible types of results for a case. The case result and its ID appear respectively as `resultType` and `resultTypeId` in the response body of API endpoints like [`GET /case/id/{caseId}`](/api-reference/cases/get-case). | *resultType* | *resultTypeId* | Description | | - | - | - | | **Open** | 8c94f0d9-57c9-4c7b-be95-5ec309cff330 | Case is ordered, processing, or pending review | | **Placed** | bbbd9fa2-598f-43f6-8363-b8b55e7aa777 | Case is complete, and candidate meets hiring criteria | | **Pre-Adverse Action** | 14bba02d-e6c7-45bf-a993-e28c306303c6 | Case entered an adverse action flow | | **Dispute Adverse Action** | result-type-dispute-adverse | Case is being disputed | | **Adverse Action** | d082a629-5dff-4303-83ae-897776ebcb17 | Case is complete, and candidate didn't meet hiring criteria | ## Primary status The following table lists the possible statuses for a case. The case status and its ID appear respectively as `caseStatus` and `caseStatusId` in the response body of API endpoints like [`GET /case/id/{caseId}`](/api-reference/cases/get-case). | *caseStatus* | *caseStatusId* | Description | | - | - | - | | **Pending** | d894b8a0-937e-46b1-8799-15bad611844f | In progress | | **Blocked** | 93827364-937e-46b1-8799-777366485997 | Blocked until KarmaCheck reviews | | **Complete** | 22334455-937e-46b1-8799-887766554433 | Done | | **Adjudicated** | 47463524-937e-46b1-8799-873f63e7b402 | Decision made | ## Secondary status The following table lists the possible secondary statuses for a case. The secondary status and its ID appear respectively as `secondaryStatus` and `secondaryCaseStatusId` in the response body of API endpoints like [`GET /case/id/{caseId}`](/api-reference/cases/get-case). | *secondaryStatus* | *secondaryCaseStatusId* | Description | | - | - | - | | **Waiting for Authorization** | 8e0c9756-a42f-4a7d-b8e2-412a0f6b9dea | Candidate has yet to start onboarding | | **Authorization in Progress** | c5f240cb-5221-451c-8bd1-4be5bf348ce5 | Candidate started onboarding | | **Waiting for Parental Consent** | b2c707af-091f-4d07-9546-4a1453f939e5 | Parental consent is required before processing can begin | | **Verifying Candidate Input** | status-type-verifying-cand-input | KarmaCheck Support is reviewing the candidate-provided data | | **Reviewing Order** | status-type-reviewing-order | KarmaCheck Support is reviewing the provided candidate data | | **Consider** | status-type-consider | Processing is complete and case needs review | | **Canceled** | 4155584b-708c-4108-86a8-8f3321b9b17c | Case canceled before processing began | ## Adverse action status The following table lists the possible statuses for an adverse action on a case. The adverse action status and its ID appear respectively as `adverseActionStatusName` and `adverseActionStatusId` in the response body of API endpoints like [`GET /case/id/{caseId}`](/api-reference/cases/get-case). | *adverseActionStatusName* | *adverseActionStatusId* | Description | | - | - | - | | **Pre-Adverse** | bb34dc52-4e3b-4baf-8e0b-b6603f9e2a84 | Adverse action flow initiated | | **Dispute** | ebbcb8e0-a0e7-43fb-930e-e52db4032d47 | Adverse action disputed by candidate | | **Cancel** | d61950cb-00aa-4839-9da5-0c97f236c813 | Adverse action canceled | | **Post** | fb32cc36-7eb6-47fa-ad4a-2635e99f197a | Adverse decision made | > **Note:** Some ID values are GUIDs, while others are human-readable identifiers. The GUID-based IDs are "legacy" values from the original statuses introduced before we adopted human-readable IDs. To preserve backward compatibility, those original GUID-based IDs were not changed and we have no plans to change them. # Professional license and certification Source: https://developer.karmacheck.com/background-check-api/reference/cplc Supported CPLC types and their IDs for use in order data. The following tables list the possible values for professional licenses and certifications by category. The name and ID of a professional license or certification appear respectively as `name` and `id` in the response body of the `GET /service/cplc/list` endpoint. The ID is also accepted as `cplcId` in the request body when providing [CPLC order data](/background-check-api/guides/order-data#professional-license-and-certification). To ensure that you always have the latest list of supported professional licenses and certifications, send a GET request to the `GET /service/cplc/list` endpoint. ## Finance | Professional license or certification | ID | | - | - | | **CFA** | 31ead3f4-48c8-4842-926c-7dbcc3aff2e9 | | **CFP** | 041c0aa6-2d64-48d0-b672-83bfcd10d47f | | **CPA** | 53c3588e-d0aa-4349-9e7a-a6820bf9085e | | **Finance - Other** | 417dfdac-3dea-4df9-a9c4-67b393f2267e | ## General | Professional license or certification | ID | | - | - | | **General - Other** | 29b0cc99-9ca5-4996-85b0-669bdf5b990f | | **Law License** | 1d16c91d-c2da-47d1-b102-bd67d5b8b1ee | | **LMT/RMT/CMP (Massage Therapist)** | 512d0d24-a4bd-4b1d-b6d1-182247a0f6ec | | **Real Estate License** | 1e972f29-93fb-48b8-aecd-839e17f668c0 | | **Social Worker** | ec401db7-7be6-4fde-b6f5-4705422a845a | ## Healthcare | Professional license or certification | ID | | - | - | | **AAB** | af2ff623-173e-4d56-936c-eb796b8796f4 | | **ACLS** | 7de4b199-7043-4e2c-a02d-460c889ba5e0 | | **ACLS-RQI** | d62f6812-65c6-46c7-81ec-fbd3ebc5781f | | **AMT** | 147a3258-0441-47d9-b691-b273f9c9efa7 | | **ASCP** | 60484692-9d72-4dd3-a5b0-d7c66d588f10 | | **AWOHNN** | 770fc7bb-43be-433e-ba26-51c5893cd5f0 | | **BLS Certification** | f269f4d6-6ed7-4d1b-8ed5-230ccc88f41b | | **BLS-RQI** | 6da53ada-32d9-459c-9a67-599b3ecdc712 | | **Board Certification (ABMS/FSMB)** | a8391111-55a4-4d46-ae43-58657c797b8d | | **CCMA** | b6bf1cae-67ba-427f-b2f5-1e29cc8d6f8c | | **CMA** | a428d71c-30e3-480d-bd2d-0edf05dba27a | | **CMAA** | c7b62a74-a3b4-4d22-b60c-a1a0e260094c | | **CNA** | e9a5f173-a9cc-4dc7-91a0-25d5586b3d50 | | **CNM (APRN)** | 524ef0a3-9a95-4068-b421-4ed03d85792b | | **CNP (APRN)** | e1138d9a-0bd1-42dd-a6ed-f0da1deed94b | | **CNS (APRN)** | 1ff54fb0-21fa-4bb4-b3c6-5e11b80341b9 | | **CPCT** | d6b4c072-f857-4c5f-bb53-ff398be61838 | | **CPR Certification** | d67fe835-6122-4f9e-a7d9-a5b43c75fa9f | | **CPT** | 3334c2d9-4e99-4dc8-af92-2f1b679009b6 | | **CRNA (APRN)** | 4801c56d-b35a-4394-8436-6e66b63dc798 | | **CSFA** | 521bbfa9-be6e-4d8b-8e4e-2ec1d7bbb397 | | **CST** | fabeb100-5417-400b-81b6-d2e7402d019c | | **DEA** | f1c90409-19ca-42e5-b91c-a922a9b13fc3 | | **ENPC** | 02262eda-9549-45c2-bd3d-1c185249a5c6 | | **Healthcare - Other** | ab2bdb65-b822-4193-b1b3-0e6691346b67 | | **HSPA** | fcfc84e6-a5fd-45e8-b4af-0b3c1b48843d | | **LPN** | 7133e306-0cdd-42d8-a2e0-a9b902a515eb | | **LVN** | 8d7fa241-3895-45f7-8d68-27817713d9cc | | **NCMA** | 7fa782b9-c89b-4a8b-9206-a4c08352411e | | **NIHSS** | e85496a9-9c12-4faa-9ccc-336cf355b7b1 | | **NP** | 83e6283d-f8b2-415f-9a2e-f3a897899fc9 | | **NPDB** | 673d8567-4986-40e6-8779-1a38217fd3fe | | **NRP** | fdd25ddc-5c57-4174-a489-8c97ca0721bd | | **ONCC** | e1ee7a23-389c-4677-8041-81411d61b46c | | **ONS** | c9ff955f-4c0d-4f6f-9800-82db22bb45fd | | **PALS** | 31c59835-41f1-4ffb-bc39-be1df0ed7186 | | **Pharmacist** | a035c255-37d6-4eb4-84a4-5a56207cf870 | | **PN** | fad49443-ff78-4114-8159-fc612bf53afe | | **PRACTICE MD** | 57a5a200-fec4-4a2e-a55d-45135380545c | | **RMA** | 781c9c0d-fb7a-4b24-a5a3-7c77beb0713a | | **RN** | cb3dac22-db86-44df-8193-877559b3e8dc | | **TNCC** | 8e5bfa80-363e-4883-818c-a834e6d2be10 | ## Other | Professional license or certification | ID | | - | - | | **Other** | 8b8c7b43-9762-4921-a484-7c0aec5c4536 | # IDP document type Source: https://developer.karmacheck.com/background-check-api/reference/idp-document-type System-defined IDs for the document types supported by Intelligent Document Processing (IDP). The following table lists the document types that Intelligent Document Processing (IDP) can classify and extract. Each type's ID and dashboard display name appear as `id` and `displayName` in the response body of `GET /document/secure/type/list?serviceId=service-intelligent-document-process`. The ID is also the value used for `documentTypeId` throughout a document processing order: * In the `metadata` of a `codt-idp` order data item on `POST /case/create`. Use `unclassified` (an input value, not one of the types below) to let IDP classify the document automatically. * In `detailsObject.documentTypeId` and `detailsObject.classificationData.type` in the results from `GET /case/id/{caseId}/data/service-type-document-processing`. See the [Document processing flow guide](/background-check-api/guides/document-processing-flow) for a full walkthrough. | ID | Display name | | - | - | | **acls-certification** | ACLS (Advanced Cardiovascular Life Support) | | **background-report** | Background Report | | **bls-certification** | BLS Certification | | **covid-card** | COVID-19 Vaccination Card | | **cpr-certification** | CPR Certification | | **diploma** | Diploma | | **drivers-license** | Driver's License | | **drug-screen-result** | Drug Screen Result | | **hipaa-training** | HIPAA Training | | **i-9-form** | I-9 Form | | **nrp-certification** | NRP (Neonatal Resuscitation) | | **nursing-license** | Nursing License | | **pals-certification** | PALS (Pediatric Advanced Life Support) | | **physical-exam-result** | Physical Exam Result | | **professional-reference** | Professional Reference | | **respirator-fit-test** | Respirator Fit Test Result | | **resume-cv** | Resume/CV | | **tb-result** | TB Result | | **titer-result** | Titer Result | | **transcript** | Transcript | | **us-passport** | U.S. Passport | | **vaccine-record** | Vaccine Record | | **w2** | W-2 Document | | **w4-form** | W4 Form | | **idp-other** | Other | # Invitation status Source: https://developer.karmacheck.com/background-check-api/reference/invitation-status System-defined IDs for all invitation statuses. When a case is created through the candidate-provided personally identifiable information (PII) flow, the candidate receives an email inviting them to participate in the background check process. This invitation email contains a link for the candidate to complete the KarmaCheck onboarding process, which involves providing the necessary PII and consenting to the background check. The following table lists the possible statuses for an invitation. The invitation status and its ID appear respectively as `invitationStatusName` and `invitationStatusId` in the response body of API endpoints like [`GET /case/id/{caseId}`](/api-reference/cases/get-case). | Invitation status | ID | Description | | - | - | - | | **pending** | 3f5e6898-6641-4685-8ee0-1363b7e10c98 | The invitation was sent to the candidate and is awaiting completion of the candidate's onboarding. | | **expired** | b5af27f7-8a03-4820-b2bd-82587dcacf5b | The invitation expired. You can call [`PUT /case/id/{caseId}/action/refreshinvite`](/api-reference/cases/refresh-invitation-for-case) to extend the candidate's onboarding period, or [`POST /case/id/{caseId}/action/resendinvite`](/api-reference/cases/post-case-id-caseid-action-resendinvite) to create a new invitation email. | | **completed** | d1962405-dd97-48f2-bede-530c2895481f | The candidate completed their onboarding. This initiates processing of the case. | | **cancelled** | 0f6acacc-71c4-43ec-80fa-941ff71c0c16 | The invitation was canceled. This happens when a case is archived before the candidate completes their onboarding. | For cases that are created through the customer-provided PII flow, the only possible invitation status is **completed**. With this flow, candidates can receive an email notifying them that their background check has been initiated. # Order configuration Source: https://developer.karmacheck.com/background-check-api/reference/order-configuration Configuration properties for controlling how services are executed when creating a case. When you create a case, you have the option to configure how certain services are executed via an `orderConfig` object in the request body. If you don't define a configuration property that applies to one or more services in the package that you're ordering, a default value will be set for that property. ## Configuration properties | **Configuration property** | **Applicable service** | **Description** | | - | - | - | | **`aliasNameConfiguration`** | All criminal screenings | Defines how to run aliases. See [Alias name configuration](#alias-name-configuration). | | **`ohsDrugPassportExpirationPolicy`** | All OHS and drug screenings | Defines how to handle expired ePassports. See [OHS/Drug passport expiration policy](#ohs/drug-passport-expiration-policy). | | **`lostOrIncompleteOHSDrugPolicy`** | All OHS and drug screenings | Defines how to handle lost or incomplete samples. See [Lost or incomplete OHS/drug policy](#lost-or-incomplete-ohs/drug-policy). | | **`diluteDrugPolicy`** | All drug screenings | Defines how to handle dilute samples. See [Dilute drug policy](#dilute-drug-policy). | | **`serviceConfigs.service-ohs-tb-quantiferon-gold.substitutionPolicy`** | Quantiferon Gold / TB Blood Test | Defines whether the test can be replaced. See [Quantiferon Gold substitution policy](#quantiferon-gold-substitution-policy). | | **`serviceConfigs.service-ohs-tb-tspot-test.substitutionPolicy`** | T-Spot / TB Blood Test | Defines whether the test can be replaced. See [T-Spot substitution policy](#t-spot-substitution-policy). | | **`serviceConfigs.9ac65633-b4c4-4062-875c-3556db9d2a08.verificationMethod`** | Employment Verification | Defines how to verify the candidate's reported employment. See [Employment verification method](#employment-verification-method). | | **`serviceConfigs.service-employment-income.verificationMethod`** | Employment Income Verification | Defines how to verify the candidate's reported employment and income. See [Employment income verification method](#employment-income-verification-method). | | **`serviceConfigs.85307784-1f84-471a-8596-c8ea088c3a62.verificationMethod`** | Education Verification | Defines how to verify the candidate's reported education. See [Education verification method](#education-verification-method). | | **`contacts`** | All services | Defines the contacts for the case. See [Contacts](#contacts). | ### Alias name configuration | Configuration value | Description | | - | - | | **no-alias** | Default, no aliases | | **alias-all** | All aliases | | **alias-all+hits-only** | All aliases, only on hits | | **alias-mnv** | Major name variations | | **alias-mnv+hits-only** | Major name variations, only on hits | ### OHS/Drug passport expiration policy | Configuration value | Description | | - | - | | **company-default** | Default, refer to company settings | | **reissue** | Automatically reissue | | **reissue-and-contact** | Automatically reissue and contact customer | | **reissue-once-contact** | Reissue once, then contact customer | | **contact-customer** | Contact the customer | | **do-not-reissue** | Do not reissue | ### Lost or incomplete OHS/drug policy | Configuration value | Description | | - | - | | **company-default** | Default, refer to company settings | | **reorder** | Automatically reorder | | **reorder-and-contact** | Automatically reorder and contact customer | | **reorder-once-contact** | Reorder once, then contact customer | | **do-not-reorder** | Do not reorder | ### Dilute drug policy | Configuration value | Description | | - | - | | **company-default** | Default, refer to company settings | | **reorder** | Automatically reorder | | **reorder-and-contact** | Automatically reorder and contact customer | | **reorder-once-contact** | Reorder once, then contact customer | | **do-not-reorder** | Do not reorder | ### Quantiferon Gold substitution policy | Configuration value | Description | | - | - | | **company-default** | Default, refer to company settings | | **replace-with-t-spot** | Replace with T-Spot | | **do-not-replace** | Do not replace | ### T-Spot substitution policy | Configuration value | Description | | - | - | | **company-default** | Default, refer to company settings | | **replace-with-quantiferon** | Replace with Quantiferon Gold | | **do-not-replace** | Do not replace | ### Employment verification method | Configuration value | Description | | - | - | | **docs-acceptable** | Default, docs are acceptable | | **psv** | Primary source verification | | **psv-first** | Primary source verification first | ### Employment income verification method | Configuration value | Description | | - | - | | **docs-acceptable** | Default, docs are acceptable | | **psv** | Primary source verification | | **psv-first** | Primary source verification first | ### Education verification method | Configuration value | Description | | - | - | | **docs-acceptable** | Default, docs are acceptable | | **psv** | Primary source verification | | **psv-first** | Primary source verification first | ### Contacts The `contacts` property is an array of contact objects for the case. Each contact object has the following properties: | Property | Type | Description | | - | - | - | | `name` | `string` | The contact's name. | | `type` | `string` | The contact type. See supported values below. | | `email` | `string` | The contact's email address. | | `phone` | `string` | The contact's phone number. | Supported `type` values: | Configuration value | Description | | - | - | | **`default`** | The default contact for the case. | | **`escalation`** | The escalation contact for the case. | | **`authorization`** | The OHS authorization contact for the case. | ```json theme={null} { "contacts": [ { "name": "Jane Smith", "type": "default", "email": "jane.smith@example.com", "phone": "800-555-0100" }, { "name": "John Doe", "type": "authorization", "email": "john.doe@example.com", "phone": "800-555-0101" } ] } ``` ## Overriding configurations You can override a case configuration by adding to the order (`POST /case/id/{caseId}/add/services`) *only if* the configuration doesn't apply to any services that have already been dispatched. For example, if an Employment Income Verification was ordered during case creation, then the `serviceConfigs.service-employment-income.verificationMethod` property cannot be updated. Attempting to do so results in a 422 response. # Reason code for OHS and drug tests Source: https://developer.karmacheck.com/background-check-api/reference/reason-code System-defined IDs for all reason codes used with OHS and drug screening services. The following table lists the possible reason codes for OHS and drug screenings. The reasons for a physical and a drug screening appear respectively as `physicalReasonDescription` and `reasonForTest` in the response body of the [`GET /case/id/{caseId}/data/{serviceTypeId}`](/api-reference/cases/get-case-data-by-case-id) endpoint. | Reason | ID | Description | | - | - | - | | **Diversion** | reason-drug-test-di | Applies to drug screenings | | **Follow Up** | reason-drug-test-fu | Applies to drug screenings | | **Other** | reason-drug-test-ot | Applies to drug screenings | | **Post Accident** | reason-drug-test-pa | Applies to drug screenings | | **Pre-employment** | reason-drug-test-pe | The default value for drug screenings | | **Periodic Medical** | reason-drug-test-pm | Applies to drug screenings | | **Promotion** | reason-drug-test-pr | Applies to drug screenings | | **Random** | reason-drug-test-ra | Applies to drug screenings | | **Return To Duty** | reason-drug-test-rd | Applies to drug screenings | | **Reasonable Suspicion** | reason-drug-test-rs | Applies to drug screenings | | **Transfer** | reason-drug-test-tr | Applies to drug screenings | | **Follow Up** | reason-physical-fu | Applies to physical screenings | | **New Certification** | reason-physical-nc | The default value for physical screenings | | **Recertification** | reason-physical-re | Applies to physical screenings | # Secure document type Source: https://developer.karmacheck.com/background-check-api/reference/secure-document-type System-defined IDs for all supported secure document types. The following table lists the possible types of documents that can be securely uploaded and downloaded in KarmaCheck. The secure document type, its ID, and its dashboard display name appear respectively as `secureDocumentType`, `id`, and `displayName` in the response body of the `GET /document/secure/type/list` endpoint. The ID also appears as `documentTypeId` in the response body of `GET /document/secure/list/case/id/{caseId}`, and is accepted in the request body of endpoints like `POST /document/secure/upload`. | Secure document type | ID | Display name | | - | - | - | | **tin-check-result** | 06813017-94ef-4250-9083-375935ce9dc8 | TIN Check Results | | **oig-verification-proof** | 4ad585b6-b087-11ec-9bf1-df77b62cb712 | null | | **provider-html-report** | 7d25e1de-0b46-4a6c-bd06-d0b55526af08 | null | | **identification** | 857d42f3-73b6-4588-8855-0ab49e376a84 | Identity Verification | | **candidate-disclosures-and-authorizations** | candidate-disclosures-and-authorizations | Candidate Disclosures & Authorizations | | **cbsv-authorization** | cbsv-authorization | CBSV Authorization | | **international-report** | da070d09-b52f-4423-9c94-eff458ea3aa0 | null | | **education-document** | education-document | Education Document | | **employment-document** | employment-document | Employment Document | | **ohs-breath-alcohol** | ohs-breath-alcohol | Breath Alcohol Document | | **ohs-chain-of-custody** | ohs-chain-of-custody | Drug Test Chain of Custody | | **ohs-occupational-health** | ohs-occupational-health | Occupational Health Document | | **ohs-participant-passport** | ohs-participant-passport | OHS Participant Passport | | **ohs-result-certificate** | ohs-result-certificate | OHS Result Certificate | | **search-result** | search-result | Search Result | # Service Source: https://developer.karmacheck.com/background-check-api/reference/service Complete list of all orderable KarmaCheck services and their IDs, organised by service type. The following sections list services by their type and category. The name and ID of a service appear respectively as `serviceName` and `serviceId` in the response body of API endpoints like [`GET /package/id/{packageId}/services`](/background-check-api/reference/packages/get-package-id-packageid-services). The ID is also accepted in the `excludeServices` array when excluding a service from a new case ([`POST /case/create`](/background-check-api/reference/cases/post-case-create)), as `services[].id` when adding to an order ([`POST /case/id/{caseId}/add/services`](/background-check-api/reference/cases/post-case-id-caseid-add-services)), and as `serviceId` when [providing order data](/background-check-api/guides/order-data). **Note:** Some service, service type, category, and subcategory IDs are GUIDs rather than human-readable IDs. KarmaCheck has standardized on human-readable IDs, but retained the older GUID IDs to avoid introducing breaking changes for existing integrations. ## Identity (`service-type-idv`) | Service | ID | | - | - | | Identity Verification | service-idv-id | | Identity And Liveliness Verification | service-idv-id-liveliness | | International Identity Verification | service-intl-idv | ## Screening (`30bc2c03-c8dd-409a-8da6-e0070ea6a681`) The screenings supported by KarmaCheck are listed by service category in each section below. ### Identity Verification (`service-cat-idv`) | Service | ID | | - | - | | Death Master File Search | service-death-master-file-search | | Social Media | service-social-media | | Social Security Search | service-social-security-search | | SSN Trace | 29cd44ab-a8f0-4b27-868e-dc4be88ff541 | | SSN Verification (CBSV) | service-ssn-verification-cbsv | ### Criminal Check (`service-cat-criminal`) | Service | ID | | - | - | | Bankruptcy | service-bankruptcy | | FACIS | 2c6bbd00-dce3-4ecd-ae91-b0f3dab268f7 | | Global Watchlist Search | c3080270-3e83-4eb2-a2a9-e5964645f8c5 | | OIG Exclusions Search | service-oig-exclusions-search | | Sex Offender Search | 03635d39-c9df-418f-948d-10d38a7e06db | | National Criminal Search | d8e3dbdb-c2d7-4787-9736-86fffab74da4 | | Federal Criminal Search | ee774b82-a411-4e2b-a38f-c0641bd836e7 | | County Criminal Search | fa226cb7-1214-4cdf-9296-6120a7376926 | | State Criminal Court Search | c407f6dd-523e-4627-a4d9-8f52d30ee744 | | State Criminal Search | d9381240-6230-40ec-9e11-35703e8041bc | | Federal Civil Search | service-federal-civil-search | | County Civil Search | service-county-civil-court | | State Search Colorado CAPS | service-colorado-state-search | | State Search Iowa Swing | service-iowa-swing-state-search | | State Search Mass iCORI | service-mass-iCORI-state-search | | State Search Missouri MACHS | service-missouri-state-search | | State Search New Hampshire State Police | service-new-hampshire-state-police | | Pennsylvania State Criminal Search (PATCH) | service-pa-state-criminal | | State Search Tennessee Abuse Registry | service-tennessee-abuse-registry | | State Search Tennessee Sex Offender List | service-tennessee-sex-offender-list | | State Search Washington WATCH | service-watch-state-search | | International Criminal Record Check | service-intl-criminal | | Canadian Criminal Record Check | service-canadian-criminal | ### Motor Vehicle Record Check (`service-cat-mvr`) | Service | ID | | - | - | | Motor Vehicle Report | 9a1aa5db-1292-423e-a17c-4a7ab380de58 | | Canadian Motor Vehicle Record Check | service-canadian-mvr | ### Verification (`service-cat-verification`) | Service | ID | | - | - | | Education Verification | 85307784-1f84-471a-8596-c8ea088c3a62 | | Employment Verification | 9ac65633-b4c4-4062-875c-3556db9d2a08 | | Employment Income Verification | service-employment-income | ### Professional License (`service-cat-pro-lic`) | Service | ID | | - | - | | Professional License and Certification | service-cplc | ### Occupational Health Screening (`service-cat-ohs`) This section lists OHS services by subcategory: #### Physical (`service-subcat-physical`) | Service | ID | | - | - | | Audiogram (Annual) | service-ohs-audiogram-annual | | Audiogram (Baseline) | service-ohs-audiogram-baseline | | Lab - CBC With Differential | service-ohs-cbc-differential | | Chest X-Ray 1 View | service-ohs-cxr-1-view | | Chest X-Ray 2 View | service-ohs-cxr-2-view | | DOT Physical | service-ohs-dotphysical | | Kraus Weber Lower Back Evaluation | service-ohs-kraus-weber-lower-back | | Lift Test Level 1 | service-ohs-lift-test-level-1 | | Lift Test Level 2 | service-ohs-lift-test-level-2 | | NDOT Physical | service-ohs-ndotphysical | | Pulmonary Function Test | service-ohs-pft | | OSHA Respirator/Fit to Wear Questionnaire | service-ohs-resp-osha-questionnaire | | Respirator/Mask Fit Testing - Qualitative | service-ohs-resp-fit-qualitative | | Respirator/Mask Fit Testing - Quantitative | service-ohs-resp-fit-quantitative | | TB Screening Form - Available at Concentra Clinics ONLY | service-ohs-tb-screen-form-concentra | | Vision Test Ishihara | service-ohs-vision-ishihara | | Vision Test Jaeger | service-ohs-vision-jaeger | | Vision Test Snellen | service-ohs-vision-snellen | | Vision Test Titmus | service-ohs-vision-titmus | #### TB (`service-subcat-tb`) | Service | ID | | - | - | | Quantiferon Gold / TB Blood Test | service-ohs-tb-quantiferon-gold | | T-Spot / TB Blood Test | service-ohs-tb-tspot-test | | TB Chest X-Ray | service-ohs-tb-cxr | | TB/PPD Test 1 | service-ohs-tb-ppd-test-1 | | TB/PPD Test 2 | service-ohs-tb-ppd-test-2 | | TB Skin Test | service-ohs-tb-skintest | #### Titer (`service-subcat-titer`) | Service | ID | | - | - | | Hepatitis A Titer | service-titer-hep-a | | Hepatitis B Core Antibody Titer | service-titer-hep-b-antibody | | Hepatitis B HBsAb Titer | service-titer-hep-b-hbsab | | Hepatitis B Surface Antigen Titer | service-titer-hep-b-surface | | Hepatitis C Titer | service-titer-hep-c | | MMR Titer | service-titer-mmr | | Titer Mumps Antibody IgG | service-titer-mumps-ab-igg | | Titer Rubella Antibody IgG | service-titer-rubella-ab-igg | | Varicella Titer | service-titer-var | #### Vaccination (`service-subcat-vacc`) | Service | ID | | - | - | | Hepatitis A Vaccine (Shot #1) | service-vacc-hep-a-1 | | Hepatitis A Vaccine (Shot #2) | service-vacc-hep-a-2 | | Hepatitis B Vaccine (Shot #1) | service-vacc-hep-b-1 | | Hepatitis B Vaccine (Shot #2) | service-vacc-hep-b-2 | | Hepatitis B Vaccine (Shot #3) | service-vacc-hep-b-3 | | Influenza Vaccine (Flu Shot) | service-vacc-influenza | | MMR Vaccine (Shot #1 / Booster) | service-vacc-mmr-1 | | MMR Vaccine (Shot #2) | service-vacc-mmr-2 | | Tdap Vaccine | service-vacc-tdap | | Varicella Vaccine (Shot #1 / Zoster) | service-vacc-var-1 | | Varicella Vaccine (Shot #2) | service-vacc-var-2 | #### Drug Screening (`service-subcat-drug`) | Service | ID | | - | - | | 9DSP OPA PHN (1206) | drug-service-1206-panel | | 10DSP EXP OPI2000 ECS PHN (1220) | drug-service-1220-panel | | 10DSP EXP OPI2000 OXY100 MEP100 PHN (1232) | drug-service-1232-panel | | 10DSP EXP OPI OXY PHN (1240) | drug-service-1240-panel | | 10 DSP EXP OPI2000 OXY MEP FENT PHN (1245) | drug-service-1245-panel | | 7DSP EXP OPI2000 MTD ECS OXY PHN (1407) | drug-service-1407-panel | | 7DSP EXP OPI MTD ECS OXY TCA PHN (1603) | drug-service-1603-panel | | 9DSP EXP OPI CUSTOM LEVELS OXY PHN (1680) | drug-service-1680-panel | | 10DSP EXP OPI OXY ECS 6AM PHN (1713) | drug-service-1713-panel | | COTININE (U) 200 200 - NICOTINE METB SCRN CONF (1747N) | drug-service-1747N-panel | | 10DSP NO THC PHN (1790) | drug-service-1790-panel | | 6-Monoacetylmorphine (1791N) | drug-service-1791N-panel | | 10DSP EXP OPI OXY BUP PHN (1840) | drug-service-1840-panel | | 10DSP EXP OPI OXY ECS 6AM UALC PHN (1999) | drug-service-1999-panel | | 10 Panel (20453N) | drug-service-20453N-panel | | SAP 10-50 OPI2k w OXY (21613N) | drug-service-21613N-panel | | SAP 10-50 2K+ALC NIT (22142N) | drug-service-22142N-panel | | 10DSP EXP OPI OXY ECS 6AM FENT BUP MEP PHN (2257) | drug-service-2257-panel | | 10DSP BRB PPX2000 PHN (2288) | drug-service-2288-panel | | SAP 9-50 OPI NIT MEPERIDINE (23395N) | drug-service-23395N-panel | | 10DSP NO EXP OPI PHN (2423) | drug-service-2423-panel | | 10DSP OPA BRB200 COT PHN (2444) | drug-service-2444-panel | | SAP 9 2000 (2595N) | drug-service-2595N-panel | | MedProA+Bup TCA Drug Test (27052N) | drug-service-27052N-panel | | MSAP 10-50 W OP+BUPR (27168N) | drug-service-27168N-panel | | 10 panel HHS DOT Mirror + OXY (27935N) | drug-service-27935N-panel | | 9Panel plus BUP+Ox (29741N) | drug-service-29741N-panel | | 10 PANEL OXY 6AM PHN (30066N) | drug-service-30066N-panel | | 10 Panel EXP OPI OXY ECS TS (30348N) | drug-service-30348N-panel | | MSAP 10-50 W OPI BNZ10 MDMA 6AM OXY BUP (30580N) | drug-service-30580N-panel | | 10DSP EXP OPI NO THC PHN (3119) | drug-service-3119-panel | | SAP 10-20 OPI 6AM A300 XBZ TS (32568N) | drug-service-32568N-panel | | 10DSP EXP OPI CUST LVLS OXY100 ECS200 6AM PHN (3264) | drug-service-3264-panel | | 9DSP EXP OPI OXY FENT TRAM MEP PHN (3361) | drug-service-3361-panel | | SAP 9-50 OP2K 3+6A OX EXPBZ TS (33681N) | drug-service-33681N-panel | | SAP 9-50 OP2K-300 6AM MDMA5 TS + FEN MEP NAL PENT (33720N) | drug-service-33720N-panel | | SAP9 OPI4 W TS (34583N) | drug-service-34583N-panel | | 110 Panel EXP OPI BNZ12 OXY ECS (34591N) | drug-service-34591N-panel | | SAP 10-50 W OPI+6AM MDMA ALC W TS+BUP FENT (36727N) | drug-service-36727N-panel | | SAP 10-50 OPI 6AM MDMA5 TS BUP FENT MEP TS (37212N) | drug-service-37212N-panel | | SAP 10-50 OP 2000 6AM OXY ECS BUP FENT MEP TS (37590N) | drug-service-37590N-panel | | SAP 7-50 W OPI MDMA2 BZ200 TS (38578N) | drug-service-38578N-panel | | Buprenorphine (39219N) | drug-service-39219N-panel | | SAP 10 6AM TS (39653N) | drug-service-39653N-panel | | 10DSP NO THC EXP OPI 6AM PHN (4034) | drug-service-4034-panel | | A +MQ 6AM BUP TS (42114N) | drug-service-42114N-panel | | A-8 ECS BUP NTHC TCA TS (42246N) | drug-service-42246N-panel | | SAP 3 OP2K 6AM MDMA FENT TS (42535N) | drug-service-42535N-panel | | SAP 3 OP2000 ECS 6AM FENT TS (42556N) | drug-service-42556N-panel | | 10+EXP OPI+MDMA+OXY (4400) | drug-service-4400-panel | | 10+EXP OPI+OXY+MDMA+6AM+FENT+BUP+MEP+SVT (4515) | drug-service-4515-panel | | 10DSP CST LVLS OXY100 ECS 6AM FENT BUP5 HYD100 PHN (4535) | drug-service-4535-panel | | 10+EXP OPI+EXP BENZOS+OXY (4540) | drug-service-4540-panel | | 5 Panel NO THC ECS 6AM TS (45765N) | drug-service-45765N-panel | | 9DSP EXP OPI OXY ECS BUP PHN (4717) | drug-service-4717-panel | | 10DSP EXP OPI 6AM ECS OXY BUP PHN (4767) | drug-service-4767-panel | | SAP7\_OPI2K\_MEPROBAMATE\_FENTANYL(51003N) | drug-service-51003N-panel | | 7DSP EXP OPI NO THC MTD OXY ECS FEN TRAM PHN (5113) | drug-service-5113-panel | | MSAP 10-50 W OPI BZ(10) 6AM ECS FENT TS (51603N) | drug-service-51603N-panel | | 10DSP OPA NO THC CST LVLS OXY FEN MEP TRAM PHN (5163) | drug-service-5163-panel | | 10DSP EXP OPI OXY ECS 6AM FEN MEP TRAM PHN (5273) | drug-service-5273-panel | | eCup+ 10G (5279) | drug-service-5279-panel | | eCup+ 10H (5316) | drug-service-5316-panel | | 9DSP EXP OPI NO THC OXY MEP PHN (5337) | drug-service-5337-panel | | 9DSP OPI NRC ZOL BUP BUT CAR KET ECS NLT TRM STIM PHN (5354) | drug-service-5354-panel | | 10DSP/OPA/NO THC,PPX/CST LVLS/ECS250/6AM/PHN (5369) | drug-service-5369-panel | | 10DSP EXP OPI OXY ECS 6AM BUP UALC FENT MEP PHN (5385) | drug-service-5385-panel | | 9DSP OPA NO THC CST LVLS OXY ECS 6AM BUP TCA PHN (5450) | drug-service-5450-panel | | 10DSP EXP OPI BNZ12 OXY ECS 6AM BUP FEN MEP TRAM PHN (5469) | drug-service-5469-panel | | 10DSP EXP OPI OXY MEP UALC PHN (5470) | drug-service-5470-panel | | 10DSP OPA NO THC BNZ12 OXY ECS 6AM BUP HYDR PHN (5474) | drug-service-5474-panel | | 9 OPA BNZ12 Cotinine (5485) | drug-service-5485-panel | | 10DSP OPA BNZ12 CST LVLS OXY ECS 6AM HYCD BUP PHN (5486) | drug-service-5486-panel | | 10DSP EXP OPI2000 NO THC BNZ12 OXY FENT MEP PHN (5528) | drug-service-5528-panel | | 9DSP EXP OPI NO THC OXY FENT MEP TRAM PHN (5541) | drug-service-5541-panel | | MSAP 6-50 OPI BZ10 FENT TS (57197N) | drug-service-57197N-panel | | 9DR OPIHY ORAL QUANTISAL (6031) | drug-service-6031-panel | | THC ORAL QUANTISAL (6051) | drug-service-6051-panel | | 9DSP EXP OPI NO PPX OXY ECS BUP PHN (6455) | drug-service-6455-panel | | 9DSP NO PPX BRB,BNZ200 UALC PHN (6530) | drug-service-6530-panel | | 10DSP EXP OPI OXY BUP PHN (6568) | drug-service-6568-panel | | 10DSP OPA 6AM COT PHN (6646) | drug-service-6646-panel | | 10DSP EXP OPI2000 NO THC PHN (6664) | drug-service-6664-panel | | 9DSP EXP OPI CUST LVLS OXY FENT TRAM MEP PHN (6671) | drug-service-6671-panel | | 5DSP EXP OPI BNZ OXY FENT PHN (6672) | drug-service-6672-panel | | 10DSP OPA NO THC OXY ECS 6AM FENT PHN (6675) | drug-service-6675-panel | | 9DSP EXP OPI BNZ100 OXY BUP5 PHN (6756) | drug-service-6756-panel | | 10DSP EXP OPI OXY100 MEP100 PHN (6757) | drug-service-6757-panel | | 10DSP OPA NO THC CST LVLS 6AM PHN (6794) | drug-service-6794-panel | | 9DSP OPI300 OXY MEP PHN (6948) | drug-service-6948-panel | | 9DSP/EXP OPI/NO THC, PPX/OXY/ECS/BUP/TCA/PHN (6979) | drug-service-6979-panel | | 10DSP EXP OPI NO THC CST LVLS OXY PHN (7011) | drug-service-7011-panel | | 10 Panel EXP OPI 6AM PHN (720089) | drug-service-720089-panel | | 10 Panel/OPA/NO THC/CST LVLS/6AM/PHN (720836) | drug-service-720836-panel | | 10 panel Alc+6AM(720969) | drug-service-720969-panel | | 10 Panel EXP OPI OXY ECS 6AM BUP FENT MEP PHN (722274) | drug-service-722274-panel | | 9 Panel EXP OPI BNZ12 OXY 6AM MEP PHN (722808) | drug-service-722808-panel | | 10 Panel EXP OPI CST LVLS OXY UALC0.02 PHN (724050) | drug-service-724050-panel | | 10 Panel EXP OPI CST LVLS150 OXY ECS PHN (724178) | drug-service-724178-panel | | 10 Panel EXP OPI OXY 6AM FENT PHN (724186) | drug-service-724186-panel | | 10+6AM+SVT (724528) | drug-service-724528-panel | | 10 Panel EXP OPI CST LVLS OXY ECS 6AM FENT BUP PHN (725589) | drug-service-725589-panel | | 7 Panel EXP OPI NO PCP MTD OXY ECS BUP TCA PHN (726217) | drug-service-726217-panel | | 9 Panel EXP OPI ECS NARC PH (726427) | drug-service-726427-panel | | 9 Panel EXP OP NO THC OXY ECS 6AM MEP FENT BUP PHN (726959) | drug-service-726959-panel | | 10 Panel EXP OPI OXY ECS 6AM MEP FEN TRAM BUP PHN (727457) | drug-service-727457-panel | | 9 Panel EXP OPI OXY ECS 6AM MEP FENN TRM BUP TCA PHM (727655) | drug-service-727655-panel | | 9 Panel EXP OPI NO THC OXY ECS 6AM PHN (727727) | drug-service-727727-panel | | 10 Panel OPA OXY ECS 6AM BUP MEP FENT UALC PHN (727794) | drug-service-727794-panel | | 9 Panel EXP OPI OXY ECS 6AM MEP FEN TRM BUP CAR PHN (727840) | drug-service-727840-panel | | 7 Panel OPA NO THC MTD OXY ECS 6AM PHN (727951) | drug-service-727951-panel | | 10DSP EXP OPI NO THC OXY ECS 6AM BUP PHN (7280) | drug-service-7280-panel | | STD 9+Oxy+Meperidine+Tramadol Urine (764548) | drug-service-764548-panel | | 10 PANEL EXP OPI OXY ECS MEP PHN (765437) | drug-service-765437-panel | | 9 Panel EXP OPI OXY BUP PHN (765438) | drug-service-765438-panel | | 10 Panel EXP OPI BRB,BNZ200 OXY300 PHN (765618) | drug-service-765618-panel | | 11+MDMA+Oxyco+Crt(765848) | drug-service-765848-panel | | 10 Panel Oxy Bup (768862) | drug-service-768862-panel | | Oxycodone(769) | drug-service-769-panel | | 10 Panel EXP OPI OXY BUP PHN (769399) | drug-service-769399-panel | | 9 Panel EXP OPI CST LVLS OXY MEP FENT TRAM PHN (770646) | drug-service-770646-panel | | 5 Panel Drug Test (788730) | drug-service-788730-panel | | 10 Panel EXP OPI NO THC BRB,BNZ200 PH (794152) | drug-service-794152-panel | | 10Panel+OXY+FEN TRAM MEP(795186) | drug-service-795186-panel | | URINE NICOTINE (798120) | drug-service-798120-panel | | 10DSP EXP OPI100 BNZ12 CST LVLS OXY MEP PHN (8112) | drug-service-8112-panel | | 10DSP EXP OPI OXY100 ECS FENT1.0 PHN (8144) | drug-service-8144-panel | | 10DSP OPY BZ12 NAR 6A BUP BUT CAR KET ECS NLT TRM PHN (8284) | drug-service-8284-panel | | 10DSP EXP OPI NO THC BRB,PPX200 OXY PHN (8531) | drug-service-8531-panel | | 10DSP OPA NO THC PHN (8655) | drug-service-8655-panel | | 9DSP/OPA/NO THC/OXY/ECS/BUP/TCA/PHN (8764) | drug-service-8764-panel | | 10DSP OPA 6AM PHN (8765) | drug-service-8765-panel | | 7DSP OPA NO THC MTD OXY ECS TCA PHN (8839) | drug-service-8839-panel | | 9DSP EXP OPI NO THC OXY ECS FENT TRAM MEP PHN (8863) | drug-service-8863-panel | | 17 Panel Hair EXP OPI (H17P) | drug-service-H17P-panel | | Drug Screen 10 Panel (1204) | service-drug-10-panel | | Drug Screen 10 Panel No THC (1790) | service-drug-10-panel-no-thc | | Drug Screen 10 Panel No THC + Urine Alcohol (4644) | service-drug-10p-nothc-urine-alc | | Drug Screen 10 Panel + Urine Alcohol (1208) | service-drug-10p-urine-alc | | eCup+ 5A (1200) | service-drug-1200-panel | | 10 PANEL URINE MDMA (1222) | service-drug-1222-panel | | 10DSP EXP OPI2000 COT PHN (1224) | service-drug-1224-panel | | 10 PANEL URINE MDMA OXY (1244) | service-drug-1244-panel | | 10DSP EXP OPI2000 OXY PHN (1246) | service-drug-1246-panel | | 10DSP/EXP OPI/OXY/FENT/TRAM/MEP/PHN (1249) | service-drug-1249-panel | | 10DSP EXP OPI2000 UALC MEP OXY PHN (1250) | service-drug-1250-panel | | Drug Screen 12 Panel A (3355) | service-drug-12p-a | | Drug Screen 12 Panel B (6916) | service-drug-12p-b | | Drug Screen 12 Panel C (3362) | service-drug-12p-c | | 9DSP EXP OPI OXY100 PHN (1303) | service-drug-1303-panel | | 9DSP EXP OPI 2000 OXY100 ECS PHN (1304) | service-drug-1304-panel | | 9DSP EXP OPI2000 CST LVLS ECS 6AM MEP OXY FEN TRM PHN (1308) | service-drug-1308-panel | | 9DSP EXP OPI2000 AMP500 COC150 ECS 6AM NARC PHN (1309) | service-drug-1309-panel | | 9DSP EXP OPI2000 ECS MEP100 OXY100 TRAM100 PHN (1319) | service-drug-1319-panel | | 9DSP EXP OPI MEP OXY PHN (1324) | service-drug-1324-panel | | 9DSP EXP OPI2000 NARC PHN (1328) | service-drug-1328-panel | | 9DSP EXP OPI2000 UALC KET SOMA MEP OXY TRAM PHN (1351) | service-drug-1351-panel | | 9DSP EXP OPI2000 UALC OXY MEP TRAM PHN (1355) | service-drug-1355-panel | | 10DSP EXP OPI OXY BUP PHN (1401) | service-drug-1401-panel | | 10DSP EXP OPI BRB200 6AM PHN (1408) | service-drug-1408-panel | | 10DSP EXP OPI OXY MEP TRAM PHN (1431) | service-drug-1431-panel | | 10DSP OXY MEP COT PHN (1465) | service-drug-1465-panel | | 10DSP EXP OPI CUSTOM LEVELS OXY ECS 6AM PHN (1624) | service-drug-1624-panel | | 10DSP EXP OPI BRB PPX300 200 PHN (1630) | service-drug-1630-panel | | 10 PANEL URINE EXP OPI OXY MDMA BUP (1693) | service-drug-1693-panel | | Urine Alcohol 0.02g%/0.02g% (17) | service-drug-17-panel | | 9DSP CUSTOM LEVELS EXP OPI OXY FENT MEP COT PHN (1705) | service-drug-1705-panel | | 10DSP BRB BNZ200 PHN (1734) | service-drug-1734-panel | | 10DSP EXP OPI OXY COT PHN (1758) | service-drug-1758-panel | | 9DSP EXP OPI BRB200 ECS 6AM PHN (1780) | service-drug-1780-panel | | 10DSP EXP OPI CUSTOM LEVELS OXY PHN (1787) | service-drug-1787-panel | | 10DSP TCA PHN (1871) | service-drug-1871-panel | | SAP 10-50, OP300, W/NIT (19259N) | service-drug-19259N-panel | | 9DSP OXY ECS TCA PHN (1937) | service-drug-1937-panel | | SAP 10-50+OXYC/MEP/N | service-drug-19507N-panel | | 10DSP EXP OPI OXY100 ECS300 TRAM100 MEP100 COT PHN (1997) | service-drug-1997-panel | | SAP 10-50, EXP OP, W NIT (20014N) | service-drug-20014N-panel | | 10 Panel Drug Test Cotinine (Quest 20286N) | service-drug-20286N-panel | | SAP 9-50 OPI/MDMA Urine (Quest 21574N) | service-drug-21574N-panel | | SAP 10-50 MDMA OXY N (21609N) | service-drug-21609N-panel | | 9DSP EXP OPI OXY BUP PHN (2260) | service-drug-2260-panel | | 9DSP EXP OPI OXY100 ECS 6AM PHN (2338) | service-drug-2338-panel | | 9DSP EXP OPI BRB, BNZ200 OXY ECS PHN (2344) | service-drug-2344-panel | | 9DSP EXP OPI OXY MEP PHN (2419) | service-drug-2419-panel | | 10DSP EXP OPI OXY ECS TCA PHN (2446) | service-drug-2446-panel | | 9DR OPA OXCD MDMA BUP FEN (2478) | service-drug-2478-panel | | 10DSP NO THC CUST LVLS OXY ECS PHN (2479) | service-drug-2479-panel | | 9 Panel + OXY + ECS (25749N) | service-drug-25749N-panel | | MSAP 10 OPI MDMA BZ Urine (Quest 26769N) | service-drug-26769N-panel | | SAP 9-50/2K-3+OX/MEP (26795N) | service-drug-26795N-panel | | 9 Panel Ox (Quest 27061N) | service-drug-27061N-panel | | SAP 10-50 W/OP+ALC/T (27348N) | service-drug-27348N-panel | | SAP 10-50 Methaqualone Antidepressants (27355N) | service-drug-27355N-panel | | SAP 8-50/2K OXY ADEP (Quest 27387N) | service-drug-27387N-panel | | SAP 10 MDMA Oxy/THC20/TS Drug Test (Quest 27420N) | service-drug-27420N-panel | | MSAP 10 OPI MEP BZ Urine (Quest 27441N) | service-drug-27441N-panel | | SAP 9 2K+MDMA5 6MAM (27536N) | service-drug-27536N-panel | | SAP 10-50 OP+MDA/6A/T (27565N) | service-drug-27565N-panel | | SAP 10-50/2K+MDA5/TS (27800N) | service-drug-27800N-panel | | SAP10-50 OP+6A/MDA/T (28558N) | service-drug-28558N-panel | | SAP 10-50 W OPI MDMA2 W TS ANTIDEPRESSANT (28707N) | service-drug-28707N-panel | | SAP 10-50/300 EXPBZ (28718N) | service-drug-28718N-panel | | SAP 9-50 OPI 6AM TS Drug Test (Quest 28847N) | service-drug-28847N-panel | | SAP 10-50 OP+6A MD TS (28950N) | service-drug-28950N-panel | | SAP 10-50/2000+OXY W/TS + BUPRENORPHINE (29339N) | service-drug-29339N-panel | | SAP 9-50 OP 6AM MDA EXPBZ TS (30668N) | service-drug-30668N-panel | | 9 Panel Mep Ox 6AM (Quest 30842N) | service-drug-30842N-panel | | 10DSP FENT MEP TRAM PHN (3108) | service-drug-3108-panel | | eCup+ 6A (3121) | service-drug-3121-panel | | eCup+ 7B (3122) | service-drug-3122-panel | | eCup+ 8B (3123) | service-drug-3123-panel | | eCup+ 9D (3124) | service-drug-3124-panel | | eCup+ 10A (3125) | service-drug-3125-panel | | 9DSP OXY ECS COT PHN (3137) | service-drug-3137-panel | | MedPro A MQ 6AM BUP Drug Test (Quest 32078N) | service-drug-32078N-panel | | 10DSP EXP OPI OXY ECS 6AM UALC PHN (3219) | service-drug-3219-panel | | SUBSTANCE ABUSE PANEL 10- 50,OP2M-3,A5,MDA,C15,OX (32364N) | service-drug-32364N-panel | | XC 10 Panel Basic (3265) | service-drug-3265-panel | | SAP 10 OPI2K 6AM BUP (Quest 32743N) | service-drug-32743N-panel | | MSAP 10-50 W OPI+6AM MDMA W TS+COTININE (32961N) | service-drug-32961N-panel | | MSAP 9-20 OPI+6AM/MDMA W/TS+COTININE 200/200 (33210N) | service-drug-33210N-panel | | SAP 7-50 OPI MDMA5/TS + BUP & ANTIDEPRESSANTS (33223N) | service-drug-33223N-panel | | SAP 9-50 w OPI+6AM MDMA5 W TS+BUP (33475N) | service-drug-33475N-panel | | HPP COMP I+MEQ/BNZ12/COT200/FENT/MEP/TRAM (33476N) | service-drug-33476N-panel | | MEDPRO B 6AM MQ BUP FENT (33529N) | service-drug-33529N-panel | | 8DSP EXP OPI OXY TCA PHN (3366) | service-drug-3366-panel | | SAP 8-50/OP300+MDMA5/OXY/TS+BUPRENORPHINE/FENTANYL (33692N) | service-drug-33692N-panel | | 10DSP EXP OPI OXY 6AM FENT BUP TRAM MEP PHN (3377) | service-drug-3377-panel | | SAP 10-50/2000+OXY/MDMA5 W/TS + BUPRENORPHINE (34041N) | service-drug-34041N-panel | | 10DSP EXP OPI OXY 6AM FENT PHN (3417) | service-drug-3417-panel | | eCup+ 9A (3477) | service-drug-3477-panel | | QD - 5 panel NDOT STANDARD (35105N) | service-drug-35105N-panel | | SAP 9-50 W NIT (35186N) | service-drug-35186N-panel | | 10 Panel Urine (Quest 35190N) | service-drug-35190N-panel | | SUBSTANCE ABUSE PANEL 10- 50, PLUS W/NITRITE (35360N) | service-drug-35360N-panel | | 11 Panel Drug Test (Quest 35639N) | service-drug-35639N-panel | | 4 Panel (amp,coc,opi,pcp) (35765N) | service-drug-35765N-panel | | SUBSTANCE ABUSE PANEL 9 PLUS #9S W/NITRITE (35786N) | service-drug-35786N-panel | | SAP 10-50 OPI4 (EXPBZ) W TS (35921N) | service-drug-35921N-panel | | 6 Panel MDA Oxy Bup (Quest 36563N) | service-drug-36563N-panel | | MEDPRO B (NTHC)+BUP FENT ANTIDEPRESSANTS (36982N) | service-drug-36982N-panel | | Urine Nicotine 500 500 (3700) | service-drug-3700-panel | | MSAP 10-50 W/OPI+MDA 6A BUP FEN MEP TRAM (37253N) | service-drug-37253N-panel | | HPP COMP I 6A MQ MDA2 BUP (37394N) | service-drug-37394N-panel | | SUBSTANCE ABUSE PANEL 10-20, OP2000 + MDMA (38885N) | service-drug-38885N-panel | | 10 Panel Alc Drug Test (Quest 39421N) | service-drug-39421N-panel | | MSAP PANEL 9 W/OPI BZ(10) MDMA+6AM/BUP/TS (39473N) | service-drug-39473N-panel | | SAP 9 OP2000 W TS (39559N) | service-drug-39559N-panel | | eCup+ 4A (4045) | service-drug-4045-panel | | 10DSP EXP OPI2000 CST LVLS OXY100 ECS 6AM HYD100 PHN (4089) | service-drug-4089-panel | | 9DSP EXP OPI2000 CST LVL OXY100 ECS 6AM HYD100 PHN (4148) | service-drug-4148-panel | | SAP 5-50 MDMA/6A/OX Drug Test (Quest 41616N) | service-drug-41616N-panel | | 9DSP EXP OPI CST LVLS OXY100 ECS 6AM HYD100 PHN (4250) | service-drug-4250-panel | | 10DSP EXP OPI OXY ECS TRAM MEP PHN (4277) | service-drug-4277-panel | | 10DSP NO THC BRB BNZ200 PHN (4343) | service-drug-4343-panel | | 9DSP EXP OPI NO THC NO PPX BRB, BNZ 200 OXY150 PHN (4344) | service-drug-4344-panel | | ALCOHOL, ETHYL (B) .01% (443N) | service-drug-443N-panel | | 9DSP CUST LVLS NO PPX OXY ECS TCA PHN (4461) | service-drug-4461-panel | | SAP 5-50 OP2M A500 MDMA C15 T (Quest 45109N) | service-drug-45109N-panel | | SUBSTANCE ABUSE PANEL 10- 50,OP2M,A500,MDMA,C15,T (45190N) | service-drug-45190N-panel | | 9DSP EXP OPI OXY 6AM MEP PHN (4520) | service-drug-4520-panel | | 9DSP EXP OPI OXY 6AM MEP PHN (4545) | service-drug-4545-panel | | 9DSP EXP OPI NO PPX OXY ECS 6AM PHN (4559) | service-drug-4559-panel | | SAP 10-50 OP MDMA T (Quest 45639N) | service-drug-45639N-panel | | 10 PANEL W-MDMA EXP-OPI 6AM OXY BUP FENT MEP TRAM (4586) | service-drug-4586-panel | | 10DSP EXP OPI OXY 6AM UALC FENT MEP PHN (4635) | service-drug-4635-panel | | 9DSP EXP OPI NO PPX OXY FENT PHN (4686) | service-drug-4686-panel | | 10DSP EXP OPI NO THC CUST LVLS OXY ECS FENT PHN (4719) | service-drug-4719-panel | | Drug Screen 5 Panel (1200) | service-drug-5-panel | | Drug Screen 5 Panel No THC (1687) | service-drug-5-panel-no-thc | | DOT Panel (5000) | service-drug-5000-panel | | MEDPRO B+6A BUP FENT ANTIDEPRESSANTS TS (50690N) | service-drug-50690N-panel | | MSAP 10-50 MDMA TRAMADOL FENTANYL (51511N) | service-drug-51511N-panel | | 7DSP/EXP OPI/NO THC/MTD/OXY/FENT/MEP/PHN (5266) | service-drug-5266-panel | | 9DSP EXP OPI/OXY/ECS/6AM/FEN/BUP/TRAM/CAR/MEP/PHN (5303) | service-drug-5303-panel | | 9DSP EXP OPI/BRB200/BNZ100/OXY/ECS/BUP/TRAM/MEP/PHN (5304) | service-drug-5304-panel | | 10DSP EXP OPI NO THC CST LVLS OXY ECS 6AM UALC PHN (5577) | service-drug-5577-panel | | HPP I Cotinine TS (56551N) | service-drug-56551N-panel | | MSAP PANEL 10-50, W/OPI BZ(10),TS/FEN (56770N) | service-drug-56770N-panel | | MSAP PANEL 10-50, W/OPI MDA,BZ10,MP,TR,FN,AL,TS (56981N) | service-drug-56981N-panel | | MEDPRO B+BUPRENORPHINE,FENTANYL & ANTIDEPRESSANTS (57149N) | service-drug-57149N-panel | | MSAP 10 MDA MEP FEN TRAM Drug Test (Quest 57528N) | service-drug-57528N-panel | | MSAP PANEL 9-50, W/OPI BZ(10),MEP,FEN,TS (57796N) | service-drug-57796N-panel | | Alcohol, Ethyl Urine Drug Test (Quest 5840N) | service-drug-5840N-panel | | 10 Panel OXY MEP FEN (Quest 58939N) | service-drug-58939N-panel | | Medical Professional Drug Test (Quest 59271N) | service-drug-59271N-panel | | Drug Screen 5 Panel Expanded Opiates Hair (H5PEO) | service-drug-5p-eo-hair | | Drug Screen 5 Panel No THC + Urine Alcohol (4306) | service-drug-5p-nothc-urine-alc | | Drug Screen 5 Panel Omega Hair (H5P) | service-drug-5p-omega-hair | | Drug Screen 5 Panel Oral (514) | service-drug-5p-oral | | Drug Screen 5 Panel + Urine Alcohol (1380) | service-drug-5p-urine-alc | | 9DSP NO THC OXY BUP PHN (6409) | service-drug-6409-panel | | 10DSP EXP OPI OXY ECS 6AM TRAM MEP PHN (6501) | service-drug-6501-panel | | SAP 10-50 SYOP 6AM TS (Quest 65190N) | service-drug-65190N-panel | | 5DSP EXP OPI NO PCP BNZ MTD OXY ECS BUP TCA PHN (6553) | service-drug-6553-panel | | 9DSP OXY FENT TRAM MEP PHN (6562) | service-drug-6562-panel | | SAP 9 SYN OP,6AM,MDMA,OXY,TS (65786N) | service-drug-65786N-panel | | 10DSP EXP OPI NO THC OXY UALC MEP PHN (6583) | service-drug-6583-panel | | 9DSP EXP OPI OXY ECS 6AM MTD PPX150 PHN (6699) | service-drug-6699-panel | | 10DSP OPA NO THC OXY UALC0.04 PHN (6730) | service-drug-6730-panel | | SAP 9-50 SYOP BRZ2 TS (Quest 67423N) | service-drug-67423N-panel | | 10DSP EXP OPI OXY 6AM BUP FEN PHN (6785) | service-drug-6785-panel | | 9DSP OPA OXY FENT MEP TRAM PHN (6876) | service-drug-6876-panel | | Urine Nicotine 200/200 (6884) | service-drug-6884-panel | | OXY100 ECS FENT PHN (6911) | service-drug-6911-panel | | 9DSP EXP OPI NO PPX BUP UALC PHN (6961) | service-drug-6961-panel | | 7DSP EXP OPI NO PCP BRB MTD OXY ECS BUP PHN (6986) | service-drug-6986-panel | | Drug Screen 7 Panel (1203) | service-drug-7-panel | | Drug Screen 7 Panel No THC (2480) | service-drug-7-panel-no-thc | | 7DSP EXP OPI NO THC MTD OXY PHN (7136) | service-drug-7136-panel | | 10DSP EXP OPI BRB,BNZ200 OXY ECS UALC PHN (7153) | service-drug-7153-panel | | Alcohol, Ethyl Urine Drug Test (LabCorp 716167) | service-drug-716167-panel | | 7DSP OPI300 MTD OXY PHN (7194) | service-drug-7194-panel | | 10 Panel Opi300 (LabCorp 720498) | service-drug-720498-panel | | 9 Panel EXP OPI OXY ECS 6AM HYDR (LabCorp 720762) | service-drug-720762-panel | | 9 Panel EXP OPI OXY 6AM FENT PHN (720803) | service-drug-720803-panel | | 10 Panel 6AM MDA Bup (LabCorp 720816) | service-drug-720816-panel | | 10 Panel 6am Oxy Mep Drug Test (LabCorp 721373) | service-drug-721373-panel | | 9 Panel MDA 6AM Drug Test (LabCorp 721646) | service-drug-721646-panel | | 4 Panel (amp,coc,opi,pcp) (721864) | service-drug-721864-panel | | 10 Panel Bup MDA OXY 6am (LabCorp 722218) | service-drug-722218-panel | | 9 Panel OPA OXY ECS 6AM BUP PHN (722281) | service-drug-722281-panel | | 7 Panel OPI300/MTD/OXY/PHN (723073) | service-drug-723073-panel | | 9 Panel Fen Mep Nal Pen 6am Drug Test (LabCorp 723297) | service-drug-723297-panel | | 9 Panel EXOPA OXY ECS 6AM HYDR PHN (723344) | service-drug-723344-panel | | 9DSP EOPI ECS 6AM TRM BUP KET BUT CAR NALT NARC PHN (723589) | service-drug-723589-panel | | 10 Panel Cot MDA Ox 6am Drug Test (LabCorp 723990) | service-drug-723990-panel | | 10 Panel Bup Fen MDA Drug Test (LabCorp 724301) | service-drug-724301-panel | | 10 ALC 6AM SVT (724490) | service-drug-724490-panel | | 10 Panel EXP OPI NO THC OXY ECS 6AM PHN (724695) | service-drug-724695-panel | | 10DSP EXP OPI NO BARB PCP PPX OXY ECS BUP TCA (LabCorp 724779) | service-drug-724779-panel | | 10 Panel OPA NO THC CST LVLS ECS 6AM PHN (724941) | service-drug-724941-panel | | 9 Panel Mep Fen Nal Pen Drug Test (LabCorp 724993) | service-drug-724993-panel | | 9 Panel EXP OPI/6AM/ECS/OXY/PHN (725055) | service-drug-725055-panel | | 10 PANEL OPA CSTLVLS (725110) | service-drug-725110-panel | | 10 Panel OPA CST LVLS OXY ECS 6AM BUP TCA PHN (725140) | service-drug-725140-panel | | 9 Panel W/MDMA + MEP + OXY + 6AM + TRAM + FENT + BUP (725141) | service-drug-725141-panel | | 9 PANEL EXP OPI NO PCP NO BRB NOPPX OXY ECS BUP PHN (LabCorp 725648) | service-drug-725648-panel | | 9 Panel BNZ12 OXY ECS 6AM FEN BUP TRAM SOMA MEP PHN (725876) | service-drug-725876-panel | | 10 Panel BNZ12 OXY ECS FENT BUP TRAM MEP PHN (725914) | service-drug-725914-panel | | 9 Panel EXP OPI NO THC TRAM MEP PHN (726613) | service-drug-726613-panel | | 9 Panel OPA NO THC CST LVLS OXY ECS 6AM BUP TCA PHN (729547) | service-drug-729547-panel | | 9 Panel Exp Opi Oxy Tram Fent Mep (LabCorp 765465) | service-drug-765465-panel | | 9 EXP OPI OXY ECS 6AM PHN (LabCorp 765533) | service-drug-765533-panel | | STD 10 Op300 Tram Oxy Mep Urine (LabCorp 765564) | service-drug-765564-panel | | 10 Panel Oxycodone Drug Test (LabCorp 765567) | service-drug-765567-panel | | 10 Panel EXP OPI OXY ECS 6AM PHN (LabCorp 768929) | service-drug-768929-panel | | 9 Panel EXP OPI OXY ECS FENT TRAM MEP COT PHN (LabCorp 769130) | service-drug-769130-panel | | 10 Panel OXY PHN (769163) | service-drug-769163-panel | | 10 Panel Mep Oxy Fen Drug Test (LabCorp 769327) | service-drug-769327-panel | | 10 Panel EXP OPI UALC PHN (788589) | service-drug-788589-panel | | 5 Panel Standard (788730) | service-drug-788730-panel | | Std 10 Nicotine Crt (LabCorp 789486) | service-drug-789486-panel | | 10 Panel Urine (LabCorp 789901) | service-drug-789901-panel | | 10 panel minus THC (LabCorp 790020) | service-drug-790020-panel | | 10 panel PH NIT (791946) | service-drug-791946-panel | | 10 Panel Exp Opi (792560) | service-drug-792560-panel | | 10 Panel/EXP OPI (792668) | service-drug-792668-panel | | 9 Panel OPA OXY ECS PHN (793064) | service-drug-793064-panel | | 10 Panel OPA OXY MEP PHN (793533) | service-drug-793533-panel | | 10 Panel OPA NO THC PHN (793614) | service-drug-793614-panel | | 10 Panel EXP OPI ECS 6AM PHN (794137) | service-drug-794137-panel | | 8 Panel Oxy TCA (LabCorp 795373) | service-drug-795373-panel | | 10DSP EXP OPI OXY ECS TRAM MEP PHN (799452) | service-drug-799452-panel | | Drug Screen 7 Panel 6AM A (1736) | service-drug-7p-6am-a | | Drug Screen 7 Panel 6AM B (2490) | service-drug-7p-6am-b | | Drug Screen 7 Panel Omega Hair (H7P) | service-drug-7p-omega-hair | | Drug Screen 7 Panel + Urine Alcohol (1384) | service-drug-7p-urine-alc | | 9DSP EXP OPI NO THC OXY BUP PHN (8130) | service-drug-8130-panel | | 7DSP EXP OPI NO THC OXY200 PHN (8193) | service-drug-8193-panel | | 9DSP OPA NO THC OXY ECS BUP PHN (8213) | service-drug-8213-panel | | 10DSP EXP OPI OXY ECS 6AM FEN BUP TRAM MEP PHN (8577) | service-drug-8577-panel | | 7DR OPIHV OXCD MDMA BUP (8638) | service-drug-8638-panel | | Drug Screen 9 Panel (1205) | service-drug-9-panel | | Drug Screen 9 Panel No THC (4365) | service-drug-9-panel-no-thc | | Drug Screen 9 Panel No THC + Urine Alcohol (4318) | service-drug-9p-nothc-urine-alc | | Drug Screen 9 Panel Oral (1509) | service-drug-9p-oral | | Drug Screen 9 Panel + Urine Alcohol (1207) | service-drug-9p-urine-alc | | DOT Breath Alcohol Test | service-drug-dot-alcohol | | DOT Drug Screen (1000) | service-drug-dot-collection | | eCup+ 9K (8756) | service-drug-e8756-panel | | Breath Alcohol Test | service-drug-non-dot-alcohol | | 7DSP OPA NO THC CUST LVLS MTD OXY100 PHN (8756) | service-drug-s8756-panel | ## Payment (`service-type-payment`) | Service | ID | | - | - | | Stripe Payment | service-payment-stripe | ## Shipment (`service-type-shipment`) | Service | ID | | - | - | | Mask Shipment | service-mask-shipment | ## Legal (`service-type-legal`) | Service | ID | | - | - | | e-Signature | 1dfeae0d-6333-47ab-83f7-861486499ed2 | | Disclosure | 92b69205-707f-4e16-b18b-5bd3cbec9005 | | FCRA | 9b1e8952-e1b6-472d-88ea-eb067f960051 | | Custom AB Disclosure 1 | service-legal-custom-ab-disc-1 | | Custom AB Disclosure 2 | service-legal-custom-ab-disc-2 | | Custom Disclosure | service-legal-custom-disclosure | | Custom Dynamic Disclosure | service-legal-custom-dyn-disc | | International Disclosure | service-legal-intl-disclosure | | Canada Disclosure | service-legal-canada-disclosure | # Service type and categories Source: https://developer.karmacheck.com/background-check-api/reference/service-type System-defined IDs for all service types, categories, and subcategories. Every KarmaCheck service belongs to a type and a category. ## Type The following table lists the possible types of services. The service type and its ID appear respectively as `serviceTypeName` and `serviceTypeId` in the response body of API endpoints like [`GET /case/id/{caseId}/services/{serviceType}`](/api-reference/cases/get-services-for-case). The ID is also accepted in the path parameter of endpoints like [`GET /case/id/{caseId}/data/{serviceTypeId}`](/api-reference/cases/get-case-data-by-case-id). | Service type | ID | | - | - | | **Screening** | 30bc2c03-c8dd-409a-8da6-e0070ea6a681 | | **Legal** | a3b74b1b-b665-40be-bad2-2a49c801cf3f | | **Payment** | service-type-payment | | **Identity** | service-type-idv | | **Shipment** | service-type-shipment | | **Document Processing** | service-type-document-processing | ## Category The following table lists the possible categories that a service can belong to. The service category and its ID appear respectively as `serviceCategory` and `serviceCategoryId` in the response body of API endpoints like [`GET /case/id/{caseId}/services/{serviceType}`](/api-reference/cases/get-services-for-case). | Service category | ID | | - | - | | **Identity Verification** | service-cat-idv | | **Criminal Check** | service-cat-criminal | | **Motor Vehicle Record Check** | service-cat-mvr | | **Verification** | service-cat-verification | | **Occupational Health Screening** | service-cat-ohs | | **Professional License** | service-cat-pro-lic | ## Subcategory Services under the Occupational Health Screening (OHS) category are further categorized by a subcategory. The following table lists the possible subcategories that an OHS service can belong to. The service subcategory and its ID appear respectively as `serviceSubCategory` and `serviceSubCategoryId` in the response body of API endpoints like [`GET /case/id/{caseId}/services/{serviceType}`](/api-reference/cases/get-services-for-case). | Service subcategory | ID | | - | - | | **Physical** | service-subcat-physical | | **Drug Screening** | service-subcat-drug | | **TB** | service-subcat-tb | | **Titer** | service-subcat-titer | | **Vaccination** | service-subcat-vacc | | **Nursing** | service-subcat-nursing | ## Hierarchy The following tree shows how types, categories, and subcategories relate to each other. ```text theme={null} Screening (30bc2c03-c8dd-409a-8da6-e0070ea6a681) |-- Criminal Check (service-cat-criminal) |-- Motor Vehicle Record Check (service-cat-mvr) |-- Verification (service-cat-verification) |-- Identity Verification (service-cat-idv) |-- Professional License (service-cat-pro-lic) |-- Nursing (service-subcat-nursing) |-- Professional Certificate (service-cat-pro-cert) |-- Nursing (service-subcat-nursing) |-- Occupational Health Screening (service-cat-ohs) |-- Drug Screening (service-subcat-drug) |-- Physical (service-subcat-physical) |-- TB (service-subcat-tb) |-- Titer (service-subcat-titer) |-- Vaccination (service-subcat-vacc) Identity (service-type-idv) |-- Identity Verification (service-cat-idv) Legal (a3b74b1b-b665-40be-bad2-2a49c801cf3f) Payment (service-type-payment) Shipment (service-type-shipment) Document Processing (service-type-document-processing) ``` Only the **Screening** and **Identity** types use categories and subcategories. The remaining types (Legal, Payment, Shipment, Document Processing) do not currently have categories. The **Identity Verification** category appears under both the Screening and Identity types. SSN-based checks (SSN Trace, SSN Verification) use the Screening type, while biometric identity checks (Identity Verification, Identity & Liveness) use the Identity type. # Testimony type Source: https://developer.karmacheck.com/background-check-api/reference/testimony-type System-defined IDs for all testimony types. The following table lists the possible types of testimonies for a case. The testimony type ID is accepted as `testimonyTypeId` in the request body of API endpoints like `POST /testimony/create/case/id/{caseId}`. | Testimony type | ID | | - | - | | **Education** | 19edb27e-5bfd-4c0f-888a-a5130b2f5250 | | **Employment** | aa99dc08-0238-4050-9176-bf322e077f71 | | **Driver's License** | 3d83f3a0-fb6c-4c5a-a4dc-4dbf6a663870 | | **Parental Consent** | 994bb728-f06d-4e4d-b689-f180adfb6ca5 | | **Address** | 4143f0d4-4e3d-4ff7-b40a-9a26b569cf32 | | **Professional License and Certification** | testimony-type-cplc | # Case data status change Source: https://developer.karmacheck.com/background-check-api/reference/webhooks/events/case-data-status-change Webhook event payload and properties for the casedata.statuschange event. The `casedata.statuschange` event is sent to the webhook whenever the status of a service changes. Note that additional events can occur even after a service reaches a completion status. For instance, you might receive a notification when a service is complete, then receive a subsequent webhook indicating that the status of the service changed back to pending due to a review or adjudication. ## Payload example ```json theme={null} { "messageId": "3d054561-e6ea-c877-3201-57256af6f1ef", "event": "casedata.statuschange", "apiTrackingCode": null, "apiTrackingUser": null, "eventObject": { "id": "2f209172-e2df-4b78-a644-c950554fd5f8", "description": "SSN Trace", "caseId": "3edec2585-29fd-4e85-ae5f-b251d1007ecd", "storageId": "def2d21d-d1a2-331dd-a4fg-dsb3aeddf713", "details": {}, "serviceId": "29cd44ab-a8f0-4b27-868e-dc4be88ff541", "serviceName": "SSN Trace", "serviceTypeId": "30bc2c03-c8dd-409a-8da6-e0070ea6a681", "serviceTypeName": "Screening", "statusId": "8f29e0de-10f2-4c84-8379-16c6eb7cdf64", "status": "pending", "pendingStatusId": null, "pendingStatus": null, "crStamp": "2024-05-25T19:16:55.000Z", "modStamp": "2024-05-25T19:18:11.000Z", "groupProfileId": "dd2346e4-ed17-2c66-ce22-06ae7e372fd2", "candidateId": "fe2d4d28-229b-4f4d-c1d6-fbedcb189275", "candidateEmail": "lee@example.com", "secondaryStatusId": null, "secondaryStatus": null, "dataKey": null, "serviceCategoryId": "service-cat-idv", "serviceCategory": "Identity Verification", "serviceSubCategoryId": null, "serviceSubCategory": null, "serviceProviderId": "ddeab230-db41-245b-af22-1d2e24dfb139" } } ``` ## `CaseDataEvent` eventObject properties | Property | Type | Required | Description | | - | - | - | - | | `id` | `string` | `Required` | Unique identifier of the case data record. | | `description` | `string` | `Required` | Description associated with the service for this case data record. | | `caseId` | `string` | `Required` | Case ID. | | `storageId` | `string` | `Required` | Storage ID for the case data record. | | `details` | `object` | `Required` | Service-specific details object; fields vary by service type. | | `serviceId` | `string` | `Required` | Service ID represented by the case data record. | | `serviceName` | `string` | `Required` | Service name. | | `serviceTypeId` | `string` | `Required` | Service type ID. | | `serviceTypeName` | `string` | `Required` | Service type name. | | `statusId` | `string` | `Required` | Case data status ID. | | `status` | `string` | `Required` | Case data status name. | | `pendingStatusId` | `string \| null` | `Required` | Pending status ID, when present. | | `pendingStatus` | `string \| null` | `Required` | Pending status name, when present. | | `crStamp` | `string` | `Required` | Creation timestamp. | | `modStamp` | `string` | `Required` | Last modified timestamp. | | `groupProfileId` | `string` | `Required` | Group profile ID. | | `candidateId` | `string` | `Required` | Candidate ID. | | `candidateEmail` | `string` | `Required` | Candidate email. | | `secondaryStatusId` | `string \| null` | `Required` | Secondary status ID, when present. | | `secondaryStatus` | `string \| null` | `Required` | Secondary status name, when present. | | `dataKey` | `string \| null` | `Required` | Optional service-specific data key. | | `serviceCategoryId` | `string` | `Required` | Service category ID. | | `serviceCategory` | `string` | `Required` | Service category name. | | `serviceSubCategoryId` | `string \| null` | `Required` | Service subcategory ID, when present. | | `serviceSubCategory` | `string \| null` | `Required` | Service subcategory name, when present. | | `serviceProviderId` | `string` | `Required` | Service provider ID. | # Case status change Source: https://developer.karmacheck.com/background-check-api/reference/webhooks/events/case-status-change Webhook event payload and properties for the case.statuschange event. The `case.statuschange` event is sent to the webhook whenever the status of a case changes. Note that additional events can occur even after a case reaches a completion status. For instance, you might receive a notification when a case is complete, then receive a subsequent webhook indicating that the case reverted to a pending status because an additional service was added. ## Payload example ```json theme={null} { "messageId": "d824e0f6-92fc-c05b-abd3-ebda5cd2a028", "event": "case.statuschange", "apiTrackingCode": null, "apiTrackingUser": null, "eventObject": { "id": "3edec2585-29fd-4e85-ae5f-b251d1007ecd", "crStamp": "2024-05-25T19:16:55.000Z", "crUserId": "dec23950-32d3-4d85-9ef1-2a77d14d9d17", "caseTypeId": "cde61186-4f22-45f4-9e19-429061365bce", "caseType": "Background Check", "caseStatusId": "22334455-937e-46b1-8799-887766554433", "caseStatus": "Complete", "secondaryCaseStatusId": null, "secondaryStatus": null, "resultType": "Open", "modStamp": "2024-05-25T19:18:11.000Z", "candidateId": "fe2d4d28-229b-4f4d-c1d6-fbedcb189275", "candidateEmail": "lee@example.com", "candidateGivenName": "Lee", "candidateFamilyName": "Johnson", "packageId": "d04dece1-1ea5-43fc-2832-231a5d23a08b", "packageName": "Basic Check", "packageCompanyName": null, "billingReferenceId": "f04dece1-1ea2-53fc-1823-231a5d23a08b", "groupProfileId": "dd2346e4-ed17-2c66-ce22-06ae7e372fd2", "resultTypeId": "8c94f0d9-57c9-4c7b-be95-5ec309cff330", "caseInvitationId": "d18286a6-2920-1397-bdef-8118b939305d", "invitationStatusId": "d1962405-dd97-48f2-bede-530c2895481f", "invitationStatusName": "completed", "invitationGivenName": "Lee", "invitationFamilyName": "Johnson", "companyId": "dde1eafd-232b-39e8-dff4-f1be061eba2c", "companyName": "Example Company", "companyCommonName": null, "companyLogo": null, "archived": 0, "serviceGroupId": "b3582ef5-72b7-4e48-9973-858464f01141", "invitationEmail": "lee@example.com", "isMinorCandidate": 0, "hasParentalConsent": 0, "groupName": "Default", "adverseActionId": null, "adverseActionStatusName": null, "adverseActionStatusId": null, "orderedStamp": "2024-05-25T19:16:55.000Z", "beginOnboardingStamp": null, "completedOnboardingStamp": "2024-05-25T19:16:56.000Z", "beginProcessingStamp": "2024-05-25T19:16:57.000Z", "completedInitialProcessingStamp": "2024-05-25T19:18:11.000Z", "completedLatestProcessingStamp": "2024-05-25T19:18:11.000Z" } } ``` ## `CaseEvent` eventObject properties | Property | Type | Required | Description | | - | - | - | - | | `id` | `string` | `Required` | Unique identifier of the case. | | `crStamp` | `string` | `Required` | Creation timestamp. | | `crUserId` | `string` | `Required` | User ID that created the case. | | `caseTypeId` | `string` | `Required` | Case type ID. | | `caseType` | `string` | `Required` | Case type name. | | `caseStatusId` | `string` | `Required` | Current case status ID. | | `caseStatus` | `string` | `Required` | Current case status name. | | `secondaryCaseStatusId` | `string \| null` | `Required` | Secondary status ID, when present. | | `secondaryStatus` | `string \| null` | `Required` | Secondary status name, when present. | | `resultTypeId` | `string` | `Required` | Result type ID. | | `resultType` | `string` | `Required` | Result type name. | | `modStamp` | `string` | `Required` | Last modified timestamp. | | `candidateId` | `string \| null` | `Required` | Candidate ID. | | `candidateEmail` | `string \| null` | `Required` | Candidate email. | | `candidateGivenName` | `string \| null` | `Required` | Candidate first name. | | `candidateFamilyName` | `string \| null` | `Required` | Candidate last name. | | `packageId` | `string` | `Required` | Package ID. | | `packageName` | `string` | `Required` | Package name. | | `packageCompanyName` | `string \| null` | `Required` | Package company name. | | `billingReferenceId` | `string` | `Required` | Customer billing reference ID. | | `groupProfileId` | `string` | `Required` | Group profile ID. | | `caseInvitationId` | `string` | `Required` | Invitation ID for this case. | | `invitationStatusId` | `string` | `Required` | Invitation status ID. | | `invitationStatusName` | `string` | `Required` | Invitation status name. | | `invitationGivenName` | `string` | `Required` | Invitation first name. | | `invitationFamilyName` | `string` | `Required` | Invitation last name. | | `companyId` | `string` | `Required` | Company ID. | | `companyName` | `string` | `Required` | Company name. | | `companyCommonName` | `string \| null` | `Required` | Company common name. | | `companyLogo` | `string \| null` | `Required` | Company logo URL or value. | | `archived` | `integer` | `Required` | Boolean integer: `1` archived, `0` not archived. | | `serviceGroupId` | `string` | `Required` | Service group ID. | | `invitationEmail` | `string` | `Required` | Invitation email address. | | `isMinorCandidate` | `integer` | `Required` | Boolean integer: `1` minor, `0` not minor. | | `hasParentalConsent` | `integer` | `Required` | Boolean integer: `1` consent provided, `0` not provided. | | `groupName` | `string` | `Required` | Group name. | | `adverseActionId` | `string \| null` | `Required` | Adverse action ID. | | `adverseActionStatusName` | `string \| null` | `Required` | Adverse action status name. | | `adverseActionStatusId` | `string \| null` | `Required` | Adverse action status ID. | | `orderedStamp` | `string` | `Required` | Timestamp when case was ordered. | | `beginOnboardingStamp` | `string \| null` | `Required` | Timestamp when onboarding began. | | `completedOnboardingStamp` | `string \| null` | `Required` | Timestamp when onboarding completed. | | `beginProcessingStamp` | `string \| null` | `Required` | Timestamp when processing began. | | `completedInitialProcessingStamp` | `string \| null` | `Required` | Timestamp when initial processing completed. | | `completedLatestProcessingStamp` | `string \| null` | `Required` | Timestamp when latest processing completed. | # Webhooks Source: https://developer.karmacheck.com/background-check-api/reference/webhooks/webhooks-overview How to subscribe to and handle KarmaCheck webhook events. The KarmaCheck system emits events for different activities. To know when these events happen, you can use webhooks to get automatic updates. For instance, services performed by KarmaCheck involve different turnaround times, so you might want to receive real-time notifications about events related to each service. These notifications are sent as webhooks containing a JSON payload with information about the event. By subscribing to webhooks, you'll know when to fetch the latest data, enabling you to respond to events in real time. This guide describes the current webhook delivery system. If you have legacy webhooks and wish to move over to the new system, see [Migrating your webhooks to the new infrastructure](./migrating-webhooks) to switch over. ## Subscriptions You can set up a webhook for your company, which will deliver events for all groups within the company. If you need webhooks to be sent to different URLs for some or all groups, webhooks can also be configured for these individual groups. When a webhook is configured for a specific group, events for that group are sent to the group webhook subscription only and not the company webhook subscription. You can subscribe to webhooks [in the KarmaCheck sandbox dashboard](https://app-stage.karmacheck.com/company-settings/webhooks). You will need the following information: * **A URL** that's configured to handle incoming HTTPS POST requests. KarmaCheck will send notifications to this URL whenever relevant events occur. * **The event types** that you want to subscribe to. See [Events](#events) for a list of supported events. * **The group ID** of a group within your company *only if* you want to configure your webhook URL to receive events occurring for just that specific group. Unless specified, a webhook is usually configured to deliver events occurring for all groups within a company. When you create a subscription, KarmaCheck generates a per-endpoint **signing secret**. Your receiver uses this secret to verify the authenticity of incoming requests. Store the secret securely (for example, in environment variables or a secrets manager) and never commit it to source control. For more information, see [Verifying signatures](#verifying-signatures). The webhook subscription link above is for your sandbox account. Use the production domain to subscribe to webhooks in production. ### Webhook structure All webhooks are delivered over HTTPS and include the following properties in a JSON payload: ```json theme={null} { "messageId": "string — the unique identifier of the event notification", "event": "string — the webhook event being delivered", "apiTrackingCode": "string | null — an identifier for tracking a case", "apiTrackingUser": "string | null — an identifier for tracking a case", "eventObject": "object — various properties with information related to the event" } ``` The following is an example of a webhook request that you'll receive when an event occurs: ```shell theme={null} POST /webhook-endpoint HTTP/1.1 host: example.com content-length: 1902 user-agent: Svix-Webhooks/1.84.0 content-type: application/json accept: */* webhook-id: msg_3ErCD0YuVlJPXMDLSUg3PpMJGN5 webhook-timestamp: 1780927177 webhook-signature: v1,IMc336RAKV7xItISRHppXKlcGlyPW2kC1xwG/jOPB4g= { "messageId": "72fcd5f8-fb13-7de2-2152-e88e5257aff4", "event": "case.statuschange", "apiTrackingCode": null, "apiTrackingUser": null, "eventObject": { ... } } ``` Every webhook request includes the following HTTP headers, which your receiver uses to authenticate the request. See [Verifying signatures](#verifying-signatures) for how to use them. | Header | Purpose | | - | - | | `webhook-id` | Unique message identifier (same ID if a message is retried) | | `webhook-timestamp` | Timestamp in [seconds since epoch](https://en.wikipedia.org/wiki/Unix_time) | | `webhook-signature` | Space-delimited list of versioned signatures, e.g. `v1,` | ### Verifying signatures KarmaCheck signs every webhook delivery using **HMAC-SHA256** with the per-endpoint signing secret shown in your dashboard. The new webhook endpoint detail view highlighting the signing secret location. Verifying the signature confirms that each event genuinely came from KarmaCheck and hasn't been tampered with in transit. To verify a request: concatenate the id, timestamp, and **raw** request body with `.` separators; HMAC-SHA256 that string using the base64-decoded portion of the signing secret (the part after `whsec_`); base64-encode the result; and compare it (in constant time) against each signature in the header, stripping the `v1,` prefix. Reject the message if no signature matches or if the timestamp is outside a small tolerance window (5 minutes is a reasonable default). ```typescript theme={null} import crypto from "crypto"; const secret = process.env.KARMACHECK_WEBHOOK_SECRET!; // "whsec_..." const TOLERANCE_SECONDS = 5 * 60; function verify(webhookId: string, webhookTimestamp: string, webhookSignature: string, rawBody: string): boolean { if (Math.abs(Date.now() / 1000 - Number(webhookTimestamp)) > TOLERANCE_SECONDS) return false; const secretBytes = Buffer.from(secret.split("_")[1], "base64"); const expected = crypto .createHmac("sha256", secretBytes) .update(`${webhookId}.${webhookTimestamp}.${rawBody}`) .digest(); return webhookSignature.split(" ").some((sig) => { const received = Buffer.from(sig.split(",")[1] ?? "", "base64"); return received.length === expected.length && crypto.timingSafeEqual(received, expected); }); } ``` Pass the raw request body bytes. JSON middleware that parses before your verification step may reorder keys or alter whitespace and break the signature. The header may contain multiple signatures during a key rotation window — accept if any one matches. A couple of operational notes: * **Store the signing secret in environment variables or a secrets manager.** Never hard-code or commit it. * **Rotate secrets from the dashboard when needed.** During rotation, the system signs with both the old and new secret simultaneously; the verifier above already handles this by accepting either match. ### Responding to webhooks To confirm receipt of a webhook, your webhook endpoint must respond with a 2*xx* HTTP status code as quickly as possible. Any response codes outside of this range, including 3*xx* codes, will indicate that you did not receive the webhook. Any other information returned does not get processed. ### Retries If your endpoint doesn't return a 2xx response within 15 seconds, the delivery is considered failed and KarmaCheck will retry it on the following schedule: | Attempt | Delay after previous attempt | | - | - | | 1 | Initial delivery | | 2 | 5 seconds | | 3 | 5 minutes | | 4 | 30 minutes | | 5 | 2 hours | | 6 | 5 hours | | 7 | 10 hours | | 8 | 10 hours | After 8 total attempts, retries stop. ## Events The following events can trigger webhooks. KarmaCheck can configure webhooks to send either or both types of event notifications to your configured URL. | Event | Description | | - | - | | [`case.statuschange`](/background-check-api/reference/webhooks/events/case-status-change) | The status of a case has changed. | | [`casedata.statuschange`](/background-check-api/reference/webhooks/events/case-data-status-change) | The status of a service (case data) has changed. | Additional events might be supported in the future. New event types will follow the same pattern as existing ones. As a best practice, use all event notifications as indicators to fetch the latest data for a case or service. The sections below provide additional best practices for event handling. ### Order of events Each supported event occurs multiple times during a case's lifecycle. As an example with the [`case.statuschange`](/background-check-api/reference/webhooks/events/case-status-change) event, the status of a case involving a candidate-provided PII flow could change like so: | Event order | Case status | Description | | - | - | - | | 1 | `caseStatus`: "Pending" / `secondaryStatus`: "Waiting for Authorization" | Invitation sent to candidate | | 2 | `caseStatus`: "Pending" / `secondaryStatus`: "Authorization in Progress" | Candidate started onboarding | | 3 | `caseStatus`: "Pending" / `secondaryStatus`: null | Case is processing | | 4 | `caseStatus`: "Complete" / `secondaryStatus`: null | Case is complete, with all screenings cleared | **Out-of-order events:** Due to network latency and other factors that might affect delivery timing, KarmaCheck does not guarantee that you will receive notifications in the order that events occur. Therefore, your endpoint should not rely on the delivery of these events in the listed order. Instead, you should fetch the latest details of a case using `GET /case/id/{caseId}` whenever you receive the `case.statuschange` event. ### Duplicate events Webhook endpoints might occasionally receive the same notification more than once if multiple events occur within a short period of time. One way to account for duplicate events is to log the events that you have processed so that you can avoid reprocessing them. For example, when receiving a `case.statuschange` event, compare the following properties to those of your logged events: * **`id`:** The case ID * **`caseStatusId` and `secondaryCaseStatusId`:** The case status * **`modStamp`:** The timestamp for the case modification ### Missed events Some issues that might occur, such as server errors, could lead to missed webhook notifications. To account for the possibility of missed events, you can build a function to check if a type of event notification hasn't been received for a specific length of time. When this happens, fetch the latest data related to the missed event. KarmaCheck webhooks are powered by Svix. For more information, check out their [documentation](https://docs.svix.com/receiving/introduction). # Screening Level Document Retrieval Source: https://developer.karmacheck.com/screening-level-document-retrieval This guide provides information to enable an API integration to retrieve documents that are associated with a specific screening in a case. > About this guide > > The endpoint described here is live and fully supported, but it is not yet published in our public API reference. ### WHAT STAYS THE SAME * Your existing authentication. Same bearer token, same header, no new credentials or scopes. * The response format, which matches the case level secure document list endpoint. * The secure document retrieval process you already use to download files. ### WHAT YOU NEED TO KNOW FIRST > **caseDataId is not the same as caseId** > > This is the most common point of confusion, so it is worth stating plainly.
- caseId identifies the overall order for a candidate.
- caseDataId identifies one individual screening or service inside that order.

An order containing three health screenings has one caseId and three separate caseDataId values.
Documents are attached at the screening level, so you will make one call per caseDataId, not one call per order. ### HOW TO RETRIEVE THE DOCUMENTS 1. Capture the caseDataId for each screening. The caseDataId is returned on the individual service object inside the [casedata.statuschange](https://developer.karmacheck.com/background-check-api/reference/webhooks/events/case-data-status-change) webhook payload (id field) you already receive, either from from the webhook as well as from the [Get Case data by case id API](https://developer.karmacheck.com/api-reference/cases/get-case-data-by-case-id). If you currently store only order level fields, begin persisting caseDataId for each service so document retrieval can run later without re-fetching the case. 2. Request the document list for that screening. Make a GET request to the endpoint below, substituting the caseDataId you captured in step 1. Add the query parameter "returnExcludedDocumentTypes=false", which limits the response to document types eligible for client viewing. Only change this value if we have specifically configured expanded access for your account.
`HTTP GET `
`https://api-stage.karmacheck.io/document/secure/list/caseData/id/{CASE_DATA_ID}?returnExcludedDocumentTypes=false`
`Authorization: Bearer `

The response returns only the secure documents tied to that one screening. 3. Identify the document you want. Use the fields described in the next section to find the document type you need. 4. Retrieve the file using the Secure Document APIs: [Get secure document download URL](https://developer.karmacheck.com/api-reference/secure-documents/get-secure-document-download-url) ### IDENTIFYING THE RIGHT DOCUMENT Each item in the returned list includes the following fields, among others: | Field | What it is | How to use it | | :- | :- | :- | | documentTypeId | Stable identifier for the type of document | Use this to determine what a document is | | fileName | Human readable file name | Use for display to your users | | fileFormat | Format of the file | Use to handle the file correctly on download | #### Important Notes * Do not match on file name * File names vary by laboratory and by collection site, so name based matching will break unpredictably as you take on volume from different providers. Match on documentTypeId, which is consistent across all providers. * To translate documentTypeId values into readable labels such as chain of custody, call the [Get Secure Document Type List](https://developer.karmacheck.com/api-reference/secure-documents/get-secure-document-type-list) endpoint once and cache the result. You do not need to call it on every request. ### RECOMMENDED IMPLEMENTATION PATTERN 1. Trigger on your existing order completion webhook or polling schedule. 2. Iterate the services on the completed case and capture each caseDataId. 3. Call the endpoint above once per caseDataId. 4. Filter the returned list down to the documentTypeId values your users need to see. 5. Retrieve each file through the existing secure document process and store it against the candidate record in your system. 6. Once this is in place, the documents your team is currently pulling manually will land in your system automatically as orders complete. ### RELATED DOCUMENTATION Get Secure Document List
[https://developer.karmacheck.com/api-reference/secure-documents/get-secure-document-list](https://developer.karmacheck.com/api-reference/secure-documents/get-secure-document-list) Get Secure Document Type List
[https://developer.karmacheck.com/api-reference/secure-documents/get-secure-document-type-list](https://developer.karmacheck.com/api-reference/secure-documents/get-secure-document-type-list) Get Secure Document
[Get secure document download URL](https://developer.karmacheck.com/api-reference/secure-documents/get-secure-document-download-url) # Verify Sandbox Email Addresses Source: https://developer.karmacheck.com/verify-sandbox-email-addresses KarmaCheck staging uses an **allowlist and routing layer** to prevent test emails from reaching arbitrary people. **In short:** Verify the inbox through the sandbox account. Staging then selectively allows delivery to that address; everything else is intercepted or redirected for safety. Emails are sent to candidates that you order background checks for as well as your dashboard users that you wish to invite to your company. If you invite a candidate that has an email address that is not already verified, the email will end up in a catch-all inbox at KarmaCheck and will not be delivered to you to use for testing. The one exception to this rule is if you have a default email address set up in your verified emails. If there is a default then candidate emails that are addressed to unverified recipients will end up getting sent to the default address. If you invite a dashboard user to be a part of your sandbox company that email address MUST be verified ahead of adding them as a user. User invites will not go to the default address. ## How an address becomes verified 1. In the staging sandbox, go to **Company Settings → Email Verification**.
Company Settings Menu **Company Settings Menu in the dashboard** 2. Enter an email address the tester controls. 3. KarmaCheck sends a one-time verification link to that inbox. 4. After the link is clicked, the address is stored as verified and associated with the sandbox. ### Address matching rules * **Case-insensitive:** Capitalization does not create a different verified address. * **Plus aliases supported:** If the recipient’s email provider supports “plus aliases” also known as “plus addressing”, verifying `qa@company.com` also permits addresses such as `qa+candidate1@company.com`. Be sure to create a default email address Image **Default Email Address Highlighted** ## What happens when staging sends an email For candidate and background-check invitations, the routing logic checks whether the intended recipient: * Is a user in the current sandbox account, or * Matches a verified sandbox contact. **If verified:** The email can be delivered to the intended real inbox. **If not verified:** The email is redirected to a safe destination—the company’s default verified sandbox contact, or ultimately KarmaCheck’s internal staging inbox—instead of being sent to the unverified person. ## Routing summary | Recipient state | Typical result | | - | - | | Verified account user or sandbox contact | Delivery to the intended real inbox is allowed. | | Unverified candidate recipient | Redirected to a safe verified/default destination or the internal staging inbox. | | Unverified company-user invitee | Currently redirected to the internal staging inbox because the default-contact fallback is skipped. |