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 Basic and 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.

Example request

$ curl https://api.blockscore.com/people \
  -u sk_test_n5049aa6053c9a0217bea78070fbf501: \
  --header "Accept: application/vnd.blockscore+json;version=4"

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.

Pagination

We split all index listings of resources into pages of 25 items. By toggling the GET parameters, you can change which items you will see.

You are able to customize how many items are shown per page and then define the offset of items before what is shown in order to advance through pages. This gives you flexibility to setup custom paging in your application.

Arguments
offsetoptional
Determines how many items are skipped before the first item that is shown.
countoptional
The number of items to show on a page (the default and maximum is 25).
start_dateoptional
What the lower bound of the creation time for the displayed items will be. This defaults to the beginning of Unix time.
end_dateoptional
What the upper bound of the creation time for the displayed items will be. This defaults to the current time.

In this example we are going to create pages of 10 items and go to the 3rd page (or an offset of 20).

Example request

$ curl -G https://api.blockscore.com/people \
  -u sk_test_709f59bd4ff5191ebaf409330bec4c27: \
  --header "Accept: application/vnd.blockscore+json;version=4" \
  -d 'offset=20' \
  -d 'count=10'

Example response

{
  "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"
      ]
    },
    { ... }
  ]
}

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.

Example request

$ curl -G https://api.blockscore.com/people \
  -u sk_test_709f59bd4ff5191ebaf409330bec4c27: \
  --header "Accept: application/vnd.blockscore+json;version=4" \
  -d 'filter[status]=valid' \
  -d 'created_at[gte]=1420099200'

Example response

