Introduction

The BlockScore API is RESTful and adheres to the philosophy of using as many native aspects of browsers as possible. For instance, authentication is handled with HTTP Basicand the API is versioned using HTTP headers. We try to make all of our endpoints predictable and understandable.

For your convenience, we generate language-specific API wrappers that make integration easier. We also provide a test mode which lets you run as many test verifications as you’d like while integrating without incurring any costs.

If you ever have any trouble while integrating, please visit our support page to join our live chat so that we can help you. Good luck!

API Endpoint

https://api.blockscore.com

Summary of Resource URL Patterns

  • /people
  • /people/{PERSON_ID}
  • /question_sets
  • /question_sets/{QUESTION_SET_ID}
  • /question_sets/{QUESTION_SET_ID}/score
  • /companies
  • /companies/{COMPANY_ID}
  • /candidates
  • /candidates/{CANDIDATE_ID}
  • /candidates/{CANDIDATE_ID}/history
  • /candidates/{CANDIDATE_ID}/hits
  • /watchlists

Client Libraries

We maintain a set of officially support client libraries which make integrating and using the BlockScore APIs significantly easier.

Code examples for any of these client libraries can be seen by selecting your language of choice from the top right of the window.

Official Libraries

Language Source Code Package Manager
Ruby View on GitHub RubyGems
Python View on GitHub Python Package Index
Node View on GitHub NPM
PHP View on GitHub Composer
Java View on GitHub MVN

Community & Deprecated Libraries

The following client libraries were made by community members and thus may be out of date or incomplete. Always do your own dilligence on these client libraries before using them in production.

Language Author Link
C# Lorne Lantz BlockScore/blockscore-csharp
Go Connor Jacobsen connorjacobsen/blockscore-go
Meteor Futurama56 resolverio/meteor-blockscore
iOS Jomell Jomell/BlockScoreWrapper

Authentication

All authentication is handled through HTTP Basic authentication. You should input your API key in the username field of the Basic auth prompt.

You can lookup your API keys on your company’s dashboard page. You will see two listed keys, one for “live” and one for “test”. The live API key (the key prepended with sk_live) is for running real verifications that will be added to your monthly bill. These will be checked against real verification data.

The test API key (the key prepended with sk_test) should be used in your development environment and will allow you to integrate BlockScore without being charged for usage.

BlockscoreApiClient client = new BlockscoreApiClient("your-api-key");

Errors

The API uses standard HTTP response codes to indicate success, failure and everything inbetween. The various codes we return are outlined on the right side. Whether a verification status is returned valid or invalid has no bearing on whether or not we return a 200 OK status.

All errors should be returned in the form of JSON along with a message which explains the issue in plain english. When a validation error occurs return the name of the field which is invalid one by one, so if you forgot to include two fields, only the name of the first field will be returned.

Attributes

error[type] string
The type of error that occurred (see all error types on the right).
error[message] string
A plain english explanation of what went wrong during the verification.
error[param] string
In the event of a validation error, this will specify which parameter was invalid.
error[code] string
In the event of a validation error, this will explain why a validation was incorrect.

HTTP Status Codes

200 OK The request was successful.
201 Created The resource was successfully created.
400 Bad Request A validation error occurred.
401 Unauthorized Your API key is invalid.
402 Request Failed Something was wrong with your parameters.
404 Not Found The resource does not exist.
50X Internal Server Error An error occurred with our API.

Error Types

invalid_request_error Something went wrong with how you submitted your request.
api_error Something went wrong with our API.

Validation Error Types

is_invalid A required parameter is incorrectly formatted.
cant_be_blank A required parameter is missing.

Filtering

Attributes

All API resources can be filtered by any attribute using the filter[] query parameter on the resource’s index. You can specify more than one filter to further constrain your results.

Arguments

filter[key] optional
Constraint on the attribute key restricting the results to objects where the attribute `key` is exactly equal to the value specified.

Comparisons

