blockscore

README

blockscore-go

Go client library for the BlockScore API.

Installation

go get github.com/connorjacobsen/blockscore-go

Usage

Import the package:

import (
    "github.com/connorjacobsen/blockscore-go"
)

Set your BlockScore API key in an environment variable:

export BLOCKSCORE_API_KEY="your key"

OR you can also set your BlockScore API key in a file:

blockscore.SetKey("YOUR_API_KEY")

Note: Make sure to use your test key when running the test suite, otherwise the test suite will make live API requests.

People

Create a new person:

params := blockscore.PeopleParams{
    NameFirst:          "John",
    NameMiddle:         "P",
    NameLast:           "Denver",
    DocumentType:       "ssn",
    DocumentValue:      "0000",
    BirthDay:           7,
    BirthMonth:         6,
    BirthYear:          1980,
    AddressStreet1:     "1234 Main Street",
    AddressStreet2:     "APT 12",
    AddressCity:        "Palo Alto",
    AddressSubdivision: "California",
    AddressPostalCode:  "94025",
    AddressCountryCode: "US",
    PhoneNumber:        "123-456-78910",
    IPAddress:          "127.0.0.1",
    Note:               "Hello, world",
}

person, err := blockscore.People.Create(&params)

Get a single existing People:

person, err := blockscore.People.Retrieve("DESIRED_PERSON_ID")

Get a list of People:

people, err := blockscore.People.List()

Get a list of X people, offset by Y people:

people, err := blockscore.People.ListN(X, Y)

Question Sets

Create a QuestionSet:

// Get the Person we want a QuestionSet for.
person, err := blockscore.People.Retrieve("DESIRED_PERSON_ID")

questionSet, err := blockscore.QuestionSets.Create(person.Id)

Score a QuestionSet:

params := ScoreParams{
    Answers: []ScoreAnswer{
        ScoreAnswer{QuestionId: 1, AnswerId: 1},
        ScoreAnswer{QuestionId: 2, AnswerId: 1},
        ScoreAnswer{QuestionId: 3, AnswerId: 1},
        ScoreAnswer{QuestionId: 4, AnswerId: 1},
        ScoreAnswer{QuestionId: 5, AnswerId: 1},
    },
}

questionSet, err := blockscore.QuestionSets.Score("QUESTION_SET_ID", &params)

if err != nil {
    // Error handling for your application.
}

// Print the QuestionSet's score.
fmt.Printf("Score: %s\n", questionSet.Score())

Retrieve a QuestionSet:

questionSet, err := blockscore.QuestionSets.Retrieve("QUESTION_SET_ID")

Get a list of QuestionSets:

questionSets, err := blockscore.QuestionSets.List()

Get a list of X QuestionSets, offset by Y QuestionSets:

questionSets, err := blockscore.QuestionSets.ListN(X, Y)

Companies

Create a new company:

params := blockscore.CompanyParams{
    EntityName:               "BlockScore",
    TaxId:                    "123410000",
    IncorporationState:       "DE",
    IncorporationCountryCode: "US",
    IncorporationType:        "corporation",
    IncorporationDay:         23,
    IncorporationMonth:       8,
    IncorporationYear:        1993,
    Dbas:                     "BitRemit",
    RegistrationNumber:       "123123123",
    Email:                    "test@example.com",
    Url:                      "https://blockscore.com",
    PhoneNumber:              "6505555555",
    IPAddress:                "67.160.8.182",
    Note:                     "Much wow",
    AddressStreet1:           "12345 Main Street",
    AddressStreet2:           "#12",
    AddressCity:              "Palo Alto",
    AddressSubdivision:       "CA",
    AddressPostalCode:        "94025",
    AddressCountryCode:       "US",
}

company, err := blockscore.Companies.Create(&params)

Get a single existing Company:

company, err := blockscore.Companies.Retrieve("DESIRED_COMPANY_ID")

Get a list of Companies:

companies, err := blockscore.Companies.List()

Get a list of X companies, offset by Y companies:

companies, err := blockscore.Companies.ListN(X, Y)

Candidates

Create a Candidate:

