Embedded Orders for Screening

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

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 for the full guide.

Why Embedded Orders for Screening

Candidate Self-Service

No waiting for HR departments to respond

Multiple Employers

Verify entire work history at once

Instant Results

Data in seconds, not days

Better Experience

Mobile-friendly, simple flow for candidates

Implement

Create an order [Server-side]

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.

Candidate opens widget [Client-side]

<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>

Handle webhooks [Server-side]

When you receive a task-status-updated webhook with status: done, fetch the employment report:

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'

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:

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 to create and manage templates.

Employment report

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

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)

Full response example

{
  "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://..."
}

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 payload — inspect error_code to route the candidate to a fallback. See the Bridge SDK for initialization options and Bridge Events for the full event reference.

Best practices

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 —>

Use hosted orders for candidate outreach

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.

Allow multiple connections

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.

Set clear deadlines

Send reminders to candidates who have not completed verification. Most completions happen within the first 24 hours.

Handle partial completions

Process available data even if not all employers are connected. Flag unverified positions for manual follow-up.

Provide fallback for unsupported employers

Some employers may not be available through payroll integration. Enable document upload or manual verification as a fallback.

Next steps

Implementation Guide

Backend and webhook setup

Testing

Test with sample candidate data

Hosted Orders

Send verification links to candidates

API Reference

Complete API docs

Screening

Integration

​Why Embedded Orders for Screening

Candidate Self-Service

Multiple Employers

Instant Results

Better Experience

​Implement

​Configure

​Order Settings

​Customization

​Employment report

​Key fields

​Common screening scenarios

​Handle errors

​Best practices

​Next steps

Implementation Guide

Testing

Hosted Orders

API Reference

Why Embedded Orders for Screening

Implement

Configure

Order Settings

Customization

Employment report

Key fields

Common screening scenarios

Handle errors

Best practices

Next steps