Accurate Background APIv3 Completely New Version

Introduction

Release of completely new version

In May of 2016 Accurate Background released a complete overhaul of their popular API for performing a variety of background checks.  I’ve been using the prior API for almost a year, and while it was powerful, it did seem a little rough around the edges in places. I’m pleased to report that the new API, called APIv3, is an enormous improvement on an already solid API product.   The new APIv3 uses a different design paradigm, follows standard RESTful conventions, and maybe best of all, has a completely new, free and automated account signup process.  You can sign up for a test account online and immediately receive access to a developer dashboard with the API credentials you need to start making calls. The documentation is complete, online, interactive and available to everyone on the web.

 

History of the prior  Background Check API

The prior version of the Accurate Background API was termed version 2, though the documentation (available only as a PDF) listed it as version 1.5.  That API was HTTPS based, but it didn’t have a completely consistent format for the URLs used, making it harder to develop for.  The different HTTP calls had differing requirements for providing parameters in the URL, as Form encoded parameters, and sometimes required JSON blocks to be passed in the call.   The error messages were not particularly useful, and so implementing the API – like most APIs – required a considerable amount of trial and error with attendant head-scratching.   The new APIv3 is so standards compliant and consistent that it can be tested in minutes with common off-the-shelf API tools like Postman.

 

What service does this API provide?

Essentially, the Accurate Background APIv3 is a tool to enable the trust economy, the sharing economy and the gig economy.  Apps like ridesharing or delivery or home services involve getting people together, to provide services to one another and to share their personal resources.  This requires a high level of trust on both sides of the transaction.  An app signing someone up to provide a service needs to know whether that person is qualified to provide the service, for instance, has a driver’s license or some other professional certification.  Background checks can also be used to look for other indicators of trustworthiness. For instance, your app could check to see if someone is on the global terror watch list, on the US sex offender registry or has one or more criminal convictions.

 

What can I check?

The Accurate Background APIv3 provides all those background searches and more. Here’s a quick table of the most useful (and interesting!) checks:

MVR Motor Vehicle Report- does the candidate have speeding tickets, revoked license, etc?
SON National Sex Offender Registry – self explanatory
TERB Global Terror Watch list – Looks at hundreds of sources globally such as OFAC, OIG, GSA, Most Wanted, Interpol, and the list goes on and on
FED-CR Federal Criminal District Court Search – Searches for criminal cases tried at the federal court level.  It is recommended you search each district where the applicant has lived as provided by the MOV search.
F/M County Court Criminal Search.  You will need one in each county where an applicant has lived, that data is provided by the associate MOV search.
MOV SSN Trace, discovers all the recent addresses for a Candidate
FACIS

 

Fraud and Abuse Control Information system – a database for health care providers who have run afoul of government agencies like the GSA, OIG, etc.
OFAC Office of Foreign Asset Control – Searches the US Dept. of Treasury for sanctions violations and other violations of national security policy
FED-BK Search the Federal Bankruptcy databases
DL5 and DL7 Drug screens! The Candidate has to go pee in a cup at a medical facility near them.

In the AB APIv3 these checks are combined into simpler packages to make ordering easy.  There are also other searches, including employment and education verification available. Check the docs in the nav section “Customizing Orders/US Searches for a complete list.

 

What can I do with it?

Any app that matches people with personal services has a use for background checks.  One set of common App use cases are ride sharing and delivery like Uber, Lyft, DoorDash and HelloFresh, where drivers contract to deliver goods and services. These companies need a simple API to verify that the folks signing up on the app have a valid driver’s license and meet other risk-reduction criteria.   If your app matches unused personal property with folks who have a need, like AirBnB, car sharing apps, bike sharing apps, book sharing or any other form of property sharing, that app may need a way to establish a higher degree of trust between the owner and the renter of the property.  Dating Apps benefit from greater trust between participants.  Employment apps can verify criminal history, level of education and prior employment.  Babysitters and other folks providing in-home services might need an automated screening on a periodic basis.

As the sharing/trust economy grows and matures I’m confident that new and innovative uses for this information will continue to show up in new mobile and social apps.

New Feature Set

OK, now let’s move along to an exploration of the actual APIv3.

Very RESTful

The APIv3 is very RESTful, which means it hews closely to a specific standard for how HTTP APIs should work. See the Wikipedia article for a complete description, but I’ll do a basic recap here.

Resource Oriented

The APIv3 establishes a set of resources, which live at specific URLs.  URL stands for Universal Resource Locator.  The AB APIv3 has a very simple set of just three resources.  The corresponding URLs are here:

https://api.accuratebackground.com/v3/candidate A candidate to run checks on. Create once, and reuse as often as you want.
https://api.accuratebackground.com/v3/order An order to place one or more background searches, or check the results of the searches.
https://api.accuratebackground.com/v3/report

 