params := CandidateParams{
    NameFirst:          "John",
    NameLast:           "Brendekamp",
    Note:               "12341234",
    Ssn:                "0001",
    DateOfBirth:        "1940-08-11",
    AddressStreet1:     "1 Infinite Loop",
    AddressCity:        "Harare",
    AddressCountryCode: "ZW",
}

candidate, err := blockscore.Candidates.Create(&params)

Retrieve a Candidate:

candidate, err := blockscore.Candidates.Retrieve("DESIRED_CANDIDATE_ID")

Update a Candidate:

params := CandidateParams{
    Passport: "123456789",
}

candidate, err := blockscore.Candidate.Update("DESIRED_CANDIDATE_ID", &params)

Delete a Candidate:

candidate, err := blockscore.Candidate.Delete("DESIRED_CANDIDATE_ID")

Get a list of Candidates:

candidates, err := blockscore.Candidates.List()

Get a list of X Candidates, offset by Y Candidates:

candidates, err := blockscore.Candidates.ListN(X, Y)

View the Revision History of a Candidate:

candidateHistory, err := blockscore.Candidates.History("CANDIDATE_ID")

View past Watchlist Hits of a Candidate:

candidateHits, err := blockscore.Candidates.Hits("CANDIDATE_ID")

Watchlists

Search a Watchlist:

watchlistParams := WatchlistParams{
    CandidateId: "DESIRED_CANDIDATE_ID",
    MatchType:   "person" // search for individuals only
}

search, err := blockscore.Watchlists.Search(&watchlistParams)

Documentation

Index

• Variables
• func SetKey(key string)
• func SetKeyEnv() (err error)
• func SetVersion(version int)
• type Answer
• type Candidate
• type CandidateClient
  • func (self *CandidateClient) Create(params *CandidateParams) (*Candidate, error)
  • func (self *CandidateClient) Delete(id string) (*Candidate, error)
  • func (self *CandidateClient) History(id string) ([]*Candidate, error)
  • func (self *CandidateClient) Hits(id string) ([]*Candidate, error)
  • func (self *CandidateClient) List() ([]*Candidate, error)
  • func (self *CandidateClient) ListN(count, offset int) ([]*Candidate, error)
  • func (self *CandidateClient) Retrieve(id string) (*Candidate, error)
  • func (self *CandidateClient) Update(id string, params *CandidateParams) (*Candidate, error)
• type CandidateParams
• type Company
• type CompanyClient
  • func (self *CompanyClient) Create(params *CompanyParams) (*Company, error)
  • func (self *CompanyClient) List() ([]*Company, error)
  • func (self *CompanyClient) ListN(count, offset int) ([]*Company, error)
  • func (self *CompanyClient) Retrieve(id string) (*Company, error)
• type CompanyDetails
• type CompanyParams
• type Error
  • func (e *Error) Error() string
• type Match
• type Person
• type PersonClient
  • func (self *PersonClient) Create(params *PersonParams) (*Person, error)
  • func (self *PersonClient) List() ([]*Person, error)
  • func (self *PersonClient) ListN(count, offset int) ([]*Person, error)
  • func (self *PersonClient) Retrieve(id string) (*Person, error)
• type PersonDetails
• type PersonParams
• type Question
• type QuestionSet
• type QuestionSetClient
  • func (self *QuestionSetClient) Create(personId string) (*QuestionSet, error)
  • func (self *QuestionSetClient) List() ([]*QuestionSet, error)
  • func (self *QuestionSetClient) ListN(count, offset int) ([]*QuestionSet, error)
  • func (self *QuestionSetClient) Retrieve(id string) (*QuestionSet, error)
  • func (self *QuestionSetClient) Score(id string, params *ScoreParams) (*QuestionSet, error)
• type ScoreAnswer
• type ScoreParams
• type Watchlist
• type WatchlistClient
  • func (self *WatchlistClient) Search(params *WatchlistParams) (*Watchlist, error)
• type WatchlistParams

Variables

var (
	People       = new(PersonClient)
	Companies    = new(CompanyClient)
	Candidates   = new(CandidateClient)
	QuestionSets = new(QuestionSetClient)
	Watchlists   = new(WatchlistClient)
)

Functions

func SetKey

func SetKey(key string)

Sets the BlockScore API key to use for authenticating API requests.

func SetKeyEnv

