Getting started

Truework’s API allows you to integrate our powerful verification capabilities directly with your application, and automate the process of creating verification requests and handling the results.

For this tutorial, we will be making requests to the Truework Sandbox. The sandbox is a parallel environment which can be used to manipulate requests and test your integration without affecting production data or being charged.

Prerequisites

To make requests to the Truework API, you will need to create an API key for the sandbox environment. It is also recommended that you configure a webhook to get notified when your order has been completed, although doing so is not required for this tutorial.

Creating an order

To create an order with the API, we will need to make an HTTP POST request to the /orders/target-employer endpoint. You can do this using curl, Postman, or via our built-in API Explorer .

1
curl -X POST https://api.truework.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 your order is created, copy the string returned in the id field, as we’ll need it for the next step.

Getting an order

Now that we’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.

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

Once you’ve fetched your order, you should notice a few things:

• The order’s list of verification_requests should include one verification with a state of completed
• The verification’s reports field is populated with a verification of Employment and Income (VOI) report
  • If you configured a webhook logger, you should see that the order.completed webhook has fired.
  • These actions occurred because we used a special SSN value (000-00-0000) in the sandbox environment, which caused the verification to be automatically processed and completed. Learn more about the SSNs that can be used in the sandbox here.

Moving to production

To start sending orders to production, you only need to change the base URL to https://api.truework.com, and change the API key to a production key.

Creating an employer search order

It’s possible to create an order that provides results synchronously, instead of requiring you to fetch results later. To do so, we’ll make an HTTP POST request to the /orders/employer-search endpoint:

1
curl -X POST "https://api.truework.com/orders/employer-search?fields=id%2Cverification_requests(id%2Creports(employee(positions(start_date)%2Csocial_security_number)))&include_income_analytics=true&include_report_annotations=true" \
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
    "date_of_birth": "1995-08-25",
9
    "first_name": "Jane",
10
    "last_name": "Doe",
11
    "social_security_number": "000-00-0000"
12
  },
13
  "type": "employment-income",
14
  "use_case": "mortgage"
15
}'

You’ll notice that the request body is largely the same, with one key difference - we did not include the target.company field. This is because employer search orders do not support verifying a specific employment. Rather, they search the Truework Instant network to find any employments that match the provided consumer.

When making requests in this fashion, you will not need to fetch the results in a separate step - any completed verifications will be included in the HTTP response. You will not receive webhooks for this type of request, since it will always be either completed or canceled by the time the response is returned.

Fetching different types of orders

While orders are created via different endpoint (POST /orders/target-employer, POST /orders/employer-search, etc.), they can all be fetched at the same base endpoint (GET /orders and GET /orders/<order_id>) regardless of the the endpoint used to create the order.