Skip to content

Create order

Request

Create a new screening order for an applicant against a property. The property and the applicant can each be supplied either inline (address / identity fields) — in which case a new record is created — or by id (property_id / applicant_id) to reuse an existing record. Provide exactly one form per side.

original_requester is optional. Omit it entirely if you are screening applicants for your own organization. Supply it only if you are a platform placing orders on behalf of your own customers, to identify the end user the report is furnished to. It follows the same inline-or-id shape, sending both forms returns a validation error, sending neither does not.

Screening fee compliance: many states and cities cap what you may charge an applicant for a screening fee, or require specific disclosures. You are responsible for determining and following the application screening fee laws that apply to each property's jurisdiction. See our Application Screening Fees page for state and city fee caps, provided for reference only and subject to change.

Security
bearer-token
Query
includestring

Comma-separated list of related objects to embed in the response. Supported values: property, applicant, original_requester. By default only the property_id, applicant_id and original_requester_id are returned.

Example:include=property,applicant
Headers
Idempotency-Keystring, [ 1 .. 255 ] charactersrequired

Unique, client-generated string (1–255 characters; a UUIDv4 is recommended) that identifies a single logical request. Generate a fresh key per logical request; only reuse it when retrying the same request.

In live mode, reusing a key after a successful create returns the original order and does not create a new, billable one. Keys are retained for that purpose and do not expire after a short window. Transient errors (5xx) are not replayed: retrying with the same key will re-execute the request. After a declined card (402), send a new key once the payment method is updated.

In test mode, the header is accepted but does not prevent duplicate orders. Sending the same key more than once can create multiple ord_test_ IDs. See Testing.

Example:8e1bce8f-2a5e-4f7e-9f61-7e1f3e6e0c7b
Checkr-Tenant-Versionstring

CalVer-dated API version to pin behavior to (e.g. 2026-04-29). When omitted, the request is served by the newest supported version. Unknown values return 422.

Value:"2026-04-29"
Bodyapplication/jsonrequired

The request body for creating a new order. Each side of the order — the property and the applicant — can be supplied either inline (the address or identity fields) or by id (a previously created pr_… / ap_…). Provide exactly one form per side; sending both, or neither, returns a validation error.

original_requester is optional. Omit it entirely if you are screening applicants for your own organization. Supply it only if you are a platform placing orders on behalf of your own customers, to identify the end user the report is furnished to. It follows the same inline-or-id shape, sending both forms returns a validation error, sending neither does not.

orderobjectrequired

Attributes for the new order.

curl -i -X POST \
  'https://tenant.checkr.com/api/orders?include=property%2Capplicant' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Checkr-Tenant-Version: 2026-04-29' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 8e1bce8f-2a5e-4f7e-9f61-7e1f3e6e0c7b' \
  -d '{
    "order": {
      "package": "starter",
      "property_id": "pr_K9dM2pXqR4vN8tLZbWyHJa",
      "property": {
        "name": "Sunset Apartments",
        "street": "1234 Market St",
        "unit": "Apt 4B",
        "city": "San Francisco",
        "state": "CA",
        "zipcode": "94103"
      },
      "original_requester_id": "req_TUyYsLnyTbG3xv9hONJF7w",
      "original_requester": {
        "external_id": "your_customer_42",
        "type": "individual",
        "name": "KimCo Property Management",
        "email": "ops@kimco.example",
        "phone_number": "415-555-0123",
        "street": "500 Market St",
        "unit": "Floor 8",
        "city": "San Francisco",
        "state": "CA",
        "zipcode": "94105"
      },
      "applicant_id": "ap_F3hQ7wEsLp2xBnVcRuMyTk",
      "applicant": {
        "email": "jane@example.com",
        "dob": "1990-05-14",
        "phone_number": "415-555-0100",
        "ssn": "123-45-6789",
        "current_address": {
          "street": "1234 Market St",
          "unit": "Apt 4B",
          "city": "San Francisco",
          "state": "CA",
          "zipcode": "94103"
        },
        "first_name": "Jane",
        "last_name": "Doe"
      },
      "add_on_products": [
        "identity_intelligence"
      ],
      "payer": "organization",
      "application_mode": "hosted"
    }
  }'

Responses

Created

Bodyapplication/json
idstring

Unique identifier for the order. Use this value in subsequent API calls; it is stable for the lifetime of the order. Test-mode IDs carry a _test_ infix (e.g. ord_test_TUyYsLnyTbG3xv9hONJF7w); live-mode IDs have no infix.

Example:"ord_TUyYsLnyTbG3xv9hONJF7w"
live_modeboolean