More detailed results of the background check. Not really needed in most cases, since the Order resource itself rolls up the results of the background checks.

When you make an HTTPS API call to one of those resources, you specify the HTTP ACTION to tell the API whether you want to create, update, or retrieve that resource.

When you want to create a resource you use the HTTP POST.

When you want to update the resource you use HTTP PUT.

When you want to read a resource, you use HTTP GET.

Simple.

 

When a resource is created (with a POST) that resource is assigned a resource ID, which is returned to you in the response to the API call.  You can then use that ID to read or update the resource in the future.

For example, to create a candidate I would make a POST HTTPS call to https://api.accuratebackground.com/v3/candidate

With some parameters describing the candidate (more on that below) and I would get back a candidate ID which would look like this:

 

“resource”:”CANDIDATE”,

“id”:”5faf84d1″,

 

When I want to retrieve that candidate, I would make an HTTP GET call to the candidate resource, and include the id in the URL like this:

https://api.accuratebackground.com/v3/candidate/5faf84d1

Simple.

 

Easy to test with Postman

A tool like Postman makes the process of learning and testing the AB APIv3 really easy.

Find Postman here:  https://www.getpostman.com/

For the remainder of this posting I’ll use Postman to demonstrate how to test the AB APIv3.

Let’s show how to get credentials and start testing.

 

Basic Auth and setting your credentials

All you need to place APIv3 calls are the HTTP basic authentication values.  When you sign up for a free account online at http://developer.accuratebackground.com  you are immediately given access to the developer dashboard, which shows your credentials.

dash

In Postman, click on the ‘Authorization’ tab, and set the Type of authorization to ‘Basic Auth’. You can then copy and paste the credentials.  Put the ‘Client ID’ into the ‘Username’ field, and use the ‘Client Secret’ for the Basic Auth password.

ready

You are now ready to use Postman to test the API.

Reading the response

In all cases (the APIv3 is very consistent) the results of an API call are a JSON formatted HTTP result.  This makes the result very easy to read, understand and to parse.

Here is a complete example of a candidate resource response:


{
"resource": "CANDIDATE",
"id": "572d035feae5744796707a88",
"created": "2016-05-06T20:49:35Z",
"updated": "2016-05-06T21:30:00Z",
"revision": "12",
"firstName": "Bugs",
"lastName": "Bunny",
"middleName": null,
"dateOfBirth": "1940-06-06",
"ssn": "123556666",
"email": "bugs@bunny.com",
"phone": "1234445566",
"address": "4000 Warner Boulevard",
"city": "Burbank",
"region": "CA",
"country": "US",
"postalCode": "98117",
"governmentId": {
"country": null,
"type": null,
"number": null
},
"aliases": [],
"educations": [],
"prevEmployed": null,
"employments": [],
"licenses": [],
"convicted": null,
"convictions": [],
"references": []
}

The resource responses always start with a description of what type of resource it is, the ID of that specific resource, and the creation and modification dates.

The revision parameter tells you how many times that candidate has been updated.

Sending Parameters

When you read a resource with a GET you don’t need to send any parameters in the body of the API call – the only important parameter is the resource ID, which goes in the URL.  But when you are creating or updating a resource you do need to provide parameters to populate the resource.  For instance, when creating a candidate you will need to provide the first name, last name, phone number, email address, and government id (SSN in the U.S.).  You can do this in all cases by passing in form-encoded parameters in the body of the HTTP call.  This is exactly the same as if an HTTP form POSTed to the API; the content type is application/x-www-form-urlencoded and the parameters are sent as key/value pairs.

Your API testing tool or development environment will put together the actual HTTP call for you, all you need to know is that there are key/value pairs for the parameters, and the correct content-type, which is ‘x-www-form-urlencoded’.

In compound parameter names, like firstName, the first letter is lower case.  The API is case sensitive.

POSTing in parameters as easy as typing the parameter names and values.  Here’s a screen shot:

dev

For a candidate, the minimum parameters required to run a basic search are:

firstName Yes, the first name
lastName Last name. Middle names are optional.
email Useful for the ‘Interactive’ workflow, where the candidate fills in the rest of the information via a web form link sent to that email
address Current candidate living address
city
region This is ‘State’ in the US
country ‘US’ in the US, UK, etc.
dateOfBirth Helpful to disambiguate people with similar names – Don’t have this? Keep reading as there are other ways to gather this.
ssn Needed for many comprehensive background checks where you are strategically searching based on a person’s address history – Don’t have this? Keep reading as there are other ways to gather this.

 

Candidates are persistent

