Skip to main content
Complete guide for integrating Truv into your background screening workflow.

​
Architecture

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.

​
Backend implementation

​
Create an order for the candidate [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"
}'
Store the order_id and send the bridge_token or share_url to the candidate.

​
Handle completion [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'

​
Candidate experience

The candidate receives a verification link (via email, SMS, or embedded in your portal) and connects their employer accounts through Truv Bridge. See the Bridge SDK for client-side initialization and the React SDK for React-based integrations.

​
Testing

Use sandbox credentials to test different candidate scenarios before going live.
UsernamePasswordScenario
goodlogingoodpasswordSuccessful connection
goodloginmfaMFA required (code: 12345)
error.userlogin_errorConnection error
See Test Credentials for the full list of sandbox credentials.

​
Best practices

  • Send clear instructions to candidates explaining what verification involves
  • Set reasonable deadlines and send follow-up reminders
  • Handle partial completions — process available data even if not all employers are connected
  • Provide a fallback process for employers not available through payroll integration
  • Store the order_id alongside your candidate record for easy lookups