Timestamp attributes support more advanced filtering methods so that you can specify time ranges as a constraint for your search results.

Comparators

gt Return values where the field is greater than the specified value
gte Return values where the field is greater than or equal to the specified value
lt Return values where the field is less than the specified value
lte Return values where the field is less than or equal to the specified value

In this example we lookup verifications created in the year 2015 which received a valid status. The value 1420099200 is the UTC timestamp for 2015-01-01 00:00:00.

There is no code example for this API call.
{
  "total_count": 5,
  "has_more": false,
  "object": "list",
  "data": [
    {
      "object": "person",
      "id": "544744f43266330002010000",
      "created_at": 1420185600,
      "updated_at": 1420185600,
      "status": "valid",
      "livemode": true,
      "phone_number": null,
      "ip_address": "",
      "birth_day": 23,
      "birth_month": 8,
      "birth_year": 1993,
      "name_first": "John",
      "name_middle": null,
      "name_last": "Doe",
      "address_street1": "1 Infinite Loop",
      "address_street2": null,
      "address_city": "Cupertino",
      "address_subdivision": "CA",
      "address_postal_code": "95014",
      "address_country_code": "US",
      "document_type": "ssn",
      "document_value": "0000",
      "note": "ref-id:12345",
      "details": {
        "address": "no_match",
        "address_risk": "low",
        "identification": "partial_match",
        "date_of_birth": "partial_match",
        "ofac": "no_match",
        "pep": "no_match"
      },
      "question_sets": [
        "536c1532627463780b000000"
      ]
    },
    { ... }
  ]
}

Searching

Similar to filtering, all API resources can perform fuzzy searches across all of their attributes. While explicit attribute filters restrict results to only resources that exactly match the provided input, fuzzy searches also return similar results.

Arguments

filter[q] optional
Fuzzy search the resource’s attributes for the value provided.

Returns

A list of the given resource where one or more of its attributes matched the given filter[q].

There is no code example for this API call.
{
  "total_count": 5,
  "has_more": false,
  "object": "list",
  "data": [
    {
      "object": "candidate",
      "id": "544aba053163310002630500",
      "created_at": 1414183429,
      "updated_at": 1414183429,
      "livemode": true,
      "note": "55555555",
      "ssn": "0002",
      "passport": null,
      "date_of_birth": "1940-08-11",
      "name_first": "John",
      "name_middle": null,
      "name_last": "Bredenkamp",
      "address_street1": null,
      "address_street2": null,
      "address_city": "Harare",
      "address_subdivision": null,
      "address_postal_code": null,
      "address_country_code": "AR"
    },
    { ... }
  ]
}

Versioning

We use HTTP headers to specify version numbers. More specifically, to define which version of the API you’d like to use, add the following to your HTTP headers along with your request:

Accept: application/vnd.blockscore+json;version=4

The rest of this article will help you understand how our versioning works and what determines whether a version number is incremented.

Minor releases

Minor releases occur every day and do not break any client integrations. These are for things like bug fixes or new features that do not disrupt existing code.

You do not need to do anything to receive these updates as they will be applied to your account automatically.

Major releases

Major releases contain backwards-incompatible changes that will require a few changes on your part to benefit from. To upgrade to a new major version, view the appropriate upgrade guide provided on this page.

Current version

The latest version of the API is 4.

If you do not include a version number, requests will default to the latest version which could break your implementation.

Client libraries will automatically handle this for you.

Security

Store as little Personally Identifiable Information (PII) on your servers as possible. We recommend deleting any non-essential PII from your servers to reduce the potential of data leaks in the event of an attack on your system.

Do not reuse question sets. It can be tempting to reuse question sets if somebody fails verification in order to save money. However, we highly discourage this as it decreases the difficulty of a fraudster circumventing your systems on a second attempt. We generate new question sets each time, which helps you keep your systems secure.

Do not submit real customer information using test credentials. Because test credentials have been historically less closely guarded by businesses we’ve worked with in the past, we recommend not submitting sensitive information using test credentials to prevent data leaks.

