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

# Yardstik

> Run Yardstik background check workflows through Firstwork App Integrations and webhook postbacks

## Overview

Firstwork can connect to **Yardstik** background check workflows through the App Integration framework. In the current backend architecture, Yardstik is configured as an `AppIntegration` with one or more `AppIntegrationTemplate` action events, not as a dedicated provider model.

This means Yardstik calls are managed through automation actions and webhook triggers:

```mermaid theme={null}
graph LR
    A[Candidate or worker data changes] --> B[Automation trigger]
    B --> C[App Integration Action]
    C --> D[Yardstik API]
    D --> E[Yardstik webhook postback]
    E --> F[Firstwork Webhook Trigger]
    F --> G[Update application form fields]
```

> \[!NOTE]
> Firstwork records the integration title as **Yardstik**. Use that configured integration title when searching Firstwork integration records.

## Integration Model

Yardstik uses the same configurable integration primitives as other App Integrations:

| Component                       | Description                                                                                                            |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `AppIntegration`                | The external app record. Yardstik appears as an integration title in this table.                                       |
| `AppIntegrationTemplate`        | The HTTP contract for a Yardstik action, including method, URL, authentication, input variables, and output variables. |
| `AppIntegrationAction`          | The automation action that renders mapped data and calls the Yardstik API.                                             |
| `AppIntegrationActionExecution` | The execution audit record for each outbound Yardstik request.                                                         |
| `WebhookTrigger`                | The inbound postback trigger that receives Yardstik status or report updates.                                          |
| `WebhookTriggerInvocation`      | The idempotent receipt record for each incoming webhook call.                                                          |

Because the integration is configuration-driven, tenant implementations may vary by hiring flow, onboarding flow, package mapping, and destination fields.

## How It Works

### Outbound Request

An automation runs an **App Integration Action** when the configured trigger condition is met. Common trigger points include a candidate reaching a background-check step, an admin completing required background-check fields, or a scheduled automation polling Yardstik for report artifacts.

The action resolves input variables from application or worker data, renders the configured HTTP request, and sends it to the Yardstik API. Execution status, response details, and errors are visible in automation execution logs.

### Inbound Postback

Yardstik sends status and result updates back to Firstwork through a generated webhook URL:

```text theme={null}
/external/v1/automations/webhooks/{public_id}/fire/
```

The webhook trigger maps payload values into automation variables. Downstream actions commonly write those values into application form fields, such as background check status, result, report metadata, or exception details.

### Data Landing

Yardstik results land in configured Firstwork fields, usually form element values on application or onboarding pages. Unlike Sterling, Yardstik does not rely on a dedicated `YardstikScreening` data object in the backend. Treat the configured fields and automation execution history as the source of truth for a tenant's Yardstik workflow.

## Setup

### Confirm the App Integration

Verify that the company has an App Integration titled **Yardstik** and that its templates point to the correct Yardstik API endpoints.

### Configure action inputs

Map each template input variable to candidate, application, worker, or form data. Typical inputs include candidate identity, contact information, package or product identifiers, location fields, and callback metadata.

### Add automation actions

Use the Yardstik App Integration Action in the relevant hiring or onboarding automation. The automation should run only after all required background-check fields are available.

### Configure webhook postbacks

Create or confirm the Webhook Trigger used for Yardstik callbacks, then provide the generated callback URL to Yardstik. Map the inbound payload fields to the Firstwork fields or automation variables that downstream actions need.

### Validate execution

Run a controlled test candidate through the flow and confirm:

* The outbound `AppIntegrationActionExecution` succeeds.
* Yardstik receives the expected payload.
* The webhook trigger receives postbacks.
* The latest status and report fields are updated on the application.

## Monitoring and Troubleshooting

Use automation execution logs to inspect both the outbound Yardstik action and the inbound webhook processing. For deeper investigation, search executions by automation, status, candidate, and execution time, then open the specific execution record for rendered payloads, response codes, and errors.

When checking background-check outcomes:

* Review the latest successful or failed execution, not just the first callback.
* Expect multiple callback executions when Yardstik sends intermediate report updates.
* Check application activity logs for form field updates made by fill-form actions.
* Distinguish Yardstik background-check workflows from E-Verify employment eligibility workflows and other screening providers.

## Related Documentation

* [Custom Integrations](/integrations/custom-integrations)
* [Webhooks](/integrations/webhooks)
* [Automation Actions](/knowledge-base/automations/actions)
* [Dynamic Variables](/knowledge-base/dynamic-variables)