Target Employer API

Make your first Target Employer Order

Truework’s Target Employer Order API enables you to seamlessly integrate robust verification capabilities directly into your application. In this guide, we’ll explore how to use the Truework Sandbox—a risk-free playground where you can test your integration without touching production data. Get ready to dive in and make your first request with ease!

Prerequisites

Creating an order

To create a verification request from your backend application, make a POST request to /orders/target-employer using a tool like curl, Postman, or via our built-in API Explorer. Making this POST request creates an order that will contain a single verification for the requested employer.

The /orders/target-employer endpoint processes your order asynchronously. Although you will receive a response instantly, there will be no reports associated with the verification on the order. You will need to retrieve the report(s) once the order is completed, which is detailed in the next section.

POST
/orders/target-employer
1curl -X POST https://api.truework-sandbox.com/orders/target-employer \
2     -H "Accept: application/json" \
3     -H "Authorization: Bearer <token>" \
4     -H "Content-Type: application/json" \
5     -d '{
6  "permissible_purpose": "child-support",
7  "target": {
8    "company": {
9      "name": "Acme Inc"
10    },
11    "first_name": "Jane",
12    "last_name": "Doe",
13    "social_security_number": "000-00-0000"
14  },
15  "type": "employment-income",
16  "use_case": "mortgage"
17}'

Once created, copy the string returned in the id field—we’ll need it for the next step.

Listening for webhooks

Truework uses webhooks to asynchronously update our partners when a verification is completed. Webhooks are configured under developer settings in the Truework app.

There are two types of webhooks: order completed and verification state change.

Of interest will mostly be the states completed and canceled:

  • A completed state indicates that new data is now available on the order
  • A canceled state indicates that a verification was not able to be completed, but may have user-provided information and/or documents

Order completed webhook

The order.completed webhook will be issued when all employer verifications associated with the order have been completed or canceled. Once you receive this webhook, you can fetch the order results.

1{
2  "hook": {
3    "id": 50,
4    "event": "order.completed",
5    "target": "https://example.com/webhook"
6  },
7  "data": {
8    "order_id": "AAAAAAAAAosABwGqF1AUKAH0-puth1tCzLNar3Jyb4bx3wdVKU99XC26",
9  }
10}

Getting an order

Now that you’ve created an order and copied its ID, we can get it from the API to see its current state and other data. To do so, we will need to make an HTTP GET request to the /orders/{order_id} endpoint.

GET
/orders/:order_id
1curl -G https://api.truework-sandbox.com/orders/AAAAAAAAQnIAAYd5YHFVOm8PNX2ecFbEjqV__upOKUE8YE_IK2GwSQTP \
2     -H "Accept: application/json" \
3     -H "Authorization: Bearer <token>" \
4     -d include_report_annotations=true

After retrieving your order, you should observe the following:

  • The verification_requests list in the order includes one verification with a completed state
  • The reports field of the verification contains a Verification of Employment and Income (VOIE) report
  • If you set up a webhook logger, you should see that the order.completed webhook has been triggered

These actions occurred because a special SSN value (000-00-0000) was used in the sandbox environment, which automatically processed and completed the verification. You can learn more about the SSNs available for use in the sandbox here.

Moving to production

A general API service account is recommended to manage the integration (e.g. truework@yourcompany.com).

When your integration is complete (or nearing completion), follow the steps below:

Questions?

Not a problem, we are here to help! Send your questions to implementations@truework.com.