This is an old version of the API. Read the latest documentation ›

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

  • /verifications

  • /verifications/{VERIFICATION_ID}

  • /questions

  • /questions/{QUESTION_SET_ID}

  • /companies

  • /companies/{COMPANY_ID}

  • /questions/score/{QUESTION_SET_ID}

  • /watchlist_candidates

  • /watchlist_candidates/{WATCHLIST_CANDIDATE_ID}

  • /watchlist_candidates/{WATCHLIST_CANDIDATE_ID}/history

  • /watchlist_candidates/{WATCHLIST_CANDIDATE_ID}/hits

  • /watchlists

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/verifications \
  -u sk_test_n5049aa6053c9a0217bea78070fbf501: \
  --header "Accept: application/vnd.blockscore+json;version=3"

The -u flag as part of the curl command passes authentication credentials to the HTTP basic auth.

The colon after the API key denotes that the password is being left blank.

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

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/verifications \
  -u sk_test_709f59bd4ff5191ebaf409330bec4c27: \
  --header "Accept: application/vnd.blockscore+json;version=3" \
  -d 'offset=20' \
  -d 'count=10'

Example response

[
  {
    "id": "51f5b51f8fcf0e4d59000001",
    "created_at": 1403762295,
    "updated_at": 1403762295,
    "status": "valid",
    "livemode": false,
    "date_of_birth": "1980-08-23",
    "phone_number": null,
    "ip_address": null,
    "identification": {
      "ssn": "0000"
    },
    "details": {
        "address": "mismatch",
        "address_risk": "low",
        "identification": "match",
        "date_of_birth": "match",
        "ofac": "not_found"
    },
    "name": {
        "first": "John",
        "middle": "Pearce",
        "last": "Doe"
    },
    "address": {
        "street1": "1 Infinite Loop",
        "street2": "Apt 6",
        "city": "Cupertino",
        "state": "CA",
        "postal_code": "95014",
        "country_code": "US"
    },
    "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=3

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.

Client library releases

Our client libraries follow a very simple upgrade path. All of the client libraries are versioned like so: 0.0.0 where the leading number indicates the major API version corresponding to that package, the middle number indicates an API change within the client library and the final number indicates a patch within the library.

Current version

The latest version of the API is 4.

Example request

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

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

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?

Verifications

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

Attributes
id string
created_at timestamp
updated_at timestamp
date_of_birth string
The date of birth of your customer.
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 landline) of your customer.
ip_address string
The IP address (v4 or v6) of the person being verified.
identification[ssn] string
This can be either the last 4 digits of the US Social Security Number or the whole SSN.
identification[passport] string
The passport number of the individual being verified. This is only used for verifying non-US customers.
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. This is automatically normalized.
address[street2] string
The second address line typically used for apartment or suite numbers. This is automatically normalized.
address[city] string
The city name of the customer. This is automatically normalized.
address[state] 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 the two character 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.

Verification object

{
  "id": "51f5b51f8fcf0e4d59000001",
  "created_at": 1403762295,
  "updated_at": 1403762295,
  "status": "valid",
  "livemode": false,
  "date_of_birth": "1980-08-23",
  "phone_number": null,
  "ip_address": null,
  "identification": {
    "ssn": "0000"
  },
  "details": {
      "address": "mismatch",
      "address_risk": "low",
      "identification": "match",
      "date_of_birth": "match",
      "ofac": "not_found"
  },
  "name": {
      "first": "John",
      "middle": "Pearce",
      "last": "Doe"
  },
  "address": {
      "street1": "1 Infinite Loop",
      "street2": "Apt 6",
      "city": "Cupertino",
      "state": "CA",
      "postal_code": "95014",
      "country_code": "US"
  },
  "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 Part of the person's name matches, such as only the last name.
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.
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 verification

This endpoint creates a new verification. 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
date_of_birth required
The date of birth of your customer.
identification[ssn] optional either ssn or passport is required
This can be either the last 4 digits of the US Social Security Number or the whole SSN.
identification[passport] optional either ssn or passport is required
The passport number of the individual being verified. This is only used for verifying non-US customers.
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
address[street1] required
The primary street address of the customer. This is automatically normalized.
address[street2] optional
The second address line typically used for apartment or suite numbers. This is automatically normalized.
address[city] required
he city name of the customer. This is automatically normalized.
address[state] 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, also known as the ZIP code of the address.
address[country_code] required
The country of the customer. Must be in the two character 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.
Returns

Along with the 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/verifications

Example request

Example response

{
  "id": "51f5b51f8fcf0e4d59000001",
  "created_at": 1403762295,
  "updated_at": 1403762295,
  "status": "valid",
  "livemode": false,
  "date_of_birth": "1980-08-23",
  "phone_number": null,
  "ip_address": null,
  "identification": {
    "ssn": "0000"
  },
  "details": {
      "address": "mismatch",
      "address_risk": "low",
      "identification": "match",
      "date_of_birth": "match",
      "ofac": "not_found"
  },
  "name": {
      "first": "John",
      "middle": "Pearce",
      "last": "Doe"
  },
  "address": {
      "street1": "1 Infinite Loop",
      "street2": "Apt 6",
      "city": "Cupertino",
      "state": "CA",
      "postal_code": "95014",
      "country_code": "US"
  },
  "question_sets": []
}

Retrieve an existing verification

You can pull up a single 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 verification took place along with all of its associated data.

Endpoint

GET https://api.blockscore.com/verifications/{VERIFICATION_ID}

Example request

Example response

{
  "id": "51f5b51f8fcf0e4d59000001",
  "created_at": 1403762295,
  "updated_at": 1403762295,
  "status": "valid",
  "livemode": false,
  "date_of_birth": "1980-08-23",
  "phone_number": null,
  "ip_address": null,
  "identification": {
    "ssn": "0000"
  },
  "details": {
      "address": "mismatch",
      "address_risk": "low",
      "identification": "match",
      "date_of_birth": "match",
      "ofac": "not_found"
  },
  "name": {
      "first": "John",
      "middle": "Pearce",
      "last": "Doe"
  },
  "address": {
      "street1": "1 Infinite Loop",
      "street2": "Apt 6",
      "city": "Cupertino",
      "state": "CA",
      "postal_code": "95014",
      "country_code": "US"
  },
  "question_sets": [
    "536c1532627463780b000000"
  ]
}

List all verifications

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 verifications appear first).

Endpoint

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

Example request

Example response

[
  {
    "id": "51f5b51f8fcf0e4d59000001",
    "created_at": 1403762295,
    "updated_at": 1403762295,
    "status": "valid",
    "livemode": false,
    "date_of_birth": "1980-08-23",
    "phone_number": null,
    "ip_address": null,
    "identification": {
      "ssn": "0000"
    },
    "details": {
        "address": "mismatch",
        "address_risk": "low",
        "identification": "match",
        "date_of_birth": "match",
        "ofac": "not_found"
    },
    "name": {
        "first": "John",
        "middle": "Pearce",
        "last": "Doe"
    },
    "address": {
        "street1": "1 Infinite Loop",
        "street2": "Apt 6",
        "city": "Cupertino",
        "state": "CA",
        "postal_code": "95014",
        "country_code": "US"
    },
    "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
id string
created_at timestamp
updated_at timestamp
livemode boolean
Indicates whether the question set was created using a live or test API key.
verification_id string
The associated verification'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 question object.
questions[answers][answer_id] integer
The ID of the answer object.

Question set object

{
  "id": "533ce7e5627463792f010000",
  "created_at": 1402450269,
  "updated_at": 1403742375,
  "livemode": false,
  "verification_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 verification ID and the questions asked as well as the order that everything is presented in will be randomized.

Arguments
verification_id required
The ID of the verification, 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.

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

Example request

Example response

{
  "id": "533ce7e5627463792f010000",
  "created_at": 1402450269,
  "updated_at": 1403742375,
  "livemode": false,
  "verification_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"
        }
      ]
    },
    { ... }
  ]
}

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/questions/{QUESTION_SET_ID}/score

