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