func SetKeyEnv() (err error)

func SetVersion

func SetVersion(version int)

Sets the version of the BlockScore API to use. Note: This library is designed to only work with v4 and newer.

Types

type Answer

type Answer struct {
	Id     int    `json:"id"`
	Answer string `json:"answer"`
}

type Candidate

type Candidate struct {
	Object             string `json:"object"`
	Id                 string `json:"id"`
	CreatedAt          int64  `json:"created_at"`
	UpdatedAt          int64  `json:"updated_at"`
	Livemode           bool   `json:"livemode"`
	Note               string `json:"note"`
	Ssn                string `json:"ssn"`
	Passport           string `json:"passport"`
	DateOfBirth        string `json:"date_of_birth"`
	NameFirst          string `json:"name_first"`
	NameMiddle         string `json:"name_middle"`
	NameLast           string `json:"name_last"`
	AddressStreet1     string `json:"address_street1"`
	AddressStreet2     string `json:"address_street2"`
	AddressCity        string `json:"address_city"`
	AddressSubdivison  string `json:"address_subdivision"`
	AddressPostalCode  string `json:"address_postal_code"`
	AddressCountryCode string `json:"address_country_code"`
}

type CandidateClient

type CandidateClient struct{}

func (*CandidateClient) Create

func (self *CandidateClient) Create(params *CandidateParams) (*Candidate, error)

func (*CandidateClient) Delete

func (self *CandidateClient) Delete(id string) (*Candidate, error)

func (*CandidateClient) History

func (self *CandidateClient) History(id string) ([]*Candidate, error)

func (*CandidateClient) Hits

func (self *CandidateClient) Hits(id string) ([]*Candidate, error)

func (*CandidateClient) List

func (self *CandidateClient) List() ([]*Candidate, error)

func (*CandidateClient) ListN

func (self *CandidateClient) ListN(count, offset int) ([]*Candidate, error)

func (*CandidateClient) Retrieve

func (self *CandidateClient) Retrieve(id string) (*Candidate, error)

func (*CandidateClient) Update

func (self *CandidateClient) Update(id string, params *CandidateParams) (*Candidate, error)

type CandidateParams

type CandidateParams struct {
	NameFirst          string `json:"name_first,omitempty"`
	NameMiddle         string `json:"name_middle,omitempty"`
	NameLast           string `json:"name_last,omitempty"`
	Note               string `json:"note,omitempty"`
	Ssn                string `json:"ssn,omitempty"`
	Passport           string `json:"passport,omitempty"`
	DateOfBirth        string `json:"date_of_birth,omitempty"`
	AddressStreet1     string `json:"address_street1,omitempty"`
	AddressStreet2     string `json:"address_street2,omitempty"`
	AddressCity        string `json:"address_city,omitempty"`
	AddressSubdivison  string `json:"address_subdivision,omitempty"`
	AddressPostalCode  string `json:"address_postal_code,omitempty"`
	AddressCountryCode string `json:"address_country_code,omitempty"`
}

type Company

type Company struct {
	Object                   string         `json:"object"`
	Id                       string         `json:"id"`
	CreatedAt                int64          `json:"created_at"`
	UpdatedAt                int64          `json:"updated_at"`
	Status                   string         `json:"status"`
	Livemode                 bool           `json:"livemode"`
	EntityName               string         `json:"entity_name"`
	TaxId                    string         `json:"tax_id"`
	IncorporationDate        string         `json:"incorporation_date"`
	IncorporationState       string         `json:"incorporation_state"`
	IncorporationCountryCode string         `json:"incorporation_country_code"`
	IncorporationType        string         `json:"incorporation_type"`
	Dbas                     string         `json:"dbas"`
	RegistrationNumber       string         `json:"registration_number"`
	Email                    string         `json:"email"`
	Url                      string         `json:"url"`
	PhoneNumber              string         `json:"phone_number"`
	IPAddress                string         `json:"ip_address"`
	Note                     string         `json:"note"`
	AddressStreet1           string         `json:"address_street1"`
	AddressStreet2           string         `json:"address_street2"`
	AddressCity              string         `json:"address_city"`
	AddressSubdivision       string         `json:"address_subdivision"`
	AddressPostalCode        string         `json:"address_postal_code"`
	AddressCountryCode       string         `json:"address_country_code"`
	Details                  CompanyDetails `json:"details"`
}

