Skip to main content

Making Your First API Request

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 API 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. When you are ready to start making requests to the production API, you will need to create a production API key, and change the base URL to that given in the API documentation.

info

The base URL for the Truework Sandbox is https://api.truework-sandbox.com.

Prerequisites#

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

Creating a Verification#

To create a verification with the API, we will need to make a POST request to the /verification-request/ endpoint. You can do this using cURL, Postman, or one of our SDKs.

$ curl 'https://api.truework-sandbox.com/verification-requests/' \
-X POST \
-H 'Authorization: Bearer sandbox-token' \
-H 'Content-Type: application/json' \
-d '{
"type": "employment",
"permissible_purpose": "risk-assessment",
"target": {
"first_name": "Joe",
"last_name": "Smith",
"social_security_number": "000-00-0000",
"contact_email": "joesmith@example.org",
"company": {
"name": "Example Inc."
}
},
"documents": []
}'

Once your verification is created, copy the string returned in the id field; we'll need it for the next step.

note

In this example, we passed a company name to create our verification. This allows you to create verifications for any company. However, it is also possible to pass a company id for faster turnaround times. To obtain a company id, we would make a GET request the companies endpoint with the company name.

Getting a Verification#

Now that we've created a verification, 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 a GET request to the /verification-request/<id>/ endpoint.

$ curl 'https://api.truework.com/verification-requests/YOUR_VERIFICATION_ID' \
-X GET \
-H 'Authorization: Bearer sandbox-token' \
-H 'Content-Type: application/json'

Once you've fetched your verification, you should notice a few things:

  • The verification's state has advanced to completed
  • The verification's reports field is populated with a VOE report
  • If you configured a webhook logger, you should see that two events have been sent: processing and completed

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. To learn more about the different special SSNs that can be used in the sandbox, see the API testing reference page.

Woohoo ๐ŸŽ‰#

You just created your first verification request!

Next Steps#

To see more detailed references regarding the requests and responses of various the API endpoints, see the API Docs.

To learn more about different ways that the endpoints can be used together to create complete verification workflows, check out our Implementation Guides.