Whether this order was created with a live API key (true) or a test API key (false). Test-mode orders are inert: they route to canned provider responses and do not produce billable activity. See Testing for details.

Example:true
statusstring

Current state of the order in its lifecycle:

  • waiting_for_applicant — invitation sent; awaiting the applicant's consent and information
  • pending — applicant submitted consent and information; screening is in progress
  • completed — screening is complete and the report is available
  • canceled — terminated before completion
Enum:"waiting_for_applicant""pending""completed""canceled"
packagestring

Slug of the screening package on the order, e.g. starter, essential or complete.

add_on_productsArray of strings, unique

Identifiers of the add-ons on this order, sorted alphabetically. Empty if none were requested.

Example:
[ "identity_intelligence" ]
payerstring

Who pays for this order, applicant or organization. applicant is live mode only — always organization for test-mode orders.

Example:"organization"
application_modestring

How the applicant's disclosures, consent, and information were collected, as sent when the order was created. hosted means Checkr invited the applicant and collected them. direct means your organization certified that it provided the disclosures and obtained consent itself. Orders placed through the Checkr web app are always hosted.

Enum:"hosted""direct"
Example:"hosted"
property_idstring

Identifier of the property record this order is screening for. Pass ?include=property to embed the full property object.

Example:"pr_K9dM2pXqR4vN8tLZbWyHJa"
applicant_idstring

Identifier of the applicant being screened. Pass ?include=applicant to embed the full applicant object.

Example:"ap_F3hQ7wEsLp2xBnVcRuMyTk"
original_requester_idstring or null

Identifier of the requester you supplied when creating this order, or null if you did not supply one. Pass ?include=original_requester to embed the full object.

Example:"req_TUyYsLnyTbG3xv9hONJF7w"
application_urlstring or null, (uri)

Absolute URL for the applicant apply flow (https://…/apply/<token>). Returned only while the order status is waiting_for_applicant — for live-mode orders, and in test mode only for the Hudson Green applicant-experience profile (other test applicants auto-submit and skip the apply flow — see Testing). null when status is pending, completed, or canceled, and for ordinary test-mode profiles. When the apply flow runs, Checkr emails this link to the applicant; in live mode, if a phone number is present, Checkr also texts it. Integrators may share application_url themselves.

Example:"https://tenant.checkr.com/apply/K7P2MX"
propertyobject(property)

Embedded property object. Only returned when the request includes ?include=property.

applicantobject(applicant)

Embedded applicant object. Only returned when the request includes ?include=applicant.

original_requesterobject(requester)

Embedded end user object. Only returned when the request includes ?include=original_requester and the order has one.

created_atstring, (date-time)

Timestamp the order was accepted by the API.

completed_atstring or null, (date-time)

Timestamp the order reached the completed status. Null while in any earlier state, and remains null if the order is canceled.

canceled_atstring or null, (date-time)

Timestamp the order was canceled. Null unless the order was canceled.

Response
{ "id": "ord_TUyYsLnyTbG3xv9hONJF7w", "live_mode": true, "status": "waiting_for_applicant", "package": "string", "add_on_products": [ "identity_intelligence" ], "payer": "organization", "application_mode": "hosted", "property_id": "pr_K9dM2pXqR4vN8tLZbWyHJa", "applicant_id": "ap_F3hQ7wEsLp2xBnVcRuMyTk", "original_requester_id": "req_TUyYsLnyTbG3xv9hONJF7w", "application_url": "https://tenant.checkr.com/apply/K7P2MX", "property": { "id": "pr_K9dM2pXqR4vN8tLZbWyHJa", "name": "Sunset Apartments", "street": "1234 Market St", "unit": "Apt 4B", "city": "San Francisco", "state": "CA", "zipcode": "94103", "created_at": "2019-08-24T14:15:22Z" }, "applicant": { "id": "ap_F3hQ7wEsLp2xBnVcRuMyTk", "full_name": "Jane Public", "email": "jane@example.com", "first_name": "string", "last_name": "string", "dob": "1990-05-14", "phone_number": "+15551234567", "ssn": "XXX-XX-6789", "created_at": "2019-08-24T14:15:22Z" }, "original_requester": { "id": "req_TUyYsLnyTbG3xv9hONJF7w", "external_id": "your_customer_42", "type": "individual", "name": "Acme Property Management, Inc.", "email": "ops@kimco.example", "phone_number": "+14155550123", "street": "500 Market St", "unit": "Floor 8", "city": "San Francisco", "state": "CA", "zipcode": "94105", "created_at": "2019-08-24T14:15:22Z" }, "created_at": "2019-08-24T14:15:22Z", "completed_at": "2019-08-24T14:15:22Z", "canceled_at": "2019-08-24T14:15:22Z" }