{
  "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].

Example request

$ curl -G https://api.blockscore.com/candidates \
  -u sk_test_709f59bd4ff5191ebaf409330bec4c27: \
  --header "Accept: application/vnd.blockscore+json;version=4"
  -d 'filter[q]=John'

Example response

{
  "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.

Example request

$ curl https://api.blockscore.com/people \
  -u sk_test_n5049aa6053c9a0217bea78070fbf501: \
  --header "Accept: application/vnd.blockscore+json;version=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 CodeCountryPostal codeSupported documents
USUnited States of AmericaYes

ssn

drivers_license

ALAlbaniaYes

passport

personal_identification

AOAngolaNo

passport

personal_identification

ARArgentinaYes

passport

personal_identification

drivers_license

AUAustraliaYes

passport

ATAustriaYes

passport

drivers_license

identity_card

BSBahamasNo

passport

drivers_license

BHBahrainYes

passport

personal_identification

BBBarbadosYes

passport

drivers_license

BEBelgiumYes

passport

drivers_license

identity_card

BOBoliviaYes

passport

drivers_license

identity_card

BABosnia and HerzegovinaYes

passport

personal_identification

BRBrazilYes

passport

drivers_license

BGBulgariaYes

passport

personal_identification

CACanadaYes

passport

identity_card

drivers_license

KYCayman IslandsYes

passport

drivers_license

CLChileYes

passport

personal_identification

drivers_license

CNChinaYes

passport

personal_identification

COColombiaYes

passport

personal_identification

drivers_license

CRCosta RicaYes

passport

drivers_license

HRCroatiaYes

passport

personal_identification

identity_card

CZCzech RepublicYes

passport

personal_identification

drivers_license

identity_card

CICote D'IvoireNo

passport

personal_identification

DKDenmarkYes

passport

drivers_license

DODominican RepublicYes

passport

drivers_license

EREritreaNo

passport

personal_identification

EEEstoniaYes

passport

personal_identification

identity_card

FIFinlandYes

passport

personal_identification

identity_card

FRFranceYes

passport

personal_identification

identity_card

GEGeorgiaYes

passport

personal_identification

DEGermanyYes

passport

personal_identification

drivers_license

identity_card

GRGreeceYes

passport

drivers_license

identity_card

GTGuatemalaYes

passport

personal_identification

GYGuyanaNo

passport

drivers_license

HNHondurasYes

passport

personal_identification

drivers_license

HKHong KongNo

passport

drivers_license

identity_card

HUHungaryYes

passport

drivers_license

identity_card

ISIcelandYes

passport

personal_identification

drivers_license

INIndiaYes

passport

IDIndonesiaYes

passport

personal_identification

travel_document

IEIrelandNo

passport

drivers_license

ILIsraelYes

passport

personal_identification

drivers_license

ITItalyYes

passport

identity_card

JPJapanYes

passport

drivers_license

JOJordanYes

passport

personal_identification

KEKenyaNo

passport

identity_card

KRKorea, Republic ofYes

passport

personal_identification

drivers_license

KWKuwaitYes

passport

drivers_license

LVLatviaYes

passport

personal_identification

identity_card

LSLesothoYes

passport

personal_identification

LILiechtensteinYes

passport

identity_card

LTLithuaniaYes

passport

personal_identification

LULuxembourgYes

passport

identity_card

MOMacaoNo

passport

travel_document

MKMacedonia, the Former Yugoslav Republic OfYes

passport

personal_identification

MYMalaysiaYes

passport

personal_identification

MTMaltaYes

passport

personal_identification

identity_card

MXMexicoYes

passport

personal_identification

drivers_license

tax_id

voter_id

MDMoldova, Republic ofYes

passport

personal_identification

identity_card

NLNetherlandsYes

passport

drivers_license

identity_card

residence_permit

ANNetherlands AntillesNo

passport

drivers_license

NZNew ZealandYes

passport

drivers_license

identity_certificate

NINicaraguaYes

passport

personal_identification

NONorwayYes

passport

personal_identification

drivers_license

OMOmanYes

passport

personal_identification

PKPakistanYes

passport

personal_identification

PAPanamaNo

passport

personal_identification

drivers_license

PEPeruYes

passport

personal_identification

PHPhilippinesYes

passport

drivers_license

PLPolandYes

passport

personal_identification

drivers_license

PTPortugalYes

passport

personal_identification

identity_card

QAQatarNo

passport

personal_identification

RORomaniaYes

passport

personal_identification

drivers_license

RURussian FederationYes

passport

drivers_license

KNSaint Kitts And NevisNo

passport

drivers_license

SMSan MarinoYes

passport

identity_card

SGSingaporeYes

passport

drivers_license

SKSlovakiaYes

passport

drivers_license

SISloveniaYes

passport

personal_identification

identity_card

ZASouth AfricaNo

passport

personal_identification

drivers_license

ESSpainYes

passport

personal_identification

drivers_license

identity_card

LKSri LankaYes

passport

personal_identification

SESwedenYes

passport

personal_identification

CHSwitzerlandYes

passport

drivers_license

identity_card

TWTaiwan, Republic Of ChinaYes

passport

personal_identification

THThailandYes

passport

personal_identification

drivers_license

TTTrinidad and TobagoNo

passport

drivers_license

identity_card

TRTurkeyYes

passport

drivers_license

GBUnited KingdomYes

passport

drivers_license

UYUruguayYes

passport

personal_identification

VEVenezuela, Bolivarian Republic ofYes

passport

personal_identification

VNVietnamYes

passport

personal_identification

ZMZambiaYes

passport

personal_identification

identity_card

ZWZimbabweNo

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

People

People are the base object for verifying any customer information. By passing us information about your customers, we can check them against government watchlists, fraudulent histories and databases from around the world.

Attributes
object
String

A definition of the type of object returned.

id
String
created_at
Timestamp
updated_at
Timestamp
birth_day
Integer

The integer day of birth of the person.

birth_month
Integer

The integer month of birth of the person.

birth_year
Integer

The 4-digit integer birth year of the person.

livemode
Boolean

Indicates whether the verification was created using a live or test API key.

status
String

Returns either valid or invalid and is the culmination of whether or not the passed in information is valid against various databases and signals.

phone_number
String

The phone number (mobile or land line) of your customer.

ip_address
String

The IP address (v4 or v6) of the person being verified.

note
String

An additional field which can be used for arbitrary storage. This is typically used for storing your internal identifiers for this customer.

document_type
String

The type of document used for identification.

document_value
String

The number of the document used for identification. For example, a Social Security Number.

name_first
String

The legal first name of the customer.

name_middle
String

The legal middle name of the customer.

name_last
String

The legal last name of the customer.

address_street1
String

The primary street address of the customer.

address_street2
String

The second address line typically used for apartment or suite numbers.

address_city
String

The city name of the customer.

address_subdivision
String

The subdivision of the entered country. For instance in the United States, this would be a ‘state’.

address_postal_code
String

The postal code of the person. Also known as a ZIP code.

address_country_code
String

The country of the customer. Should be of the ISO code form.

question_sets
Array

This is an array of IDs which are associated with the verification. Because you can create multiple question sets per verification, they will all be listed in this attribute.

details
Object

This is an array of IDs which are associated with the verification. Because you can create multiple question sets per verification, they will all be listed in this attribute.

details[address]
String

Whether the submitted address matches the person trying to be verified.

details[address_risk]
String

Whether the given address is associated with a high risk business industry.

details[identification]
String

Whether the submitted documentation matches the person trying to be verified.

details[date_of_birth]
String

Whether the submitted birthday matches the person trying to be verified.

details[ofac]
String

Whether a US Office of Foreign Assets Control match occurred. Sensitivity is different from Candidate product.

details[pep]
String

Whether a Politically Exposed Persons match occurred. Sensitivity is different from Candidate product.

Person object

{
  "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": "Pearce",
  "name_last": "Doe",
  "address_street1": "1 Infinite Loop",
  "address_street2": "Apt 6",
  "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"
  ]
}

Detail response codes

Address

Code Description
match There is evidence to indicate that this person lived at this address.
no_match There is no evidence that this person has lived at this address.
partial_match There was an address match on city and subdivision with a partial match on streets.
mismatch A different person is associated with this address.
insufficient_data There was not enough data to verify this attribute.

Address risk

Code Description
high This address is associated with high risk activity.
low This address has no history of high risk activity.
no_match This address could not be found.
insufficient_data There was not enough data to verify this attribute.

Identification

Code Description
match This ID matches to all pieces of submitted information.
partial_match This ID matches with part of this person's identity. This means part of their name, address or date of birth have slight mismatches with the data on file associated with this identity.
invalid Either this ID was never issued or is otherwise invalid.
no_match The ID does not match any of the identity information provided or could not be found.
mismatch The identity data is associated with another individual.
insufficient_data There was not enough data to verify this attribute.

Date of Birth

Code Description
match There is a full match to the date of birth on record.
partial_match One of the day, year or month does not match records.
invalid The date of birth was not provided or was invalid.
not_found No date of birth records could be found on this person.
insufficient_data There was not enough data to verify this attribute.

OFAC, PEP

Code Description
match There is a strong match on this identity being on OFAC.
partial_match An inconclusive part of their identity was found (such as their last name). These occur relatively often and are usually just cause for further review.
no_match This identity was not found on OFAC.

Create a new person

This endpoint creates a new person. The information will be run through our verification process and then returned with additional information that will help you determine the authenticity of the information given.

Arguments
name_first
required

The legal first name of the customer.

name_middle
optional

The legal middle name of the customer.

name_last
required

The legal last name of the customer.

document_type
required

Must be one of the document types described in the Documents section.

document_value
required

The number associated with the form of documentation used.

birth_day
required

The integer associated with the day of birth.

birth_month
required

The integer associated with the month of birth.

birth_year
required

The full 4-digit year of birth.

address_street1
required

The primary street address of the customer.

address_street2
optional

The second address line typically used for apartment or suite numbers.

address_city
required

The city name of the customer.

address_subdivision
required

The subdivision of the entered country. For instance in the United States, this would be a ‘state’.

address_postal_code
required

The postal code of the person. Also known as a ZIP code.

address_country_code
required

The country of the customer. Should be of the ISO code form.

phone_number
optional

If you pass in the phone number, we will use it as an additional ‘positive’ data point for the consumer. That is, if it is provided, it will help us identify them, but if we cannot, they will not be penalized.

ip_address
optional

Your customers’ IP address can be passed to us for storage purposes. Soon we will be using this information for anti-fraud and verification purposes. With this information we will be able to back-test your verifications when this feature is released.

note
optional

You can store additional information about the candidate here such as your internal system’s identifier for this individual. This will allow you to keep track of them.

Returns

Along with the person object containing all of the information you submitted, we also return two key pieces of information. The first is the status object which will either be valid or invalid and will give you a very quick idea of whether or not this information was valid according to our data.

The other piece of information is the details object which contains a breakdown of how the status was determined. It will let you diagnose problems like address inconsistencies.

Endpoint

POST
https://api.blockscore.com/people

Example request

$ curl https://api.blockscore.com/people \
  -u sk_test_n5049aa6053c9a0217bea78070fbf501: \
  --header "Accept: application/vnd.blockscore+json;version=4" \
  -d 'name_first=John' \
  -d 'name_middle=Pearce' \
  -d 'name_last=Doe' \
  -d 'document_type=ssn' \
  -d 'document_value=0000' \
  -d 'birth_day=23' \
  -d 'birth_month=8' \
  -d 'birth_year=1993' \
  -d 'address_street1=1 Infinite Loop' \
  -d 'address_street2=Apt 6' \
  -d 'address_city=Cupertino' \
  -d 'address_subdivision=CA' \
  -d 'address_postal_code=95014' \
  -d 'address_country_code=US' \
  -d 'note=ref-id:12345'

Example response

{
  "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": "Pearce",
  "name_last": "Doe",
  "address_street1": "1 Infinite Loop",
  "address_street2": "Apt 6",
  "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"
  ]
}

Retrieve an existing person

You can pull up a single person at any time (typically this is used for auditing purposes).

Returns

This will return a record exactly as it was when you created it. This route is useful for auditing purposes as you can provide proof that a verification took place along with all of its associated data.

Endpoint

GET
https://api.blockscore.com/people/{PERSON_ID}

Example request

$ curl -G https://api.blockscore.com/people/544744f43266330002010000 \
  -u sk_test_709f59bd4ff5191ebaf409330bec4c27: \
  --header "Accept: application/vnd.blockscore+json;version=4"

Example response

{
  "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": "Pearce",
  "name_last": "Doe",
  "address_street1": "1 Infinite Loop",
  "address_street2": "Apt 6",
  "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"
  ]
}

List all people

