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

offset	optional Determines how many items are skipped before the first item that is shown.
count	optional The number of items to show on a page (the default and maximum is 25).

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

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 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

People

A person object is used to perform domestic identity verification. The purpose of this endpoint is to validate customer information with our data sources.

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. Must be in the ISO 3166-1 alpha-2 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. Must be in ISO 3166-1 alpha-2 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	Must be in the ISO 3166-1 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 postal code of the customer. Also known as a ZIP code.
address_country_code required	The country of the customer. Must be in the ISO 3166-1 alpha-2 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 using our re-scan system.

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.
digital_currency_address String	The digital currency address belonging to the candidate.
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. Must be in the two character ISO 3166-1 alpha-2 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",
  "digital_currency_address": "1AjZPMsnmpdK2Rv9KQNfMurTXinscVro9V",
  "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.
digital_currency_address optional	The digital currency address belonging to the candidate.
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. Must be in the ISO 3166-1 alpha-2 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 'digital_currency_address=1AjZPMsnmpdK2Rv9KQNfMurTXinscVro9V' \
  -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",
  "digital_currency_address": "1AjZPMsnmpdK2Rv9KQNfMurTXinscVro9V",
  "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",
  "digital_currency_address": "1AjZPMsnmpdK2Rv9KQNfMurTXinscVro9V",
  "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",
  "digital_currency_address": "1AjZPMsnmpdK2Rv9KQNfMurTXinscVro9V",
  "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

If you are enrolled in our rescanning program, when candidates are created, they are automatically enrolled in a re-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 as an ISO 3166-1 alpha-2 code.
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 3166-1 alpha-2 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.

Watchlist Codes

List code(s)	Name	Country
`US_ENL` `US_EL`	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` `CA_OSFII`	OSFI Anti-terrorism financing individuals	CA
`CA_OSE` `CA_OSFIE`	OSFI Anti-terrorism financing entities	CA
`EU_CON`	European Union Consolidated List	EU
`AU_CON`	Department of Foreign Affairs and Trade	AU
`IZ_UNC` `UN_CON`	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"
        }
      ]
    }
  ]
}