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

# Embedded Orders for Screening

> Implement employment verification for background screening

Embedded Orders enables candidates to verify their own employment history, dramatically speeding up the background check process.

<Tip>
  **Hosted orders work well for screening.** Candidates typically aren't logged into your platform when they need to verify. Send them a link and get notified when they complete. See [Hosted Orders](/developers/integration/hosted-orders/new-user) for the full guide.
</Tip>

***

## Why Embedded Orders for Screening

<CardGroup cols={2}>
  <Card title="Candidate Self-Service" icon="user-check">
    No waiting for HR departments to respond
  </Card>

  <Card title="Multiple Employers" icon="building">
    Verify entire work history at once
  </Card>

  <Card title="Instant Results" icon="clock">
    Data in seconds, not days
  </Card>

  <Card title="Better Experience" icon="face-smile">
    Mobile-friendly, simple flow for candidates
  </Card>
</CardGroup>

***

## Implement

<Steps>
  <Step title="Create an order [Server-side]">
    ```bash theme={null}
    curl --request POST \
         --url https://prod.truv.com/v1/orders/ \
         --header 'X-Access-Client-Id: YOUR_TRUV_CLIENT_ID' \
         --header 'X-Access-Secret: YOUR_TRUV_CLIENT_SECRET' \
         --header 'Content-Type: application/json' \
         --data '{
      "products": ["employment"],
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com",
      "external_user_id": "candidate-123"
    }'
    ```

    Extract the `bridge_token` from the response and pass it to the candidate's frontend, or use the `share_url` to send a hosted verification link.
  </Step>

  <Step title="Candidate opens widget [Client-side]">
    ```html theme={null}
    <script src="https://cdn.truv.com/bridge.js"></script>
    <script>
      var bridge = TruvBridge.init({
        bridgeToken: bridgeToken,
        isOrder: true,
        onSuccess: function() {
          console.log('Verification complete');
        }
      });
      bridge.open();
    </script>
    ```
  </Step>

  <Step title="Handle webhooks [Server-side]">
    When you receive a `task-status-updated` webhook with `status: done`, fetch the employment report:

    ```bash theme={null}
    curl --request GET \
         --url https://prod.truv.com/v1/links/{link_id}/employment/report/ \
         --header 'X-Access-Client-Id: YOUR_TRUV_CLIENT_ID' \
         --header 'X-Access-Secret: YOUR_TRUV_CLIENT_SECRET'
    ```
  </Step>
</Steps>

***

## Configure

### Order Settings

| Field              | Recommended                | Notes                                  |
| ------------------ | -------------------------- | -------------------------------------- |
| `products`         | `['employment']`           | Add `'income'` for Income & Employment |
| `first_name`       | Candidate's first name     | Required                               |
| `last_name`        | Candidate's last name      | Required                               |
| `external_user_id` | Your internal candidate ID | Optional, for tracking                 |

### Customization

To customize the Bridge widget appearance, create a template in the Truv Dashboard and pass the `template_id` when creating the order:

```bash theme={null}
curl -X POST https://prod.truv.com/v1/orders/ \
  -H "X-Access-Client-Id: YOUR_TRUV_CLIENT_ID" \
  -H "X-Access-Secret: YOUR_TRUV_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "products": ["employment"],
    "first_name": "Jane",
    "last_name": "Doe",
    "template_id": "YOUR_TEMPLATE_ID"
  }'
```