type CompanyClient

type CompanyClient struct{}

func (*CompanyClient) Create

func (self *CompanyClient) Create(params *CompanyParams) (*Company, error)

func (*CompanyClient) List

func (self *CompanyClient) List() ([]*Company, error)

func (*CompanyClient) ListN

func (self *CompanyClient) ListN(count, offset int) ([]*Company, error)

func (*CompanyClient) Retrieve

func (self *CompanyClient) Retrieve(id string) (*Company, error)

type CompanyDetails

type CompanyDetails struct {
	EntityName string `json:"entity_name"`
	TaxId      string `json:"tax_id"`
	Ofac       string `json:"ofac"`
}

type CompanyParams

type CompanyParams struct {
	EntityName               string `json:"entity_name"`
	TaxId                    string `json:"tax_id"`
	IncorporationState       string `json:"incorporation_state"` // optional
	IncorporationCountryCode string `json:"incorporation_country_code"`
	IncorporationType        string `json:"incorporation_type"`
	IncorporationDay         int64  `json:"incorporation_day"`   // optional
	IncorporationMonth       int64  `json:"incorporation_month"` // optional
	IncorporationYear        int64  `json:"incorporation_year"`  // optional
	Dbas                     string `json:"dbas"`                // optional
	RegistrationNumber       string `json:"registration_number"` // optional
	Email                    string `json:"email"`               // optional
	Url                      string `json:"url"`                 // optional
	PhoneNumber              string `json:"phone_number"`        // optional
	IPAddress                string `json:"ip_address"`          // optional
	Note                     string `json:"note"`                // optional
	AddressStreet1           string `json:"address_street1"`
	AddressStreet2           string `json:"address_street2"`
	AddressCity              string `json:"address_city"`
	AddressSubdivision       string `json:"address_subdivision"`
	AddressPostalCode        string `json:"address_postal_code"`
	AddressCountryCode       string `json:"address_country_code"`
}

type Error

type Error struct {
	Code   int
	Detail struct {
		Code    string `json:"code"`
		Message string `json:"message"`
		Param   string `json:"param"`
		Type    string `json:"type"`
	} `json:"error"`
}

Error encapsulates an error returned by the BlockScore REST API.

func (*Error) Error

func (e *Error) Error() string

type Match

type Match struct {
	WatchlistName      string   `json:"watchlist_name"`
	MatchingInfo       []string `json:"matching_info"`
	NameFull           string   `json:"name_full"`
	AlternateNames     string   `json:"alternate_names"`
	DateOfBirth        string   `json:"date_of_birth"`
	Ssn                string   `json:"ssn"`
	Passport           string   `json:"passport"`
	AddressRaw         string   `json:"address_raw"`
	AddressStreet1     string   `json:"address_street1"`
	AddressCity        string   `json:"address_city"`
	AddressState       string   `json:"address_state"`
	AddressPostalCode  string   `json:"address_postal_code"`
	AddressCountryCode string   `json:"address_country_code"`
}

type Person

type Person struct {
	Object             string        `json:"object"`
	Id                 string        `json:"id"`
	CreatedAt          int64         `json:"created_at"`
	UpdatedAt          int64         `json:"updated_at"`
	Status             string        `json:"status"`
	Livemode           bool          `json:"livemode"`
	PhoneNumber        string        `json:"phone_number"`
	IPAddress          string        `json:"ip_address"`
	BirthDay           int64         `json:"birth_day"`
	BirthMonth         int64         `json:"birth_month"`
	BirthYear          int64         `json:"birth_year"`
	NameFirst          string        `json:"name_first"`
	NameMiddle         string        `json:"name_middle"`
	NameLast           string        `json:"name_last"`
	DocumentType       string        `json:"document_type"`
	DocumentValue      string        `json:"document_value"`
	AddressStreet1     string        `json:"address_street1"`
	AddressStreet2     string        `json:"address_street2"`
	AddressCity        string        `json:"address_city"`
	AddressSubdivision string        `json:"address_subdivision"`
	AddressPostalCode  string        `json:"address_postal_code"`
	AddressCountryCode string        `json:"address_country_code"`
	Note               string        `json:"note"`
	Details            PersonDetails `json:"details"`
	QuestionSets       []string      `json:"question_sets"`
}