Use SSL for every API request. When communicating with the BlockScore API, it is necessary that you use SSL for every request you make to our servers. If you’re using test keys, SSL is optional, but using live keys we mandate that all requests originate from an SSL-encrypted source.

Do not store your API keys in version control. If you’re using version control like Git or Subversion, do not store your API keys in your version control. It is recommended that you store keys in a file that is never checked into the repository. If you use Heroku, learn about environment variables and store your credentials using them.

Getting started with SSL

If you need help getting started with SSL on your application, you can use the resources below to help.

Ruby OpenSSL Ruby API Documentation
PHP OpenSSL PHP API Documentation
Python SSL API Documentation
Node.js HTTPS API Documentation
.NET SslStream Class Documentation
Go TLS Package Documentation

Testing

Test verifications

If you’d like to run test verifications, make sure to use your test API key while authenticating. Verifications you make using this key will not be verified using real data and will not be charged.

In order to test certain outcomes, we have supplied some special SSNs that when submitted using one of your test API keys will always return a predictable result.

If you’d like to run a test international verification, make sure that the last 4 digits of whichever identification method you choose are either 0000 or 0001 to test validity and invalidity respectively.

Test question sets

These are some of the possible questions that can come up when creating test question sets. Their order will be randomized, so you’ll need to find the answer ID corresponding to the answers written below in your particular question set.

Test companies

To test companies, make sure that the last 4 digits of the tax_id are one of the predetermined values listed to the right.

Test codes for verifications

Last digits of identification Outcome
0000 The verification will always return valid.
0001 The verification will always return invalid.

Test codes for companies

Tax ID Outcome
000000000 The company will always return valid.
000000001 The company will always return invalid.

Test codes for question sets

Answer Question
309 Colver Rd Which one of the following addresses is associated with you?
812 Which one of the following area codes is associated with you?
Jasper Which one of the following counties is associated with you?
49230 Which one of the following zip codes is associated with you?
None of the above What state was your SSN issued in?
None of the above Which one of the following adult individuals is most closely associated with you?

Documents

We offer the ability to verify a variety of international documents in our people verification system. Below are all of the valid document types for each country.

Included for your convenience is whether or not we require a postal code for each of the countries we support.

Document types