This endpoint will allow you to see a historical record of all verifications that you have completed.

The list is displayed in reverse chronological order (newer people appear first).

Endpoint

GET
https://api.blockscore.com/people

Example request

$ curl -G https://api.blockscore.com/people \
  -u sk_test_709f59bd4ff5191ebaf409330bec4c27: \
  --header "Accept: application/vnd.blockscore+json;version=4"

Example response

{
  "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"
      ]
    },
    { ... }
  ]
}

Question Sets

Question sets, also known as Knowledge-Based Authentication (KBA), help you authenticate customers to see if they are who they say they are. They are dependent upon a verification being created first. The identity in the verification then acts as the seed of data that the question set is based on.

Attributes
object
String

A definition of the type of object returned.

id
String
created_at
Timestamp
updated_at
Timestamp
livemode
Boolean

Indicates whether the question set was created using a live or test API key.

person_id
String

The associated person’s ID.

score
Float

The percentage (from 0.0 - 100.0) result of scoring the question set’s answers.

expired
Boolean

Indicates whether the time_limit has been passed since the creation of the question set.

time_limit
Integer

The number of seconds after the creation of the question set before the expired boolean will switch to true.

questions
Array

The wrapper array containing all of the questions and related metadata generated for the question set.

questions[id]
Integer

The ID of the question object.

questions[question]
String

The text of the question such as ‘Which one of the following area codes is associated with you?’

questions[answers]
Array

The wrapper array containing all of the answers possible for the given question object.

questions[answers][answer]
String

The text of the answer for the current answer object.

questions[answers][id]
Integer

The ID of the answer object.

Question set object

{
  "object": "question_set",
  "id": "533ce7e5627463792f010000",
  "created_at": 1402450269,
  "updated_at": 1403742375,
  "livemode": false,
  "person_id": "530c48b2627463452b570000",
  "score": 60.0,
  "expired": false,
  "time_limit": 300,
  "questions": [
    {
      "id": 1,
      "question": "Which of these people do you know?",
      "answers": [
        { "id": 1, "answer": "Alain" },
        { "id": 2, "answer": "John" },
        { "id": 3, "answer": "Chris" },
        { "id": 4, "answer": "Connor" },
        { "id": 5, "answer": "None Of The Above" }
      ]
    },
    { ... }
  ]
}

Create a new question set

This method will create a new question set to ask your users. You can call this endpoint multiple times with the same person ID and the questions asked as well as the order that everything is presented in will be randomized.

Arguments
person_id
required

The ID of the person, and thus the identity, on which to base the question sets. You can create multiple question sets using the same question set ID.

time_limit
optional

How long after creating a question set that the expired boolean will remain false. This is inputted in seconds and defaults to 0, which means no time limit. This allows you to make sure that your customer does not take too long to answer a question set.

Returns

This returns a set of questions which you can ask your users. These questions help to authenticate them and make sure that they are who they say they are.

In some cases there will be enough data to verify an individual but not enough data to build a set of questions. In this situation the array of questions will be empty. This should be a case that your code checks for even though it is not particularly common.

These questions are typically presented in a multiple choice format. It is very important to impose a time limit on answering the questions as that makes it more difficult to circumvent.

It is also highly recommended that you throttle the number of times people can retry ID verification if they fail. An effective strategy that we have seen is allowing people to attempt ID verification once or twice in a 24-hour period.

Endpoint

POST
https://api.blockscore.com/question_sets

Example request

$ curl https://api.blockscore.com/question_sets \
  -u sk_test_n5049aa6053c9a0217bea78070fbf501: \
  --header "Accept: application/vnd.blockscore+json;version=4" \
  -d 'person_id=530c48b2627463452b570000' \
  -d 'time_limit=300'

Example response

{
  "object": "question_set",
  "id": "533ce7e5627463792f010000",
  "created_at": 1402450269,
  "updated_at": 1403742375,
  "livemode": false,
  "person_id": "530c48b2627463452b570000",
  "score": null,
  "expired": false,
  "time_limit": 300,
  "questions": [
    {
      "id": 1,
      "question": "Which of these people do you know?",
      "answers": [
        { "id": 1, "answer": "Alain" },
        { "id": 2, "answer": "John" },
        { "id": 3, "answer": "Chris" },
        { "id": 4, "answer": "Connor" },
        { "id": 5, "answer": "None Of The Above" }
      ]
    },
    { ... }
  ]
}

Score a question set

Once the user has finished answering the questions, you will need to send us their answers so that we can score it. The scoring system will score it based on how many questions you submit, so if you would only like to ask 3 questions, only submit the 3 questions which you would like scored.

Arguments
answers
required

An array of objects containing question_id and answer_id pairs. This is the container for all of the user’s answers.

answers[][question_id]
required

The ID of the question to which the user is responding. This ID is found in the response when creating a question set.

answers[][answer_id]
required

The ID of the answer that the user picks while answering questions. The ID is found in the response when creating a question set.

Interpreting the results

The most important part of this endpoint's return object is the score key. This key is a percentage (from 0 - 100) that says how many of the questions were correct.

Though it is up to your own judgement and fraud practices, most of our customers elect to allow one incorrect answer, which translates to a score of 80%.

Limiting the time that a user can take to submit their answers is an important measure to combat fraud. Most of our customers implement a 2 minute time limit. It is also important to limit the number of question sets that any user can answer in any given day - a typical restriction is one or two question sets per 24 hour period.

Endpoint

POST
https://api.blockscore.com/question_sets/{QUESTION_SET_ID}/score

Example request

$ curl https://api.blockscore.com/question_sets/533ce7e5627463792f010000/score \
  -u sk_test_n5049aa6053c9a0217bea78070fbf501: \
  --header "Accept: application/vnd.blockscore+json;version=4" \
  -d 'answers[][question_id]=1' \
  -d 'answers[][answer_id]=3' \
  -d 'answers[][question_id]=2' \
  -d 'answers[][answer_id]=2' \
  -d 'answers[][question_id]=3' \
  -d 'answers[][answer_id]=2' \
  -d 'answers[][question_id]=4' \
  -d 'answers[][answer_id]=2' \
  -d 'answers[][question_id]=5' \
  -d 'answers[][answer_id]=5'

Example response

{
  "object": "question_set",
  "id": "533ce7e5627463792f010000",
  "created_at": 1402450269,
  "updated_at": 1403742375,
  "livemode": false,
  "person_id": "530c48b2627463452b570000",
  "score": 60.0,
  "expired": false,
  "time_limit": 300,
  "questions": [
    {
      "id": 1,
      "question": "Which of these people do you know?",
      "answers": [
        { "id": 1, "answer": "Alain" },
        { "id": 2, "answer": "John" },
        { "id": 3, "answer": "Chris" },
        { "id": 4, "answer": "Connor" },
        { "id": 5, "answer": "None Of The Above" }
      ]
    },
    { ... }
  ]
}

Retrieve an existing question set

This allows you to retrieve a question set you have created. If you have already scored the question set, we will also return the last score of your submitted answers.

Endpoint

GET
https://api.blockscore.com/question_sets/{QUESTION_SET_ID}

Example request

