> ## Documentation Index
> Fetch the complete documentation index at: https://docs.readyhealth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Requirement ingestion

> Pull requirement lists from a VMS, MSP email, or pre-configuration via the Job and Placement APIs

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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

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

## Outcome

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

```json theme={null}
{
  "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](/guides/intake-vs-scan). Classification and validations are matched to the requirement’s category / type.
* **`REGISTRY_SEARCH`** — a [search](/guides/search) is created (OIG, Nursys, state license, etc.).
* **`STATEMENT`** — a [statement](/guides/statements) 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](/guides/vms-upload).