{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Getting Started"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"getting-started","__idx":0},"children":["Getting Started"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Checkr Tenant API powers tenant screening workflows. This guide walks through"," ","the steps required to place your first order."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"how-it-works","__idx":1},"children":["How it works"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/sequence-diagram.a9abb87f12c662cba5ebaf5dbf5d0eae6a146713aabf65f9a4cfc39ad9fa7acb.9c1bb791.jpg","alt":"Sequence diagram showing the flow between Customer, Server, and Checkr for placing an order, completing the applicant flow, and receiving a report via webhook."},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["End-to-end, a screening flows through three parties — you, the Checkr Tenant"," ","API, and your applicant:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["You create an order."]}," Send a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /orders"]}," request with the screening"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["package"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["property"]}," address, and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["applicant"]}," identity fields."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["We return an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["order_id"]},"."]}," You'll get back a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201 Created"]}," with the new"," ","order, including its id, current status, and often ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application_url"]}," — the"," ","applicant apply link. That field is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," when the apply flow is skipped"," ","(most test-mode profiles auto-submit; see"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/testing#applicant-experience-in-test-mode"},"children":["Applicant Experience in Test Mode"]},")"," ","or once the order is no longer ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["waiting_for_applicant"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pending"]},","," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["completed"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["canceled"]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["We contact your applicant."]}," When the apply flow runs, we email them a"," ","link to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tenant.checkr.com/apply/<code>"]}," (the same URL as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application_url"]},")."," ","In live mode, if the applicant has a phone number, we also send an SMS with"," ","the link. They provide consent, their current residence, and any remaining"," ","identity details (DOB, SSN). You can also share ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["application_url"]}," yourself."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Your applicant completes the flow."]}," Once they submit their information,"," ","we start running the screening asynchronously."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["We send you a webhook."]}," When the report is ready, we ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}," a"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["report.completed"]}," event (along with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["report.created"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["report.updated"]}," ","along the way) to your registered webhook endpoints, including the"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["report_id"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["You pull the report."]}," Fetch it via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /reports/{id}"]}," using the"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["report_id"]}," from the webhook payload."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The rest of this guide walks through the one-time setup required before you"," ","can place your first order."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"1-get-your-account-authorized-for-api-access","__idx":2},"children":["1. Get your account authorized for API access"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["API access is granted on a per-organization basis. To request access, email"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"mailto:hello-tenant@checkr.com"},"children":["hello-tenant@checkr.com"]}," from your"," ","work address and include your organization name. A member of the Checkr Tenant"," ","team will reach out to confirm and enable API access on your account."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"2-set-up-billing","__idx":3},"children":["2. Set up billing"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A saved payment method is required before any orders can be placed. Add one from"," ","the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://tenant.checkr.com/settings/billing"},"children":["Billing settings"]}," page in your dashboard."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you attempt to create an order without a saved payment method, the API"," ","responds with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422 Unprocessable Entity"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"errors\": [\n    {\n      \"code\": \"validation_error\",\n      \"detail\": \"A saved payment method is required to place an order.\"\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"3-create-your-api-keys","__idx":4},"children":["3. Create your API keys"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Generate keys from the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://tenant.checkr.com/settings/developer"},"children":["Developer settings"]}," page in your"," ","dashboard. Two key types are supported:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Prefix"},"children":["Prefix"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Environment"},"children":["Environment"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Use for"},"children":["Use for"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ckr_sk_test_…"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Test"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Development and integration testing"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ckr_sk_live_…"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Live"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Real screening orders billed to your account"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Test keys route to canned provider responses and produce inert, unbilled"," ","records. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/testing"},"children":["Testing"]}," for the available scenarios and how mode"," ","isolation works."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send the key on every request as a bearer token:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"Authorization: Bearer <your-api-key>\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"4-place-your-first-order","__idx":5},"children":["4. Place your first order"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The minimum required fields are a screening ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["package"]},", a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["property"]}," address,"," ","and an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["applicant"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["first_name"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["last_name"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["email"]},". The applicant"," ","is prompted to complete identity fields (DOB, SSN) via the consent form if you"," ","don't supply them. Legacy clients may still send ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["full_name"]}," instead of"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["first_name"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["last_name"]},", but the two name forms are mutually exclusive."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl https://api.example.com/api/orders \\\n  -X POST \\\n  -H \"Authorization: Bearer <your-api-key>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"order\": {\n      \"package\": \"starter\",\n      \"property\": {\n        \"street\": \"123 Main St\",\n        \"city\": \"San Francisco\",\n        \"state\": \"CA\",\n        \"zipcode\": \"94105\"\n      },\n      \"applicant\": {\n        \"first_name\": \"Jane\",\n        \"last_name\": \"Doe\",\n        \"email\": \"jane@example.com\"\n      }\n    }\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A successful request returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201 Created"]}," with the new order. See the full"," ","schema in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/v1#tag/orders"},"children":["API Reference"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"5-listen-for-report-events-optional","__idx":6},"children":["5. Listen for report events (optional)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Reports are processed asynchronously after an order is placed. Rather than"," ","polling, you can register webhook endpoints to receive events as they happen:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["report.created"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["report.updated"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["report.completed"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Webhook payloads are signed so you can verify they originated from Checkr. See"," ","the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/webhooks"},"children":["Webhooks guide"]}," for endpoint registration, the full event"," ","list, and signature verification."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you'd rather not run a webhook receiver, you can poll"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /orders/{id}/report"]}," instead. While the report is still pending the"," ","endpoint returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404 Not Found"]}," — treat this as \"not ready yet\" and retry,"," ","not as a broken link. Once it returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200 OK"]},", the report is available."," ","Terminal status lives on each product included in the order"," ","(",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["criminal_history"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["credit_report"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["eviction_history"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identity_verification"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["income_verification"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sex_offender_registry"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["global_watchlist"]},"); inspect the"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," field on each non-null product for values ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["clear"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["consider"]}," to"," ","determine when the screening is fully resolved."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"next-steps","__idx":7},"children":["Next steps"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/testing"},"children":["Testing guide"]}," — test API keys, canned provider scenarios, and mode isolation"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/webhooks"},"children":["Webhooks guide"]}," — register endpoints and verify signatures"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/v1#tag/orders"},"children":["API Reference"]}," — full resource and schema documentation"]}]}]},"headings":[{"value":"Getting Started","id":"getting-started","depth":2},{"value":"How it works","id":"how-it-works","depth":3},{"value":"1. Get your account authorized for API access","id":"1-get-your-account-authorized-for-api-access","depth":3},{"value":"2. Set up billing","id":"2-set-up-billing","depth":3},{"value":"3. Create your API keys","id":"3-create-your-api-keys","depth":3},{"value":"4. Place your first order","id":"4-place-your-first-order","depth":3},{"value":"5. Listen for report events (optional)","id":"5-listen-for-report-events-optional","depth":3},{"value":"Next steps","id":"next-steps","depth":3}],"frontmatter":{"seo":{"title":"Getting Started"}},"lastModified":"2026-07-16T00:47:41.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}