$ curl -G https://api.blockscore.com/question_sets/533ce7e5627463792f010000 \
  -u sk_test_n5049aa6053c9a0217bea78070fbf501: \
  --header "Accept: application/vnd.blockscore+json;version=4"

Example response

{
  "object": "question_set",
  "id": "533ce7e5627463792f010000",
  "created_at": 1402450269,
  "updated_at": 1403742375,
  "livemode": false,
  "person_id": "530c48b2627463452b570000",
  "score": 60.0,
  "expired": false,
  "time_limit": 300,
  "questions": [
    {
      "id": 1,
      "question": "Which of these people do you know?",
      "answers": [
        { "id": 1, "answer": "Alain" },
        { "id": 2, "answer": "John" },
        { "id": 3, "answer": "Chris" },
        { "id": 4, "answer": "Connor" },
        { "id": 5, "answer": "None Of The Above" }
      ]
    },
    { ... }
  ]
}

List all question sets

This endpoint will allow you to see a historical record of all question sets that you have created.

The list is displayed in reverse chronological order (newer question sets appear first).

Endpoint

GET
https://api.blockscore.com/question_sets

Example request

$ curl -G https://api.blockscore.com/question_sets \
  -u sk_test_709f59bd4ff5191ebaf409330bec4c27: \
  --header "Accept: application/vnd.blockscore+json;version=4"

Example response

{
  "total_count": 5,
  "has_more": false,
  "object": "list",
  "data": [
    {
      "object": "question_set",
      "id": "533ce7e5627463792f010000",
      "created_at": 1402450269,
      "updated_at": 1403742375,
      "livemode": false,
      "person_id": "530c48b2627463452b570000",
      "score": 60.0,
      "expired": false,
      "time_limit": 300,
      "questions": [
        {
          "id": 1,
          "question": "Which of these people do you know?",
          "answers": [
            { "id": 1, "answer": "Alain" },
            { "id": 2, "answer": "John" },
            { "id": 3, "answer": "Chris" },
            { "id": 4, "answer": "Connor" },
            { "id": 5, "answer": "None Of The Above" }
          ]
        }
      ]
    },
    { ... }
  ]
}

Companies

Companies allow you to verify the authenticity of private and public company information. This is particularly useful when you need to verify firms for things like marketplace payouts.

Attributes
object
String

A definition of the type of object returned.

id
String
created_at
Timestamp
updated_at
Timestamp
status
String

Returns either valid or invalid and is the culmination of whether or not the passed in information is valid against various databases and signals.

livemode
Boolean

Indicates whether the company was created using a live or test API key.

entity_name
String

The legal name for the company (excluding endings like Inc or Co)

tax_id
String

The tax ID provided by the IRS for this firm or an SSN for sole proprietorships.

incorporation_day
String

The day in integer form of the company’s incorporation.

incorporation_month
String

The month in integer form of the company’s incorporation.

incorporation_year
String

The year in 4-digit integer form of the company’s incorporation.

incorporation_state
String

The state or region of incorporation of the company.

incorporation_country_code
String

The country of incorporation of the company.

incorporation_type
String

The type of legal business entity that this company is such as a Limited Liability Company.

dbas
String

A list of ‘doing business as’ names, which are other names this business may be known by.

registration_number
String

This is the number typically provided by the state of incorporation which is assigned to a business.

email
String

The contact email of the company being verified.

url
String

The business’ main website URL.

phone_number
String

The phone number (mobile or land line) of your company.

ip_address
String

The IP address (v4 or v6) of the company being verified.

note
String

An additional field which can be used for arbitrary storage. This is typically used for storing your internal identifiers for this customer.

address_street1
String

The primary street address of the customer.

address_street2
String

The second address line typically used for apartment or suite numbers.

address_city
String

The city name of the customer.

address_subdivision
String

The state of the customer. Should be of the FIPS code form. For example California would be CA.

address_postal_code
String

The postal code, also known as the ZIP code of the address.

address_country_code
String

The country of the customer. Should be of the ISO code form.

details
Object

A breakdown of some of the information that determines the status element.

details[ofac]
String

Whether a US Office of Foreign Assets Control match occurred. Sensitivity is different from Candidate product.

details[state]
String

Whether the submitted state matches the company trying to be verified.

details[tax_id]
String

Whether the submitted tax ID matches the company trying to be verified.

details[address]
String

Whether the submitted address matches the company trying to be verified.

details[entity_name]
String

Whether the submitted entity name appears to be attached to a real entity.

details[incorp_date]
String

Whether the submitted incorporation date matches the company trying to be verified.

details[country_code]
String

Whether the given company is located in the country that was entered.

Company object

{
  "object": "company",
  "id": "54d956c06230620003760500",
  "created_at": 1423529664,
  "updated_at": 1423529664,
  "status": "valid",
  "livemode": false,
  "entity_name": "BlockScore",
  "tax_id": "123410000",
  "incorporation_day": 23,
  "incorporation_month": 8,
  "incorporation_year": 1993,
  "incorporation_state": "DE",
  "incorporation_country_code": "US",
  "incorporation_type": "corporation",
  "dbas": "BitRemit",
  "registration_number": "123123123",
  "email": "test@example.com",
  "url": "https://blockscore.com",
  "phone_number": "6505555555",
  "note": "ref-id:12345",
  "ip_address": "67.160.8.182",
  "address_street1": "123 Fake Streets",
  "address_street2": null,
  "address_city": "Stanford",
  "address_subdivision": "CA",
  "address_postal_code": "94305",
  "address_country_code": "US",
  "details": {
    "ofac": "no_match",
    "state": "match",
    "tax_id": "match",
    "address": "no_match",
    "entity_name": "mismatch",
    "incorp_date": "no_match",
    "country_code": "match"
  }
}

Incorporation types

Code Name
corporation Corporation
llc Limited liability company
partnership Any type of partnership
sp Sole proprietorship
other Any business type not listed

Detail response codes

Entity name

Code Description
match The entity name matches the tax ID.
partial_match The entity name partially matches the tax ID.
mismatch The entity name and tax ID do not match.
no_match The entity name could not be found.
insufficient_data There was not enough data to verify this attribute.

Tax ID

Code Description
match The supplied tax ID was found with the IRS.
no_match The supplied tax ID was not found with the IRS.
insufficient_data There was not enough data to verify this attribute.

OFAC

Code Description
match The entity name was found on OFAC lists.
no_match The entity name was not found on OFAC lists.
insufficient_data There was not enough data to verify this attribute.

Create a new company

This endpoint creates a new company. The information will be run through our company verification process and then returned with additional information that will help you determine the authenticity of the information given.

Please be aware that the response time can sometimes be more than 6 seconds due to the speed of some government data sources.

Arguments
entity_name
required

This should exclude any legal endings like ‘Co’ or ‘Inc’ for best results.

tax_id
required

The tax ID should only include the digits of the ID with no extraneous characters like dashes.

incorporation_state
optional

Can be either of ISO code form or the full length name of the state.

incorporation_country_code
required

Should be of the ISO alpha-2 code form.

incorporation_type
required

Must be one of the pre-defined incorporation types listed in the ‘Incorporation types’ table.

incorporation_day
optional

The day in integer form of the company’s incorporation.

incorporation_month
optional

The month in integer form of the company’s incorporation.

incorporation_year
optional