ISO Code Country Postal code Supported documents
US United States of America Yes ssn
drivers_license
AL Albania Yes passport
personal_identification
AO Angola No passport
personal_identification
AR Argentina Yes passport
personal_identification
drivers_license
AU Australia Yes passport
AT Austria Yes passport
drivers_license
identity_card
BS Bahamas No passport
drivers_license
BH Bahrain Yes passport
personal_identification
BB Barbados Yes passport
drivers_license
BE Belgium Yes passport
drivers_license
identity_card
BO Bolivia Yes passport
drivers_license
identity_card
BA Bosnia and Herzegovina Yes passport
personal_identification
BR Brazil Yes passport
drivers_license
BG Bulgaria Yes passport
personal_identification
CA Canada Yes passport
identity_card
drivers_license
KY Cayman Islands Yes passport
drivers_license
CL Chile Yes passport
personal_identification
drivers_license
CN China Yes passport
personal_identification
CO Colombia Yes passport
personal_identification
drivers_license
CR Costa Rica Yes passport
drivers_license
HR Croatia Yes passport
personal_identification
identity_card
CZ Czech Republic Yes passport
personal_identification
drivers_license
identity_card
CI Cote D’Ivoire No passport
personal_identification
DK Denmark Yes passport
drivers_license
DO Dominican Republic Yes passport
drivers_license
ER Eritrea No passport
personal_identification
EE Estonia Yes passport
personal_identification
identity_card
FI Finland Yes passport
personal_identification
identity_card
FR France Yes passport
personal_identification
identity_card
GE Georgia Yes passport
personal_identification
DE Germany Yes passport
personal_identification
drivers_license
identity_card
GR Greece Yes passport
drivers_license
identity_card
GT Guatemala Yes passport
personal_identification
GY Guyana No passport
drivers_license
HN Honduras Yes passport
personal_identification
drivers_license
HK Hong Kong No passport
drivers_license
identity_card
HU Hungary Yes passport
drivers_license
identity_card
IS Iceland Yes passport
personal_identification
drivers_license
IN India Yes passport
ID Indonesia Yes passport
personal_identification
travel_document
IE Ireland No passport
drivers_license
IL Israel Yes passport
personal_identification
drivers_license
IT Italy Yes passport
identity_card
JP Japan Yes passport
drivers_license
JO Jordan Yes passport
personal_identification
KE Kenya No passport
identity_card
KR Korea, Republic of Yes passport
personal_identification
drivers_license
KW Kuwait Yes passport
drivers_license
LV Latvia Yes passport
personal_identification
identity_card
LS Lesotho Yes passport
personal_identification
LI Liechtenstein Yes passport
identity_card
LT Lithuania Yes passport
personal_identification
LU Luxembourg Yes passport
identity_card
MO Macao No passport
travel_document
MK Macedonia, the Former Yugoslav Republic Of Yes passport
personal_identification
MY Malaysia Yes passport
personal_identification
MT Malta Yes passport
personal_identification
identity_card
MX Mexico Yes passport
personal_identification
drivers_license
tax_id
voter_id
MD Moldova, Republic of Yes passport
personal_identification
identity_card
NL Netherlands Yes passport
drivers_license
identity_card
residence_permit
AN Netherlands Antilles No passport
drivers_license
NZ New Zealand Yes passport
drivers_license
identity_certificate
NI Nicaragua Yes passport
personal_identification
NO Norway Yes passport
personal_identification
drivers_license
OM Oman Yes passport
personal_identification
PK Pakistan Yes passport
personal_identification
PA Panama No passport
personal_identification
drivers_license
PE Peru Yes passport
personal_identification
PH Philippines Yes passport
drivers_license
PL Poland Yes passport
personal_identification
drivers_license
PT Portugal Yes passport
personal_identification
identity_card
QA Qatar No passport
personal_identification
RO Romania Yes passport
personal_identification
drivers_license
RU Russian Federation Yes passport
drivers_license
KN Saint Kitts And Nevis No passport
drivers_license
SM San Marino Yes passport
identity_card
SG Singapore Yes passport
drivers_license
SK Slovakia Yes passport
drivers_license
SI Slovenia Yes passport
personal_identification
identity_card
ZA South Africa No passport
personal_identification
drivers_license
ES Spain Yes passport
personal_identification
drivers_license
identity_card
LK Sri Lanka Yes passport
personal_identification
SE Sweden Yes passport
personal_identification
CH Switzerland Yes passport
drivers_license
identity_card
TW Taiwan, Republic Of China Yes passport
personal_identification
TH Thailand Yes passport
personal_identification
drivers_license
TT Trinidad and Tobago No passport
drivers_license
identity_card
TR Turkey Yes passport
drivers_license
GB United Kingdom Yes passport
drivers_license
UY Uruguay Yes passport
personal_identification
VE Venezuela, Bolivarian Republic of Yes passport
personal_identification
VN Vietnam Yes passport
personal_identification
ZM Zambia Yes passport
personal_identification
identity_card
ZW Zimbabwe No passport
personal_identification

Document types

We support a variety of document types for each country. Below are all of the possible document types and to the left you can see which country supports which document types.

Document type Document name
ssn Social Security Number (Full 9 or last 4)
drivers_license Driver’s license
personal_identification Personal Identification (PIN)
identity_card Identity Card
tax_id Tax ID
voter_id Voter ID
travel_document Travel Document
residence_permit Residence Permit
identity_certificate Identity Certificate
passport Passport

Get Started with Cognito

We will contact you within 2 business hours to talk with our solutions team.

Thanks, we’ll be
in touch soon!

Why not read more about
Cognito in the meantime?