Example request

Example response

{
  "id": "533ce7e5627463792f010000",
  "created_at": 1402450269,
  "updated_at": 1403742375,
  "livemode": false,
  "verification_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/questions/{QUESTION_SET_ID}

Example request

Example response

{
  "id": "533ce7e5627463792f010000",
  "created_at": 1402450269,
  "updated_at": 1403742375,
  "livemode": false,
  "verification_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/questions

Example request

Example response

[
  {
  "id": "533ce7e5627463792f010000",
  "created_at": 1402450269,
  "updated_at": 1403742375,
  "livemode": false,
  "verification_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
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.
incorp_date string
When the company was incorporated.
incorp_state string
The state or region of incorporation of the company.
incorp_country_code string
The country of incorporation of the company.
incorp_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 landline) of your company
ip_address string
The IP address (v4 or v6) of the company being verified.
address[street1] string
The primary street address of the company. This is automatically normalized.
address[street2] string
The second address line typically used for apartment or suite numbers. This is automatically normalized.
address[city] string
The city name of the company. This is automatically normalized.
address[state] string
The state of the company. 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 company. Must be in the two character ISO code form.
details array
A breakdown of some of the information that determines the status element.

Company object

{
  "id": "53afcb1b62746367130a0000",
  "created_at": 1404029723,
  "updated_at": 1404029723,
  "status": "valid",
  "livemode": false,
  "entity_name": "BlockScore",
  "tax_id": "123410000",
  "incorp_date": "1980-08-25",
  "incorp_state": "DE",
  "incorp_country_code": "US",
  "incorp_type": "corporation",
  "dbas": "BitRemit",
  "registration_number": "123123123",
  "email": "test@example.com",
  "url": "https://blockscore.com",
  "phone_number": "6505555555",
  "ip_address": "67.160.8.182",
  "address": {
    "street1": "123 Fake Streets",
    "street2": null,
    "city": "Stanford",
    "state": "CA",
    "postal_code": "94305",
    "country_code": "US"
  },
  "details": {
    "entity_name": "match",
    "tax_id": "match",
    "ofac": "no_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 exlude 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.
incorp_date optional
Should be of the ISO date form (YYYY-MM-DD)
incorp_state optional
Can be either of ISO code form or the full length name of the state.
incorp_country_code required
Must be in the two character ISO code form.
incorp_type required
Must be one of the pre-defined incorporation types listed in the "Incorporation types" table.
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.
address[street1] required
The primary street address of the company. This is automatically normalized.
address[street2] optional
The second address line typically used for apartment or suite numbers. This is automatically normalized.
address[city] required
he city name of the company. This is automatically normalized.
address[state] required
The state of the company. Should be of the FIPS code form. For example California would be CA.
address[postal_code] required
The postal code, also known as the ZIP code of the address.
address[country_code] required
The country of the company. Must be in the two character 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

Example response

{
  "id": "53afcb1b62746367130a0000",
  "created_at": 1404029723,
  "updated_at": 1404029723,
  "status": "valid",
  "livemode": false,
  "entity_name": "BlockScore",
  "tax_id": "123410000",
  "incorp_date": "1980-08-25",
  "incorp_state": "DE",
  "incorp_country_code": "US",
  "incorp_type": "corporation",
  "dbas": "BitRemit",
  "registration_number": "123123123",
  "email": "test@example.com",
  "url": "https://blockscore.com",
  "phone_number": "6505555555",
  "ip_address": "67.160.8.182",
  "address": {
    "street1": "123 Fake Streets",
    "street2": null,
    "city": "Stanford",
    "state": "CA",
    "postal_code": "94305",
    "country_code": "US"
  },
  "details": {
    "entity_name": "match",
    "tax_id": "match",
    "ofac": "no_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

Example response

{
  "id": "53afcb1b62746367130a0000",
  "created_at": 1404029723,
  "updated_at": 1404029723,
  "status": "valid",
  "livemode": false,
  "entity_name": "BlockScore",
  "tax_id": "123410000",
  "incorp_date": "1980-08-25",
  "incorp_state": "DE",
  "incorp_country_code": "US",
  "incorp_type": "corporation",
  "dbas": "BitRemit",
  "registration_number": "123123123",
  "email": "test@example.com",
  "url": "https://blockscore.com",
  "phone_number": "6505555555",
  "ip_address": "67.160.8.182",
  "address": {
    "street1": "123 Fake Streets",
    "street2": null,
    "city": "Stanford",
    "state": "CA",
    "postal_code": "94305",
    "country_code": "US"
  },
  "details": {
    "entity_name": "match",
    "tax_id": "match",
    "ofac": "no_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

Example response

[
  {
    "id": "53afcb1b62746367130a0000",
    "created_at": 1404029723,
    "updated_at": 1404029723,
    "status": "valid",
    "livemode": false,
    "entity_name": "BlockScore",
    "tax_id": "123410000",
    "incorp_date": "1980-08-25",
    "incorp_state": "DE",
    "incorp_country_code": "US",
    "incorp_type": "corporation",
    "dbas": "BitRemit",
    "registration_number": "123123123",
    "email": "test@example.com",
    "url": "https://blockscore.com",
    "phone_number": "6505555555",
    "ip_address": "67.160.8.182",
    "address": {
      "street1": "123 Fake Streets",
      "street2": null,
      "city": "Stanford",
      "state": "CA",
      "postal_code": "94305",
      "country_code": "US"
    },
    "details": {
      "entity_name": "match",
      "tax_id": "match",
      "ofac": "no_match"
    }
  },
  { ... }
]

Watchlist 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
id string
created_at timestamp
updated_at timestamp
date_of_birth string
The date of birth of your candidate.
livemode boolean
Indicates whether the candidate was created using a live or test API key.
note string
An additional field which can be used for arbitrary storage. This is typically used for storing your internal identifiers for this customer.
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 customers.
first_name string
The legal first name of the customer
middle_name string
The legal middle name of the customer
last_name string
The legal last name of the customer
address_street1 string
The primary street address of the customer. This is automatically normalized.
address_street2 string
The second address line typically used for apartment or suite numbers. This is automatically normalized.
address_city string
The city name of the customer. This is automatically normalized.
address_state 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 the two character ISO code form.

Watchlist object

{
  "id": "53a15d256235350002010000",
  "created_at": 1403084069,
  "updated_at": 1403084069,
  "livemode": false,
  "note": null,
  "ssn": null,
  "passport": null,
  "date_of_birth": null,
  "first_name": "John",
  "middle_name": null,
  "last_name": "Bredenkamp",
  "address_street1": null,
  "address_street2": null,
  "address_city": null,
  "address_state": null,
  "address_postal_code": null,
  "address_country_code": null
}

Create a new watchlist candidate

This endpoint creates a new watchlist candidate.

Arguments
date_of_birth optional
The date of birth of your customer.
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.
first_name optional
The legal first name of the customer
middle_name optional
The legal middle name of the customer
last_name optional
The legal last name of the customer
address_street1 optional
The primary street address of the customer. This is automatically normalized.
address_street2 optional
The second address line typically used for apartment or suite numbers. This is automatically normalized.
address_city optional
he city name of the customer. This is automatically normalized.
address_state optional
The state of the customer. Should be of the FIPS code form. For example California would be CA.
address_postal_code optional
The postal code, also known as the ZIP code of the address.
address_country_code optional
The country of the customer. Must be in the two character ISO code form.
Returns

If the request is successful, we return the watchlist 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/watchlist_candidates

Example request

Example response

{
  "id": "53a15d256235350002010000",
  "created_at": 1403084069,
  "updated_at": 1403084069,
  "livemode": false,
  "note": "12341234",
  "ssn": "0001",
  "passport": null,
  "date_of_birth": "1940-08-11",
  "first_name": "John",
  "middle_name": null,
  "last_name": "Bredenkamp",
  "address_street1": null,
  "address_street2": null,
  "address_city": "Harare",
  "address_state": null,
  "address_postal_code": null,
  "address_country_code": "ZW"
}

Edit a watchlist 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/watchlist_candidates/{WATCHLIST_CANDIDATE_ID}

Example request

Example response

{
  "id": "53a15d256235350002010000",
  "created_at": 1403084069,
  "updated_at": 1403084069,
  "livemode": false,
  "note": "55555555",
  "ssn": "0002",
  "passport": null,
  "date_of_birth": "1940-08-11",
  "first_name": "John",
  "middle_name": null,
  "last_name": "Bredenkamp",
  "address_street1": null,
  "address_street2": null,
  "address_city": "Harare",
  "address_state": null,
  "address_postal_code": null,
  "address_country_code": "AR"
}

Delete a watchlist candidate

This endpoint allows you to remove a watchlist 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/watchlist_candidates/{WATCHLIST_CANDIDATE_ID}

Example request

Example response

{
  "id": "53a15d256235350002010000",
  "created_at": 1403084069,
  "updated_at": 1403084069,
  "livemode": false,
  "deleted": true,
  "note": "55555555",
  "ssn": "0002",
  "passport": null,
  "date_of_birth": "1940-08-11",
  "first_name": "John",
  "middle_name": null,
  "last_name": "Bredenkamp",
  "address_street1": null,
  "address_street2": null,
  "address_city": "Harare",
  "address_state": null,
  "address_postal_code": null,
  "address_country_code": "AR"
}

Retrieve an existing watchlist candidate

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

Endpoint

GET https://api.blockscore.com/watchlist_candidates/{WATCHLIST_CANDIDATE_ID}

Example request

Example response

{
  "id": "53a15d256235350002010000",
  "created_at": 1403084069,
  "updated_at": 1403084069,
  "livemode": false,
  "note": "55555555",
  "ssn": "0002",
  "passport": null,
  "date_of_birth": "1940-08-11",
  "first_name": "John",
  "middle_name": null,
  "last_name": "Bredenkamp",
  "address_street1": null,
  "address_street2": null,
  "address_city": "Harare",
  "address_state": null,
  "address_postal_code": null,
  "address_country_code": "AR"
}

List all watchlist candidates

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

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

Endpoint

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

Example request

Example response

[
  {
    "id": "53a15d256235350002010000",
    "created_at": 1403084069,
    "updated_at": 1403084069,
    "livemode": false,
    "note": "55555555",
    "ssn": "0002",
    "passport": null,
    "date_of_birth": "1940-08-11",
    "first_name": "John",
    "middle_name": null,
    "last_name": "Bredenkamp",
    "address_street1": null,
    "address_street2": null,
    "address_city": "Harare",
    "address_state": null,
    "address_postal_code": null,
    "address_country_code": "AR"
  },
  { ... }
]

Receive a watchlist candidate webhook

When watchlist 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 watchlist 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 watchlist_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 watchlist candidate's revision history

We store a complete revision history of a watchlist 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/watchlist_candidates/:id/history

Example request

Example response

[
  {
    "id": "53b1fbf33538620002000000",
    "created_at": 1404173299,
    "updated_at": 1404173359,
    "livemode": true,
    "note": null,
    "ssn": null,
    "passport": null,
    "date_of_birth": null,
    "first_name": "John",
    "middle_name": null,
    "last_name": "Bredenkamp",
    "address_street1": null,
    "address_street2": null,
    "address_city": null,
    "address_state": null,
    "address_postal_code": null,
    "address_country_code": "ZW"
  },
  {
    "id": "53b1fbf33538620002000000",
    "created_at": 1404173299,
    "updated_at": 1404173299,
    "livemode": true,
    "note": null,
    "ssn": null,
    "passport": null,
    "date_of_birth": null,
    "first_name": "John",
    "middle_name": null,
    "last_name": "Bredenkamp",
    "address_street1": null,
    "address_street2": null,
    "address_city": null,
    "address_state": null,
    "address_postal_code": null,
    "address_country_code": null
  }
]

View a watchlist candidate's past hits

Whenever a search is executed for a watchlist 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/watchlist_candidates/:id/hits

Example request

Example response

[
  {
    "id": "53d96b753934300118000000",
    "created_at": 1406757749,
    "updated_at": 1406757749,
    "matching_info": ["name"],
    "confidence": 0.25,
    "livemode": true,
    "list": "US_SDN",
    "id_type": "passport",
    "id_value": "nd1285143",
    "date_of_birth": "1940-08-11",
    "full_name": "john bredenkamp",
    "street_address": "Hurst Grove, Sanford Lane, Hurst",
    "city": "Reading, Berkshire RG10 0SQ",
    "state": null,
    "postal_code": null,
    "country_code": "United Kingdom"
  }
]

Watchlists

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

Attributes
search_time float
How long it took (in milliseconds) to find the records.
searched_lists array
An array of all watchlists that were searched.
matches array
Matching individuals on the requested watchlists.
matches[watchlist_name] string
The name of the watchlist where this particular match was found.
matches[confidence] float
The percentage of information about the given candidate that matches this watchlist individual.
matches[matching_info] array
An array of all of the matching information between that individual and the watchlist hit.
matches[matching_record] array
matches[matching_record][id] string
matches[matching_record][full_name] string
The full legal name of the matching watchlist individual.
matches[matching_record][alternate_names] string
Other names that this person is known by.
matches[matching_record][date_of_birth] string
matches[matching_record][address] string
matches[matching_record][street] string
matches[matching_record][city] string
matches[matching_record][state] string
matches[matching_record][country] string
The country of the match. Must be in the two character ISO code form.
matches[matching_record][postal_code] string
matches[matching_record][ssn] string
matches[matching_record][passport] string

Watchlist object

{
  "search_time": 7.27531,
  "searched_lists": ["US_SDN"],
  "matches": [
    {
      "watchlist_name": "US_SDN",
      "confidence": 0.6,
      "matching_info": ["name"],
      "matching_record": {
        "id": "53a153d83337300002dd2700",
        "full_name": "john bredenkamp",
        "alternate_names": "john a. bredenkamp;;",
        "date_of_birth": "1940-08-11",
        "ssn": null,
        "passport": "nd1285143",
        "address": "thetford farm, p.o. box hp86",
        "street_address": "Thetford Farm, P.O. Box HP86",
        "city": "Harare",
        "state": null,
        "country": "Zimbabwe",
        "postal_code": null
      }
    }
  ]
}

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 creates a new verification. 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
watchlist_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 people or entities on the watchlists.
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

Example response

{
  "search_time": 7.27531,
  "searched_lists": ["US_SDN"],
  "matches": [
    {
      "watchlist_name": "US_SDN",
      "confidence": 0.6,
      "matching_info": ["name"],
      "matching_record": {
        "id": "53a153d83337300002dd2700",
        "full_name": "john bredenkamp",
        "alternate_names": "john a. bredenkamp;;",
        "date_of_birth": "1940-08-11",
        "ssn": null,
        "passport": "nd1285143",
        "address": "thetford farm, p.o. box hp86",
        "street_address": "Thetford Farm, P.O. Box HP86",
        "city": "Harare",
        "state": null,
        "country": "Zimbabwe",
        "postal_code": null
      }
    }
  ]
}
curlrubypythonnodephp
java