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

# Trigger Quick Scan Screening

This endpoint triggers a **Quick Scan screening** for an **individual** or a **corporate entity**.
The scan runs **asynchronously** — the response returns immediately with a `screeningId` that you can use to poll for results.

***

## Query Parameters

| Parameter       | Type       | Required | Description                                                                  |
| --------------- | ---------- | -------- | ---------------------------------------------------------------------------- |
| `name`          | `string`   | Yes      | The name of the individual or corporate entity to screen.                    |
| `customerType`  | `string`   | Yes      | Type of customer. Possible values: `INDIVIDUAL`, `CORPORATE`.                |
| `chosenEngines` | `string[]` | Yes      | One or more screening engines to include (repeat the parameter to add more). |

### Available Screening Engines

| Value                 | Description                                |
| --------------------- | ------------------------------------------ |
| `ARTEMISCAN`          | Cynopsis proprietary screening engine      |
| `DJ`                  | Dow Jones                                  |
| `TR`                  | World-Check (Refinitiv / LSEG)             |
| `INTERNET_SEARCH`     | Internet-based adverse media search        |
| `OWN_RESTRICTED_LIST` | Your organisation's custom restricted list |

***

## Headers

| Header          | Type      | Required | Description                                             |
| --------------- | --------- | -------- | ------------------------------------------------------- |
| `Authorization` | `string`  | Yes      | Bearer token obtained from the authentication endpoint. |
| `X-Domain-ID`   | `integer` | Yes      | The domain identifier for your organisation.            |

***

## Example Requests

### Screen an Individual with ArtemiScan

```bash theme={null}
curl -X POST "{{backend_url}}/api/quickscan/screen?name=John%20Doe&customerType=INDIVIDUAL&chosenEngines=ARTEMISCAN" \
  -H "Authorization: Bearer <token>" \
  -H "X-Domain-ID: {{domain_id}}"
```

### Screen a Corporate Entity with Multiple Engines

```bash theme={null}
curl -X POST "{{backend_url}}/api/quickscan/screen?name=Acme%20Corp&customerType=CORPORATE&chosenEngines=ARTEMISCAN&chosenEngines=DJ&chosenEngines=INTERNET_SEARCH" \
  -H "Authorization: Bearer <token>" \
  -H "X-Domain-ID: {{domain_id}}"
```

***

## Response

A successful response returns a `ScreeningResponseDto` with an HTTP `200` status code.

### Key Response Fields

| Field                 | Type       | Description                                                                                                        |
| --------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------ |
| `id`                  | `integer`  | The unique screening ID. Use this as `screeningId` in subsequent API calls.                                        |
| `quickscanName`       | `string`   | The name that was screened.                                                                                        |
| `quickscanType`       | `string`   | `INDIVIDUAL` or `CORPORATE`.                                                                                       |
| `finalStatus`         | `string`   | Current status: `PENDING`, `DONE`, `FAILED`, or `NEVER`.                                                           |
| `screenedWith`        | `string[]` | List of engines used in this screening.                                                                            |
| `screeningConclusion` | `string[]` | Conclusions after screening completes — e.g., `PEP`, `SANCTION`, `ADVERSE_MEDIA`, `OWN_RESTRICTED_LIST`, `NO_HIT`. |
| `hasHit`              | `boolean`  | Whether any potential hits were found.                                                                             |
| `potentialHits`       | `object`   | Map of engine name to hit count — e.g., `{ "ARTEMISCAN": 3, "DJ": 1 }`.                                            |
| `status`              | `object`   | Detailed per-engine status — see below.                                                                            |
| `createdAt`           | `string`   | Timestamp when the screening was created.                                                                          |

### Status Object

The `status` field contains a map of each screening engine to its individual status:

```json theme={null}
{
  "status": {
    "ARTEMISCAN": "DONE",
    "DJ": "PENDING",
    "INTERNET_SEARCH": "DONE"
  }
}
```

Possible values per engine: `PENDING`, `DONE`, `FAILED`.

### Example Response

