Requirement ingestion

Requirement ingestion is the sync that turns a job or placement into a concrete list of compliance items. Ready Health then creates the document slots and searches needed to fulfill those items. You trigger the sync by calling the Job or Placement APIs. You do not pick the source on each request — that is configured for the integration.

Sources

Depending on the integration, Ready Health retrieves requirements from one or more of:

Source	When it is used
VMS	Ready Health scrapes or reads the job/placement requirement list from the VMS (the `vmsType` + `vmsJobRefId` / `vmsPlacementRefId` you send).
Client email	The Client, MSP (or VMS) emails a requirement checklist. Ready Health parses that email and attaches the items to the job or placement, or reconciles with existing requirements populated from other sources.
Pre-configuration	A facility, client or job matrix already has a requirement template in Ready Health. The sync applies that template instead of (or in addition to) external data source.

A single integration can mix these. For example: pull the live list from the VMS, fall back to a pre-configured template when the VMS job is unavailable, and accept MSP email updates as they arrive to modify the list if needed.

Triggering the sync

Job API

POST /job creates or updates a job and queues a requirement scrape when the job is available.

{
  "vmsType": "your_vms",
  "vmsJobRefId": "JOB-10482",
  "title": "RN - ICU",
  "facility": "Memorial Hospital",
  "atsJobRefId": "ats-8891",
  "atsSystem": "your_ats"
}

Required: vmsType, vmsJobRefId
The response includes scrapeQueued. true means a sync is running in the background. false means the job is UNAVAILABLE and nothing was queued.
GET /job/{id} returns the template requirements for that job (requirements[], plus requirementCount / mappedCount).

Use the job trigger when you know the VMS job and want the requirement set before a candidate is attached.

Placement API

POST /placement binds a candidate to a job. It is idempotent on (jobId, externalUser) — a repeat call returns the existing placement.

{
  "externalId": "candidate-4421",
  "jobId": "3f2a1c8e-0b11-4d3a-9c2e-1a2b3c4d5e6f",
  "vmsPlacementRefId": "PLC-2201",
  "candidateName": "Jane Doe"
}

Creating a placement can also kick a sync — for integrations that only resolve requirements once a candidate is on a specific assignment (or that read placement-level items from the VMS / MSP email). GET /placement/{id} returns the candidate’s requirement rows and packet status. This is the list you fulfill against.

Create the job first, then the placement. The placement jobId is the Ready Health job UUID from POST /job or GET /job/{id}.

Outcome

After the sync completes, the job or placement has a requirement list. Each row looks like:

{
  "id": "a1b2c3d4-5678-90ab-cdef-111111111111",
  "vmsRequirementName": "BLS Certification",
  "fulfillmentType": "DOCUMENT",
  "documentCategory": "certification",
  "documentType": "bls",
  "requirementKey": "bls",
  "status": "PENDING",
  "isMapped": true,
  "packetGroup": "clinical",
  "sortOrder": 2
}

What Ready Health does next depends on fulfillmentType:

DOCUMENT — a document requirement is opened. Your app (or the candidate) uploads via intake or scan. Classification and validations are matched to the requirement’s category / type.
REGISTRY_SEARCH — a search is created (OIG, Nursys, state license, etc.).
STATEMENT — a statement is generated from candidate / placement data.
PASS_THROUGH — no new document or search. The item is tracked but fulfilled outside this flow.

Poll GET /job/{id} or GET /placement/{id} until requirements[] is populated and statuses move off PENDING / AWAITING_CONFIG.

Statuses

Status	Meaning
`PENDING`	Ingested, not started
`AWAITING_CONFIG`	Source label is not mapped
`IN_PROGRESS`	Document, search, or statement is in flight
`FULFILLED`	Requirement is satisfied — eligible for VMS upload
`REJECTED`	Submitted artifact failed validation
`INVALIDATED`	Previously fulfilled item is no longer valid
`EXPIRED`	Time-bound item lapsed
`SKIPPED`	Intentionally not required for this candidate

When the items you care about are FULFILLED, start a VMS upload.

Getting Started

Requirement Lifecycle

Document Processing

Searches

Statements

Sources

Triggering the sync

Job API

Placement API

Outcome

Statuses

​Sources

​Triggering the sync

​Job API

​Placement API

​Outcome

​Statuses

Sources

Triggering the sync

Job API

Placement API

Outcome

Statuses