The year in 4-digit integer form of the company’s incorporation.

dbas
optional

Both commas and spaces are acceptable for delimiting multiple names.

registration_number
optional

Should only include the digits of the registration number with no extraneous characters like dashes.

email
optional

Any form of valid email is accepted.

url
optional

Can either contain protocol information or not (ex. www.example.com and http://www.example.com).

phone_number
optional

Extra characters like parenthesis and dashes are accepted - can either contain the country code or not.

ip_address
optional

Both IPv4 and IPv6 style IP addresses are acceptable.

note
optional

You can store additional information about the candidate here such as your internal system’s identifier for this individual. This will allow you to keep track of them.

address_street1
required

The primary street address of the customer.

address_street2
optional

The second address line typically used for apartment or suite numbers.

address_city
required

The city name of the customer.

address_subdivision
required

The state of the customer. Should be of the FIPS code form. For example California would be CA.

address_postal_code
required

The country of the customer. Should be of the ISO code form.

address_country_code
required

The country of the customer. Should be of the ISO code form.

Returns

Along with the company verification object containing all of the information you submitted, we also return two key pieces of information. The first is the status object which will either be valid or invalid and will give you a very quick idea of whether or not this information was valid according to our data.

The other piece of information is the details object which contains a breakdown of how the status was determined. It will let you diagnose problems like address inconsistencies.

Endpoint

POST
https://api.blockscore.com/companies

Example request

$ curl https://api.blockscore.com/companies \
  -u sk_test_n5049aa6053c9a0217bea78070fbf501: \
  --header "Accept: application/vnd.blockscore+json;version=4" \
  -d 'entity_name=BlockScore' \
  -d 'tax_id=123410000' \
  -d 'incorporation_country_code=US' \
  -d 'incorporation_state=DE' \
  -d 'dbas=BitRemit' \
  -d 'incorporation_type=corporation' \
  -d 'incorporation_day=23' \
  -d 'incorporation_month=8' \
  -d 'incorporation_year=1993' \
  -d 'registration_number=123123123' \
  -d 'email=test@example.com' \
  -d 'address_street1=123 Fake Streets' \
  -d 'address_city=Stanford' \
  -d 'note=ref-id:12345' \
  -d 'url=https://blockscore.com' \
  -d 'phone_number=650555555' \
  -d 'ip_address-67.160.8.182' \
  -d 'address_subdivision=CA' \
  -d 'address_postal_code=94305' \
  -d 'address_country_code=US'

Example response

{
  "object": "company",
  "id": "54d956c06230620003760500",
  "created_at": 1423529664,
  "updated_at": 1423529664,
  "status": "valid",
  "livemode": false,
  "entity_name": "BlockScore",
  "tax_id": "123410000",
  "incorporation_day": 23,
  "incorporation_month": 8,
  "incorporation_year": 1993,
  "incorporation_state": "DE",
  "incorporation_country_code": "US",
  "incorporation_type": "corporation",
  "dbas": "BitRemit",
  "registration_number": "123123123",
  "email": "test@example.com",
  "url": "https://blockscore.com",
  "phone_number": "6505555555",
  "note": "ref-id:12345",
  "ip_address": "67.160.8.182",
  "address_street1": "123 Fake Streets",
  "address_street2": null,
  "address_city": "Stanford",
  "address_subdivision": "CA",
  "address_postal_code": "94305",
  "address_country_code": "US",
  "details": {
    "ofac": "no_match",
    "state": "match",
    "tax_id": "match",
    "address": "no_match",
    "entity_name": "mismatch",
    "incorp_date": "no_match",
    "country_code": "match"
  }
}

Retrieve an existing company

You can pull up a single company verification at any time (typically this is used for auditing purposes).

Returns

This will return a record exactly as it was when you created it. This route is useful for auditing purposes as you can provide proof that a company verification took place along with all of its associated data.

Endpoint

GET
https://api.blockscore.com/companies/{COMPANY_ID}

Example request

$ curl -G https://api.blockscore.com/companies/54d956c06230620003760500 \
  -u sk_test_709f59bd4ff5191ebaf409330bec4c27: \
  --header "Accept: application/vnd.blockscore+json;version=4"

Example response

{
  "object": "company",
  "id": "54d956c06230620003760500",
  "created_at": 1423529664,
  "updated_at": 1423529664,
  "status": "valid",
  "livemode": false,
  "entity_name": "BlockScore",
  "tax_id": "123410000",
  "incorporation_day": 23,
  "incorporation_month": 8,
  "incorporation_year": 1993,
  "incorporation_state": "DE",
  "incorporation_country_code": "US",
  "incorporation_type": "corporation",
  "dbas": "BitRemit",
  "registration_number": "123123123",
  "email": "test@example.com",
  "url": "https://blockscore.com",
  "phone_number": "6505555555",
  "note": "ref-id:12345",
  "ip_address": "67.160.8.182",
  "address_street1": "123 Fake Streets",
  "address_street2": null,
  "address_city": "Stanford",
  "address_subdivision": "CA",
  "address_postal_code": "94305",
  "address_country_code": "US",
  "details": {
    "ofac": "no_match",
    "state": "match",
    "tax_id": "match",
    "address": "no_match",
    "entity_name": "mismatch",
    "incorp_date": "no_match",
    "country_code": "match"
  }
}

List all companies

This endpoint will allow you to see a historical record of all company verifications that you have completed.

The list is displayed in reverse chronological order (newer company verifications appear first).

Endpoint

GET
https://api.blockscore.com/companies

Example request

$ curl -G https://api.blockscore.com/companies \
  -u sk_test_709f59bd4ff5191ebaf409330bec4c27: \
  --header "Accept: application/vnd.blockscore+json;version=4"

Example response

{
  "total_count": 443,
  "has_more": true,
  "object": "list",
  "data": [
    {
      "object": "company",
      "id": "54d956c06230620003760500",
      "created_at": 1423529664,
      "updated_at": 1423529664,
      "status": "valid",
      "livemode": false,
      "entity_name": "BlockScore",
      "tax_id": "123410000",
      "incorporation_day": 23,
      "incorporation_month": 8,
      "incorporation_year": 1993,
      "incorporation_state": "DE",
      "incorporation_country_code": "US",
      "incorporation_type": "corporation",
      "dbas": "BitRemit",
      "registration_number": "123123123",
      "email": "test@example.com",
      "url": "https://blockscore.com",
      "phone_number": "6505555555",
      "note": "ref-id:12345",
      "ip_address": "67.160.8.182",
      "address_street1": "123 Fake Streets",
      "address_street2": null,
      "address_city": "Stanford",
      "address_subdivision": "CA",
      "address_postal_code": "94305",
      "address_country_code": "US",
      "details": {
        "ofac": "no_match",
        "state": "match",
        "tax_id": "match",
        "address": "no_match",
        "entity_name": "mismatch",
        "incorp_date": "no_match",
        "country_code": "match"
      }
    },
    { ... }
  ]
}

Candidates

Candidates are individuals who are queued up to either execute one-off watchlist scans or so that they can be continuously verified against watchlists once per day.

Attributes
object
String

A definition of the type of object returned.

id
String
created_at
Timestamp
updated_at
Timestamp
livemode
Boolean

Indicates whether the candidate was created using a live or test API key.

date_of_birth
String

The candidates birth date in ISO form.

note
String

An additional field which can be used for arbitrary storage. This is typically used for storing your internal identifiers for this candidate.

ssn
String

This can be either the last 4 digits of the US Social Security Number or the whole SSN.

passport
String

The passport number of the individual being verified. This is only used for verifying non-US candidates.

name_first
String

The legal first name of the candidate. Can also be the name of an entity/company.

name_middle
String

The legal middle name of the candidate.

name_last
String

The legal last name of the candidate.

address_street1
String

The primary street address of the candidate.

address_street2
String

The second address line typically used for apartment or suite numbers.

address_city
String

The city name of the candidate.

address_subdivision
String

The subdivision of the entered country. For instance in the United States, this would be a ‘state’.

address_postal_code
String

The postal code of the candidate. Also known as a ZIP code.

address_country_code
String

The country of the candidate. Should be of the ISO code form.

Candidate object

{
  "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": "1 Infinite Loop",
  "address_street2": "Apt 6",
  "address_city": "Cupertino",
  "address_subdivision": "CA",
  "address_postal_code": "95014",
  "address_country_code": "US"
}

Create a new candidate

This endpoint creates a new candidate.

Arguments
name_first
optional

The legal first name of the individual. If you are trying to store a entity/company’s information, enter it here as the first name of the candidate.

name_middle
optional

The legal middle name of the individual.

name_last
optional

The legal last name of the individual.

note
optional

You can store additional information about the candidate here such as your internal system’s identifier for this individual. This will allow you to keep track of them.

ssn
optional

This can be either the last 4 digits of the US Social Security Number or the whole SSN.

passport
optional

The passport number of the individual being verified. This is only used for verifying non-US customers.

date_of_birth
optional

The date of birth of the candidate in ISO form. If you are storing an entity/company’s information, this would be their incorporation date.

address_street1
optional

The primary street address of the customer.

address_street2
optional

The second address line typically used for apartment or suite numbers.

address_city
optional

The city name of the customer.

address_subdivision
optional

The subdivision of the entered country. For instance in the United States, this would be a ‘state’.

address_postal_code
optional

The postal code of the person. Also known as a ZIP code.

address_country_code
optional

The country of the customer. Should be of the ISO code form.

Returns

If the request is successful, we return the candidate that you just created. With this candidate, you can either take its ID to perform a manual watchlist check or if you upgrade to our continuous verification system, this person is then queued up to be continuously verified.

Endpoint

POST
https://api.blockscore.com/candidates

Example request

$ curl https://api.blockscore.com/candidates \
  -u sk_test_n5049aa6053c9a0217bea78070fbf501: \
  --header "Accept: application/vnd.blockscore+json;version=4" \
  -d 'note=55555555' \
  -d 'ssn=0002' \
  -d 'date_of_birth=1940-08-11' \
  -d 'name_first=John' \
  -d 'name_last=Bredenkamp' \
  -d 'address_street1=1 Infinite Loop' \
  -d 'address_street2=Apt 6' \
  -d 'address_city=Cupertino' \
  -d 'address_subdivision=CA' \
  -d 'address_postal_code=95014' \
  -d 'address_country_code=US'

Example response

{
  "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": "1 Infinite Loop",
  "address_street2": "Apt 6",
  "address_city": "Cupertino",
  "address_subdivision": "CA",
  "address_postal_code": "95014",
  "address_country_code": "US"
}

Edit a candidate

If you'd like to amend the information associated with a candidate, you can modify it using this route. For instance, if your candidate changes addresses or you learn additional information about them. Only the information you send us will be updated - the rest will remain the same.

Endpoint

PATCH
https://api.blockscore.com/candidates/{CANDIDATE_ID}

Example request

$ curl https://api.blockscore.com/candidates/544aba053163310002630500 \
  -u sk_test_n5049aa6053c9a0217bea78070fbf501: \
  --header "Accept: application/vnd.blockscore+json;version=4" \
  -X PATCH \
  -d 'note=55555555' \
  -d 'ssn=0002' \
  -d 'address_country_code=AR'

Example response

{
  "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"
}

Delete a candidate

This endpoint allows you to remove a candidate from our system. If you have signed up for continuous verification, then the deleted candidate will no longer be scanned.

Returns

If the deletion was successful, we will return the deleted object with an additional "deleted": true attribute.

Endpoint

DELETE
https://api.blockscore.com/candidates/{CANDIDATE_ID}

Example request

$ curl https://api.blockscore.com/candidates/544aba053163310002630500 \
  -u sk_test_n5049aa6053c9a0217bea78070fbf501: \
  --header "Accept: application/vnd.blockscore+json;version=4" \
  -X DELETE

Example response

{
  "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": "1 Infinite Loop",
  "address_street2": "Apt 6",
  "address_city": "Cupertino",
  "address_subdivision": "CA",
  "address_postal_code": "95014",
  "address_country_code": "US"
}

Retrieve an existing candidate

This endpoint allows you to retrieve the record of a candidate using their stored candidate_id.

Endpoint

GET
https://api.blockscore.com/candidates/{CANDIDATE_ID}

Example request

$ curl -G https://api.blockscore.com/candidates/544aba053163310002630500 \
  -u sk_test_709f59bd4ff5191ebaf409330bec4c27: \
  --header "Accept: application/vnd.blockscore+json;version=4"

Example response

{
  "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": "1 Infinite Loop",
  "address_street2": "Apt 6",
  "address_city": "Cupertino",
  "address_subdivision": "CA",
  "address_postal_code": "95014",
  "address_country_code": "US"
}

List all candidates

This endpoint will allow you to see a historical record of all candidates you have created.

The list is displayed in reverse chronological order (newer candidates appear first).

Endpoint

GET
https://api.blockscore.com/candidates

Example request

$ curl -G https://api.blockscore.com/candidates \
  -u sk_test_709f59bd4ff5191ebaf409330bec4c27: \
  --header "Accept: application/vnd.blockscore+json;version=4"

Example response

{
  "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"
    },
    { ... }
  ]
}