Candidate resources are persistent within the AB APIv3.  This means that you can reuse candidates easily, either to run additional checks on the same person over time, or perhaps to run the same checks on a periodic basis, for example to confirm that the candidate Motor Vehicle Registration is still clean.  You can also use the APIv3 to find your candidates.  If you issue a GET to the candidate resource without a candidate ID, you’ll see all your candidates returned.  If you issue a GET to the candidate resource with any combination of firstName, lastName, dateOfBirth or ssn and you’ll receive only those candidates back which match your criteria.

 

Two ways to collect or pass candidate data

In many cases you may not have all the candidate information (date of birth, ssn, etc) required to run the searches you want.  The AB APIv3 has you covered.  You can create a candidate with only a firstName, lastName and email, and then when you place an order (with POST to the order resource) you can specify the ‘Interactive’ workflow.  This will place the order, and send an email to the candidate with a link to fill in the required information.  When the candidate completes the data entry your order will pick back up and perform the background checks.  If you already have all the information required to place an order for the background check, and you have the candidate’s consent to do it, you can use the ‘Express’ workflow.

 

Store more data on the Candidate

Because the candidate resource is persistent, it’s a great place to store more information as you generate it.  (because there are no fees for creating or managing candidates, you could also use the AB APIv3 as a form of free and secure CRM tool!)  You can add aliases, conviction information, additional forms of identification and more to a candidate record.  Check the documentation for complete details.

 

Pass in a JSON body to create candidates

Creating a candidate is pretty simple in the most common cases, but you can imagine that if you wanted to create a really complex candidate with a lot of education entries, aliases, etc, you would end up with a complicated set of parameters.  In these cases is might be easier to POST in a completed JSON object to describe the candidate you want to enter.  The AB APIv3 supports this (for candidate and order creation, but not modification).  In Postman, you change the body from ‘x-www-form-urlencoded’ to ‘raw’, and change the content-type to ‘JSON application/json’.  Then paste in a JSON object that matches the format and layout of that returned by a GET to the candidate resource, but without the ID, creation, modification and revision.

persistent

Orders are Persistent

Order resources are persistent as well.  When you place an order it has a ‘status’ set to ‘PENDING’, meaning that it is processing.   When processing is complete, which could take anywhere from a few seconds to a few days, the status changes to ‘COMPLETE’.  In this version of the API you’ll need to check back on your orders by issuing a GET to the order resource to check the status.  I have it on good authority that subsequent versions of the APIv3 will have a callback functionality which will notify you when orders complete.

 

Order with pre-built packages or customize

The Accurate Background APIv3 has a wide range of background searches it can run, but it’s often easier (at least for testing) to use one of the prebuilt packages of background searches.  There are three packages available (plus an empty package for building your own searches), listed and explained in the table below.

 

PKG_BASIC Does a national criminal search in the U.S. Returns any past convictions if included in the database. This search completes very quickly, so it’s good for automated systems however it can have gaps in the information so it is recommended you conduct this alongside a county criminal search (F/M).
PKG_STANDARD Does a search on criminal convictions included in the national database, but also looks up the location where the candidate lives and runs a county criminal records search in that jurisdiction as well.  It also checks the global terror watch list.
PKG_PRO Like the PKG_STANDARD, but runs an SSN trace to find out everywhere the candidate has lived in the last seven years, and checks criminal records in those jurisdictions as well.
PKG_EMPTY You use this package to ‘roll your own’.  For instance, if you just need to check drivers, you could start with the PKG_EMPTY and add MVR, Global Terror, and National Criminal Database.

The process for adding your own custom searches to the empty package is a little tricky, because the packages go into an array called ‘’additionalProductTypes” on the order resource.

If you are using form-encoded params in Postman, then the parameter names look like this:


additionalProductTypes[0].productType

and so in Postman that might look like this:

next1
Note that the array enumerator increments for each new product you add.  In this example, I get an error message back because I have not entered a driver’s license for my Bugs Bunny candidate, so the API cannot run a Motor Vehicle Report on him.  The error message nicely describes the problem and tells me exactly which parameter I need to add on my candidate.

Checking an Order

Depending on what sorts of checks you included in the order, it may complete immediately or it might take several days.  Many county criminal court systems don’t have automated systems which can be searched, and so those checks might require an actual visit from a human being, which obviously is going to take a few days to complete.  You’ll know when the order is complete by checking the ‘status’ field in the response to a GET on an order.

For instance, if I do a GET to this URL:

https://api.accuratebackground.com/v3/order/572d0bb7f1b9a4602bc83a0a

I see this snippet included (with much more information) in the response.