```json theme={null}
{
  "id": 12345,
  "quickscanName": "John Doe",
  "quickscanType": "INDIVIDUAL",
  "finalStatus": "PENDING",
  "hasHit": false,
  "screenedWith": ["ARTEMISCAN", "DJ"],
  "screeningConclusion": [],
  "potentialHits": {},
  "status": {
    "id": 67890,
    "screeningId": 12345,
    "status": {
      "ARTEMISCAN": "PENDING",
      "DJ": "PENDING"
    }
  },
  "valid": true,
  "oddStatus": "OPEN",
  "remarks": [],
  "createdAt": "2025-01-15T10:30:00.000+00:00",
  "updatedAt": "2025-01-15T10:30:00.000+00:00"
}
```

***

## What to Do Next

1. **Poll for completion** — Call [`GET /api/quickscan/screen/{screeningId}`](./get-quick-scan-screening) using the returned `id` until `finalStatus` becomes `DONE`.
2. **Retrieve hits** — Call [`GET /api/quickscan/screen/{screeningId}/hit?screeningType=ARTEMISCAN`](./get-quick-scan-screening-hits) to get potential matches for each engine.

***

## Notes

* This is an **ad-hoc scan** and does not require a customer record to be created.
* Multiple screening engines can be combined by repeating the `chosenEngines` query parameter.
* The screening runs asynchronously. The initial response will have `finalStatus: "PENDING"`.
* Use **Get Quick Scan List** to retrieve historical Quick Scans and review past results.

***

## Important Notice

<Warning>
  The **Try-it SEND button** in the documentation UI may not serialize query parameters correctly for this endpoint.
  **Always copy the generated cURL command** and run it in your terminal or API client (e.g., Postman, Insomnia).
</Warning>


## OpenAPI

````yaml POST /api/quickscan/screen
openapi: 3.1.0
info:
  description: Api Documentation
  version: '3.0'
  title: Api Documentation
  termsOfService: urn:tos
  contact: {}
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0
servers:
  - url: https://api.artemis.cynopsis.co
security: []
tags:
  - name: app-config-controller
    description: App Config Controller
  - name: asia-verify-controller
    description: Asia Verify Controller
  - name: authentication-controller
    description: Authentication Controller
  - name: authentication-manager-controller
    description: Authentication Manager Controller
  - name: basic-error-controller
    description: Basic Error Controller
  - name: comment-controller
    description: Comment Controller
  - name: customer-controller
    description: Customer Controller
  - name: dashboard-controller
    description: Dashboard Controller
  - name: domain-controller
    description: Domain Controller
  - name: expiring-document-controller
    description: Expiring Document Controller
  - name: hand-shake-controller
    description: Hand Shake Controller
  - name: media-controller
    description: Media Controller
  - name: on-going-due-diligent-controller
    description: On Going Due Diligent Controller
  - name: own-restricted-list-controller
    description: Own Restricted List Controller
  - name: periodic-review-controller
    description: Periodic Review Controller
  - name: quick-scan-controller
    description: Quick Scan Controller
  - name: user-controller
    description: User Controller
paths:
  /api/quickscan/screen:
    post:
      tags:
        - quick-scan-controller
      summary: triggerQuickScan
      operationId: triggerQuickScanUsingPOST
      parameters:
        - name: chosenEngines
          in: query
          required: true
          description: One or more screening engines (repeat param to add more).
          schema:
            type: array
            items:
              type: string
              enum:
                - ARTEMISCAN
                - DJ
                - FACE_COMPARE
                - INTERNET_SEARCH
                - OCR
                - OWN_RESTRICTED_LIST
                - TR
          style: form
          explode: true
        - name: customerType
          in: query
          description: customerType
          required: true
          schema:
            type: string
            enum:
              - CORPORATE
              - INDIVIDUAL
        - name: name
          in: query
          description: name
          required: true
          schema:
            type: string
        - name: X-Domain-ID
          in: header
          description: X-Domain-ID
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ScreeningResponseDto'
        '201':
          description: Created
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
      security:
        - OAuth2_Client_Credentials: []
        - OAuth2_Password: []