Receive a candidate webhook

When candidates are created, they are automatically enrolled in an automatic scanning program that will update you in the event that the status of one of your candidates changes.

These changes are delivered as POST requests from our servers to yours. Your webhook endpoint can be defined from your dashboard.

Attributes
note string
The free-form field (typically indicating the ID of the individual on your systems) that you filled out when creating a candidate.
livemode boolean
Indicates whether the webhook was sent to a live or test webhook.
watchlist_candidate_id string
The matching record ID for the candidate who has shown up on watchlists.
reason string
The reason that the webhook was sent for this candidate.

Example payload

{
  "note": "55555555",
  "livemode": false,
  "watchlist_candidate_id": "53a15d256235350002010000",
  "reason": "watchlist_match"
}

Reason codes

Code Description
watchlist_match The candidate who was previously not on a watchlist now has some results indicating that they are.

View a candidate's revision history

We store a complete revision history of a candidate's edits. This allows you to maintain a full audit trail of when and how you update a client's profile over time.

The latest revision is presented at the top of the array, and the original is at the end of the array.

Endpoint

GET
https://api.blockscore.com/candidates/{CANDIDATE_ID}/history

Example request

$ curl -G https://api.blockscore.com/candidates/544aba053163310002630500/history \
  -u sk_test_709f59bd4ff5191ebaf409330bec4c27: \
  --header "Accept: application/vnd.blockscore+json;version=4"

