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

# Unified Screening API

> Unified Screening API for candidate verification across platforms, with consistent data models for background checks, assessments, and screening workflows.

## What is a Unified API?

A **unified API** provides a single, standardized interface to interact with multiple third-party providers. Instead of learning each provider's unique API format, authentication scheme, and data model, you write code once, and StackOne handles the differences.

**What StackOne normalizes:**

* **Data models** – Consistent field names and structures across providers (e.g., `files` in Google Drive, SharePoint, and Dropbox all return the same schema; `users` in Google Workspace, Okta, and 1Password all return the same schema)
* **Authentication** – OAuth, API keys, and tokens are managed per-provider; you just pass an `x-account-id` header
* **Pagination** – Cursor-based pagination works the same regardless of whether the provider uses offsets, pages, or cursors
* **Error formats** – Standardized error responses with provider-specific details when available

<Tip>
  **Building AI agents?** Use the [MCP Server](/mcp/quickstart), an [AI Toolset SDK](/agents/typescript/introduction), or the [Actions API (RPC)](/platform/api-reference/actions/make-an-rpc-call-to-an-action) instead — same data, optimized for LLM tool calling.
</Tip>

## Benefits of StackOne Screening API

<AccordionGroup>
  <Accordion title="Standardized Endpoints for Screening Management">
    StackOne provides endpoints not just for initiating screenings but also for managing the entire screening lifecycle, making it easier to customize hiring workflows.
  </Accordion>

  <Accordion title="Privacy-First Design Ensuring Compliance">
    With a [focus on security](https://www.stackone.com/blog/why-your-choice-of-unified-api-could-make-or-break-compliance), StackOne's architecture ensures secure handling of sensitive candidate data, maintaining compliance with FCRA and data protection regulations.
  </Accordion>

  <Accordion title="Synthetic and Native Webhooks for Updates">
    The platform provides both [synthetic and native webhooks](/guides/webhooks), enabling real-time notifications for screening status changes and results.
  </Accordion>

  <Accordion title="Comprehensive Screening Provider Coverage">
    StackOne offers [pre-built connectors](https://www.stackone.com/integrations) with leading background check and assessment providers, simplifying the integration process.
  </Accordion>

  <Accordion title="Scalability and Ease of Use">
    The unified API allows for scalable and efficient integration, reducing the time and resources required for implementing multiple screening providers.
  </Accordion>
</AccordionGroup>

## Key Features

The table below shows key features of the Screening API that make candidate screening easier, from background checks to skills assessments:

| **Feature**                 | **Description**                                                                       |
| --------------------------- | ------------------------------------------------------------------------------------- |
| Background Check Management | Easily initiate, track, and retrieve results for various types of background checks.  |
| Assessment Integration      | Manage candidate assessments, from technical skills tests to personality evaluations. |
| Real-Time Webhooks          | Receive instant notifications for screening status updates and completed results.     |

## StackOne SDKs & OpenAPI Specification

<p class="sdk-text">Use our official SDKs for faster integration. Build with language-native libraries. Full list [here](/guides/stackone-api-sdks).</p>

<CardGroup cols={2}>
  <Card title="OpenAPI Specification" icon="link" href="https://api.eu1.stackone.com/oas/screening.json" arrow="true" cta="Click here" />

  <Card title="Popular SDKs" icon="download" class="sdk-card">
    [Node.js](https://www.npmjs.com/package/@stackone/stackone-client-ts)
    [Java (JVM)](https://mvnrepository.com/artifact/com.stackone/stackone-client-java)
    [PHP](https://packagist.org/packages/stackone/client-sdk)
    [Ruby](https://rubygems.org/gems/stackone_client)
  </Card>
</CardGroup>

## Entity Model and Relationships

The following diagram illustrates the key entities within the Screening API:

```mermaid theme={null}
erDiagram
    Candidate {
        string id
        string first_name
        string last_name
        string email
    }

    ScreeningOrder {
        string id
        string remote_id
        string package_id
        string candidate_id
        object passthrough
        object unified_custom_fields
    }

    ScreeningPackage {
        string id
        string remote_id
        string name
        string description
        object unified_custom_fields
    }

    ScreeningResult {
        string id
        string remote_id
        string order_id
        string summary
        string status
        string result_url
        datetime start_date
        datetime submission_date
        object unified_custom_fields
    }

    ResultScore {
        string label
        string value
        string min
        string max
    }

    WebhookEvent {
        string event
        object data
        array raw
    }

    Candidate ||--o{ ScreeningOrder : "requests"
    ScreeningPackage ||--o{ ScreeningOrder : "uses"
    ScreeningOrder ||--o{ ScreeningResult : "produces"
    ScreeningResult ||--|| ResultScore : "has"
    ScreeningResult ||--o{ WebhookEvent : "triggers"
```

The following table outlines key entities within the Screening system and provides a brief description of each.

| Entity           | Description                                                                                                                     |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Candidate        | Contains essential candidate information required for screening, including first name, last name, and email.                    |
| ScreeningOrder   | Represents a screening request for a candidate using a specific package, including any custom fields or provider-specific data. |
| ScreeningPackage | Defines available screening services, including name, description, and provider-specific configuration.                         |
| ScreeningResult  | Contains the outcome of a screening order, including status, summary, scoring, and access to detailed results.                  |
| ResultScore      | Represents the scoring details of a screening result, with label, value, and score range.                                       |
| Provider         | Represents the screening service providers integrated with the system.                                                          |
| WebhookEvent     | Defines the structure of webhook notifications for screening status updates and results.                                        |

The API supports the following screening result statuses:

* `pending`: Initial state when the screening is requested

* `in_progress`: Screening is currently being processed

* `completed`: Screening has been successfully completed

* `failed`: Screening process encountered an error

* `cancelled`: Screening was cancelled before completion

Webhook events are triggered for the following scenarios:

* `screening.result.created`: New screening result created

* `screening.result.updated`: Existing result updated

* `screening.result.completed`: Screening process completed

* `screening.result.failed`: Screening process failed

* `screening.result.cancelled`: Screening was cancelled

## Use cases

<CardGroup cols={3}>
  <Card title="Automated Background Checks">
    Streamline your hiring process by automatically initiating background checks when candidates reach specific stages.
  </Card>

  <Card title="Assessment Integration">
    Add skills assessments and personality tests directly into your hiring workflow.
  </Card>
</CardGroup>