> ## Documentation Index > Fetch the complete documentation index at: https://developer.karmacheck.com/llms.txt > Use this file to discover all available pages before exploring further. # 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.