Example response

[
  {
    "object": "candidate",
    "id": "544aba053163310002630500",
    "created_at": 1414183429,
    "updated_at": 1414183429,
    "livemode": true,
    "note": null,
    "ssn": null,
    "passport": null,
    "date_of_birth": null,
    "name_first": "John",
    "name_middle": null,
    "name_last": "Bredenkamp",
    "address_street1": null,
    "address_street2": null,
    "address_city": null,
    "address_subdivision": null,
    "address_postal_code": null,
    "address_country_code": "ZW"
  },
  {
    "object": "candidate",
    "id": "544aba053163310002630500",
    "created_at": 1414183429,
    "updated_at": 1414183429,
    "livemode": true,
    "note": null,
    "ssn": null,
    "passport": null,
    "date_of_birth": null,
    "name_first": "John",
    "name_middle": null,
    "name_last": "Bredenkamp",
    "address_street1": null,
    "address_street2": null,
    "address_city": null,
    "address_subdivision": null,
    "address_postal_code": null,
    "address_country_code": null
  }
]

View a candidate's past hits

Whenever a search is executed for a candidate, we store the results of that search with timestamps of when those hits occurred. This endpoint allows you to view all historical watchlist hits for a given candidate.

Endpoint

GET
https://api.blockscore.com/candidates/{CANDIDATE_ID}/hits

Example request

$ curl -G https://api.blockscore.com/candidates/53b1fbf33538620002000000/hits \
  -u sk_test_709f59bd4ff5191ebaf409330bec4c27: \
  --header "Accept: application/vnd.blockscore+json;version=4"

Example response

{
  "object": "list",
  "data": [
    {
      "id": "ent_554056e4b4cf7103000009d5",
      "list": "US_SDN",
      "entry_type": "individual",
      "matching_info": ["name"],
      "confidence": 1.0,
      "livemode": true,
      "url": null,
      "notes": null,
      "title": null,
      "name_full": "John Arnold Bredenkamp",
      "alternate_names": "John A. Bredenkamp; John Bredenkamp",
      "date_of_birth": "1940-8-11",
      "id_type": "passport",
      "id_value": "367537C",
      "address_street1": "62 Chester Square",
      "address_street2": null,
      "address_city": "London",
      "address_state": null,
      "address_postal_code": null,
      "address_country_code": "GB",
      "address_raw": "62 Chester Square, London, GB",
      "names": [
        {
          "name_primary": false,
          "name_full": "John Arnold Bredenkamp",
          "name_strength": "medium"
        }
      ],
      "births": [
        {
          "birth_day": 11,
          "birth_month": 8,
          "birth_year": 1940,
          "birth_day_end": null,
          "birth_month_end": null,
          "birth_year_end": null
        }
      ],
      "documents": [
        {
          "document_type": "passport",
          "document_value": "367537C",
          "document_country_code": "SR"
        }
      ],
      "addresses": [
        {
          "address_street1": "62 Chester Square",
          "address_street2": null,
          "address_city": "London",
          "address_state": null,
          "address_postal_code": null,
          "address_country_code": "GB",
          "address_full": "62 Chester Square, London, GB"
        }
      ]
    }
  ]
}

Watchlists

The watchlists endpoint allows you to take a candidate token and perform a global watchlist search.

Attributes
livemode
Boolean

Indicates whether the search was executed using a live or test API key.

searched_lists
Array

A full list of watchlists that were searched in this query.

count
Integer

The number of watchlist hits that occurred.

matches
Array

Any matching hits on the watchlists for your inputted arguments.

matches[id]
String

BlockScore’s internal identifier for this watchlist hit. It will remain the same across searches.

matches[watchlist_name]
String

The watchlist on which this match took place.

matches[entry_type]
Enum

Defines whether the hit is a person or a company. Will either be individual or entity.

matches[matching_info]
Array

A list of elements in your request that match this watchlist hit.

matches[confidence]
Float

The similarity of this match’s full name to your submitted names. 0.0 would indicate no similarity and 1.0 would indicate a perfect match.

matches[url]
String

When available, this attribute links to a direct government source where this match can be found.

matches[notes]
String

A text field which some governments will use for storing arbitrary notes on a match.

matches[title]
String

This match’s professional title (such as Cabinet Official).

matches[name_full]
String

The full name of the watchlist match.

matches[alternate_names]
String

Other names that this candidate goes by.

matches[date_of_birth]
String

The date of birth of the match in ISO form.

matches[passport]
String

The matching candidate’s passport number.

matches[ssn]
String

The matching candidate’s Social Security Number.

matches[address_street1]
String

The primary street address of the candidate.

matches[address_street2]
String

The second address line typically used for apartment or suite numbers.

matches[address_city]
String

The city name of the candidate.

matches[address_subdivision]
String

The subdivision of the entered country. For instance in the United States, this would be a ‘state’.

matches[address_postal_code]
String

The postal code of the candidate. Also known as a ZIP code.

matches[address_country_code]
String

The country of the candidate. Should be of the ISO code form.

matches[address_raw]
String

The full, unmodified address from the watchlist.

matches[names]
Array

A list of all names associated with this match.

matches[names][name_primary]
Boolean

Indicates whether or not the current name object is the primary name that this match is referred to by.

matches[names][name_full]
String

The full name of the entity or individual.

matches[names][name_strength]
Enum

Indicates the reliability of this name according to the official government source. Can be one of: low, medium or high.

matches[births]
Array

A list of all incorporation dates or birth dates associated with this match.

matches[births][birth_day]
Integer

The day of birth or incorporation for this match

matches[births][birth_month]
Integer

The month of birth or incorporation for this match

matches[births][birth_year]
Integer

The year of birth or incorporation for this match

matches[births][birth_day_end]
Integer

If a range of dates is given for a potential birth day, this value will indicate the end day of that range.

matches[births][birth_month_end]
Integer

If a range of dates is given for a potential birth month, this value will indicate the end month of that range.

matches[births][birth_year_end]
Integer

If a range of dates is given for a potential birth year, this value will indicate the end year of that range.

matches[documents]
Array

A list of all forms of documentation for this match such as passports, SSNs or business numbers

matches[documents][document_type]
String

The form of documentation that this object describes such as passport, SSN or business number.

matches[documents][document_value]
String

The core identifying number of this document

matches[documents][document_country_code]
String

The 2-letter ISO code indicating the origin of this document

Watchlist object

