---
title: "Request screening for a supplier"
method: POST
path: "/public/v2/suppliers/sites/screening"
tags: ["Suppliers - Sites"]
---

# Request screening for a supplier

`POST /public/v2/suppliers/sites/screening`

Request a history screening for a supplier site. The body has two parts: `identifier` (how to find the site) and `options` (screening parameters).

**Request body shape (OpenAPI schema: `PublicScreeningRequestPayloadV2`):**
```json
{
  "identifier": {
    "supplierId": null,
    "customerId": null,
    "ownId": null,
    "prewaveId": 102006215,
    "source": null
  },
  "options": {
    "periodInYears": 2
  }
}
```
- **`identifier`:** At least one of `supplierId`, `customerId`, `ownId`, or `prewaveId` must be non-empty / non-null (same semantics as query params on `find-by-identifier`). Optional `source` applies to the string IDs only.
- **`options.periodInYears`:** Required. Must be **2**, **5**, or **10** (years).

**Asynchronous Processing:**
- Screening is an asynchronous process that may take several hours to complete.
- The endpoint returns immediately with `202 Accepted` and the created screening request ID(s).
- Poll status with the **same** supplier identifiers you used in `identifier`, e.g. `GET /public/v2/suppliers/sites/screening?prewaveId=...` (see get screening status).

**Supplier Identification (`identifier`):**
- At least one of supplierId, customerId, ownId, or prewaveId must be provided inside `identifier`.
- **Exactly one supplier must match** (same rules as `DELETE /public/v2/suppliers/sites` and `POST /public/v2/suppliers/sites/identifiers`). If your criteria match zero suppliers, `404` is returned; if more than one, `400` with a multiple-suppliers error.
- If the matched target is already screened or otherwise ineligible, it may be skipped (reflected by an empty `screeningRequestIds` list in the response).

**Costs:**
- Screening requests may incur additional costs or consume quota. Ensure your plan supports screening before calling this endpoint.

**Required Permission**: `ACCESS_PUBLIC_SCREENING_REQUEST`

## Request body

- PublicScreeningRequestPayloadV2 — Payload for requesting screening for a supplier site
  - `identifier` PublicExternalTargetIdentifier, required — Supplier site identifier. At least one lookup key (`supplierId`, `customerId`, `ownId`, or `prewaveId`) should be set; `source` optionally narrows text identifiers.
    - `supplierId` string, nullable — Supplier ID of the target. Can be combined with customerId, ownId, and/or prewaveId.
    - `customerId` string, nullable — Customer ID of the target. Can be combined with supplierId, ownId, and/or prewaveId.
    - `ownId` string, nullable — Own site ID of the target. Can be combined with supplierId, customerId, and/or prewaveId.
    - `prewaveId` integer, nullable — Prewave ID of the target. Can be combined with supplierId, customerId, and/or ownId.
    - `source` string, nullable — Optional source system to filter by. Applies to supplierId, customerId, and ownId (not prewaveId).
  - `options` PublicScreeningOptionsV2, required — Screening parameters to apply
    - `periodInYears` 2 | 5 | 10, required — Screening window length in **years**. Supported values: 2, 5, 10. Note: screening requests may incur additional costs.

## Response `202`

Screening request accepted for processing

- PublicScreeningCreatedResponseV2 — Response returned when a screening request is successfully submitted
  - `screeningRequestIds` integer[], required — IDs of the created screening requests. One ID per resolved target. Empty if all targets were already screened or otherwise ineligible.
  - `message` string, required — Human-readable confirmation message.

## Other responses

- `400` — Bad Request - Invalid payload (e.g. missing identifier/options, periodInYears out of range, or multiple suppliers match)
- `403` — Forbidden - Missing ACCESS_PUBLIC_SCREENING_REQUEST permission
- `404` — Not Found - No supplier found matching the provided identifiers
- `429` — 429 Too Many Requests - API rate limit exceeded. The request has been rejected because the rate limit for this endpoint has been exceeded. Default rate limits: GET requests - 100 per 10 seconds, 500 per minute; POST/PUT/PATCH/DELETE requests - 20 per 10 seconds, 100 per minute. For increased access, please contact customer success.
- `500` — 500 Internal Server Error - An unexpected error occurred on the server. The request may or may not have been processed.

---

[API](https://skmtc.net/prewave/apis/public-prewave-api.md) · [All operations](https://skmtc.net/prewave/apis/public-prewave-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/prewave/public-prewave-api/revisions/466169815b78/schema)