type PersonClient

type PersonClient struct{}

func (*PersonClient) Create

func (self *PersonClient) Create(params *PersonParams) (*Person, error)

func (*PersonClient) List

func (self *PersonClient) List() ([]*Person, error)

func (*PersonClient) ListN

func (self *PersonClient) ListN(count, offset int) ([]*Person, error)

func (*PersonClient) Retrieve

func (self *PersonClient) Retrieve(id string) (*Person, error)

type PersonDetails

type PersonDetails struct {
	Address        string `json:"address"`
	AddressRisk    string `json:"address_risk"`
	Identification string `json:"identification"`
	DateOfBirth    string `json:"date_of_birth"`
	Ofac           string `json:"ofac"`
	Pep            string `json:"pep"`
}

type PersonParams

type PersonParams struct {
	NameFirst          string `json:"name_first"`
	NameMiddle         string `json:"name_middle"`
	NameLast           string `json:"name_last"`
	DocumentType       string `json:"document_type"`
	DocumentValue      string `json:"document_value"`
	BirthDay           int64  `json:"birth_day"`
	BirthMonth         int64  `json:"birth_month"`
	BirthYear          int64  `json:"birth_year"`
	AddressStreet1     string `json:"address_street1"`
	AddressStreet2     string `json:"address_street2"`
	AddressCity        string `json:"address_city"`
	AddressSubdivision string `json:"address_subdivision"`
	AddressPostalCode  string `json:"address_postal_code"`
	AddressCountryCode string `json:"address_country_code"`
	PhoneNumber        string `json:"phone_number"`
	IPAddress          string `json:"ip_address"`
	Note               string `json:"note"`
}

Options for creating People.

type Question

type Question struct {
	Id       int      `json:"id"`
	Question string   `json:"question"`
	Answers  []Answer `json:"answers"`
}

type QuestionSet

type QuestionSet struct {
	Object         string     `json:"object"`
	Id             string     `json:"id"`
	CreatedAt      int        `json:"created_at"`
	UpdatedAt      int        `json:"updated_at"`
	Livemode       bool       `json:"livemode"`
	VerificationId string     `json:"verification_id"`
	Score          float64    `json:"score"`
	Expired        bool       `json:"expired"`
	TimeLimit      int        `json:"time_limit"`
	Questions      []Question `json:"questions"`
}

type QuestionSetClient

type QuestionSetClient struct{}

func (*QuestionSetClient) Create

func (self *QuestionSetClient) Create(personId string) (*QuestionSet, error)

func (*QuestionSetClient) List

func (self *QuestionSetClient) List() ([]*QuestionSet, error)

func (*QuestionSetClient) ListN

func (self *QuestionSetClient) ListN(count, offset int) ([]*QuestionSet, error)

func (*QuestionSetClient) Retrieve

func (self *QuestionSetClient) Retrieve(id string) (*QuestionSet, error)

func (*QuestionSetClient) Score

func (self *QuestionSetClient) Score(id string, params *ScoreParams) (*QuestionSet, error)

type ScoreAnswer

type ScoreAnswer struct {
	QuestionId int `json:"question_id"`
	AnswerId   int `json:"answer_id"`
}

type ScoreParams

type ScoreParams struct {
	Answers []ScoreAnswer `json:"answers"`
}

type Watchlist

type Watchlist struct {
	Object        string   `json:"object"`
	Livemode      string   `json:"livemode"`
	SearchedLists []string `json:"searched_lists"`
	Matches       []Match  `json:"matches"`
}

type WatchlistClient

type WatchlistClient struct{}

func (*WatchlistClient) Search

func (self *WatchlistClient) Search(params *WatchlistParams) (*Watchlist, error)

type WatchlistParams

type WatchlistParams struct {
	// The ID of the Candidate you have created.
	CandidateId string `json:"candidate_id"`

	// Can either be `person` or `company` and will restrict the search to
	// only search for people or entities on watchlists respectively.
	// Optional param.
	MatchType string `json:"match_type"`
}