"completed": "2016-05-06T21:25:13Z",
"candidateInfoComplete": true,
"supportReferenceId": "Y3156519",
"status": "COMPLETE",
"result": "NEEDS REVIEW",
"reports": [
{
"base64encodedHTML": "/report/572d0bb7f1b9a4602bc83a0a"
}

 

The   “status”: “COMPLETE” indicates that the background check completed, and the “result”: “NEEDS REVIEW” indicates that some flags were found in the checks.  To be compliant with US regulations, the AB APIv3 can’t say that someone ‘failed’ a background check, it can only indicate that the search turned up some results that someone should check out further.

A search that comes back complete without finding any red flags looks like this:

 

"completed": "2016-05-06T21:13:50Z",
"candidateInfoComplete": true,
"supportReferenceId": "Y4043279",
"status": "COMPLETE",
"result": "MEETS REQUIREMENTS",

The ‘supportReference’ field shows an order ticket number that can be used to look up the results if you need to contact Accurate Background for some reason.

So, let’s say that the order comes back ‘NEEDS REVIEW’.  How do you know which search in the background check had the red flags, and what findings those flags were based on?  With a little more digging in the order resource results you can find out.

The ‘products’ array in the result shows each of the constituent searches that was performed.  For example, in this order:

"products": [
{
"id": 46300177,
"productType": "NCRIM",
"status": "COMPLETE",
"result": "NOT APPLICABLE",
"flag": false
},
{
"id": 94473809,
"productType": "F/M",
"status": "COMPLETE",
"result": "NO RECORD FOUND",
"flag": false
}

There was a National Criminal search and a County Criminal search, and the result of each was either “NOT APPLICABLE” or “NO RECORD FOUND” to indicate that no criminal records were discovered.

In this much longer order result for a PKG_PRO:


"completed": "2016-05-06T21:25:13Z",
"candidateInfoComplete": true,
"supportReferenceId": "Y3156519",
"status": "COMPLETE",
"result": "NEEDS REVIEW",
"reports": [
{
"base64encodedHTML": "/report/572d0bb7f1b9a4602bc83a0a"
}
],
"additionalProductTypes": null,
"products": [
{
"id": 120414137,
"productType": "NCRIM",
"status": "COMPLETE",
"result": "NOT APPLICABLE",
"flag": false
},
{
"id": 59053106,
"productType": "MOV",
"status": "COMPLETE",
"result": "NOT APPLICABLE",
"flag": false
},
{
"id": 86249016,
"productType": "TERB",
"status": "COMPLETE",
"result": "RECORD FOUND",
"flag": true
},
{
"id": 49895801,
"productType": "F/M",
"status": "COMPLETE",
"result": "RECORD FOUND",
"flag": true
}
],

We can see that the order as a whole received a result of ‘NEEDS REVIEW”, and when we look at the individual search products we see a “RECORD FOUND” for the terror watch-list (TERB) and for a county criminal search.  Don’t loan that guy a car, or a plane.

 

Even more report details

What if you want to see even more detail? The API results are designed to be simplified to make it easier to evaluate the background check, but in some cases you may want to see the underlying background check report in more detail.  You can retrieve a human readable HTML formatted report with the report resource.   In the example above, note the “reports’ array:


"reports": [
{
"base64encodedHTML": "/report/572d0bb7f1b9a4602bc83a0a"
}

If you do a GET to that resource (the full URL would be https://api.accuratebackground.com/v3/report/572d0bb7f1b9a4602bc83a0a ) you will receive a long text string, which you can base64 decode and store as an HTML file.

The response to that API call (with the report string truncated) looks like this:

 


{
"id": "573626147114b8175a783fb5",
"resource": "REPORT",
"created": "2016-05-13T19:21:14Z",
"supportReferenceId": "Y8069013",
"reportFormat": "HTML",
"report": "PCEtLSANCiAgQ3Jl…. Realllllly long string here…….++"
}

The decoded, saved HTML file looks like this:

last1

Conclusion

The Accurate Background APIv3 is a huge improvement over the previous version in terms of consistency, ease of implementation, standards compliance and general simplicity.  Using standard HTTPS and basic auth for security and standard REST resource behaviors makes it easy to test and develop for. Being able to get a free test account online with no other intermediary is very developer friendly and forward thinking, particularly compared to Checkr, where you now need to talk to a salesperson who ‘reviews’ your application before you get account credentials.

There are currently no SDK type libraries published for different languages or dev environments, but I suppose that’s a task for the developer community.  The docs are complete and do have examples in curl and ruby, though examples in node.js, php, or java would be welcome.

Going from test to production is pretty easy, and uses an online document signing solution (DocVerify) to collect company information.  Billing is done via credit card through the developer portal, and is done on a pay-as-you-go basis, charging for the production background checks you order.  There are no charges for any API calls in the test environment.

I give this API a big thumbs up, and am looking forward to see additional features and functionality as Accurate Background rolls out enhancements to the APIv3!