See the [Truv Dashboard](https://dashboard.truv.com) to create and manage templates.

***

## Employment report

The employment report returns an `employments` array with job history from the connected payroll provider.

```bash theme={null}
curl https://prod.truv.com/v1/links/{link_id}/employment/report/ \
  -H "X-Access-Client-Id: YOUR_TRUV_CLIENT_ID" \
  -H "X-Access-Secret: YOUR_TRUV_CLIENT_SECRET"
```

### Key fields

| Field            | Path                            | Example                                          |
| ---------------- | ------------------------------- | ------------------------------------------------ |
| Active status    | `employments[].is_active`       | `true` / `false`                                 |
| Job title        | `employments[].job_title`       | `"Software Engineer"`                            |
| Start date       | `employments[].start_date`      | `"2022-03-15"`                                   |
| End date         | `employments[].end_date`        | `null` (current) or `"2023-04-29"`               |
| Employer name    | `employments[].company.name`    | `"Acme Corp"`                                    |
| Employer address | `employments[].company.address` | Street, city, state, zip                         |
| Job type         | `employments[].job_type`        | `F` (Full-time), `P` (Part-time), `C` (Contract) |

<Accordion title="Full response example" icon="code">
  ```json theme={null}
  {
    "id": "24d7e80942ce4ad58a93f70ce4115f5c",
    "status": "done",
    "provider": "adp",
    "data_source": "payroll",
    "employments": [
      {
        "is_active": true,
        "job_title": "Software Engineer",
        "job_type": "F",
        "start_date": "2022-03-15",
        "end_date": null,
        "original_hire_date": "2022-03-15",
        "company": {
          "name": "Current Company Inc",
          "address": {
            "street": "123 Main St",
            "city": "San Francisco",
            "state": "CA",
            "zip": "94102"
          }
        },
        "profile": {
          "first_name": "Jane",
          "last_name": "Smith"
        }
      },
      {
        "is_active": false,
        "job_title": "Junior Developer",
        "job_type": "F",
        "start_date": "2019-06-01",
        "end_date": "2022-03-01",
        "company": {
          "name": "Previous Corp"
        },
        "profile": {
          "first_name": "Jane",
          "last_name": "Smith"
        }
      }
    ],
    "pdf_report": "https://..."
  }
  ```
</Accordion>

***

## Common screening scenarios

| Scenario                      | Product      | Report endpoint                              | Description                                                                         |
| ----------------------------- | ------------ | -------------------------------------------- | ----------------------------------------------------------------------------------- |
| **Standard Background Check** | `employment` | `GET /v1/links/{link_id}/employment/report/` | Employment history only                                                             |
| **Tenant Screening**          | `income`     | `GET /v1/links/{link_id}/income/report/`     | Income and employment (the `income` product includes employment data automatically) |

***

## Handle errors

Implement `onEvent` and `onClose` callbacks when initializing Bridge to handle candidate-side issues. Errors fire through `onEvent` with `type=ERROR` and an [`ErrorData`](/developers/sdks/bridge-events#errordata) payload -- inspect `error_code` to route the candidate to a fallback. See the [Bridge SDK](/developers/sdks/overview) for initialization options and [Bridge Events](/developers/sdks/bridge-events) for the full event reference.

***

## Best practices

<Tip>
  **Improve candidate completion rates with deeplinking.** If you know the candidate's employer, pass a `company_mapping_id` when creating the order. This skips the employer search step and drops candidates directly into the login flow -- a simple change with a significant impact on completion rates. [Learn more -->](/developers/integration/embedded-orders/deeplinking)
</Tip>

<AccordionGroup>
  <Accordion title="Use hosted orders for candidate outreach" icon="envelope">
    Candidates typically aren't logged into your screening platform when they need to verify employment. Create a hosted order with their email and phone. Truv sends them a link and handles reminders automatically. Use `notification_settings.suppress_user_notifications: true` only if you want to send the link through your own email system.
  </Accordion>

  <Accordion title="Allow multiple connections" icon="building">
    Candidates may have many past employers. Each employer connection produces a separate link. Retrieve the employment report for each link to build a complete history. For standard background checks requiring 5-7 years of history, candidates may need to connect multiple employers through separate Bridge sessions.
  </Accordion>

  <Accordion title="Set clear deadlines" icon="calendar">
    Send reminders to candidates who have not completed verification. Most completions happen within the first 24 hours.
  </Accordion>

  <Accordion title="Handle partial completions" icon="circle-half-stroke">
    Process available data even if not all employers are connected. Flag unverified positions for manual follow-up.
  </Accordion>

  <Accordion title="Provide fallback for unsupported employers" icon="file-arrow-up">
    Some employers may not be available through payroll integration. Enable document upload or manual verification as a fallback.
  </Accordion>
</AccordionGroup>

***

## Next steps

<CardGroup cols={2}>
  <Card title="Implementation Guide" icon="code" href="/screening/integration/implementation">
    Backend and webhook setup
  </Card>

  <Card title="Testing" icon="flask" href="/developers/testing/test-credentials">
    Test with sample candidate data
  </Card>

  <Card title="Hosted Orders" icon="envelope" href="/developers/integration/hosted-orders/new-user">
    Send verification links to candidates
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference">
    Complete API docs
  </Card>
</CardGroup>