{
  "livemode": true,
  "searched_lists": ["US_SDN"],
  "count": 1,
  "matches": [
    {
      "id": "ent_554056e4b4cf7103000009d5",
      "watchlist_name": "US_SDN",
      "entry_type": "individual",
      "matching_info": ["name"],
      "confidence": 1.0,
      "url": null,
      "notes": null,
      "title": null,
      "name_full": "John Bredenkamp",
      "alternate_names": "John A. Bredenkamp; John Arnold Bredenkamp",
      "date_of_birth": "1940-8-11",
      "passport": "367537C; Z153612; Z01024064; ND1285143",
      "ssn": null,
      "address_street1": "62 Chester Square",
      "address_street2": null,
      "address_city": "London",
      "address_state": null,
      "address_postal_code": null,
      "address_country_code": "GB",
      "address_raw": "62 Chester Square, London, GB",
      "names": [
        {
          "name_primary": true,
          "name_full": "John Bredenkamp",
          "name_strength": "medium"
        },
        {
          "name_primary": false,
          "name_full": "John A. Bredenkamp",
          "name_strength": "medium"
        },
        {
          "name_primary": false,
          "name_full": "John Arnold Bredenkamp",
          "name_strength": "medium"
        }
      ],
      "births": [
        {
          "birth_day": 11,
          "birth_month": 8,
          "birth_year": 1940,
          "birth_day_end": null,
          "birth_month_end": null,
          "birth_year_end": null
        }
      ],
      "documents": [
        {
          "document_type": "passport",
          "document_value": "367537C",
          "document_country_code": "SR"
        },
        {
          "document_type": "passport",
          "document_value": "Z153612",
          "document_country_code": "NL"
        }
      ],
      "addresses": [
        {
          "address_street1": "62 Chester Square",
          "address_street2": null,
          "address_city": "London",
          "address_state": null,
          "address_postal_code": null,
          "address_country_code": "GB",
          "address_full": "62 Chester Square, London, GB"
        },
        {
          "address_street1": "Dennerlei 30",
          "address_street2": null,
          "address_city": "Schoten",
          "address_state": null,
          "address_postal_code": null,
          "address_country_code": "BE",
          "address_full": "Dennerlei 30, Schoten, BE"
        }
      ]
    }
  ]
}

Confidence meanings

Each match is assigned a confidence rating. To understand the meaning of this number, you can use the following chart:

Confidence range Meaning
1.0 Exact Match of Data Elements Considered
0.95 - 0.99 Highly Likely Match
0.90 - 0.94 Very Good Match
0.85 - 0.89 Good Match
0.80 - 0.84 Less Likely Match
0.75 - 0.79 Weak Match
0.00 - 0.74 Unlikely Match

Matching info array

In the search response we return an array of matching information. These are all of the possible values in that array.

Parameter Note
name There is a full name match.
date_of_birth The day, month and year match.
passport There is an exact passport match.
street_address There is a partial address match.
city There is an exact city match.
state There is an exact state match.
country There is an exact country match.
postal_code There is an exact postal code match.

Search watchlists

This endpoint will execute a watchlist search for any given Candidate. The more information that is included in a Candidate, the more information we will match against. Less information, such as just including a name, will result in broader results. To help reduce false positives and refine results, we recommend progressively building up the amount of information stored within a Candidate and searching for them at each step.

We only charge for a successful Candidate creation, not each individual search executed. This means you are free to use as many searches as necessary to evaluate a potential customer.

Arguments
candidate_id required
The ID the candidate you have created. We search on all of the information provided in the associated profile.
match_type optional
Can be either the value person or company and will restrict the search to only search for individuals or entities on the watchlists respectively.
similarity_threshold optional
Any watchlist matches with confidence less than this threshold will be filtered out of the results. Used for tweaking watchlist hit sensitivity. Expects a float between 0.0 and 1.0 where 1.0 is exact matches only and 0.0 is lenient matching. The default value is 0.7.
Returns

We return a list of all associated matches. The results are sorted by confidence level, meaning that stronger matches are at the top. You can input as much or as little information as you wish and we will not exclude results if you include more information. However, the more information you include, the more we can tell you about what matches.

Watchlist Codes
List code Name Country
US_ENL Entity List US
US_SDN Specially Designated Nationals US
US_DPL Denied Persons List US
US_ISN Nonproliferation Sanctions US
US_FSE Foreign Sanctions Evaders US
US_UVL Unverified List US
US_DTC AECA Debarred US
US_PLC Palestinian Legislative Council US
US_IRA List of Persons Identified as Blocked Solely Pursuant to Executive Order 13599 US
UK_HMC HM Treasury UK
CA_OSI OSFI Anti-terrorism financing individuals CA
CA_OSE OSFI Anti-terrorism financing entities CA
EU_CON European Union Consolidated List EU
AU_CON Department of Foreign Affairs and Trade AU
IZ_UNC Consolidated United Nations Sanctions UN
CH_CON Consolidated List of Sanctioned Individuals, Entities and Organizations CH
JP_EUL Foreign End User List JP
IZ_PEP Politically Exposed Persons IZ
US_FSO The List of Foreign Financial Institutions Subject to Part 561 US

Endpoint

POST
https://api.blockscore.com/watchlists

Example request

$ curl https://api.blockscore.com/watchlists \
  -u sk_test_n5049aa6053c9a0217bea78070fbf501: \
  --header "Accept: application/vnd.blockscore+json;version=4" \
  -d 'candidate_id=51f5b51f8fcf0e4d59000001' \
  -d 'match_type=person'

Example response

{
  "livemode": true,
  "searched_lists": ["US_SDN"],
  "count": 1,
  "matches": [
    {
      "id": "ent_554056e4b4cf7103000009d5",
      "watchlist_name": "US_SDN",
      "entry_type": "individual",
      "matching_info": ["name"],
      "confidence": 1.0,
      "url": null,
      "notes": null,
      "title": null,
      "name_full": "John Bredenkamp",
      "alternate_names": "John A. Bredenkamp; John Arnold Bredenkamp",
      "date_of_birth": "1940-8-11",
      "passport": "367537C; Z153612; Z01024064; ND1285143",
      "ssn": null,
      "address_street1": "62 Chester Square",
      "address_street2": null,
      "address_city": "London",
      "address_state": null,
      "address_postal_code": null,
      "address_country_code": "GB",
      "address_raw": "62 Chester Square, London, GB",
      "names": [
        {
          "name_primary": true,
          "name_full": "John Bredenkamp",
          "name_strength": "medium"
        },
        {
          "name_primary": false,
          "name_full": "John A. Bredenkamp",
          "name_strength": "medium"
        },
        {
          "name_primary": false,
          "name_full": "John Arnold Bredenkamp",
          "name_strength": "medium"
        }
      ],
      "births": [
        {
          "birth_day": 11,
          "birth_month": 8,
          "birth_year": 1940,
          "birth_day_end": null,
          "birth_month_end": null,
          "birth_year_end": null
        }
      ],
      "documents": [
        {
          "document_type": "passport",
          "document_value": "367537C",
          "document_country_code": "SR"
        },
        {
          "document_type": "passport",
          "document_value": "Z153612",
          "document_country_code": "NL"
        }
      ],
      "addresses": [
        {
          "address_street1": "62 Chester Square",
          "address_street2": null,
          "address_city": "London",
          "address_state": null,
          "address_postal_code": null,
          "address_country_code": "GB",
          "address_full": "62 Chester Square, London, GB"
        },
        {
          "address_street1": "Dennerlei 30",
          "address_street2": null,
          "address_city": "Schoten",
          "address_state": null,
          "address_postal_code": null,
          "address_country_code": "BE",
          "address_full": "Dennerlei 30, Schoten, BE"
        }
      ]
    }
  ]
}