components:
  schemas:
    ScreeningResponseDto:
      type: object
      properties:
        additionalInformation:
          $ref: '#/components/schemas/ScreeningAdditionalInformation'
        createdAt:
          $ref: '#/components/schemas/Timestamp'
        createdBy:
          $ref: '#/components/schemas/UserInfo'
        facInformation:
          $ref: '#/components/schemas/ScreeningFACInformation'
        finalStatus:
          type: string
          enum:
            - DONE
            - FAILED
            - NEVER
            - PENDING
        hasHit:
          type: boolean
        id:
          type: integer
          format: int64
        isPeriodic:
          type: boolean
        ocrInformation:
          $ref: '#/components/schemas/ScreeningOCRInformation'
        oddStatus:
          type: string
          enum:
            - CLOSED
            - OPEN
        profileId:
          type: integer
          format: int64
        quickscanName:
          type: string
        quickscanType:
          type: string
          enum:
            - CORPORATE
            - INDIVIDUAL
        remarks:
          type: array
          items:
            type: string
        screenedWith:
          type: array
          items:
            type: string
            enum:
              - ARTEMISCAN
              - DJ
              - FACE_COMPARE
              - INTERNET_SEARCH
              - OCR
              - OWN_RESTRICTED_LIST
              - TR
        screeningConclusion:
          type: array
          items:
            type: string
            enum:
              - ADVERSE_MEDIA
              - NO_HIT
              - OWN_RESTRICTED_LIST
              - PEP
              - SANCTION
        status:
          $ref: '#/components/schemas/ScreeningStatusResponseDto'
        updatedAt:
          $ref: '#/components/schemas/Timestamp'
        updatedBy:
          $ref: '#/components/schemas/UserInfo'
        valid:
          type: boolean
      title: ScreeningResponseDto
    ScreeningAdditionalInformation:
      type: object
      properties:
        djMonitoringCaseId:
          type: string
        djMonitoringTxId:
          type: string
        faceCompareDocumentId:
          type: string
        faceCompareSelfieId:
          type: string
        ocrDocumentId:
          type: string
      title: ScreeningAdditionalInformation
    Timestamp:
      type: object
      properties:
        date:
          type: integer
          format: int32
        day:
          type: integer
          format: int32
        hours:
          type: integer
          format: int32
        minutes:
          type: integer
          format: int32
        month:
          type: integer
          format: int32
        nanos:
          type: integer
          format: int32
        seconds:
          type: integer
          format: int32
        time:
          type: integer
          format: int64
        timezoneOffset:
          type: integer
          format: int32
        year:
          type: integer
          format: int32
      title: Timestamp
    UserInfo:
      type: object
      properties:
        email:
          type: string
        firstName:
          type: string
        fullName:
          type: string
        id:
          type: integer
          format: int64
        lastName:
          type: string
      title: UserInfo
    ScreeningFACInformation:
      type: object
      properties:
        faceCompareDocumentId:
          type: integer
          format: int64
        faceCompareSelfieId:
          type: integer
          format: int64
      title: ScreeningFACInformation
    ScreeningOCRInformation:
      type: object
      properties:
        ocrDocumentId:
          type: integer
          format: int64
      title: ScreeningOCRInformation
    ScreeningStatusResponseDto:
      type: object
      properties:
        createdAt:
          $ref: '#/components/schemas/Timestamp'
        createdBy:
          $ref: '#/components/schemas/UserInfo'
        id:
          type: integer
          format: int64
        profileId:
          type: integer
          format: int64
        screeningId:
          type: integer
          format: int64
        status:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Status'
        updatedAt:
          $ref: '#/components/schemas/Timestamp'
        updatedBy:
          $ref: '#/components/schemas/UserInfo'
      title: ScreeningStatusResponseDto
    Status:
      type: object
      properties:
        message:
          type: string
        status:
          type: string
          enum:
            - DONE
            - FAILED
            - NEVER
            - PENDING
      title: Status
  securitySchemes:
    OAuth2_Client_Credentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://crm.cynopsis.co/oauth/token
          scopes: {}
    OAuth2_Password:
      type: oauth2
      flows:
        password:
          tokenUrl: https://crm.cynopsis.co/oauth/token
          scopes: {}

````