Screening Orders

A screening order is a request from an applicant tracking system (ATS) to screen one candidate. Your ATS places the order; Oho turns it into a recruitment check, collects the candidate's details, runs the checks, and hands the result back. The Screening Orders API is how you watch that happen and step in when one gets stuck.

You don't create screening orders

Orders arrive from the ATS. Today that means the SmartRecruiters Assessment API integration, which calls Oho's order-intake endpoints. There is no "create a screening order" call for your own integration to make — if you want to screen someone programmatically, you want Screening an Applicant, which creates a recruitment check directly.

This page covers the admin surface: listing orders, reading one, and the two recovery actions.

When to use this versus a recruitment check

You want to…	Use
Screen a candidate from your own system	Recruitment checks
See what your ATS has asked Oho to do, and how it went	Screening Orders (this page)
Unstick an order your ATS placed that didn't go through	Screening Orders → retry

An order and a recruitment check are not alternatives — an order that processes successfully becomes a recruitment check. The order is the ATS's side of the conversation; the check is the screening itself. The order's credentialCheckUrn points at the check it produced.

The lifecycle

ATS places order  →  RECEIVED  →  ┬→  COMPLETED        → result delivered back to the ATS
                                  ├→  NEEDS_ATTENTION  → something in the configuration is missing
                                  └→  FAILED           → processing errored

Status	What it means	What to do
`RECEIVED`	Oho has the order and is working on it.	Nothing — wait.
`COMPLETED`	The screening ran and the result went back to the ATS.	Nothing. If the ATS never got it, redeliver.
`NEEDS_ATTENTION`	Oho couldn't match the order to a position or package. `needsAttentionReason` says which.	Fix the configuration, then retry.
`FAILED`	Processing errored.	Retry.

The commonest cause of NEEDS_ATTENTION is a Position Source configuration that doesn't resolve the position the order names. See Connect SmartRecruiters for fixing that in the app.

Authorization

Orders are authorized against the screeningOrder entity type:

Action	Privilege required
List, fetch	`READ`
Retry, redeliver	`UPDATE`

An authenticated caller without the privilege gets 403. See Authentication & Tokens.

List orders

curl -sS "$OHO_BASE/screening-orders?status=NEEDS_ATTENTION&page=1&pageSize=25" \
  -H "Authorization: Bearer $OHO_TOKEN"

status is optional and case-insensitive (it's upper-cased server-side); omit it to get every status. pageSize is clamped to 1..100.

This endpoint returns a bare array

Unlike most of the v1 API, the screening-orders list returns a plain JSON array rather than the { "data": [...], "meta": {...} } envelope described in API Basics. There is no meta.total, so page until you get a short page.

[
  {
    "orderId": "ord_7Kq2...",
    "source": "smartrecruiters",
    "status": "NEEDS_ATTENTION",
    "assessmentPackageId": "pkg_standard_care",
    "positionId": "POS-4471",
    "applicantUrn": "urn:li:applicant:app_9Vd...",
    "needsAttentionReason": "No position source mapping for POS-4471",
    "candidateEmail": "jordan.lee@example.com",
    "receivedAt": 1789520289287
  }
]

Null-valued fields are omitted, so don't assume every key is present. receivedAt is epoch milliseconds.

Fetch one order

curl -sS "$OHO_BASE/screening-orders/$ORDER_ID" \
  -H "Authorization: Bearer $OHO_TOKEN"

Returns the same OrderDto, or 404 if no order has that id.

Retry a stuck order

Re-runs the whole screening pipeline for an order sitting in NEEDS_ATTENTION or FAILED — use it after you've fixed whatever the order tripped over.

curl -sS -X POST "$OHO_BASE/screening-orders/$ORDER_ID/retry" \
  -H "Authorization: Bearer $OHO_TOKEN"

The response is the order's state after the attempt. A retry that fails again is reported in the returned status, not as a non-200 — so check the body, don't just check the HTTP code:

curl -sS -X POST "$OHO_BASE/screening-orders/$ORDER_ID/retry" \
  -H "Authorization: Bearer $OHO_TOKEN" | jq -r '.status'
# NEEDS_ATTENTION  → still not resolved; read .needsAttentionReason again
# RECEIVED         → accepted, processing

Redeliver a result

When the screening finished but the hand-back to the ATS didn't land, redeliver sends the existing result again.

curl -sS -X POST "$OHO_BASE/screening-orders/$ORDER_ID/redeliver" \
  -H "Authorization: Bearer $OHO_TOKEN"

Redelivering does not re-run the screening — no checks are re-ordered and nothing is charged again. Reach for retry when the screening itself didn't happen, and redeliver when it did but the ATS never heard about it.

A worked recovery

Find everything that needs a hand, fix the configuration, then retry the lot:

# 1. What's stuck?
curl -sS "$OHO_BASE/screening-orders?status=NEEDS_ATTENTION&pageSize=100" \
  -H "Authorization: Bearer $OHO_TOKEN" \
  | jq -r '.[] | "\(.orderId)\t\(.positionId // "-")\t\(.needsAttentionReason // "-")"'

# 2. …fix the Position Source mapping in the app…

# 3. Retry each, and report where it landed
for id in $(curl -sS "$OHO_BASE/screening-orders?status=NEEDS_ATTENTION&pageSize=100" \
  -H "Authorization: Bearer $OHO_TOKEN" | jq -r '.[].orderId'); do
  status=$(curl -sS -X POST "$OHO_BASE/screening-orders/$id/retry" \
    -H "Authorization: Bearer $OHO_TOKEN" | jq -r '.status')
  echo "$id -> $status"
done

Where to go next

Screening an Applicant — create a recruitment check from your own system
Connect SmartRecruiters — setting the integration up, and the admin screens for orders
Screening packages — what assessmentPackageId refers to
API Reference: Screening Orders — every field and parameter

When to use this versus a recruitment check​

The lifecycle​

Authorization​

List orders​

Fetch one order​

Retry a stuck order​

Redeliver a result​

A worked recovery​

Where to go next​